A while back we shipped a skill for writing authorization policies. It took the part everyone found fiddly, modelling roles and resources in YAML, and let you describe what you wanted in plain language instead. People liked it.
So we did the same thing for the other half of the system, the part where you extend the authorization pipeline itself. It lives in the same repo: https://github.com/cerbos/skills
Cerbos Synapse sits alongside your PDP and lets you shape what flows through it. You can enrich a principal with attributes from a database before the decision runs, map an incoming HTTP or Envoy request onto a Cerbos check, or stand up a custom endpoint under /ext/ that does exactly what your application needs. The logic itself is usually small. The friction is everything around it, picking the right kind of extension, getting the runtime set up, wiring it into config, and working out why it isn't firing. That's the part the skill removes.
What the Synapse extension skill does
There are five kinds of extension, and several ways to write each one. A call mapper translates HTTP or Envoy traffic into a Cerbos check with no code at all, just CEL. A data source does attribute lookups for other extensions. A proxy extension rewrites check, plan, or AuthZEN requests and responses on the way through. A route extension exposes a custom endpoint. An Envoy extension turns ext_authz calls into Cerbos decisions. Each one can be declarative CEL, Starlark with no build step, or compiled WASM in Go, TypeScript, or Python.
Most of the time spent building one goes on deciding which combination you actually need and then wiring it up correctly. The skill knows the whole matrix. You tell it what you're trying to do, something like "enrich the principal with the user's department from Postgres before the check runs", and it picks the kind and runtime that fit, scaffolds the files, wires them into config.yaml, and gets it running against a local PDP.
How the skill builds a Synapse extension
It runs the same way the policy skill does, in clear phases rather than one big generation step.
- Intake. Works out what you're mapping and what data you need, in plain terms. What traffic comes in, what decision comes out, what attributes have to be looked up, and which language you want to write it in if it needs code.
- Scaffold. Picks the extension kind and runtime, then writes everything in one batch. The extension itself, the
config.yamlwiring, sample policies, and a docker-compose setup for local dev. - Build. For WASM extensions it runs the compile step first, so what gets mounted is the built artefact, not the source.
- Run and test. Starts Synapse with the extension loaded and exercises it. It can write
*_test.starsuites and run them withsynapse test, which spins up a fresh instance per suite, so there's no manual restart loop. - Debug. If an extension isn't loading or isn't firing, it works through the usual causes, drops into the Starlark REPL where that helps, and reads the decision logs to see the inputs the PDP actually evaluated.
What you get from the skill
A working extension you can run straight away. The extension code, the config that loads it, sample policies, a compose file for local development, and a test suite that proves it does what you asked. Drop it into your own project, point it at your real data sources and policies, and it's a starting point rather than a blank file.
One thing worth knowing: The Synapse image lives in a licensed distribution repository, so the skill asks you for your repo URL before it tries to pull anything or run a test. If you don't have a licence yet, you can get one at cerbos.dev/workshop.
Install the Cerbos Synapse extension skill
It installs the same way as the rest of the Cerbos skills.
npx skills add cerbos/skills --skill cerbos-synapse-extension
If you're on Claude Code, add the marketplace and install the plugin.
claude plugin marketplace add cerbos/skills
claude plugin install cerbos-skills@cerbos-skills
It works with Cursor, Claude Code, Codex, OpenCode, and a dozen other agents.
Why we built a Synapse extension skill
Synapse is the most flexible part of Cerbos, and flexibility cuts both ways. Five extension kinds, three runtimes, host functions that differ per language, a build step for the compiled ones, and a handful of gotchas that only show up when something silently doesn't fire. None of it is hard once you've done it a few times. The problem is the few times.
So we wrote down what we've learned shipping these, the pipeline ordering, the callback modes, the runtime quirks in each language, the way an extension fails to load versus the way it loads but never runs, and put it where the agent can use it while it builds. It pairs with the policy skill. One writes the rules, the other extends the pipeline that enforces them, and increasingly the things people are putting in that pipeline are AI agents and non-human identities that need the same authorization guarantees as everyone else.
Try Cerbos to enforce fine-grained, contextual, and continuous authorization across applications, gateways, workloads, and AI agents. Or talk to an engineer to walk through the options for your specific use case.
Go deeper:
- How to adopt externalized authorization (eBook) for a step-by-step playbook on pulling authorization out of application code
- Why you should externalize authorization for the architecture thinking behind a PDP and the pipeline in front of it
FAQ
Tagged in
