STPA Control Analysis: monolith

logic @ ac81a1554 · security @ 34d4f1816

Auto-generated STPA safety model: unsafe states this system can reach and control actions that get it there. Single or multiple lenses: logic (mission failure), security (deliberate attack), governance (data safety).

STPA (System-Theoretic Process Analysis, Leveson) treats the system as controllers issuing control actions to controlled processes, with feedback flowing back. Instead of "what component fails," it asks "what control action, given or withheld at the wrong time, drives the system into an unsafe state?" Unsafe means a violation of this system's reason to exist. Multiple lenses (logic, security, governance) analyze the same control structure for different safety questions: mission failure, deliberate attack, data-processing violations. A finding appearing in multiple lenses is expected and correct.

Read top-down: Losses are outcomes we must prevent; Hazards are states leading to loss; diagrams show control structure (solid = control action, dashed = feedback); Unsafe Control Actions table is the core; Unsafe Feedback covers data channels (absent, stale, corrupted, spoofed). Every claim cites path:line; unbuilt elements are marked. Semantic stable IDs mean regenerating changes only findings that changed.

Control structure

Logical view

flowchart TD
  subgraph actor["actor"]
    console-caller["Private /agents console (human operator)"]
    discord-user["Discord user"]
    mcp-caller["MCP-authenticated caller (agent)"]
  end
  subgraph boundary["boundary"]
    embervm-sandbox["EmberVM per-language sandbox task guests (see projects/embervm/STPA.md)"]
    embervm-shotter["EmberVM shotter task guest (see projects/embervm/STPA.md)"]
  end
  subgraph control_plane["control_plane"]
    agent-runner["Agent session runner (claim-lease over all replicas)"]
    bot["Discord bot (leader singleton)"]
    kg-drainer["DBOS-scheduled routine drainer (qwen-drain, kg-drain)"]
    kg-feed["Leader-owned Ember session to knowledge raw exporter"]
    leader-elector["Leader elector"]
    outbox["Discord outbox drain"]
    scheduler-api["Scheduler read/trigger API"]
  end
  subgraph enforcement["enforcement"]
    acl["Feature ACL (grant cache)"]
    principal-mw["Principal middleware (bearer auth, cached JWKS)"]
    shotter-validate["Shotter URL/host allowlist (2nd layer)"]
  end
  subgraph publish["publish"]
    docs-manifest-gen["Docs/posts manifest generator (CI Format stage)"]
  end
  subgraph serving["serving"]
    public-api["Public backend (read + bounded writes)"]
    public-frontend["Public SSR frontend"]
    sandbox-tool["run_code MCP tool (per-language sandbox broker)"]
    shotter-tool["Shotter screenshot MCP tool"]
  end
  subgraph store["store"]
    postgres["Postgres (per-domain schemas)"]
  end
  bot -- "acl.check" --> acl
  leader-elector -- "agent.reclaim" --> agent-runner
  bot -- "agent.submit" --> agent-runner
  console-caller -- "console.submit" --> agent-runner
  docs-manifest-gen -- "docs.publish" --> public-frontend
  kg-drainer -- "kg-drainer.dispatch" --> agent-runner
  kg-feed -- "kg-feed.export" --> pg-primary
  leader-elector -- "leader.acquire" --> postgres
  bot -- "lock.reclaim" --> postgres
  mcp-caller -- "mcp.agent-session" --> agent-runner
  mcp-caller -- "mcp.authorize" --> principal-mw
  mcp-caller -- "mcp.chat-pardon" --> bot
  mcp-caller -- "mcp.report-knowledge" --> pg-primary
  outbox -- "outbox.post" --> bot
  public-api -- "public.health" --> postgres
  console-caller -- "raws.create" --> pg-primary
  mcp-caller -- "sandbox.run" --> sandbox-tool
  scheduler-api -- "scheduler.trigger" --> postgres
  mcp-caller -- "shotter.capture" --> shotter-tool
  shotter-tool -- "shotter.dispatch" --> embervm-shotter
  shotter-tool -- "shotter.validate" --> shotter-validate
  leader-elector -- "singletons.start" --> bot
  embervm-sandbox -. "stdout/stderr/exit_code/files for the run (Idempotency-Key from language+code only)" .-> sandbox-tool
  embervm-shotter -. "captured PNG + render metadata (random per-call Idempotency-Key)" .-> shotter-tool
  postgres -. "feature grant rows (30s cached)" .-> acl
  postgres -. "claimed_by_replica + claimed_at lease row" .-> agent-runner
  postgres -. "lease heartbeat freshness" .-> leader-elector
  postgres -. "disputed flag + verification_state on search/get_note results" .-> mcp-caller
  postgres -. "observability topology/stats snapshots" .-> public-api
  public-frontend -. "SSR/API proxy" .-> public-api
  shotter-tool -. "stored URL + stored flag (_meta) for the captured PNG" .-> mcp-caller

