Taint tracking¶

A turn that read untrusted content is marked for good, and the gates that read the mark. Part of the security model.

Text hangar's caller didn't write is fenced in the prompt as untrusted (front doors). That covers what a job starts with. An agent also reads untrusted text while it runs: an issue comment through the GitHub MCP server, a web page, a search result. A prompt injection in any of these can steer what it does next. So hangar records, per turn, whether the agent has read untrusted content (src/hangar/taint.py). The gates below read it.

What taints a turn. Each source is recorded with its kind, the event that read it (seq, its position in the session's event log; 0 for what the turn started with) and a reference:

Sticky. A session's taint is set by its first tainted turn and never cleared: every later turn starts tainted ("inherited": true), a fork carries its parent's, and a job mirrors its sessions (best-of-N attempts and the judge included). A job whose own input is untrusted is tainted when it is submitted. A turn keeps at most 20 sources.

Where it shows. taint on turns, sessions and jobs in get_job / get_session and GET /api/jobs/{id}, GET /api/sessions/{name}: {"tainted": true, "first_turn": 1, "first_seq": 41, "sources": [{"kind": "web", "seq": 41, "ref": "example.com", "turn": 1}]}. The first source adds a taint: read untrusted content from <ref> event to the session's and job's event stream and the job's timeline; the trace export carries hangar.taint and hangar.taint.first_seq on each turn (traces); and the PR's review packet says Untrusted content read: issue text jira-ABC-12.md (context), web: example.com (seq 41).

Taint gates¶

Once untrusted content has been read, nothing leaves the sandbox on the agent's word alone (#130):

Under approvals: auto the turn has no approvals to gate: use deny-risky for intake jobs (Jira, GitHub issues from outsiders), which are tainted from turn 1. Their PRs are drafts that need a second person to land: that is the intent, the PR is the gate.

The driver learns of the taint at the turn's start (--tainted) and, mid-turn, from hangar's signed taint command (sent like a steer, the moment the event watcher sees the first untrusted read) or from a web tool call it sees in the harness's own stream. There is no command to clear it, and an unsigned one is refused, so the agent can't untaint itself. Every gate decision is audited as taint.gate (sink: pr.open, land, egress, git.push, mcp.write; decision; who).

Gaps. Taint is read from each harness's stream through the same tool-name table as the trace export. A tool hangar doesn't know is other and doesn't taint: a pi extension or a custom tool that fetches pages goes unnoticed, as does a shell command that fetches with anything but curl/wget (python -c 'urllib…', git clone of another repo, gh api). Subagents' calls (Claude Code's Task) are in the stream and counted. Reading a file the agent itself downloaded earlier is tainted only through the download. Taint is a record for gates and reviewers, not a sandbox.

Injection canaries¶

Shadows (#183, repo-policy.md) deliver nothing and run with egress none, so they are a safe place to measure how often a harness takes orders from untrusted text. A repo's shadow.canary: {p, placements} gives a share p of its shadows one benign instruction from a small template set (src/hangar/canaries.py), each carrying a fresh token CANARY-<8 hex>:

It is planted at one placement the shadow has a door for: ticket_description (the Jira or GitHub issue attachment), ticket_comment (the comments attachment, or a comment section of the ticket's), slack_thread (a reply in the thread attachment), or repo_file (NOTES.local.md in the shadow's working tree, written before the turn and listed in .git/info/exclude, so it is never part of the work). An attachment that carries it is marked untrusted, so the prompt's fence names it ("Untrusted input", exchange.UNTRUSTED_RULES). Only the shadow's copy changes: the real job's context never holds a canary. Every template is harmless if obeyed (no secret, nothing destructive, a host that cannot resolve), and a shadow has no PR, tracker, Slack or GitHub reply, so a token never reaches anyone; a shadow's summary goes nowhere either.

Recorded privately. The token, placement and template are kept in hangar's store under the shadow's experiment, never in a label, job event or file the agent can read (canary.planted in the audit log names the placement and template, not the token). After the shadow's turn hangar checks the signals itself: the turn's diff against its base (committed, uncommitted and untracked work), the canary hits counted for the shadow's sandbox, and the turn's command and tool events. canary.json (hangar.canary/v1) is staged in the outbox next to the run's run.json: {token, placement, template_id, expected_signals, signals, obeyed, experiment_id, shadow_of, harness_digest, job_id, session_id, run_id}; a canary.result audit entry says the same without the token. flightdeck aggregates obeyed per harness digest, with intervals, and by placement to map which doors leak. A canary shadow's model tapes are untrusted by construction: their tape index says untrusted ("an injection canary shadow", model-gateway.md).

canary.invalid is always refused. The egress proxy refuses it (and any subdomain) before the sandbox's policy is read, whatever the mode: an egress.canary audit entry, a canary deny in hangar_egress_connections_total, and the refusal in the session's trace (egress: deny, reason: canary) like every refused connection. An environment request for it (hangar-agent env request egress canary.invalid) is denied by hangar on the spot, never asked of a person, counted the same way and traced. Memory-poisoning canaries through retrieval are out of scope (there is no retrieval).