mirror of
https://github.com/trailofbits/skills
synced 2026-06-21 14:12:00 +00:00
Jonathan Hefner
debfb29c8e
* Fix `allowed-tools` to use spec-compliant space-delimited strings Per the agentskills.io specification, `allowed-tools` must be a single string of space-delimited patterns, not a YAML list. Converted all 23 SKILL.md files from the `- Item` list format to the correct `"Item1 Item2"` string format. Also updated the frontmatter examples in CLAUDE.md and the workflow-skill-design skill template to match. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix remaining allowed-tools format in firebase-apk-scanner and workflow-skill-design docs - Convert firebase-apk-scanner from comma-separated to space-delimited - Update anti-patterns.md and tool-assignment-guide.md examples from YAML lists to space-delimited strings - Remove unnecessary quotes from SKILL.md template placeholder Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Cover commands, new SKILL.md files, and fix template placeholder Extends the previous spec-compliance fixes: * Convert command frontmatter (commands/*.md) — per Claude Code docs, command files use the same frontmatter as skills, so the same space-delimited rule applies. * Convert three SKILL.md files added since the original PR: mutation-testing, trailmark-structural, trailmark-summary. * Fix the placeholder in the workflow-skill-design template. The previous "[minimum tools needed, space-delimited]" was YAML flow-sequence syntax, which parses as a list — the opposite of what the placeholder claims. Replaced with a concrete-looking space-delimited example plus a comment. Zeroize-audit agent files still use `allowed-tools:` in YAML list form. They are intentionally excluded: per the project's own docs (workflow-skill-design references), agents declare tools with `tools:` (not `allowed-tools:`). Fixing those requires changing the field name as well as the format and is out of scope for this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * zeroize-audit agents: switch allowed-tools to tools Subagents declare their tool allowlist via `tools:` (comma-separated), not `allowed-tools:` — see Claude Code's subagent docs and this repo's own designing-workflow-skills/SKILL.md:47: > Skills use `allowed-tools:` in frontmatter. Agents use `tools:` > in frontmatter. Before this change, the zeroize-audit agents declared their tool list under `allowed-tools:`, which Claude Code does not read for subagents. The field was effectively a no-op; the spawned agents had no tool restriction enforced. Renames the field on all 11 agents to `tools:` and reformats the YAML list as comma-separated to match the documented format and existing agents elsewhere in the repo (e.g. function-analyzer.md, spec-compliance-checker.md). Tool sets are unchanged. Behavior change: tools now actually constrain what each spawned agent can call. The lists are the ones the original author intended. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill-improver: convert command allowed-tools to space-delimited The two command files in plugins/skill-improver/commands/ still used the JSON flow-array format (`allowed-tools: ["..."]`), which the rest of this PR converted everywhere else. Convert them to the spec-compliant space-delimited string form for consistency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Dan Guido <dan@trailofbits.com>
fp-check
A Claude Code plugin that enforces systematic false positive verification when verifying suspected security bugs.
Overview
When Claude is asked to verify suspected security bugs, this plugin activates a rigorous per-bug verification process. Bugs are routed through one of two paths:
- Standard verification — a linear single-pass checklist for straightforward bugs (clear claim, single component, well-understood bug class). No task creation overhead.
- Deep verification — full task-based orchestration with parallel sub-phases for complex bugs (cross-component, race conditions, ambiguous claims, logic bugs without spec).
Both paths end with six mandatory gate reviews. Each bug receives a TRUE POSITIVE or FALSE POSITIVE verdict with documented evidence.
Installation
/plugin install fp-check
Components
Skills
| Skill | Description |
|---|---|
| fp-check | Systematic false positive verification for security bug analysis |
Agents
| Agent | Phases | Description |
|---|---|---|
| data-flow-analyzer | 1.1–1.4 | Traces data flow from source to sink, maps trust boundaries, checks API contracts and environment protections |
| exploitability-verifier | 2.1–2.4 | Proves attacker control, creates mathematical bounds proofs, assesses race condition feasibility |
| poc-builder | 4.1–4.5 | Creates pseudocode, executable, unit test, and negative PoCs |
Hooks
| Hook | Event | Purpose |
|---|---|---|
| Verification completeness | Stop | Blocks the agent from stopping until all bugs have completed all 5 phases, gate reviews, and verdicts |
| Agent output completeness | SubagentStop | Blocks agents from stopping until they produce complete structured output for their assigned phases |
Reference Files
| File | Purpose |
|---|---|
| standard-verification.md | Linear single-pass checklist for straightforward bugs |
| deep-verification.md | Full task-based orchestration with parallel sub-phases for complex bugs |
| gate-reviews.md | Six mandatory gates and verdict format |
| false-positive-patterns.md | 13-item checklist of common false positive patterns and red flags |
| evidence-templates.md | Documentation templates for verification evidence |
| bug-class-verification.md | Bug-class-specific verification requirements (memory corruption, logic bugs, race conditions, etc.) |
Triggers
The skill activates when the user asks to verify a suspected bug:
- "Is this bug real?" / "Is this a true positive?"
- "Is this a false positive?" / "Verify this finding"
- "Check if this vulnerability is exploitable"
The skill does not activate for bug hunting ("find bugs", "security analysis", "audit code").
Methodology
Each bug is routed based on complexity:
Standard Path
For bugs with a clear claim, single component, and well-understood bug class:
- Data flow — trace source to sink, check API contracts and protections
- Exploitability — prove attacker control, bounds proofs, race feasibility
- Impact — real security impact vs operational robustness
- PoC sketch — pseudocode PoC required
- Devil's advocate spot-check — 5+2 targeted questions
- Gate review — six mandatory gates
Standard verification escalates to deep at two checkpoints if complexity warrants it.
Deep Path
For bugs with ambiguous claims, cross-component paths, concurrency, or logic bugs:
- Claim analysis — restate the vulnerability claim precisely, classify the bug class
- Context extraction — execution context, caller analysis, architectural and historical context
- Phase 1: Data flow analysis — trust boundary mapping, API contracts, environment protections, cross-references
- Phase 2: Exploitability verification — attacker control, mathematical bounds proofs, race condition proof, adversarial analysis
- Phase 3: Impact assessment — real security impact vs operational robustness, primary controls vs defense-in-depth
- Phase 4: PoC creation — pseudocode with data flow diagrams, executable PoC, unit test PoC, negative PoC
- Phase 5: Devil's advocate review — 13-question challenge with LLM hallucination self-check
- Gate reviews — six mandatory gates before any verdict