Cerebro Web

Important

Active development has moved to apps/web in the Cerebro monorepo. Open application changes and issues in writer/cerebro. This repository accepts only migration-closure changes and emergency fixes until cutover is complete.

Cerebro 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.

Status

Development is frozen for the monorepo migration. The current source remains available until cutover, reconciliation, and rollback evidence are complete.

Source and Deployment Contract

• writer/cerebro/apps/web owns the public console application, shared UI behavior, API proxy semantics, OpenAPI rendering, tests, and portable release inputs.
• Environment values, private mappings, credentials, deployment adapters, rollout policy, and operational verification remain outside the public repository.
• Public examples must stay placeholder-only. Do not add environment-specific configuration or deployment material to the public application.

Requirements

• Node.js 22+
• npm
• A running Cerebro API, defaulting to http://localhost:8080

Configuration

Variable	Purpose
NEXT_PUBLIC_CEREBRO_API_BASE	Browser-visible API base URL. Defaults to http://localhost:8080.
CEREBRO_API_BASE	Server-side proxy API base URL override.
CEREBRO_WEB_FIXTURE_MODE	Set to 1 to serve public placeholder fixtures from /api/cerebro/* for backend-free local UI work.
CEREBRO_API_KEY, CEREBRO_API_TOKEN, CEREBRO_X_API_KEY, CEREBRO_API_KEYS	Server-side API key configuration.
CEREBRO_BEARER_TOKEN	Server-side bearer token configuration.
CEREBRO_FORWARD_AUTH_HEADERS	Set to true to forward request auth headers instead of server-side credentials.
CEREBRO_PROXY_TIMEOUT_MS	Proxy timeout for long-running requests.
CEREBRO_PROXY_CACHE_TTL_MS	Proxy cache TTL; set to 0 to disable local proxy caching.
CEREBRO_PROXY_CACHE_STALE_MS	Proxy stale-if-error window after the local proxy cache TTL expires.
CEREBRO_IDENTITY_PROFILE	Identity source profile: auto, local, okta-proxy, cloudflare-access, auth-proxy, azure-client-principal, or oidc-bearer.
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.
CEREBRO_TRUSTED_IDENTITY_HEADERS	Optional comma-separated allowlist of upstream identity headers. Overrides profile defaults.
CEREBRO_IDENTITY_ISSUER, CEREBRO_IDENTITY_AUDIENCE	Expected JWT issuer and audience claim checks.
CEREBRO_IDENTITY_JWKS_URL	JWKS endpoint used to verify JWT signatures for accepted identity tokens.
CEREBRO_AUTHZ_REQUIRED_GROUPS, CEREBRO_AUTHZ_REQUIRED_ROLES, CEREBRO_AUTHZ_REQUIRED_SCOPES	Optional global entitlement requirements for protected app actions.
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.
CEREBRO_AUTHZ_READ_*, CEREBRO_AUTHZ_WRITE_*, CEREBRO_AUTHZ_AGENT_*, CEREBRO_AUTHZ_IDENTITY_*	Optional legacy per-surface entitlement requirements, using _GROUPS, _ROLES, or _SCOPES suffixes.
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.
OPENAI_API_KEY	Enables the platform-wide Cerebro AI agent. Without it, Ask falls back to the existing /grc/ask stream.
CEREBRO_AGENT_MODEL	Optional OpenAI model override for the Cerebro AI agent. Defaults to gpt-5.4-mini.
CEREBRO_MCP_URL	Optional Cerebro MCP Streamable HTTP endpoint. Defaults to /api/v1/mcp on CEREBRO_API_BASE.
CEREBRO_MCP_BEARER_TOKEN, CEREBRO_MCP_TOKEN	Optional bearer token used specifically for Cerebro MCP.
NEXT_PUBLIC_CEREBRO_SECURITY_PRODUCERS_JSON	Optional deployment-provided JSON array for security producer coverage shown in /developer/security-producers.
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.

For deployed environments, use server-side credentials or forwarded request auth. Browser-entered API keys are for local development and manual API checks.

/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.

Built-in Cerebro RBAC recognizes these role bundles from identity roles or OAuth/API scopes:

Role	Web permissions
cerebro.viewer	Read, Ask, and identity views. Aliases: viewer, reader, read_only.
cerebro.analyst	Viewer plus findings and GRC inventory writes. Aliases: analyst, editor.
cerebro.finding_manager	Viewer plus finding lifecycle writes.
cerebro.grc_reviewer	Viewer plus GRC inventory writes.
cerebro.connector_manager	Viewer plus connector credentials, definitions, and connection writes.
cerebro.responder	Viewer plus runtime response writes.
cerebro.source_manager	Viewer plus source previews, report runs, and source-runtime writes.
cerebro.job_manager	Viewer plus platform job writes.
cerebro.admin	All web permissions. Aliases: admin, owner.

Observability

Server-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.

Telemetry 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.

Focused checks:

npm run test -- src/lib/observability.test.ts src/lib/cerebro-proxy.test.ts

/api/identity/health reports the active identity profile, trusted-header contract, JWT verification posture, and whether the current request is blocked, degraded, or ready.

Development

npm install
npm run doctor
npm run dev:fixtures

Open http://localhost:3000.

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.

To point the app at a local Cerebro runtime:

npm run dev:local:cerebro

To run the default Next.js dev server without fixture or local API defaults:

npm run dev

Validation

npm run verify:fast
npm run verify:build
npm run oss:audit
npm run audit:high

Useful focused checks:

npm run doctor
npm run smoke:standalone
npm run smoke:deploy -- https://cerebro-web.example.com
npm run sync:check

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.

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.

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.

Optional local end-to-end and image validation:

npm run verify:e2e
npm run verify:docker

Local 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.

Optional Ask evaluation checks:

npm run eval:ask:local
npm run eval:ask:adversarial

Release Runbook

1. Develop against fixtures first: npm run doctor and npm run dev:fixtures.
2. Before opening a PR, run npm run verify:fast and npm run verify:build.
3. For proxy, routing, Docker, or runtime-sensitive changes, add npm run verify:e2e and npm run verify:docker.
4. After deployment, run npm run smoke:deploy -- <base-url> from a context that can reach the target environment.
5. Submit application changes through writer/cerebro/apps/web. Run deployment verification only from the environment-specific operations repository.

Security

Do not open public issues for vulnerabilities. Report suspected security issues privately to security@writer.com.

License

Licensed under the MIT License. See LICENSE.