{"id":49730645,"url":"https://github.com/writer/cerebro","last_synced_at":"2026-06-10T23:00:57.378Z","repository":{"id":342363429,"uuid":"1173694394","full_name":"writer/cerebro","owner":"writer","description":"Security Data Platform for Cloud and SaaS Posture Management","archived":false,"fork":false,"pushed_at":"2026-06-05T07:16:03.000Z","size":88289,"stargazers_count":8,"open_issues_count":59,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T09:14:26.403Z","etag":null,"topics":["aws","cloud-security","compliance","cspm","devsecops","gcp","go","iam","kubernetes","security"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/writer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-05T16:42:32.000Z","updated_at":"2026-06-05T07:08:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/writer/cerebro","commit_stats":null,"previous_names":["writer/cerebro"],"tags_count":219,"template":false,"template_full_name":null,"purl":"pkg:github/writer/cerebro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/writer","download_url":"https://codeload.github.com/writer/cerebro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34174148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cloud-security","compliance","cspm","devsecops","gcp","go","iam","kubernetes","security"],"created_at":"2026-05-09T06:14:58.854Z","updated_at":"2026-06-10T23:00:57.366Z","avatar_url":"https://github.com/writer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cerebro\n\n**Operations data platform for cloud, SaaS, identity, workflow, finding, and graph signals.**\n\nCerebro is Writer's original operations platform repository. The current `main` branch is centered on a Go bootstrap service with Connect and JSON HTTP APIs, built-in source integrations, source runtime sync, finding and report workflows, append-log replay, MCP access, device-authenticated telemetry, and optional graph projection/query tooling.\n\nIn practical terms, Cerebro ingests source and runtime signals, turns them into claims, findings, reports, workflow events, and graph context, then exposes that substrate through the CLI, JSON HTTP, Connect RPC, SDK helpers, and MCP.\n\n[![Go Version](https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat\u0026logo=go)](https://go.dev/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n---\n\n## Current capabilities\n\n- **Bootstrap API service** — `net/http` plus Connect RPC handlers for health, source, runtime, claim, finding, candidate, report, workflow, MCP, device, and graph routes.\n- **Source previews and runtime sync** — built-in sources can be checked, discovered, read, bootstrapped from config, persisted as source runtimes, synced through an append log, and projected into state/graph stores when configured.\n- **Panopticon S3 ingest** — first-class `panopticon` source runtimes read canonical alert, case, and IOC event archives from S3 NDJSON or NDJSON-gzip prefixes and emit validated `panopticon.*` events for projections and findings.\n- **Finding workflows** — built-in finding rules can evaluate source runtime events, produce candidates, persist evidence/evaluation runs, promote or reject candidates, and drive finding lifecycle actions.\n- **Report runs** — report definitions can be listed and executed with durable run retrieval when a state store is configured.\n- **Workflow event replay** — knowledge decisions, actions, and outcomes can be written and replayed through append-log-backed projections.\n- **Graph operations** — Neo4j/Aura-backed graph counts, relation counts, neighborhoods, path summaries, impact queries, graph health, source/runtime ingest, ingest run status, repair/cleanup helpers, and isolated dry-run rebuilds.\n- **MCP and graph-agent surfaces** — an authenticated MCP endpoint, optional OAuth 2.1 authorization-server flow for MCP clients, and an optional graph agent LLM adapter.\n- **Device telemetry surface** — optional first-party device enrollment, token, telemetry ingest, and device vulnerability finding routes.\n- **Policy catalog** — JSON policy definitions under `policies/` for cloud, identity, GitHub, Kubernetes, SaaS, runtime, vulnerability, compliance, and business-operation checks.\n\nCerebro has historical and forward-looking docs in `docs/`. For current runtime behavior, treat `cmd/cerebro`, `internal/config`, `internal/bootstrap`, `proto/cerebro/v1/bootstrap.proto`, and the Makefile as the source of truth.\n\n---\n\n## Public boundaries and non-goals\n\nCerebro exposes JSON HTTP, Connect RPC, CLI, and release artifacts. This repository does not ship an end-user web console, a SIEM/CSPM/CNAPP/EDR/SOAR replacement, an endpoint sensor, a plugin marketplace, a general-purpose graph database product, autonomous remediation, or a cloud-specific control plane.\n\n### Cross-repo contract\n\nThis 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.\n\nThe 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.\n\nVolatile details should stay in their source-of-truth files and be linked from here: configuration variables in `docs/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`.\n\nSee [Non-goals](docs/NON_GOALS.md) 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.\n\nPanopticon integration uses canonical event archives and supported SDK claim writes. EvidenceCAS data stays pointer-only (`evidencecas://` URI plus digest/Merkle metadata) and Cerebro does not provide a legacy claims-NDJSON importer.\n\n---\n\n## Architecture\n\n```text\nCLI / JSON HTTP / Connect / MCP clients\n              |\n              v\n      Bootstrap service\n   (cmd/cerebro, internal/bootstrap)\n              |\n              +--\u003e Source registry, preview, and runtime sync\n              +--\u003e Claim, finding, report, workflow, and graph services\n              +--\u003e Optional MCP OAuth and device-auth services\n              |\n              +--\u003e Optional append log: NATS JetStream\n              +--\u003e Optional state store: Postgres\n              +--\u003e Optional graph store: Neo4j/Aura\n```\n\nExternal dependency drivers are opt-in. With no external drivers configured, the server can start and serve lightweight routes such as `/health`, `/healthz`, `/livez`, and `/sources`. `/health` is the dependency-aware readiness check; `/healthz` and `/livez` are liveness-only checks. Durable runtime, claim, finding, report, replay, and graph operations require their corresponding stores.\n\n---\n\n## Quick start\n\n### Prerequisites\n\n- Go 1.26+; this repo pins toolchain `go1.26.4`.\n- Optional: NATS JetStream for append-log-backed sync/replay.\n- Optional: Postgres for durable source runtime, claim, finding, evidence, evaluation, and report state.\n- Optional: Neo4j or AuraDB for graph projection/query operations.\n\n### First run\n\n```bash\ngit clone https://github.com/writer/cerebro.git\ncd cerebro\n\nmake doctor\nmake build\nmake serve\n```\n\nBy default, Cerebro listens on `:8080`.\n\nIn another shell:\n\n```bash\ncurl -sS http://127.0.0.1:8080/health\ncurl -sS http://127.0.0.1:8080/sources\n```\n\nRun focused tests while iterating, then use CI-parity validation before broad PRs:\n\n```bash\nmake test\nmake verify\n```\n\n### Durable local stack\n\n```bash\ndocker compose up --build\n```\n\nThe compose stack starts Cerebro with NATS JetStream, Postgres, and Neo4j using service-local `CEREBRO_*` environment variables. For a standalone environment template, start from `.env.example`.\n\n---\n\n## Choose your path\n\n| Goal | Start here | Notes |\n| --- | --- | --- |\n| Run the lightweight server | `make serve` | Starts the API without external stores; useful for health, source catalog, and OpenAPI checks. |\n| Run the durable local stack | `docker compose up --build` | Starts Cerebro with NATS JetStream, Postgres, and Neo4j. |\n| Try a local end-to-end path | `docs/GETTING_STARTED.md` | Creates an SDK source runtime, writes a synthetic claim, and reads it back. |\n| Explore the API | `GET /openapi.yaml` or `api/openapi.yaml` | JSON HTTP routes are generated and checked against the OpenAPI contract. |\n| Call the Connect API | `proto/cerebro/v1/bootstrap.proto` and `gen/cerebro/v1` | Connect RPCs are served under `/cerebro.v1.BootstrapService/{Method}`. |\n| Use SDK helpers | `sdk/python/README.md`, `sdk/typescript/README.md`, and `sources/sdk` | Maintained helpers target current bootstrap routes; the historical Agent SDK gateway is retired. |\n| Ingest Panopticon exports | `sources/panopticon`, source runtime config, and `sdk/python/examples/panopticon_push_claims.py` | S3 runtimes read canonical `alerts/`, `cases/`, and `iocs/` event archives; SDK helper writes supported claim payloads only. |\n| Preview a source | `./bin/cerebro source check/discover/read ...` | Source config is passed as `key=value` pairs or HTTP query parameters. |\n| Persist and sync a runtime | `source-runtime put/get/list/sync` | Requires Postgres; sync also requires JetStream. |\n| Work on graph behavior | `graph counts`, `graph health`, `graph ingest-runtime` | Requires Neo4j/Aura and, for runtime-backed operations, the configured runtime stores. |\n| Integrate MCP clients | `docs/MCP_DROID_SETUP.md` and `/api/v1/mcp` | Covers stateless Streamable HTTP, OAuth discovery, and compatibility checks. |\n| Integrate endpoint telemetry | `docs/ENDPOINT_SECURITY_PLATFORM_INTEGRATION.md` | Covers device-authenticated telemetry, trusted endpoint claims, and trust-gate evidence. |\n| Author policies or finding rules | `policies/`, `internal/findings`, and catalog checks | Run the relevant catalog and finding-rule tests before opening a PR. |\n| Contribute code or docs | `docs/DEVELOPMENT.md`, `docs/NON_GOALS.md`, and the Makefile | Prefer focused `make` targets while iterating; use `make verify` for broad PR preflight. |\n\n---\n\n## Configuration\n\nThe bootstrap binary currently reads core, auth, store, graph-agent, MCP OAuth, device-auth, and source-config environment variables through `internal/config`. Start from `.env.example` for a local template, and use `docs/CONFIG_ENV_VARS.md` as the expanded configuration reference.\n\nCore runtime and store variables:\n\n| Variable | Purpose | Default |\n| --- | --- | --- |\n| `CEREBRO_HTTP_ADDR` | HTTP listen address | `:8080` |\n| `CEREBRO_SHUTDOWN_TIMEOUT` | graceful shutdown timeout | `10s` |\n| `CEREBRO_IMAGE_TAG` | image tag exported by release/deploy tooling | unset |\n| `CEREBRO_API_AUTH_ENABLED` | require bearer/API-key auth for non-public routes | `false` |\n| `CEREBRO_API_KEYS` | comma-separated `key[:principal[:tenant_id]]` entries | unset |\n| `CEREBRO_API_CREDENTIALS_JSON` | structured bearer credentials with scopes and tenant metadata | unset |\n| `CEREBRO_ALLOWED_TENANTS` | optional tenant allowlist for unscoped API keys | unset |\n| `CEREBRO_CAPABILITY_TOKEN_SECRETS` | comma-separated HMAC secrets for capability-token auth | unset |\n| `CEREBRO_CAPABILITY_TOKEN_AUDIENCE` | expected capability-token audience | `cerebro-api` |\n| `CEREBRO_PUBLIC_ORIGIN` | canonical external origin for DPoP and proxy-aware URL reconstruction | request host |\n| `CEREBRO_TRUSTED_PROXY_CIDRS` | comma-separated trusted proxy/load-balancer CIDRs for forwarded headers | private/link-local remotes |\n| `CEREBRO_TRUSTED_PROXY_COUNT` | trusted trailing `X-Forwarded-For` hops | `0` |\n| `CEREBRO_APPEND_LOG_DRIVER` | append-log driver; supported value: `jetstream` | unset |\n| `CEREBRO_JETSTREAM_URL` | NATS URL for JetStream | unset |\n| `CEREBRO_JETSTREAM_SUBJECT_PREFIX` | JetStream subject prefix | `events` |\n| `CEREBRO_STATE_STORE_DRIVER` | state-store driver; supported value: `postgres` | unset |\n| `CEREBRO_POSTGRES_DSN` | Postgres DSN | unset |\n| `CEREBRO_GRAPH_STORE_DRIVER` | graph-store driver; supported value: `neo4j` | unset |\n| `CEREBRO_NEO4J_URI` | Neo4j/Aura connection URI | unset |\n| `CEREBRO_NEO4J_USERNAME` | Neo4j/Aura username | unset |\n| `CEREBRO_NEO4J_PASSWORD` | Neo4j/Aura password | unset |\n| `CEREBRO_NEO4J_DATABASE` | optional Neo4j database name; empty uses the server default | unset |\n\nAdvanced config families include:\n\n| Variable family | Purpose |\n| --- | --- |\n| `source-runtime bootstrap env=\u003cenv-var\u003e`, `CEREBRO_SOURCE_CONFIG_ENV_ALLOWLIST`, `CEREBRO_AWS_ASSUME_ROLE_ARNS` | bootstrap source runtimes and allow `env:` source config references |\n| `CEREBRO_GRAPH_AGENT_LLM_*`, `CEREBRO_OPENROUTER_API_KEY` | optional graph-agent LLM provider/model settings |\n| `CEREBRO_MCP_OAUTH_*` | optional OAuth 2.1 authorization-server surface for MCP clients |\n| `CEREBRO_DEVICE_AUTH_*` | optional first-party device enrollment, token, DPoP, attestation, and telemetry controls |\n\nDriver selection is inferred when a driver-specific setting is present. For example, `CEREBRO_POSTGRES_DSN` selects the Postgres state store, and `CEREBRO_NEO4J_URI` selects the Neo4j graph store.\n\nEnable `CEREBRO_API_AUTH_ENABLED=true` in shared or production deployments. API keys can be scoped to a tenant with `key:principal:tenant_id`; requests that provide a different `tenant_id` are rejected before service logic runs.\n\nExample durable local configuration:\n\n```bash\nexport CEREBRO_APPEND_LOG_DRIVER=jetstream\nexport CEREBRO_JETSTREAM_URL=nats://127.0.0.1:4222\nexport CEREBRO_STATE_STORE_DRIVER=postgres\nexport CEREBRO_POSTGRES_DSN='postgres://127.0.0.1:5432/cerebro?sslmode=disable'\nexport CEREBRO_GRAPH_STORE_DRIVER=neo4j\nexport CEREBRO_NEO4J_URI=bolt://127.0.0.1:7687\nexport CEREBRO_NEO4J_USERNAME=neo4j\nexport CEREBRO_NEO4J_PASSWORD='local-password'\n```\n\n---\n\n## Dependencies by operation\n\n| Operation | Required backing dependencies |\n| --- | --- |\n| `serve`, `/health`, `/sources`, source `check/discover/read` | none beyond provider-specific source config/auth |\n| `source-runtime put/get` | Postgres state store |\n| `source-runtime sync` | Postgres state store + NATS JetStream append log |\n| Claim, finding, evidence, evaluation, and report run persistence | Postgres state store |\n| Workflow replay | NATS JetStream append log plus configured projection stores |\n| Graph query/ingest operations | Neo4j/Aura graph store; runtime-backed graph operations also need Postgres and/or JetStream |\n| Graph rebuild dry-runs | Postgres state store; replay mode also needs NATS JetStream append log |\n| MCP endpoint | API auth; OAuth mode additionally requires Postgres, public origin, client/upstream config, and capability-token secrets |\n| Device-auth telemetry | API auth, device-auth signing keys, and a device-auth-capable state store |\n\n---\n\n## CLI\n\nBuild first with `make build`, then run `./bin/cerebro`.\n\n```bash\n# Server and version\n./bin/cerebro serve\n./bin/cerebro version\n\n# Source catalog and previews\n./bin/cerebro source list\n./bin/cerebro source check github owner=writer repo=cerebro\n./bin/cerebro source discover github owner=writer repo=cerebro\n./bin/cerebro source read github owner=writer repo=cerebro per_page=1\n\n# Source runtimes require configured stores\n./bin/cerebro source-runtime list\n./bin/cerebro source-runtime bootstrap env=SOURCE_RUNTIMES_JSON\n./bin/cerebro source-runtime put example-github github tenant_id=example owner=writer repo=cerebro\n./bin/cerebro source-runtime get example-github\n./bin/cerebro source-runtime sync example-github page_limit=1\n\n# Finding rule scaffolding and graph-backed evaluation\n./bin/cerebro finding-rule new identity-example source_id=okta event_kinds=okta.user name=\"Example identity rule\" dry_run=true\n./bin/cerebro finding-rule graph-evaluate \u003crule-id\u003e tenant_id=example limit=10\n\n# Graph inspection and ingest require a configured graph store\n./bin/cerebro graph counts\n./bin/cerebro graph relation-counts\n./bin/cerebro graph neighborhood \u003croot-urn\u003e limit=10\n./bin/cerebro graph paths limit=10\n./bin/cerebro graph integrity\n./bin/cerebro graph health\n./bin/cerebro graph ingest github tenant_id=example owner=writer repo=cerebro page_limit=1\n./bin/cerebro graph ingest-runtime example-github page_limit=1\n./bin/cerebro graph ingest-run \u003crun-id\u003e\n./bin/cerebro graph ingest-runs runtime_id=example-github\n./bin/cerebro graph rebuild example-github dry_run=true mode=replay\n```\n\nTop-level commands are `serve`, `version`, `source`, `source-runtime`, `finding-rule`, `graph`, `orchestrator`, `vulndb`, and `closeout`.\n\n---\n\n## Built-in sources\n\n| Source ID | Description | Emitted kinds / families |\n| --- | --- | --- |\n| `anthropic` | Anthropic organization source | users, workspaces, API keys |\n| `aurelius` | SaaS/business-operation export source | configured catalog families |\n| `aws` | AWS IAM, cloud, workload, network exposure, and CloudTrail source | access keys, IAM users/groups/roles/trust, EC2, ECS, EKS, Lambda, public endpoints, resource exposure, CloudTrail |\n| `azure` | Azure Entra ID, RBAC, activity, and audit source | activity logs, directory audit, users, groups, role/app assignments, service principals, credentials, resource exposure |\n| `backstage` | Backstage catalog source | components |\n| `cerebro` | Cerebro product access telemetry source backed by structured NDJSON archives | API access audit events |\n| `cloudflare` | Cloudflare account and network source | accounts, members, roles, zones, DNS records |\n| `cosmo` | Cosmo workflow and message source | messages, survey feedback, configured families |\n| `duo` | Duo identity and MFA source | users, groups, endpoints, phones, tokens, WebAuthn credentials |\n| `evidence_cas` | EvidenceCAS content-addressed evidence reference source | object manifests |\n| `gcp` | GCP IAM, Cloud Identity, service-account, and audit source | audit, groups, IAM role assignments, service accounts, resource exposure |\n| `github` | GitHub audit, repository, Dependabot, and pull request source | audit, repository, Dependabot alerts, pull requests |\n| `google_workspace` | Google Workspace Directory and Admin audit source | audit, groups, group members, role assignments, users |\n| `grc` | Governance/risk/compliance source | configured GRC families |\n| `kandji` | Kandji device/application/vulnerability source | devices, applications, vulnerabilities |\n| `kolide` | Kolide device posture source | configured catalog families |\n| `kubernetes` | Kubernetes inventory source | clusters, namespaces, pods, containers, service accounts, workloads, workload identity bindings |\n| `okta` | Okta audit, identity inventory, app, group, authenticator, assignment, and admin role source | audit, users, groups, applications, assignments, admin roles, authenticators, threat insight |\n| `openai` | OpenAI organization source | users, projects, service accounts, API keys, admin API keys |\n| `pagerduty` | PagerDuty incident management source | users, teams, services, schedules, escalation policies, integrations, vendors |\n| `panopticon` | Panopticon security operations source backed by canonical S3 event archives | alerts, cases, IOCs |\n| `sdk` | Generic SDK push source for onboarded applications | validates pushed integration config; preview reads are empty |\n| `sentinelone` | SentinelOne endpoint posture and threat source | agents, threats, activities, applications, exclusions, groups, sites |\n| `security_tooling_map` | Security tooling inventory source | configured tooling-map families |\n| `slack` | Slack workspace source | teams, users, channels, user groups |\n| `tailscale` | Tailscale network source | tailnets, users, devices, groups, tags, services, grants |\n| `trivy` | Trivy report source | image scans, image packages, image vulnerabilities, fixes |\n| `trusted_endpoint` | Trusted Endpoint posture, AI trust, GRC evidence, and trust-gate source | metadata-only endpoint posture, AI risk, evidence, findings, and action outcomes |\n| `vulnview` | Vulnerability and attack-surface source | sites, scans, vulnerabilities, assets, DNS alerts |\n\nSource-specific configuration is passed as `key=value` pairs in CLI calls or query parameters in HTTP calls. Required keys vary by source and family.\n\n---\n\n## HTTP and Connect API surface\n\nConnect RPC procedures are served under `/cerebro.v1.BootstrapService/{Method}`. JSON HTTP is described by `api/openapi.yaml` and is served by the binary at `GET /openapi.yaml`.\n\nMajor route groups include:\n\n- Public health and metadata: `/health` readiness, `/healthz` and `/livez` liveness, `/openapi.yaml`, OAuth protected-resource/authorization-server metadata.\n- Source catalog and previews: `/sources`, `/sources/{sourceID}/check`, `/discover`, `/read`.\n- Source runtime operations: `/source-runtimes`, runtime `sync`, claims, findings, candidates, evidence, evaluation runs, and graph ingest runs.\n- Finding and candidate lifecycle: `/finding-rules`, `/findings/*`, `/finding-candidates/*`, `/finding-evidence/*`, `/finding-evaluation-runs/*`.\n- Reports and workflow events: `/reports`, `/report-runs`, `/platform/knowledge/*`, `/platform/workflow/replay`.\n- Graph platform APIs: `/platform/graph/neighborhood`, impact, attack paths, crown-jewel rankings, AWS public endpoint insights, ingest health, and ingest run retrieval.\n- MCP: `/api/v1/mcp` over GET/POST.\n- Device auth and telemetry when enabled: `/platform/devices/*`, `/platform/telemetry/ingest`, and `/.well-known/device-jwks.json`.\n\nWhen auth is enabled, only health/OpenAPI and OAuth/device metadata-style routes are public; platform, source, finding, report, graph, MCP, and device mutation routes require appropriate authentication and scopes.\n\n---\n\n## SDK helpers\n\nMaintained SDK helpers live directly under `sdk/python` and `sdk/typescript`. They target the current bootstrap API surface for source runtime setup, claim writes, graph neighborhoods, and integration examples such as Jira posture onboarding and Panopticon push-claim onboarding.\n\nThese helpers are separate from the retired historical Agent SDK gateway. Future SDK methods should start from the current HTTP/OpenAPI or Connect contracts, then add generated or hand-maintained helpers after the runtime route exists.\n\nUseful checks:\n\n```bash\nmake sdk-test\ncd sdk/python \u0026\u0026 python3 -m unittest discover -s tests\ncd sdk/typescript \u0026\u0026 npm test\n```\n\n---\n\n## Policies\n\nPolicy definitions live under `policies/` as JSON files. The catalog includes cloud posture, identity governance, GitHub, Kubernetes, M365, Okta, runtime, vulnerability, compliance, and business-operation checks.\n\nUseful directories include `policies/aws/`, `policies/azure/`, `policies/gcp/`, `policies/github/`, `policies/identity/`, `policies/kubernetes/`, `policies/okta/`, `policies/runtime/`, and `policies/vulnerability/`.\n\n---\n\n## Development\n\n```bash\nmake build          # compile ./bin/cerebro\nmake serve          # build and run the server\nmake test           # go test ./...\nmake lint           # golangci-lint over app packages\nmake proto-lint     # buf lint\nmake check          # build, tests, lint, proto lint, structural checks, arch tests\nmake verify         # CI-parity local verification\nmake doctor         # check required local developer tools\nmake release-smoke  # validate GoReleaser config\nmake docker-smoke   # build the runtime Dockerfile locally\nmake readme-check   # README drift checks\nmake docs-drift-check  # generated docs drift checks\nmake oss-audit      # public repository hygiene scan\nmake clean          # remove bin/\n```\n\nFocused validation and utility targets include `make openapi-check`, `make openapi-lint`, `make catalog-check`, `make detection-catalog-check`, `make workflow-e2e-test`, `make workflow-replay-test`, `make finding-rule-test`, `make graph-rebuild-dryrun`, `make workflow-replay`, and `make workflow-neighborhood`.\n\nPublic-facing docs, config, or example changes should run:\n\n```bash\nmake oss-audit\n```\n\nChoose validators by change type:\n\n| Change type | Minimum local validation |\n| --- | --- |\n| README-only | `make readme-check` and `make oss-audit` |\n| Go runtime/API change | `make test` plus focused package tests |\n| OpenAPI route or handler change | `make openapi-check openapi-lint` |\n| Proto change | `make proto-lint` and generated contract checks when applicable |\n| Source catalog or policy change | `make catalog-check detection-catalog-check` |\n| Public docs/config/examples | `make docs-drift-check` when generated docs are touched, plus `make oss-audit` |\n| Broad PR preflight | `make verify` |\n\n---\n\n## Release and deploy artifacts\n\nReleases are tag-driven (`vMAJOR.MINOR.PATCH[-PRERELEASE]`). The release workflow runs the same verify shards as CI, publishes GoReleaser binaries, builds multi-arch runtime images at `ghcr.io/writer/cerebro:\u003ctag\u003e`, signs images and runtime deploy contracts with cosign, and uploads `cerebro-runtime-contract.json` plus its signature/certificate to the GitHub release.\n\n`cmd/sourcedeploy` renders source deployment fragments and the runtime deploy contract from `sources/*/deploy.yaml` manifests:\n\n```bash\ngo run ./cmd/sourcedeploy -env \u003cenv\u003e -tenant \u003ctenant\u003e -format yaml\ngo run ./cmd/sourcedeploy -env \u003cenv\u003e -tenant \u003ctenant\u003e -format contract-json -image-tag vX.Y.Z\n```\n\nIf release-promotion secrets are configured, release publishes can dispatch downstream deployment proposal workflows. The repository still treats deployments as explicit, validated, and reviewable.\n\n---\n\n## Documentation\n\nSome files in `docs/` describe broader or historical architecture and may be ahead of or behind the current bootstrap implementation. Useful entry points:\n\n| Document | Notes |\n| --- | --- |\n| [Getting started](docs/GETTING_STARTED.md) | local durable stack plus SDK source runtime and claim-write walkthrough |\n| [API contracts](docs/API_CONTRACTS_AUTOGEN.md) | current bootstrap HTTP and Connect contract reference |\n| [API reference](docs/API_REFERENCE.md) | OpenAPI-oriented route reference |\n| [CloudEvents](docs/CLOUDEVENTS_AUTOGEN.md) | generated event contract reference |\n| [Configuration](docs/CONFIGURATION.md) | configuration and deployment notes |\n| [MCP native Droid setup](docs/MCP_DROID_SETUP.md) | native Droid MCP setup, OAuth flow, transport compatibility, and troubleshooting |\n| [DevEx codegen catalog](docs/DEVEX_CODEGEN_AUTOGEN.md) | generated surface map for OpenAPI, proto, and detection catalog checks |\n| [Graph ontology](docs/GRAPH_ONTOLOGY_AUTOGEN.md) | generated graph ontology reference |\n| [Graph report contracts](docs/GRAPH_REPORT_CONTRACTS_AUTOGEN.md) | generated graph/report contract reference |\n| [Endpoint security platform integration](docs/ENDPOINT_SECURITY_PLATFORM_INTEGRATION.md) | trusted-endpoint, secheck, Security/Kairos, identity, telemetry, and trust-gate integration contract |\n| [Non-goals](docs/NON_GOALS.md) | what Cerebro intentionally does not try to do, with rationale and enforcement pointers |\n| [Policies](docs/POLICIES.md) | policy catalog and authoring notes |\n| [Packages](docs/PACKAGES.md) | package overview; verify against current code before relying on details |\n| [Development](docs/DEVELOPMENT.md) | development notes; verify commands against the Makefile |\n\n---\n\n## Stack\n\n| Component | Technology |\n| --- | --- |\n| Language | Go 1.26+ (`go1.26.4` toolchain) |\n| HTTP server | Go `net/http` `ServeMux` |\n| RPC | Connect |\n| CLI | Standard Go CLI under `cmd/cerebro` |\n| Append log | NATS JetStream |\n| State store | Postgres |\n| Graph store | Neo4j/Aura |\n| Source integrations | Aurelius, AWS, Azure, Backstage, Cosmo, EvidenceCAS, GCP, GitHub, Google Workspace, GRC, Kandji, Kolide, Okta, Panopticon, SDK, SentinelOne, Security Tooling Map, Trusted Endpoint, VulnView |\n| Validation | `go test`, `golangci-lint`, Buf, Spectral, catalog checks, OSS audit, custom structural linters, arch tests |\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwriter%2Fcerebro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwriter%2Fcerebro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwriter%2Fcerebro/lists"}