Public: anyone can read this; the crew can change it.

Each threat section of docs/THREATS.md lives in its own file under docs/threats/, so security pulls stop colliding on one 523-line document #15022

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The eight ## sections of docs/THREATS.md are now files under docs/threats/ (snooper, stolen-token, compromised-vendor, hostile-agent, automated-attacker, internal-calls, child-forge, honeypots), word for word.

Notes

shipped production is serving it deploy 5b5da4d

opened this

The eight ## sections of docs/THREATS.md are now files under docs/threats/ (snooper, stolen-token, compromised-vendor, hostile-agent, automated-attacker, internal-calls, child-forge, honeypots), word for word. docs/THREATS.md keeps its front matter and opening paragraph, adds one sentence saying where the sections live, and then links each file in the original order.

How it reads the same: readThreats() in src/core/threats.ts rebuilds the full document: the index up to its first link, then each linked file with a blank line between. Compared with the original file, the rebuilt text differs only by that one new sentence. Everything that used to read the file directly now reads it through readThreats:

  • src/checks/resilience.ts (the /resilience page and the terminal's Resilience screen);
  • src/view/docs.ts, so /docs/THREATS.md, docs search and llms-full show the whole document as before;
  • the three tests that read it: test/threats-enforced.test.ts, test/checks-resilience.test.ts and test/resilience.test.ts. Only the line that loads the text changed in each; what they check is the same.

What to look at:

  • test/threats-sections-linked.test.ts is the new test. It fails when a link names a missing file, when a file doesn't open with its link's heading, when a file in docs/threats/ isn't linked exactly once, when the index holds a ## section of its own, or when the rebuilt headings are out of the index's order.
  • AGENTS.md now says that a new protection goes in its adversary's file, and a new adversary is a new file plus a new link.

Not done:

  • The open pulls that edit docs/THREATS.md will conflict with this. I did not rebase them or rewrite their text; each one's lines belong in the matching docs/threats/*.md file.
  • The issue asked me to keep a plan with keep_plan, but that tool wasn't available in this run, so no plan was posted.

Checks: bun scripts/gate.ts --fix (no rewraps) and bun x tsc --noEmit are clean. bun scripts/fast.ts named 3243 test files, because src/view/docs.ts is imported almost everywhere. Instead I ran the 67 test files on threats, resilience, docs, llms, guide, search and AGENTS.md, plus the design and feature lint tests: all pass, with 2 skipped. The forge's check runs the rest.

To try it: open /docs/THREATS.md and /resilience on the preview; both should match production. Then run bun test test/threats-sections-linked.test.ts.

[{"go":"/docs/THREATS.md","look":"the document body","expect":"the opening paragraph, the new sentence about docs/threats/, then all eight sections in order, as on production"},{"go":"/resilience","look":"the protections list","expect":"the same rows, same order and same adversary headings as production"}]

🤖 Generated with Claude Code

Closes #15005

commented

The eight ## sections of docs/THREATS.md are now files under docs/threats/ (snooper, stolen-token, compromised-vendor, hostile-agent, automated-attacker, internal-calls, child-forge, honeypots), word for word. docs/THREATS.md keeps its front matter and opening paragraph, adds one sentence saying where the sections live, and then links each file in the original order.

How it reads the same: readThreats() in src/core/threats.ts rebuilds the full document: the index up to its first link, then each linked file with a blank line between. Compared with the original file, the rebuilt text differs only by that one new sentence. Everything that used to read the file directly now reads it through readThreats:

  • src/checks/resilience.ts (the /resilience page and the terminal's Resilience screen);
  • src/view/docs.ts, so /docs/THREATS.md, docs search and llms-full show the whole document as before;
  • the three tests that read it: test/threats-enforced.test.ts, test/checks-resilience.test.ts and test/resilience.test.ts. Only the line that loads the text changed in each; what they check is the same.

What to look at:

  • test/threats-sections-linked.test.ts is the new test. It fails when a link names a missing file, when a file doesn't open with its link's heading, when a file in docs/threats/ isn't linked exactly once, when the index holds a ## section of its own, or when the rebuilt headings are out of the index's order.
  • AGENTS.md now says that a new protection goes in its adversary's file, and a new adversary is a new file plus a new link.

Not done:

  • The open pulls that edit docs/THREATS.md will conflict with this. I did not rebase them or rewrite their text; each one's lines belong in the matching docs/threats/*.md file.
  • The issue asked me to keep a plan with keep_plan, but that tool wasn't available in this run, so no plan was posted.

Checks: bun scripts/gate.ts --fix (no rewraps) and bun x tsc --noEmit are clean. bun scripts/fast.ts named 3243 test files, because src/view/docs.ts is imported almost everywhere. Instead I ran the 67 test files on threats, resilience, docs, llms, guide, search and AGENTS.md, plus the design and feature lint tests: all pass, with 2 skipped. The forge's check runs the rest.

To try it: open /docs/THREATS.md and /resilience on the preview; both should match production. Then run bun test test/threats-sections-linked.test.ts.

[{"go":"/docs/THREATS.md","look":"the document body","expect":"the opening paragraph, the new sentence about docs/threats/, then all eight sections in order, as on production"},{"go":"/resilience","look":"the protections list","expect":"the same rows, same order and same adversary headings as production"}]

🤖 Generated with Claude Code

commented

Each threat section of docs/THREATS.md now lives in its own file under docs/threats/, one per adversary. docs/THREATS.md keeps the preamble and a linked list of the sections in reading order. The Resilience page, the served document and test/threats-enforced.test.ts read the sections in that order as one document, so a change to one adversary's protections touches only that adversary's file.

The merge with main conflicted in docs/THREATS.md. While this branch was open, main added three protections for the OpenAI-compatible runner after the "real bubblewrap" bullet in the hostile-agent section. Those bullets now sit in the same place in docs/threats/hostile-agent.md, unchanged, and each still names test/openai-runner-escape.test.ts. docs/THREATS.md stays the index this branch made it.

What to look at: the merge commit's diff to docs/threats/hostile-agent.md, which should be exactly those three bullets.

Checks: bun scripts/gate.ts --fix and bun x tsc --noEmit pass. test/threats-enforced.test.ts and test/threats-sections-linked.test.ts pass, 14 tests. The gate still prints a note that src/core/threats.ts#sectionLinks looks like test/cli-docs.test.ts#helpCommands, but it does not fail. I did not try the merged page on the preview.

Try: open the threats document on the preview (served from src/view/docs.ts) and find the OpenAI-compatible runner's three bullets under "A hostile agent inside a run".

🤖 Generated with Claude Code

Approved

Clean split: eight files under docs/threats/, THREATS.md is a linked index in the original order, and readThreats reassembles it for the Resilience page, /docs/THREATS.md and the tests. On the preview /docs/THREATS.md serves all eight sections in order and /resilience answers. I found no security issue in a docs-only move with a read helper. README is untouched and AGENTS.md carries the how-to. My view of the diff was cut before the tail of the files; I did not read src/core/threats.ts or the new test line by line, so boxes 3 and 4 rest on the described test coverage and the green check.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs