autonomous-ai / trailofbits-harness

A Trail of Bits audit in Harness

Trail of Bits' skills are the method; this skill only says how their work lands in the report pane
and how the plugin features they assume are provided here. It changes none of their instructions.

findings.json

security-audit/findings.json is the one file you edit. "$TOB_REPORT" checks it, rebuilds the
pane and the Markdown report from it, and prints every entry it had to leave out and why — fix those
before moving on.

{
  "spec": 1,
  "target": { "name": "shop-api", "path": ".", "commit": "3f2c9a1…", "scope": ["src/", "api/"] },
  "phase": "review",
  "final": false,
  "summary": "Markdown: what was audited, how, and the headline risks.",
  "findings": [
    {
      "id": "F-1",
      "title": "SQL query built from request input",
      "severity": "high",
      "status": "unverified",
      "category": "injection",
      "source": "static-analysis/semgrep",
      "location": [{ "file": "src/db.py", "line": 42 }],
      "description": "Markdown: what is wrong.",
      "evidence": "Markdown: the data flow, the rule that fired, the fp-check verdict and its reasons.",
      "recommendation": "Markdown: how to fix it."
    }
  ]
}

• phase: scope → context → scan → review → verify → report. The header's strip is this.
• severity: high, medium, low, informational, undetermined — Trail of Bits' own scale.

• status: unverified when found, then confirmed or false-positive after fp-check. False
  positives stay in the file (the report lists them as dismissed, with their evidence).

• id: F-1, F-2, … in the order found; never reuse one. Paths are relative to the target.

• The Markdown fields render paragraphs, - lists, code, fenced code, bold and italics — nothing else.
  Everything is escaped, so quoting hostile strings from the code is safe.

• The report is ready (ready in the header) only when final is true and nothing is unverified.

Which skill serves which phase

Turn each skill's output — SARIF, ledgers, reports — into findings.json entries, citing it in
source.

Plugin features, provided here

These skills were written as Claude Code plugins. Harness links their skills into every agent, so
the plugin machinery they mention is provided like this:

• Plugin root. Where a skill uses ${CLAUDE_PLUGIN_ROOT}, ${CODEX_PLUGIN_ROOT} or
  <plugin_root>, it is $TOB_SKILLS/plugins/<plugin> for the plugin the skill belongs to. Set it
  on the command that needs it — CLAUDE_PLUGIN_ROOT="$TOB_SKILLS/plugins/c-review" … — and use
  that path, not a search: a search of . would find copies inside the audited repository.

• Named sub-agents. When a skill dispatches <plugin>:<agent> (fp-check:poc-builder,
  rust-review:rust-review-worker, audit-context-building:function-analyzer), start a sub-agent
  with your own sub-agent tool and give it $TOB_SKILLS/plugins/<plugin>/agents/<agent>.md as its
  instructions, plus the task the skill describes. Hold it to the tools that file's front matter
  lists. Where the skill runs several in parallel, run them in parallel.

• Plugin commands. A /<plugin>:<command> that a skill mentions is a Markdown file,
  $TOB_SKILLS/plugins/<plugin>/commands/<command>.md (/differential-review:diff-review): read
  it and follow it, with the arguments the person gave.

• Workflow scripts. Where a skill calls Claude Code's Workflow tool with a
  script under <plugin_root>/workflows/, or a command such as /audit-context-building:audit-context
  that is backed by one, call Workflow with the absolute scriptPath
  ($TOB_SKILLS/plugins/<plugin>/workflows/<name>.js) and the arguments the skill documents. An
  agent without a Workflow tool follows the skill's single-unit mode over each unit in scope and
  says so in the report's summary.

• fp-check's gates. Its plugin hooks check, before a verification ends, that every phase and
  gate was done. Here nothing runs them for you: before you set a finding confirmed or
  false-positive, read the two prompts in $TOB_SKILLS/plugins/fp-check/hooks/hooks.json and
  check your own work against them; a gap keeps the finding unverified.

Tools

The Semgrep, pip-audit, uv and Python the skills expect are in $TOB_BIN; put it first on each
command's PATH: PATH="$TOB_BIN:$PATH" semgrep --metrics=off …. CodeQL and ripgrep are optional
here; when they are missing, the skills' own fallbacks apply (toolchain/doctor.sh in the package
says which are present).