{"id":51608688,"url":"https://github.com/writer/cerebro-web","last_synced_at":"2026-07-12T04:30:28.560Z","repository":{"id":361929226,"uuid":"1256486200","full_name":"writer/cerebro-web","owner":"writer","description":"Next.js operator console for Cerebro findings, controls, evidence, connectors, and graph/Ask workflows.","archived":false,"fork":false,"pushed_at":"2026-06-28T17:53:52.000Z","size":1660,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T18:14:38.822Z","etag":null,"topics":["cerebro","graph","grc","nextjs","react","security","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","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":null,"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-06-01T20:30:09.000Z","updated_at":"2026-06-28T17:53:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/writer/cerebro-web","commit_stats":null,"previous_names":["writer/cerebro-web"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/writer/cerebro-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/writer","download_url":"https://codeload.github.com/writer/cerebro-web/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/writer%2Fcerebro-web/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35382323,"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-07-12T02:00:06.386Z","response_time":87,"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":["cerebro","graph","grc","nextjs","react","security","typescript"],"created_at":"2026-07-12T04:30:26.816Z","updated_at":"2026-07-12T04:30:28.554Z","avatar_url":"https://github.com/writer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cerebro Web\n\nCerebro Web is a Next.js operator console for a Cerebro API. It provides UI surfaces for sources, runtimes, findings, reports, workflow metadata, graph projections, and Ask/LLM-backed graph queries.\n\n## Status\n\nMaintained by WRITER on a best-effort basis. There are no support SLAs.\n\n## Cross-Repo Contract\n\nCerebro Web mirrors the app-vs-deploy split used by Cerebro runtime:\n\n- `writer/cerebro-web` is authoritative for the public console app, shared UI behavior, generic source-readiness views, API proxy semantics, OpenAPI rendering, tests, and the source-linked web image.\n- `WriterInternal/cerebro-web` is the private deployment and operations mirror for Writer's web console. It should regularly promote the public app surface, then layer Writer-only dependency policy, deployment environment wiring, secret references, image promotion, rollout, rollback, and operational verification.\n- Private producer registries, private labels, source/runtime mappings, hostnames, identity wiring, and credentials are deployment concerns. Keep them in the internal mirror's deployment configuration or secret store and pass them through documented environment variables.\n\nApplication changes should land here first and then be promoted to `WriterInternal/cerebro-web`. Public examples must remain placeholder-only; real Writer deployment material belongs only in `WriterInternal/cerebro-web`.\n\n## Requirements\n\n- Node.js 22+\n- npm\n- A running Cerebro API, defaulting to `http://localhost:8080`\n\n## Configuration\n\n| Variable | Purpose |\n| --- | --- |\n| `NEXT_PUBLIC_CEREBRO_API_BASE` | Browser-visible API base URL. Defaults to `http://localhost:8080`. |\n| `CEREBRO_API_BASE` | Server-side proxy API base URL override. |\n| `CEREBRO_WEB_FIXTURE_MODE` | Set to `1` to serve public placeholder fixtures from `/api/cerebro/*` for backend-free local UI work. |\n| `CEREBRO_API_KEY`, `CEREBRO_API_TOKEN`, `CEREBRO_X_API_KEY`, `CEREBRO_API_KEYS` | Server-side API key configuration. |\n| `CEREBRO_BEARER_TOKEN` | Server-side bearer token configuration. |\n| `CEREBRO_FORWARD_AUTH_HEADERS` | Set to `true` to forward request auth headers instead of server-side credentials. |\n| `CEREBRO_PROXY_TIMEOUT_MS` | Proxy timeout for long-running requests. |\n| `CEREBRO_PROXY_CACHE_TTL_MS` | Proxy cache TTL; set to `0` to disable local proxy caching. |\n| `CEREBRO_PROXY_CACHE_STALE_MS` | Proxy stale-if-error window after the local proxy cache TTL expires. |\n| `CEREBRO_IDENTITY_PROFILE` | Identity source profile: `auto`, `local`, `okta-proxy`, `cloudflare-access`, `auth-proxy`, `azure-client-principal`, or `oidc-bearer`. |\n| `CEREBRO_IDENTITY_REQUIRED` | Set to `true` to fail closed when current-user identity is missing, conflicting, local fallback, or unverified. Defaults to required in production except the `local` profile. |\n| `CEREBRO_TRUSTED_IDENTITY_HEADERS` | Optional comma-separated allowlist of upstream identity headers. Overrides profile defaults. |\n| `CEREBRO_IDENTITY_ISSUER`, `CEREBRO_IDENTITY_AUDIENCE` | Expected JWT issuer and audience claim checks. |\n| `CEREBRO_IDENTITY_JWKS_URL` | JWKS endpoint used to verify JWT signatures for accepted identity tokens. |\n| `CEREBRO_AUTHZ_REQUIRED_GROUPS`, `CEREBRO_AUTHZ_REQUIRED_ROLES`, `CEREBRO_AUTHZ_REQUIRED_SCOPES` | Optional global entitlement requirements for protected app actions. |\n| `CEREBRO_AUTHZ_BUILTIN_RBAC` | Set to `true` to enforce built-in Cerebro role aliases such as `viewer`, `analyst`, and `admin`. Explicit `cerebro.*` roles and Cerebro scopes enforce built-in RBAC automatically. |\n| `CEREBRO_AUTHZ_READ_*`, `CEREBRO_AUTHZ_WRITE_*`, `CEREBRO_AUTHZ_AGENT_*`, `CEREBRO_AUTHZ_IDENTITY_*` | Optional legacy per-surface entitlement requirements, using `_GROUPS`, `_ROLES`, or `_SCOPES` suffixes. |\n| `CEREBRO_AUTHZ_FINDINGS_WRITE_*`, `CEREBRO_AUTHZ_GRC_INVENTORY_WRITE_*`, `CEREBRO_AUTHZ_CONNECTOR_CREDENTIALS_READ_*`, `CEREBRO_AUTHZ_CONNECTOR_CREDENTIALS_WRITE_*`, `CEREBRO_AUTHZ_CONNECTOR_DEFINITIONS_WRITE_*`, `CEREBRO_AUTHZ_CONNECTORS_WRITE_*`, `CEREBRO_AUTHZ_RUNTIME_RESPONSE_WRITE_*`, `CEREBRO_AUTHZ_REPORTS_RUN_*`, `CEREBRO_AUTHZ_KNOWLEDGE_WRITE_*`, `CEREBRO_AUTHZ_WORKFLOW_REPLAY_*`, `CEREBRO_AUTHZ_SOURCES_PREVIEW_*`, `CEREBRO_AUTHZ_SOURCE_RUNTIMES_WRITE_*`, `CEREBRO_AUTHZ_JOBS_WRITE_*` | Optional route-family entitlement requirements, using `_GROUPS`, `_ROLES`, or `_SCOPES` suffixes. |\n| `OPENAI_API_KEY` | Enables the platform-wide Cerebro AI agent. Without it, Ask falls back to the existing `/grc/ask` stream. |\n| `CEREBRO_AGENT_MODEL` | Optional OpenAI model override for the Cerebro AI agent. Defaults to `gpt-5.4-mini`. |\n| `CEREBRO_MCP_URL` | Optional Cerebro MCP Streamable HTTP endpoint. Defaults to `/api/v1/mcp` on `CEREBRO_API_BASE`. |\n| `CEREBRO_MCP_BEARER_TOKEN`, `CEREBRO_MCP_TOKEN` | Optional bearer token used specifically for Cerebro MCP. |\n| `NEXT_PUBLIC_CEREBRO_SECURITY_PRODUCERS_JSON` | Optional deployment-provided JSON array for security producer coverage shown in `/developer/security-producers`. |\n| `NEXT_PUBLIC_CEREBRO_WEB_VERSION`, `NEXT_PUBLIC_APP_VERSION`, `CEREBRO_WEB_VERSION`, `APP_VERSION`, `RELEASE_VERSION`, `IMAGE_TAG` | Build-time version stamp for the sidebar. Without an explicit value, local builds fall back to Git metadata and then `package.json`. |\n\nFor deployed environments, use server-side credentials or forwarded request auth. Browser-entered API keys are for local development and manual API checks.\n\n`/api/cerebro/*` keeps a small process-local cache for high-traffic GRC reads. Responses expose `x-cerebro-cache` for the web proxy cache state and `x-cerebro-upstream-cache` when the API also reports a shared backend cache state. Manual refreshes send `Cache-Control: no-cache` through the proxy so the API can bypass both layers.\n\nBuilt-in Cerebro RBAC recognizes these role bundles from identity roles or OAuth/API scopes:\n\n| Role | Web permissions |\n| --- | --- |\n| `cerebro.viewer` | Read, Ask, and identity views. Aliases: `viewer`, `reader`, `read_only`. |\n| `cerebro.analyst` | Viewer plus findings and GRC inventory writes. Aliases: `analyst`, `editor`. |\n| `cerebro.finding_manager` | Viewer plus finding lifecycle writes. |\n| `cerebro.grc_reviewer` | Viewer plus GRC inventory writes. |\n| `cerebro.connector_manager` | Viewer plus connector credentials, definitions, and connection writes. |\n| `cerebro.responder` | Viewer plus runtime response writes. |\n| `cerebro.source_manager` | Viewer plus source previews, report runs, and source-runtime writes. |\n| `cerebro.job_manager` | Viewer plus platform job writes. |\n| `cerebro.admin` | All web permissions. Aliases: `admin`, `owner`. |\n\n## Observability\n\nServer-side API proxy and agent routes emit structured JSON span/event lines to stderr with `service=cerebro-web`. The proxy generates or continues W3C `traceparent`, forwards it to Cerebro API and MCP calls, and returns `x-cerebro-web-trace-id` on responses. The Ask agent `done.trace_id` is the same web trace id.\n\nTelemetry is intentionally bounded. It records route family, method, status, cache state, retry attempts, upstream host, and error kind/fingerprint. It does not log request bodies, authorization headers, API keys, cookies, full URLs, or query strings.\n\nFocused checks:\n\n```bash\nnpm run test -- src/lib/observability.test.ts src/lib/cerebro-proxy.test.ts\n```\n\n`/api/identity/health` reports the active identity profile, trusted-header contract, JWT verification posture, and whether the current request is blocked, degraded, or ready.\n\n## Development\n\n```bash\nnpm install\nnpm run doctor\nnpm run dev:fixtures\n```\n\nOpen `http://localhost:3000`.\n\n`dev:fixtures` runs the full Next.js app against deterministic public placeholder data. It is the fastest path for UI, navigation, proxy, and state work when a Cerebro API is not running locally.\n\nTo point the app at a local Cerebro runtime:\n\n```bash\nnpm run dev:local:cerebro\n```\n\nTo run the default Next.js dev server without fixture or local API defaults:\n\n```bash\nnpm run dev\n```\n\n## Validation\n\n```bash\nnpm run verify:fast\nnpm run verify:build\nnpm run oss:audit\nnpm run audit:high\n```\n\nUseful focused checks:\n\n```bash\nnpm run doctor\nnpm run smoke:standalone\nnpm run smoke:deploy -- https://cerebro-web.example.com\nnpm run sync:check\n```\n\n`smoke:standalone` builds and starts `.next/standalone/server.js` with fixture mode, then verifies `/api/health`, `/`, and the referenced `/_next/static/*.js` chunks return executable JavaScript MIME types. Use `-- --skip-build` after a fresh `npm run build`.\n\n`smoke:deploy` performs the same HTTP checks against an already deployed base URL. It is intentionally generic; keep environment-specific URLs and credentials outside this public repo.\n\n`sync:check` compares public-safe application paths between `origin/main` and `internal/main` when both refs are available. It skips cleanly when the private mirror remote is not configured.\n\nOptional local end-to-end and image validation:\n\n```bash\nnpm run verify:e2e\nnpm run verify:docker\n```\n\nLocal GRC E2E writes logs, screenshots, and `summary.json` under `/tmp/cerebro-grc-e2e-*` on failure. Pass `-- --artifacts` or set `CEREBRO_GRC_E2E_RETAIN_ARTIFACTS=1` to keep them for successful runs too.\n\nOptional Ask evaluation checks:\n\n```bash\nnpm run eval:ask:local\nnpm run eval:ask:adversarial\n```\n\n## Release Runbook\n\n1. Develop against fixtures first: `npm run doctor` and `npm run dev:fixtures`.\n2. Before opening a PR, run `npm run verify:fast` and `npm run verify:build`.\n3. For proxy, routing, Docker, or runtime-sensitive changes, add `npm run verify:e2e` and `npm run verify:docker`.\n4. After deployment, run `npm run smoke:deploy -- \u003cbase-url\u003e` from a context that can reach the target environment.\n5. Promote app changes from `writer/cerebro-web` to the private mirror, then run `npm run sync:check` where the `internal` remote is available.\n\n## Security\n\nDo not open public issues for vulnerabilities. Report suspected security issues privately to security@writer.com.\n\n## License\n\nLicensed under the MIT License. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwriter%2Fcerebro-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwriter%2Fcerebro-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwriter%2Fcerebro-web/lists"}