Cerebro

Compliance superpowers for coding agents.

Cerebro turns security, identity, cloud, SaaS, workflow, policy, and compliance signals into evidence-backed context that coding agents can query through a Go CLI, JSON HTTP, Connect RPC, SDK helpers, and MCP.

Use it to help agents answer:

• Can this change ship?
• Which controls, policies, findings, or approvals apply?
• What evidence already exists?
• What remediation or next action is safe to propose?
• Which systems, identities, and risks are connected?

Give Your Coding Agent Compliance Context

The fastest path is to start Cerebro, add it to your agent over MCP, and let the agent read live source data before any stores are configured:

make serve-dev
droid mcp add cerebro-local http://127.0.0.1:8080/api/v1/mcp --type http \
  --header "Authorization: Bearer local-dev-key"

Use Cerebro as compliance context for this repo.
Call cerebro.sources.read with source_id=github and config
{"owner":"<owner>","repo":"<repo>","per_page":"5"}, then tell me what
evidence exists and what security or compliance context applies before this
can ship.

Do not commit provider credentials, customer names, tenant-specific hostnames,
account IDs, or live secret values.

The MCP source tools (cerebro.sources.list/check/discover/read) hit live providers through the existing source service and do not require Postgres, NATS, or Neo4j. For durable evidence and graph context, run make github-business-demo with GITHUB_OWNER, GITHUB_REPO, and GITHUB_TOKEN, then hand tmp/onboarding/github-receipt.json to the agent.

For a live agent integration, connect your MCP client to POST /api/v1/mcp and expose Cerebro as the source for policy memory, compliance evidence, graph context, and safe action planning. See Agent onboarding, MCP native Droid setup, and Agent platform contract.

Start Here

git clone https://github.com/writer/cerebro.git
cd cerebro

make doctor
make serve-dev

By default, the local server listens on :8080.

curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/sources

Run focused tests while iterating, then use CI-parity validation before broad PRs:

make test
make verify

For a durable local stack with NATS JetStream, Postgres, Neo4j, and the local bearer key local-dev-key:

docker compose pull
docker compose up -d

Plain Compose initializes the local Postgres volume with the compose-file password. The onboarding Make targets use tmp/local-postgres-password. Before switching from plain Compose to make agent-onboard-e2e or make github-business-demo, run docker compose down -v to recreate local volumes, or run the Make target with CEREBRO_LOCAL_POSTGRES_PASSWORD=cerebro to reuse that volume. docker compose down -v deletes local stack data.

What Is In This Repo

• A Go bootstrap service built around net/http, Connect RPC, and cmd/cerebro.
• Built-in source integrations for cloud, SaaS, identity, endpoint, vulnerability, compliance, and workflow signals.
• Source runtime sync, append-log replay, claim/finding/report workflows, compliance control coverage, and optional graph projection, query, and action tooling.
• Optional MCP, graph-agent, and device-authenticated telemetry surfaces for agent-readable evidence and control context.
• Policy and FindingRule YAML DSL catalogs, generated detection catalogs, SDK helpers, OpenAPI/Connect contracts, release artifacts, and local validation tooling.

Choose A Path

Goal	Start here
Get the shortest runnable path	Quick reference
Walk through a local end-to-end flow	Getting started
Hand setup to a coding agent	Agent onboarding
Understand runtime shape and stores	Architecture
Configure auth, tenancy, stores, MCP, or device auth	Configuration variables and .env.example
Host or operate Cerebro	Hosting, runtime profiles, deployment readiness, cloud deployment, deployment examples, and operations runbook
Explore JSON HTTP or Connect APIs	API reference, api/openapi.yaml, and proto/cerebro/v1/bootstrap.proto
Use the CLI	CLI reference
Browse built-in integrations	Source catalog
Use SDK helpers	Python SDK, TypeScript SDK, and sources/sdk
Persist and sync source runtimes	Source runtime guide
Work on graph behavior	Graph operations
Design persona-specific graph views	Persona view lenses
Integrate MCP clients	MCP native Droid setup
Integrate endpoint telemetry	Endpoint security platform integration
Author policies, control mappings, or finding rules	Policies, compliance controls, policies/, internal/findingdsl, and internal/findings
Contribute code or docs	Development, non-goals, and the Makefile

Optional Docs Site

The Markdown docs work directly on GitHub. To browse them as a local site:

python3 -m pip install mkdocs
mkdocs serve

The site entry point is docs/index.md, and mkdocs.yml defines the navigation.

Runtime Boundaries

This public repository is authoritative for runtime behavior, CLI/API contracts, source catalogs, configuration semantics, and release artifacts. Environment-specific deployment details, stack configuration, account wiring, hostnames, and rollout procedures intentionally live outside this public repo.

The handoff to deployment repositories is the release payload: container images plus cerebro-runtime-contract.json. Treat that contract as the bridge between public runtime releases and environment-specific promotion/deploy automation.

Volatile details should stay in their source-of-truth files and be linked from here: configuration variables in docs/reference/config-env-vars.md, API shape in api/openapi.yaml, source capabilities in sources/*/catalog.yaml, and release/deploy handoff data in cerebro-runtime-contract.json.

See Non-goals before changing storage shape, Source CDK boundaries, graph/Cypher behavior, findings workflow contracts, action/runtime response semantics, platform/security namespace boundaries, or public product language.

Common Commands

make build          # compile ./bin/cerebro
make serve-dev      # run the local server with acknowledged dev-mode opt-out
make secure-business-demo  # run local security onboarding and write a receipt
make github-business-demo  # seed durable graph context from a real GitHub repo
make agent-onboard  # run an onboarding plan and write a redacted receipt
make agent-onboard-e2e  # run the Docker-backed local onboarding workflow
make test           # go test ./...
make check          # build, tests, lint, proto lint, structural checks, arch tests
make verify         # CI-parity local verification
make readme-check   # README and docs drift checks
make docs-drift-check
make oss-audit      # public repository hygiene scan
cerebro deploy preflight  # emit a redacted deployment readiness receipt
cerebro append-log dead-letters list  # list pending exhausted publish records

Top-level commands are serve, version, source, source-runtime, append-log, finding-rule, graph, orchestrator, vulndb, closeout, and deploy.

For policy or compliance-control work, run make finding-dsl-check, make policy-rule-check, make detection-catalog-check, and make control-index-check as applicable. Control extension packs are documented in Compliance controls and use --init-extension, --extension, --profile, --output, and --write workflows.

Stack

Component	Technology
Language	Go 1.26+ (go1.26.4 toolchain)
HTTP server	Go net/http ServeMux
RPC	Connect
CLI	Standard Go CLI under cmd/cerebro
Append log	NATS JetStream
State store	Postgres
Graph store	Neo4j/Aura
Validation	go test, golangci-lint, Buf, Spectral, catalog checks, policy-rule checks, control-index checks, README drift checks, OSS audit, custom structural linters, arch tests

License

Apache 2.0; see LICENSE.