Physical view

flowchart TD
  subgraph compute["compute"]
    frontend-ssr["SvelteKit SSR sidecar"]
    private-binary["monolith (full secrets)"]
    public-binary["monolith-public backend (constrained DB + FaaS access)"]
  end
  subgraph control_plane["control_plane"]
    embervm["EmberVM / FaaS admission"]
  end
  subgraph data["data"]
    migrations["Grant migrations"]
    pg-primary["CNPG primary (-rw)"]
    pg-replica["CNPG hot standby (-ro)"]
    shotter-store["SeaweedFS shotter bucket (content-addressed PNGs)"]
  end
  subgraph ingress["ingress"]
    cf-ingress["Cloudflare ingress (Envoy Gateway)"]
  end
  subgraph secrets["secrets"]
    k8s-api["Kubernetes API"]
    onepassword["1Password operator"]
  end
  public-binary -- "chatpublic.write" --> pg-primary
  frontend-ssr -- "frontend.proxy" --> public-binary
  migrations -- "grant.public-reader" --> pg-replica
  private-binary -- "k8s.mutate" --> k8s-api
  cf-ingress -- "route.public" --> frontend-ssr
  onepassword -- "secret.deliver-public" --> public-binary
  private-binary -- "shotter.store" --> shotter-store
  cf-ingress -. "X-Auth-Email identity header (attribution only, allowlisted senders, not cryptographically bound)" .-> agent-runner
  pg-primary -. "streaming replication lag" .-> pg-replica

Control actions

Lens: logic

Scope. A single Postgres-backed personal platform served as two composed binaries: a private read-write binary (full app capabilities, private.jomcgi.dev) and an isolated public binary (jomcgi.dev via the separate monolith-public chart). The public binary is read-only for public datasets with two constrained write/invocation paths, the private binary now also serves an agent-session console, a six-language code sandbox, a screenshot tool, and MCP over native streamable HTTP; safety is governed data access, bounded public capabilities, the secret boundary, and correct claim/lease ownership of queued agent work.

• Built: framework/core.py composition and profiles, separate private/public module registries, Postgres leader-lease singletons (Discord bot, AIS ingest, outbox drain, message-lock sweep), the agent_sessions claim-lease turn engine (atomic per-message claiming across all replicas plus a leader-owned stale-claim sweep) backing both the Discord bot and the private /agents console HTTP API, goosecracker recipe/repo catalog, chat feature ACL with 30s grant cache, public_reader/public_writer roles with schema/view confinement, public/private HTTPRoutes, Turnstile secret isolation, public chat admission/concurrency limits, public FaaS identity gate, observability snapshot rollup, the shotter MCP domain (URL/host validation, EmberVM task dispatch, best-effort SeaweedFS PNG storage with a random per-call Idempotency-Key), the sandbox MCP domain (run_code, six per-language EmberVM task workloads, zero-egress except an optional scratch-Postgres credential), the native /mcp mount on stateless streamable HTTP with PrincipalMiddleware authenticating every message via cached JWKS, and the docs/posts manifest generators that publish an exact allowlist of committed repository documents to the public site. The factory knowledge-graph evidence lanes (#5527, ADR agents/063) add a shared raw-input write boundary (knowledge/ingest_queue.py ingest_raw_with_status) reached by the generic POST /api/knowledge/raws endpoint, three MCP tools (report_knowledge, dispute_fact, report_distress), and a leader-owned Ember-session exporter (agent_sessions/kg_feed.py), a daily-capped DBOS drainer (swarm/drainer.py) that runs Luna extraction in an EmberVM guest and writes atoms with server-side provenance (knowledge/extraction.py, knowledge/atoms.py), and a live disputed/verification_state signal on search results (knowledge/store.py).
• Designed-only: Strict per-domain database isolation and the ADR 010 cross-domain contract remain architectural goals; the Module/build_app framework itself is built. ADR 059 (Draft) proposes removing Context Forge entirely as the MCP entry point and serving /mcp directly behind Cloudflare; only the first, independently-sequenced slice (the stateless-HTTP transport switch) has landed, Context Forge is still deployed and still in the request path. The Context Forge tool-visibility reconcile pass (#4569) that would scope which principal may call which tool is designed, not built, so per-tool authorization beyond bearer-token authentication does not exist for any MCP tool yet.</details>

Losses

Hazards

Unsafe control actions

Unsafe feedback

Data channels (absent, stale, corrupted, spoofed) whose failure drives a controller into a hazard.

• Luna claiming verification_state=verified with no evidence array: apply_extraction force-downgrades to unverified server-side whenever assertion.evidence is empty, regardless of what the model claimed (projects/monolith/knowledge/extraction.py:364)
• a rendered public doc linking out to a non-public repository document: buildPathIndex only maps allowlisted manifest paths to slugs; a link to anything else is stripped to plain text rather than left live (projects/monolith/frontend/src/lib/server/docs.js:9)
• a repeat POST of the same shotter.capture request colliding across two unrelated captures: Fixed: the Idempotency-Key is now a random per-call nonce, so it only buys transport-retry safety within one call and cannot collapse two distinct captures of the same URL onto one cached result (projects/monolith/shotter/client.py:82)
• a repo doc outside the seven PUBLIC_PROJECTS directories reaching the docs manifest: The generator indexes only exact path matches built from a fixed PUBLIC_PROJECTS x DOC_KINDS product, not a directory walk, so nothing else in the repo, including ADRs and nested READMEs, is reachable through this generator regardless of what git ls-files returns (projects/monolith/knowledge/tools/gen_docs_manifest.py:49)
• a single missed leadership heartbeat: Bounded by 2s renew inside the 5s TTL, and any error resolves to follower fail-safe (projects/monolith/core/leadership.py:29)
• an ungated docs/posts draft (no public key, or public: false) reaching the public site: Fails closed: _declared_public_value returns None for an ungated file and it is skipped, and a strict literal-match check on the public key raises rather than guessing (projects/monolith/knowledge/tools/gen_posts_manifest.py:64)
• apply_extraction re-running on a raw that already extracted successfully: Guarded by an early replayed-check keyed on (raw_fk, gardener_version, non-failed provenance) that returns before writing any atom (projects/monolith/knowledge/extraction.py:326)
• outbox at-least-once duplicate on crash between post and mark: Bounded and mostly idempotent: reactions/edits resolve missing targets, a duplicate notify is a rare nuisance (projects/monolith/chat/outbox.py:135)
• public_reader denied on a private schema: Not a hazard but the enforced control: DB permission denies the read; asserted by projects/monolith/public_reader_grants_test.py:44
• report_distress's Discord notification failing without the reporting agent knowing: notify() failure is caught and reflected honestly in the returned status (recorded vs notified), and the underlying enqueue reuses the durable at-least-once outbox row already covered by the existing outbox non_uca (projects/monolith/knowledge/mcp.py:446)
• scheduler.trigger submits the wrong execution path: Bounded by run-now looking up the CronWorkflow whose replaces annotation names the requested job and creating a one-off Workflow from its workflowSpec; ARGO_JOBS only suppresses legacy registry metadata, including for suspended entries (projects/monolith/scheduler/service.py:53)
• shotter.capture exceeding its render budget: Bounded by the nested timeout chain (Context Forge 60s > client read 55s > workload 50s > guest handler 45s > CDP navigate), converted into a ToolTimeout rather than an indefinite hold (projects/monolith/shotter/client.py:96)
• the kg daily-cap deferral calling both finish_drainer_job and defer_drainer_job for the same one-shot job: complete_job's NULL next_run_at write for a one-shot row (interval_secs IS NULL) is immediately overwritten by defer_job's later write in the same call sequence, so the job still re-arms at +3600s despite the double write (projects/monolith/factory/orchestration/drainer.py:407)
• two replicas racing to claim the same pending message: claim_pending_message_for_session_sync is a single atomic UPDATE ... WHERE claimed_by_replica IS NULL, so only one of two concurrent claimants can succeed (projects/monolith/factory/execution/store.py:634)</details>

Open questions

• #5568's claude-session/codex-session producers are not yet shipped, but EXTRACTABLE_SOURCES already accepts those source labels via the generic POST /api/knowledge/raws endpoint today; will that producer route through the same unredacted shared boundary, or call agent_sessions.redact.redact_text itself the way kg_feed.py does?
• ADR 059 is still Draft: does the full Context Forge removal change anything about the ingestion allowlist in cilium-ingress-policy.yaml (the mcp entry), or does the direct-mount path simply add a second ingress source alongside it?
• Does any workload other than shotter and the six sandbox languages share the same EmberVM Idempotency-Key-from-request-parameters pattern, and if so does its key cover every parameter that affects the result?
• In production, can a chat message handler (LLM summarizer) exceed the 30s message-lock TTL under load and trip lock.reclaim.wrong-timing, or is processing reliably shorter?
• Is the X-Auth-Email header ever going to gate an authorization decision, or does #4940's delegation model deliberately avoid keying on inbound headers at all? If the latter, header-authz-drift can be downgraded once that is documented somewhere durable.
• Is the shotter SeaweedFS bucket's read path gated the way artifact's is (proxied through a monolith-mediated read), or does anything with in-cluster network reach get an anonymous GET against the S3 endpoint once it has or guesses a content hash?
• Is there an intended path to make a KG-lane dead letter recoverable (re-create the routine_jobs row on replay, or align the ExtractionOutputInvalid retry policy with MAX_GARDENER_RETRIES), or is a stuck-open dispute meant to be resolved by hand in Postgres today?
• Now that PrincipalMiddleware authenticates every MCP message, when does #4569's tool-visibility reconcile pass land, and will it gate shotter.capture, sandbox.run, and k8s_sync_argocd_app by Principal scope, or only by the coarser tool-granular ACL ADR 059 compares Context Forge against?
• Should an enqueue_extraction failure inside ingest_raw_with_status roll back the whole raw write instead of being swallowed, now that no sweep exists anywhere to repair a missed enqueue?
• The framework is now built, but strict per-domain schema isolation and the cross-domain contract are still conventions. Re-run this analysis when those controls become enforceable rather than merely compositional.
• The private chart enables HPA from 1 to 3 replicas; verify claim-lease behavior under real scale-out and termination, especially whether a terminating pod's in-flight claims are released promptly enough for the 30s lease to matter in practice.
• The public backend has a deliberate primary write path and public FaaS invocation path. Confirm production Cilium/EmberVM policy matches the chart claims: public_writer must remain limited to chat_public, and the public service account must remain identity-only with no Kubernetes RBAC.
• When the scratch-Postgres feature is re-enabled (embervm side), should run_code's docstring be corrected to stop claiming zero network for python, or should the DSN injection move behind a separate, explicitly-network-capable tool so the isolation claim stays true for the tool most callers reach for?

Lens: security

Scope. Adversarial abuse of the monolith's control structure: an attacker who deliberately forges or withholds identity, reaches a tool the entitlement model does not yet gate, or crosses a tier boundary in the control structure.

• Built: Separate public and private binaries (ADR security/004), public_reader role with visibility filters on the replica, Turnstile-gated chat with three nested budgets, PrincipalMiddleware bearer-token verification on every MCP message, Discord trust ledger with per-guild per-user scoring and heuristics-fed instant enforcement, Cloudflare Access lane projecting verified email to agents console, Kubernetes RBAC scoping cluster mutation to the private pod.
• Designed-only: Per-tool authorization on the monolith's MCP surface (ADR 059 to route through delegation-consuming broker, #4569 tool-visibility reconcile pass), default-deny egress CiliumNetworkPolicy for the private pod, per-domain database isolation and cross-domain contract.</details>

Losses

Hazards

Unsafe control actions

Unsafe feedback

Data channels (absent, stale, corrupted, spoofed) whose failure drives a controller into a hazard.

• Authentik and Kubernetes control-plane compromise: Assumed not to hold
• Cluster layers below the monolith: Ingress tunnel, CNI policy, admission control, secret operator are owned by docs/security.md
• Cluster-wide capacity exhaustion outside modeled admission and budget gates: Not analyzed here
• Discord platform account compromise: Outside the trust ledger's design
• EmberVM guest and hypervisor isolation: Covered in projects/embervm/STPA.md (logic and security lenses); this document covers only monolith-side broker
• Supply chain of the monolith's own image build: Not analyzed here</details>

Open questions

• Should run_code's docstring be corrected to stop claiming zero network for Python, or should the scratch-Postgres DSN injection move behind a separate explicitly-network-capable tool?
• When #4569's tool-visibility reconcile pass lands, will it gate shotter.capture, sandbox.run, k8s_sync_argocd_app, and agent-session tools by Principal scope, or only by coarser tool-granular ACL?
• When will the default-deny egress CiliumNetworkPolicy (#5277) land for the private pod's open-ended cluster and internet reach?
• Will the public tier's cluster-reach policy (#5276) be scoped to only the four intended destinations (Postgres, vLLM, embeddings, SeaweedFS)?