heimdall-agent 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -26
- package/README.pt-BR.md +429 -0
- package/agents/cloud-engineer.md +77 -0
- package/agents/code-sentinel.md +66 -35
- package/agents/database-architect.md +31 -25
- package/agents/frontend-designer.md +30 -28
- package/agents/mobile-designer.md +25 -24
- package/agents/modernizer.md +66 -0
- package/agents/orchestrator.md +94 -93
- package/agents/reviewer.md +100 -71
- package/agents/security-auditor.md +27 -27
- package/agents/tester.md +97 -90
- package/commands/grill-me.md +20 -4
- package/commands/orchestrate.md +16 -0
- package/commands/orchestrator.md +16 -0
- package/commands/plan.md +17 -1
- package/config/agents.json +21 -3
- package/config/mcp.json +72 -0
- package/config/models.json +26 -16
- package/config/profiles.json +2 -4
- package/config/skills.json +210 -100
- package/docs/SKILLS.md +341 -245
- package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
- package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
- package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
- package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
- package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
- package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
- package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
- package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
- package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
- package/docs/runs/skill-audit/customization-report.json +380 -0
- package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
- package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
- package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
- package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
- package/docs/runs/skill-audit/inventory.json +308 -0
- package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
- package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
- package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
- package/docs/runs/skill-audit/probe.ps1 +16 -0
- package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
- package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
- package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
- package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
- package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
- package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
- package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
- package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
- package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
- package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
- package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
- package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
- package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
- package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
- package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
- package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
- package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
- package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
- package/docs/runs/skill-audit/update-manifest.md +88 -0
- package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
- package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
- package/docs/runs/skill-audit/upstream-status.json +563 -0
- package/docs/runs/skill-audit/verification-results.json +252 -0
- package/doctrine/AGENTS.md +39 -77
- package/hooks/git/pre-commit +11 -0
- package/hooks/heimdall-hook.cjs +81 -2
- package/hooks/herdr-agent-state.ps1 +55 -0
- package/hooks/hooks.json +0 -11
- package/lib/catalog-sync.cjs +162 -0
- package/lib/hermes-context.cjs +57 -0
- package/lib/model-context.cjs +123 -0
- package/lib/path-discovery.cjs +94 -0
- package/package.json +7 -3
- package/playbooks/01-interactive-grilling-gate.md +14 -1
- package/playbooks/02-fast-code-deep-verification.md +3 -2
- package/playbooks/03-adversarial-code-review.md +3 -3
- package/playbooks/05-canonical-plan-template.md +32 -18
- package/playbooks/06-model-registry-matrix.md +24 -13
- package/playbooks/07-legacy-code-modernization.md +74 -0
- package/playbooks/08-backlog-and-change-request-flow.md +122 -0
- package/setup.mjs +592 -172
- package/skills/antislop/SKILL.md +76 -56
- package/skills/antislop/VERSION +1 -0
- package/skills/antislop-copywriting/SKILL.md +372 -372
- package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-human/SKILL.md +204 -147
- package/skills/antislop-human/contrast-check.py +168 -165
- package/skills/antislop-human/contrast-mcp.py +6 -3
- package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
- package/skills/antislop-human/references/WCAG.md +127 -0
- package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-ui/SKILL.md +344 -304
- package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
- package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
- package/skills/brainstorming/SKILL.md +274 -265
- package/skills/brainstorming/builder-check-prompt.md +23 -0
- package/skills/brainstorming/scripts/frame-template.html +213 -213
- package/skills/brainstorming/scripts/server.cjs +723 -723
- package/skills/brandkit/SKILL.md +798 -798
- package/skills/brutalist-skill/SKILL.md +93 -92
- package/skills/caveman/README.md +68 -0
- package/skills/caveman/SKILL.md +73 -38
- package/skills/claude-collaborator/SKILL.md +24 -44
- package/skills/clean-code/SKILL.md +152 -0
- package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
- package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
- package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
- package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
- package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
- package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
- package/skills/cloudflare-security-audit/HUNTING.md +251 -251
- package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
- package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
- package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
- package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
- package/skills/cloudflare-security-audit/SKILL.md +192 -192
- package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
- package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
- package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
- package/skills/cloudflare-security-audit/report-schema.json +461 -461
- package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
- package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
- package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
- package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
- package/skills/codex-collaborator/SKILL.md +24 -45
- package/skills/communication-doctrine/SKILL.md +89 -0
- package/skills/diagnosing-superpowers/SKILL.md +1 -1
- package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
- package/skills/diagnosing-superpowers/templates/issue.md +23 -4
- package/skills/executing-plans/SKILL.md +0 -52
- package/skills/executing-plans/scripts/task-done +52 -52
- package/skills/executing-plans/scripts/task-start +28 -28
- package/skills/gemini-collaborator/SKILL.md +24 -56
- package/skills/herdr/SKILL.md +243 -0
- package/skills/image-to-code-skill/SKILL.md +1228 -1228
- package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
- package/skills/imagegen-frontend-web/SKILL.md +987 -987
- package/skills/karpathy-guidelines/SKILL.md +67 -67
- package/skills/mcp-engineering/SKILL.md +74 -0
- package/skills/minimalist-skill/SKILL.md +87 -85
- package/skills/output-skill/SKILL.md +49 -49
- package/skills/ponytail/SKILL.md +36 -52
- package/skills/postgres-best-practices/SKILL.md +30 -52
- package/skills/postgres-best-practices/references/backup-restore.md +372 -0
- package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
- package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
- package/skills/postgres-best-practices/references/hot-standby.md +221 -0
- package/skills/postgres-best-practices/references/indexing.md +318 -0
- package/skills/postgres-best-practices/references/logical-replication.md +610 -0
- package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
- package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
- package/skills/postgres-best-practices/references/query-optimization.md +294 -0
- package/skills/postgres-best-practices/references/query-patterns.md +566 -0
- package/skills/postgres-best-practices/references/schema-design.md +362 -0
- package/skills/postgres-best-practices/references/security-roles.md +489 -0
- package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
- package/skills/progressive-disclosure/SKILL.md +68 -0
- package/skills/pstack-discipline/SKILL.md +40 -0
- package/skills/receiving-code-review/SKILL.md +2 -23
- package/skills/requesting-code-review/SKILL.md +7 -36
- package/skills/soft-skill/SKILL.md +99 -98
- package/skills/stitch-skill/DESIGN.md +121 -121
- package/skills/stitch-skill/SKILL.md +185 -184
- package/skills/strix-security/SKILL.md +54 -53
- package/skills/subagent-driven-development/SKILL.md +28 -260
- package/skills/subagent-driven-development/references/batching.md +11 -0
- package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
- package/skills/subagent-driven-development/references/final-review.md +47 -0
- package/skills/subagent-driven-development/references/fix-loop.md +77 -0
- package/skills/subagent-driven-development/references/handling-reports.md +15 -0
- package/skills/subagent-driven-development/references/preflight.md +26 -0
- package/skills/subagent-driven-development/references/resuming.md +12 -0
- package/skills/subagent-driven-development/scripts/review-package +53 -53
- package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
- package/skills/subagent-driven-development/scripts/task-brief +43 -43
- package/skills/systematic-debugging/SKILL.md +283 -306
- package/skills/taste-skill/SKILL.md +542 -1206
- package/skills/taste-skill/references/app-screens.md +1199 -0
- package/skills/taste-skill/references/colour.md +141 -0
- package/skills/taste-skill/references/copy.md +177 -0
- package/skills/taste-skill/references/critique.md +182 -0
- package/skills/taste-skill/references/imagery.md +791 -0
- package/skills/taste-skill/references/layout.md +292 -0
- package/skills/taste-skill/references/motion.md +980 -0
- package/skills/taste-skill/references/research.md +356 -0
- package/skills/taste-skill/references/scenes.md +174 -0
- package/skills/taste-skill/references/tells.md +115 -0
- package/skills/taste-skill/references/type.md +170 -0
- package/skills/test-driven-development/SKILL.md +330 -337
- package/skills/thermo/SKILL.md +67 -0
- package/skills/threat-modeling/SKILL.md +55 -0
- package/skills/trailofbits-audit-context/SKILL.md +72 -72
- package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
- package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
- package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
- package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
- package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
- package/skills/verification-before-completion/SKILL.md +0 -14
- package/skills/writing-plans/SKILL.md +11 -15
- package/skills/writing-skills/SKILL.md +21 -303
- package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
- package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
- package/skills/writing-skills/references/bulletproofing.md +80 -0
- package/skills/writing-skills/references/discovery.md +201 -0
- package/skills/writing-skills/references/flowcharts.md +37 -0
- package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
- package/skills/writing-skills/references/persuasion-principles.md +187 -0
- package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
- package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
- package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
- package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
- package/skills/gpt-tasteskill/SKILL.md +0 -74
- package/skills/taste-skill-v1/SKILL.md +0 -226
- /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
- /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
- /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
- /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
- /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
- /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
- /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
- /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
|
@@ -1,156 +1,156 @@
|
|
|
1
|
-
# Reconnaissance
|
|
2
|
-
|
|
3
|
-
### Phase 1: Map the source and plan coverage
|
|
4
|
-
|
|
5
|
-
The parent initializes `run-metadata.json`, applies the strict pre-reconnaissance budget gate in `SKILL.md`, then creates agent scratch roots and the shared ledger before hunting. If the gate fails, record the incomplete status in metadata and launch no reconnaissance agent. Reconnaissance reads the target and locally available build/configuration state only. It does not contact deployed endpoints, external identity providers, registries, brokers, cloud APIs, or other shared services.
|
|
6
|
-
|
|
7
|
-
Launch several `research` agents in parallel. They return structured facts to the parent and do not write files.
|
|
8
|
-
|
|
9
|
-
**Agent 1a: Product, stack, and local operation**
|
|
10
|
-
|
|
11
|
-
```text
|
|
12
|
-
Read the target at <target>. Do not use network access. Return:
|
|
13
|
-
1. Product type, users, operators, and ordinary trust-sensitive actions.
|
|
14
|
-
2. Languages, frameworks, build system, runtimes, and locally visible deployment models.
|
|
15
|
-
3. Repository-relative entry points and subsystem boundaries.
|
|
16
|
-
4. Exact build and test commands that could run offline with local dependencies, their expected write locations, and the target-controlled inputs they process. Do not run them during reconnaissance.
|
|
17
|
-
5. Comparable software or protocol visible from local documentation and dependencies. If no useful comparison is source-grounded, say so.
|
|
18
|
-
6. Missing local toolchains or runtime facts that limit bounded execution.
|
|
19
|
-
Return only source facts with repository-relative file:line references.
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
**Agent 1b: Principals, authority, and controls**
|
|
23
|
-
|
|
24
|
-
```text
|
|
25
|
-
Read all source that establishes identity, authorization, isolation, and privilege. Map:
|
|
26
|
-
1. Each lower-trust principal and the actions it has by design.
|
|
27
|
-
2. Authentication or peer identity at each entry surface.
|
|
28
|
-
3. Per-resource authorization and tenant/owner scope.
|
|
29
|
-
4. Process, browser, workload, CI, plugin, model/tool, device, or local-IPC authority.
|
|
30
|
-
5. Privilege changes, confirmation, revocation, recovery, and fallback paths.
|
|
31
|
-
6. Which controls are source-visible and which depend on an unobserved deployment fact.
|
|
32
|
-
Return trust boundaries and control locations with repository-relative file:line references. Do not infer live reachability.
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
**Agent 1c: Entry surfaces, copies, and sinks**
|
|
36
|
-
|
|
37
|
-
```text
|
|
38
|
-
Inventory every source-visible place external or lower-trust input enters:
|
|
39
|
-
- HTTP/browser, RPC/message/protocol, files/archive/document, CLI/env/config, plugins/dependencies/CI, cloud events/IAM selectors, model context/tool arguments, mobile/deep-link/webview, and local IPC.
|
|
40
|
-
For each surface, follow major transformations, stored or derived copies, and security-relevant sinks. Record source-visible limits and parallel paths to the same effect.
|
|
41
|
-
Return repository-relative paths and line numbers. Be complete, but do not execute or send inputs.
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
**Agent 1d: Local execution and deployment visibility**
|
|
45
|
-
|
|
46
|
-
```text
|
|
47
|
-
Read tests, build definitions, manifests, packaging, and maintained environment overlays. Return:
|
|
48
|
-
1. Small offline tests or existing fixtures that could validate trust boundaries with dummy data inside the required OS-enforced sandbox.
|
|
49
|
-
2. Processes that could use an isolated loopback network namespace without external or shared dependencies.
|
|
50
|
-
3. Commands that would fetch dependencies, publish artifacts, contact paid/provider APIs, or affect shared state; mark them prohibited for this run.
|
|
51
|
-
4. Deployed controls and attachments that source cannot establish and therefore require needs_validation if decisive.
|
|
52
|
-
5. The final active source path for each deployment mode only where the repository selects it deterministically.
|
|
53
|
-
6. Whether the local platform can enforce an empty allowlisted environment, no external network, read-only target/toolchain mounts, scratch-only writes, and explicit CPU, memory, process, file-size, disk, and wall-clock limits. Missing controls block target-controlled execution.
|
|
54
|
-
7. Whether trusted parent-side code can promote predeclared scratch files with path-confined no-follow descriptor traversal, nonblocking regular-file checks, no-follow traversal of every destination parent, exclusive regular-file destination creation, and explicit per-file and cumulative size bounds. Missing promotion controls block use of scratch files as evidence.
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Add focused reconnaissance agents for materially distinct deployment modes or subsystems that these four do not map. Do not silently omit them: if the budget gate in `SKILL.md` blocks a focused agent, launch nothing for it, seed the unmapped area as a `deferred` ledger unit with reason `budget_cannot_reserve_critics_and_validation`, and disclose the gap in the report.
|
|
58
|
-
|
|
59
|
-
## Prior-run input
|
|
60
|
-
|
|
61
|
-
Before selecting work, the parent reads every available prior `coverage-ledger.json` and `findings.json` for the same repo:
|
|
62
|
-
|
|
63
|
-
- Compare the source locations, controls, conditions, and source-derived identity for every prior record and unit against the current source.
|
|
64
|
-
- Carry an unchanged prior `confirmed` record into the current candidate set, with the same fingerprint, only when its relevant source, conditions, and qualifying evidence still apply. Link it to a current `planned` unit with `prior_status: "prior_confirmed_same_source"` and put only that root cause on the hunter exclusion list. The Phase 3 verifier that re-verifies the carried record becomes that unit's assignment owner; its source re-check is the unit's first check and moves the unit to `candidate` with the carried fingerprint.
|
|
65
|
-
- Build a current planned `prior_confirmed_changed_source` revalidation unit when any relevant source or condition changed. Do not exclude that root cause from hunting or assume the prior verdict still applies.
|
|
66
|
-
- Build current work units for every prior `needs_validation`, `deferred`, `blocked`, `out_of_scope`, and changed-source unit. These states are priority input, never deduplication or suppression keys.
|
|
67
|
-
- Carry a still-blocked prior `needs_validation` record with the same fingerprint only after current source supports its trace. Link it to a current `planned` unit with `prior_status: "prior_needs_validation"`; the record keeps the unresolved blocker. The Phase 3 verifier that re-checks the carried record becomes that unit's assignment owner; its re-check is the unit's first check and moves the unit to `candidate` with the carried fingerprint. Include the record in final verification.
|
|
68
|
-
- Treat prior rejected records as stale claims unless current evidence changes the failed trace or missing condition. An unchanged rejection suppresses only that exact claim, not review of the coverage unit.
|
|
69
|
-
- Record missing or incompatible ledgers instead of treating them as empty coverage.
|
|
70
|
-
|
|
71
|
-
State paths and source refs used in `run-metadata.json`. Summarize only the coverage consequences in `architecture.md`.
|
|
72
|
-
|
|
73
|
-
## Architecture summary and companion selection
|
|
74
|
-
|
|
75
|
-
The parent synthesizes `<output-dir>/architecture.md`, with a hard cap of about 1,000 words. Include:
|
|
76
|
-
|
|
77
|
-
1. Product, principals, normal authority, and protected resources.
|
|
78
|
-
2. The comparable-software baseline from Agent 1a, when one is source-grounded: what security trade-offs the comparable accepts. Use it to calibrate effort and severity, never to dismiss a demonstrated finding; if the comparable shares a defect pattern that has mattered in practice, that strengthens the finding. Omit this line when no meaningful comparable exists.
|
|
79
|
-
3. Tech stack, source-visible deployment paths, and offline build/test limits.
|
|
80
|
-
4. Entry surfaces and the important source-to-sink or lifecycle paths.
|
|
81
|
-
5. Trust boundaries and the strongest source-visible control on each.
|
|
82
|
-
6. Repository-relative starting paths.
|
|
83
|
-
7. Prior coverage gaps, changed-source and blocked revalidation targets, and same-source confirmed exclusions.
|
|
84
|
-
8. A short companion-selection summary derived from [ATTACK-CLASSES.md](ATTACK-CLASSES.md): selected files and the source-visible boundaries that require them.
|
|
85
|
-
|
|
86
|
-
Keep the assignment-level ordinary block, selected companion blocks, and excluded blocks with reasons in each ledger unit, not in `architecture.md`. This keeps the architecture cap valid for large runs and makes the exact hunter prompt map machine-checkable.
|
|
87
|
-
|
|
88
|
-
Do not select a companion file merely because the language or dependency name appears. Select it because reconnaissance found the trust-sensitive boundary described by its `When to use this file` section. Do not exclude a visible boundary just because another agent will review a related class.
|
|
89
|
-
|
|
90
|
-
## Deterministic coverage ledger
|
|
91
|
-
|
|
92
|
-
The parent writes `<output-dir>/coverage-ledger.json` as a top-level JSON array. Derive one unit for every material combination of entry surface, trust boundary, subsystem, and applicable ordinary or companion attack class at the granularity the run profile sets (`quick` uses one all-in-scope subsystem identity; `deep` adds lifecycle modes). For a scoped run, seed in-scope surfaces for assignment and retain discovered excluded surfaces as `out_of_scope` units so later full runs can turn them into current work.
|
|
93
|
-
|
|
94
|
-
Each dimension has a human label and a stable source-derived value in `canonical_refs`. Use the same canonical reference for the same source object across runs even if its display label changes. Suitable references include a repository-relative entry path plus exported scope, a route or message identity defined in source, the source control that defines a boundary, a repository package path, and the exact attack-class block reference. A block reference is `FILE.md#` plus the exact class name as written in bold or as a heading in that file — a stable identifier matched against the file text, not a rendered HTML anchor. For companion section blocks, use the heading text before any parenthetical qualifier (for example `Core discipline`). Do not derive references by lowercasing or slugging display labels.
|
|
95
|
-
|
|
96
|
-
Derive `coverage_id` without lossy slugs:
|
|
97
|
-
|
|
98
|
-
1. Require every reference to be Unicode NFC with valid scalar values, visible content, no control, format, line/paragraph separator, or default-ignorable code point, and no surrounding whitespace.
|
|
99
|
-
2. Encode its UTF-8 bytes with RFC 3986 percent encoding: leave only `A-Z a-z 0-9 - . _ ~` unescaped and use uppercase `%HH` for every other byte.
|
|
100
|
-
3. Join encoded `surface`, `boundary`, `subsystem`, and `attack_class` references with `::`; append encoded `lifecycle` when present.
|
|
101
|
-
|
|
102
|
-
Use the fixed canonical value `profile/quick/all-in-scope-subsystems` for the quick profile's coarsened subsystem dimension. Do not include wave number, agent, verdict, severity, or line number in a reference or ID. Sort units lexicographically by `coverage_id` before each assignment. Fail on every duplicate ID. If duplicate IDs have different semantic fields, treat that as a canonical identity collision; never merge or silently overwrite them. The validator also rejects one semantic tuple represented by different canonical references.
|
|
103
|
-
|
|
104
|
-
Each unit records:
|
|
105
|
-
|
|
106
|
-
```json
|
|
107
|
-
{
|
|
108
|
-
"coverage_id": "...",
|
|
109
|
-
"canonical_refs": {
|
|
110
|
-
"surface": "src/router.ts#POST /users/:id",
|
|
111
|
-
"boundary": "src/authz.ts#requireOwner",
|
|
112
|
-
"subsystem": "packages/api",
|
|
113
|
-
"attack_class": "ATTACK-CLASSES.md#Access control"
|
|
114
|
-
},
|
|
115
|
-
"surface": "...",
|
|
116
|
-
"boundary": "...",
|
|
117
|
-
"subsystem": "...",
|
|
118
|
-
"attack_class": "...",
|
|
119
|
-
"starting_paths": ["repo/relative/path"],
|
|
120
|
-
"ordinary_attack_class_block": "ATTACK-CLASSES.md#Access control",
|
|
121
|
-
"selected_companion_blocks": ["FILE.md#section"],
|
|
122
|
-
"excluded_blocks": [{"block": "FILE.md#section", "reason": "..."}],
|
|
123
|
-
"prior_status": "new|prior_confirmed_same_source|prior_confirmed_changed_source|prior_needs_validation|prior_deferred|prior_blocked|prior_out_of_scope|prior_covered_same_source|prior_covered_changed_source|prior_rejected_claim_changed|none",
|
|
124
|
-
"attempts": [],
|
|
125
|
-
"wave": 1,
|
|
126
|
-
"status": "planned",
|
|
127
|
-
"agent_id": null,
|
|
128
|
-
"reviewed_paths": [],
|
|
129
|
-
"local_checks": [],
|
|
130
|
-
"result_fingerprints": [],
|
|
131
|
-
"unresolved": []
|
|
132
|
-
}
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
When `lifecycle` is material, add both `canonical_refs.lifecycle` and a human `lifecycle` field. `ordinary_attack_class_block` is null only when no ordinary block applies. The selected companion list includes each applicable class plus its companion `Core discipline`, `Universal moves`, and `Validation rules`; `excluded_blocks` records every considered but unselected block and the source fact that excludes it.
|
|
136
|
-
|
|
137
|
-
The parent may add bookkeeping fields but keeps the semantic fields above stable. In `prior_status`, `new` marks a surface first seen in this run when compatible prior ledgers exist; `none` marks a unit seeded when no compatible prior ledger is available. Prior `deferred`, `blocked`, `out_of_scope`, and changed-source units initialize as current `planned` work when now in scope. A prior same-source covered unit remains visible in the current ledger; assign changed source, important lifecycle paths, and exact conflicts first, then use the coverage critic to decide whether it needs another pass.
|
|
138
|
-
|
|
139
|
-
`attempts` is an append-only archive for evidence-bearing assignments that a coverage critic reopens. Before reassignment, append the prior unit's exact `wave`, `status`, `agent_id`, `reviewed_paths`, `local_checks`, `result_fingerprints`, and `unresolved`, plus the critic's source-backed `reassignment_reason`. Only `blocked`, `covered`, and `candidate` states can be archived. Archived attempts retain the same state and evidence invariants as live units, use strictly increasing waves below the current wave, and retain their producing owners and artifacts. The next assignment increments `wave`, uses a fresh owner, and starts with empty live evidence. If the profile or budget prevents another assignment, increment `wave` and use live `deferred` state with null owner, empty evidence, and the stop reason. Never copy an archived owner's checks or artifacts into the live state. A later live terminal state contains only the new attempt's evidence; the archive remains unchanged.
|
|
140
|
-
|
|
141
|
-
Enforce this state table exactly:
|
|
142
|
-
|
|
143
|
-
| Status | Unit `agent_id` | `reviewed_paths` / `local_checks` | `result_fingerprints` | `unresolved` |
|
|
144
|
-
|---|---|---|---|---|
|
|
145
|
-
| `planned` | null | empty | empty | empty |
|
|
146
|
-
| `not_applicable`, `out_of_scope`, `deferred` | null | empty | empty | nonempty reason |
|
|
147
|
-
| `in_progress` | canonical owner | empty | empty | empty |
|
|
148
|
-
| `blocked` | canonical owner | both nonempty owned partial evidence | empty | nonempty blocker |
|
|
149
|
-
| `covered` | canonical owner | both nonempty | empty | empty |
|
|
150
|
-
| `candidate` | canonical owner | both nonempty | nonempty | optional |
|
|
151
|
-
|
|
152
|
-
Canonical agent IDs match `^[a-z0-9][a-z0-9_-]{0,63}$` and are not Windows device names. Lowercase is mandatory, so one ledger cannot contain case-fold aliases. The unit `agent_id` records the assignment owner. Every check records its own `agent_id` and nonempty `reviewed_paths`; the unit-level `reviewed_paths` is exactly their union. A source-only check uses `artifact: null`. A local check requires a regular file promoted only by trusted parent-side code under exactly `agents/<check.agent_id>/artifacts/`. This lets hunter and verifier checks coexist in one unit. Scratch paths, output-root files, symlinks, special files, and another check owner's artifacts are not evidence.
|
|
153
|
-
|
|
154
|
-
The ledger is the coverage claim. An architecture summary, agent count, or generic "auth reviewed" sentence is not coverage evidence. Phase 2 closes units only from the paths and checks in a hunter's structured result.
|
|
155
|
-
|
|
156
|
-
Run `node <skill-dir>/validate-coverage-ledger.cjs <output-dir>/coverage-ledger.json` after seeding, after every parent update, and before Phase 6. The validator rejects input beyond 5 MiB, 64 nesting levels, 10,000 units, 1,000 entries in a nested collection, or 500,000 traversed values, and caps reported validation errors at 100. In practice the 5 MiB byte limit holds roughly 2,000-5,000 realistic units, so it binds before the 10,000-unit cap. Fix every error before assigning work or making a coverage claim.
|
|
1
|
+
# Reconnaissance
|
|
2
|
+
|
|
3
|
+
### Phase 1: Map the source and plan coverage
|
|
4
|
+
|
|
5
|
+
The parent initializes `run-metadata.json`, applies the strict pre-reconnaissance budget gate in `SKILL.md`, then creates agent scratch roots and the shared ledger before hunting. If the gate fails, record the incomplete status in metadata and launch no reconnaissance agent. Reconnaissance reads the target and locally available build/configuration state only. It does not contact deployed endpoints, external identity providers, registries, brokers, cloud APIs, or other shared services.
|
|
6
|
+
|
|
7
|
+
Launch several `research` agents in parallel. They return structured facts to the parent and do not write files.
|
|
8
|
+
|
|
9
|
+
**Agent 1a: Product, stack, and local operation**
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
Read the target at <target>. Do not use network access. Return:
|
|
13
|
+
1. Product type, users, operators, and ordinary trust-sensitive actions.
|
|
14
|
+
2. Languages, frameworks, build system, runtimes, and locally visible deployment models.
|
|
15
|
+
3. Repository-relative entry points and subsystem boundaries.
|
|
16
|
+
4. Exact build and test commands that could run offline with local dependencies, their expected write locations, and the target-controlled inputs they process. Do not run them during reconnaissance.
|
|
17
|
+
5. Comparable software or protocol visible from local documentation and dependencies. If no useful comparison is source-grounded, say so.
|
|
18
|
+
6. Missing local toolchains or runtime facts that limit bounded execution.
|
|
19
|
+
Return only source facts with repository-relative file:line references.
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
**Agent 1b: Principals, authority, and controls**
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
Read all source that establishes identity, authorization, isolation, and privilege. Map:
|
|
26
|
+
1. Each lower-trust principal and the actions it has by design.
|
|
27
|
+
2. Authentication or peer identity at each entry surface.
|
|
28
|
+
3. Per-resource authorization and tenant/owner scope.
|
|
29
|
+
4. Process, browser, workload, CI, plugin, model/tool, device, or local-IPC authority.
|
|
30
|
+
5. Privilege changes, confirmation, revocation, recovery, and fallback paths.
|
|
31
|
+
6. Which controls are source-visible and which depend on an unobserved deployment fact.
|
|
32
|
+
Return trust boundaries and control locations with repository-relative file:line references. Do not infer live reachability.
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Agent 1c: Entry surfaces, copies, and sinks**
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
Inventory every source-visible place external or lower-trust input enters:
|
|
39
|
+
- HTTP/browser, RPC/message/protocol, files/archive/document, CLI/env/config, plugins/dependencies/CI, cloud events/IAM selectors, model context/tool arguments, mobile/deep-link/webview, and local IPC.
|
|
40
|
+
For each surface, follow major transformations, stored or derived copies, and security-relevant sinks. Record source-visible limits and parallel paths to the same effect.
|
|
41
|
+
Return repository-relative paths and line numbers. Be complete, but do not execute or send inputs.
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Agent 1d: Local execution and deployment visibility**
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
Read tests, build definitions, manifests, packaging, and maintained environment overlays. Return:
|
|
48
|
+
1. Small offline tests or existing fixtures that could validate trust boundaries with dummy data inside the required OS-enforced sandbox.
|
|
49
|
+
2. Processes that could use an isolated loopback network namespace without external or shared dependencies.
|
|
50
|
+
3. Commands that would fetch dependencies, publish artifacts, contact paid/provider APIs, or affect shared state; mark them prohibited for this run.
|
|
51
|
+
4. Deployed controls and attachments that source cannot establish and therefore require needs_validation if decisive.
|
|
52
|
+
5. The final active source path for each deployment mode only where the repository selects it deterministically.
|
|
53
|
+
6. Whether the local platform can enforce an empty allowlisted environment, no external network, read-only target/toolchain mounts, scratch-only writes, and explicit CPU, memory, process, file-size, disk, and wall-clock limits. Missing controls block target-controlled execution.
|
|
54
|
+
7. Whether trusted parent-side code can promote predeclared scratch files with path-confined no-follow descriptor traversal, nonblocking regular-file checks, no-follow traversal of every destination parent, exclusive regular-file destination creation, and explicit per-file and cumulative size bounds. Missing promotion controls block use of scratch files as evidence.
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Add focused reconnaissance agents for materially distinct deployment modes or subsystems that these four do not map. Do not silently omit them: if the budget gate in `SKILL.md` blocks a focused agent, launch nothing for it, seed the unmapped area as a `deferred` ledger unit with reason `budget_cannot_reserve_critics_and_validation`, and disclose the gap in the report.
|
|
58
|
+
|
|
59
|
+
## Prior-run input
|
|
60
|
+
|
|
61
|
+
Before selecting work, the parent reads every available prior `coverage-ledger.json` and `findings.json` for the same repo:
|
|
62
|
+
|
|
63
|
+
- Compare the source locations, controls, conditions, and source-derived identity for every prior record and unit against the current source.
|
|
64
|
+
- Carry an unchanged prior `confirmed` record into the current candidate set, with the same fingerprint, only when its relevant source, conditions, and qualifying evidence still apply. Link it to a current `planned` unit with `prior_status: "prior_confirmed_same_source"` and put only that root cause on the hunter exclusion list. The Phase 3 verifier that re-verifies the carried record becomes that unit's assignment owner; its source re-check is the unit's first check and moves the unit to `candidate` with the carried fingerprint.
|
|
65
|
+
- Build a current planned `prior_confirmed_changed_source` revalidation unit when any relevant source or condition changed. Do not exclude that root cause from hunting or assume the prior verdict still applies.
|
|
66
|
+
- Build current work units for every prior `needs_validation`, `deferred`, `blocked`, `out_of_scope`, and changed-source unit. These states are priority input, never deduplication or suppression keys.
|
|
67
|
+
- Carry a still-blocked prior `needs_validation` record with the same fingerprint only after current source supports its trace. Link it to a current `planned` unit with `prior_status: "prior_needs_validation"`; the record keeps the unresolved blocker. The Phase 3 verifier that re-checks the carried record becomes that unit's assignment owner; its re-check is the unit's first check and moves the unit to `candidate` with the carried fingerprint. Include the record in final verification.
|
|
68
|
+
- Treat prior rejected records as stale claims unless current evidence changes the failed trace or missing condition. An unchanged rejection suppresses only that exact claim, not review of the coverage unit.
|
|
69
|
+
- Record missing or incompatible ledgers instead of treating them as empty coverage.
|
|
70
|
+
|
|
71
|
+
State paths and source refs used in `run-metadata.json`. Summarize only the coverage consequences in `architecture.md`.
|
|
72
|
+
|
|
73
|
+
## Architecture summary and companion selection
|
|
74
|
+
|
|
75
|
+
The parent synthesizes `<output-dir>/architecture.md`, with a hard cap of about 1,000 words. Include:
|
|
76
|
+
|
|
77
|
+
1. Product, principals, normal authority, and protected resources.
|
|
78
|
+
2. The comparable-software baseline from Agent 1a, when one is source-grounded: what security trade-offs the comparable accepts. Use it to calibrate effort and severity, never to dismiss a demonstrated finding; if the comparable shares a defect pattern that has mattered in practice, that strengthens the finding. Omit this line when no meaningful comparable exists.
|
|
79
|
+
3. Tech stack, source-visible deployment paths, and offline build/test limits.
|
|
80
|
+
4. Entry surfaces and the important source-to-sink or lifecycle paths.
|
|
81
|
+
5. Trust boundaries and the strongest source-visible control on each.
|
|
82
|
+
6. Repository-relative starting paths.
|
|
83
|
+
7. Prior coverage gaps, changed-source and blocked revalidation targets, and same-source confirmed exclusions.
|
|
84
|
+
8. A short companion-selection summary derived from [ATTACK-CLASSES.md](ATTACK-CLASSES.md): selected files and the source-visible boundaries that require them.
|
|
85
|
+
|
|
86
|
+
Keep the assignment-level ordinary block, selected companion blocks, and excluded blocks with reasons in each ledger unit, not in `architecture.md`. This keeps the architecture cap valid for large runs and makes the exact hunter prompt map machine-checkable.
|
|
87
|
+
|
|
88
|
+
Do not select a companion file merely because the language or dependency name appears. Select it because reconnaissance found the trust-sensitive boundary described by its `When to use this file` section. Do not exclude a visible boundary just because another agent will review a related class.
|
|
89
|
+
|
|
90
|
+
## Deterministic coverage ledger
|
|
91
|
+
|
|
92
|
+
The parent writes `<output-dir>/coverage-ledger.json` as a top-level JSON array. Derive one unit for every material combination of entry surface, trust boundary, subsystem, and applicable ordinary or companion attack class at the granularity the run profile sets (`quick` uses one all-in-scope subsystem identity; `deep` adds lifecycle modes). For a scoped run, seed in-scope surfaces for assignment and retain discovered excluded surfaces as `out_of_scope` units so later full runs can turn them into current work.
|
|
93
|
+
|
|
94
|
+
Each dimension has a human label and a stable source-derived value in `canonical_refs`. Use the same canonical reference for the same source object across runs even if its display label changes. Suitable references include a repository-relative entry path plus exported scope, a route or message identity defined in source, the source control that defines a boundary, a repository package path, and the exact attack-class block reference. A block reference is `FILE.md#` plus the exact class name as written in bold or as a heading in that file — a stable identifier matched against the file text, not a rendered HTML anchor. For companion section blocks, use the heading text before any parenthetical qualifier (for example `Core discipline`). Do not derive references by lowercasing or slugging display labels.
|
|
95
|
+
|
|
96
|
+
Derive `coverage_id` without lossy slugs:
|
|
97
|
+
|
|
98
|
+
1. Require every reference to be Unicode NFC with valid scalar values, visible content, no control, format, line/paragraph separator, or default-ignorable code point, and no surrounding whitespace.
|
|
99
|
+
2. Encode its UTF-8 bytes with RFC 3986 percent encoding: leave only `A-Z a-z 0-9 - . _ ~` unescaped and use uppercase `%HH` for every other byte.
|
|
100
|
+
3. Join encoded `surface`, `boundary`, `subsystem`, and `attack_class` references with `::`; append encoded `lifecycle` when present.
|
|
101
|
+
|
|
102
|
+
Use the fixed canonical value `profile/quick/all-in-scope-subsystems` for the quick profile's coarsened subsystem dimension. Do not include wave number, agent, verdict, severity, or line number in a reference or ID. Sort units lexicographically by `coverage_id` before each assignment. Fail on every duplicate ID. If duplicate IDs have different semantic fields, treat that as a canonical identity collision; never merge or silently overwrite them. The validator also rejects one semantic tuple represented by different canonical references.
|
|
103
|
+
|
|
104
|
+
Each unit records:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"coverage_id": "...",
|
|
109
|
+
"canonical_refs": {
|
|
110
|
+
"surface": "src/router.ts#POST /users/:id",
|
|
111
|
+
"boundary": "src/authz.ts#requireOwner",
|
|
112
|
+
"subsystem": "packages/api",
|
|
113
|
+
"attack_class": "ATTACK-CLASSES.md#Access control"
|
|
114
|
+
},
|
|
115
|
+
"surface": "...",
|
|
116
|
+
"boundary": "...",
|
|
117
|
+
"subsystem": "...",
|
|
118
|
+
"attack_class": "...",
|
|
119
|
+
"starting_paths": ["repo/relative/path"],
|
|
120
|
+
"ordinary_attack_class_block": "ATTACK-CLASSES.md#Access control",
|
|
121
|
+
"selected_companion_blocks": ["FILE.md#section"],
|
|
122
|
+
"excluded_blocks": [{"block": "FILE.md#section", "reason": "..."}],
|
|
123
|
+
"prior_status": "new|prior_confirmed_same_source|prior_confirmed_changed_source|prior_needs_validation|prior_deferred|prior_blocked|prior_out_of_scope|prior_covered_same_source|prior_covered_changed_source|prior_rejected_claim_changed|none",
|
|
124
|
+
"attempts": [],
|
|
125
|
+
"wave": 1,
|
|
126
|
+
"status": "planned",
|
|
127
|
+
"agent_id": null,
|
|
128
|
+
"reviewed_paths": [],
|
|
129
|
+
"local_checks": [],
|
|
130
|
+
"result_fingerprints": [],
|
|
131
|
+
"unresolved": []
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
When `lifecycle` is material, add both `canonical_refs.lifecycle` and a human `lifecycle` field. `ordinary_attack_class_block` is null only when no ordinary block applies. The selected companion list includes each applicable class plus its companion `Core discipline`, `Universal moves`, and `Validation rules`; `excluded_blocks` records every considered but unselected block and the source fact that excludes it.
|
|
136
|
+
|
|
137
|
+
The parent may add bookkeeping fields but keeps the semantic fields above stable. In `prior_status`, `new` marks a surface first seen in this run when compatible prior ledgers exist; `none` marks a unit seeded when no compatible prior ledger is available. Prior `deferred`, `blocked`, `out_of_scope`, and changed-source units initialize as current `planned` work when now in scope. A prior same-source covered unit remains visible in the current ledger; assign changed source, important lifecycle paths, and exact conflicts first, then use the coverage critic to decide whether it needs another pass.
|
|
138
|
+
|
|
139
|
+
`attempts` is an append-only archive for evidence-bearing assignments that a coverage critic reopens. Before reassignment, append the prior unit's exact `wave`, `status`, `agent_id`, `reviewed_paths`, `local_checks`, `result_fingerprints`, and `unresolved`, plus the critic's source-backed `reassignment_reason`. Only `blocked`, `covered`, and `candidate` states can be archived. Archived attempts retain the same state and evidence invariants as live units, use strictly increasing waves below the current wave, and retain their producing owners and artifacts. The next assignment increments `wave`, uses a fresh owner, and starts with empty live evidence. If the profile or budget prevents another assignment, increment `wave` and use live `deferred` state with null owner, empty evidence, and the stop reason. Never copy an archived owner's checks or artifacts into the live state. A later live terminal state contains only the new attempt's evidence; the archive remains unchanged.
|
|
140
|
+
|
|
141
|
+
Enforce this state table exactly:
|
|
142
|
+
|
|
143
|
+
| Status | Unit `agent_id` | `reviewed_paths` / `local_checks` | `result_fingerprints` | `unresolved` |
|
|
144
|
+
|---|---|---|---|---|
|
|
145
|
+
| `planned` | null | empty | empty | empty |
|
|
146
|
+
| `not_applicable`, `out_of_scope`, `deferred` | null | empty | empty | nonempty reason |
|
|
147
|
+
| `in_progress` | canonical owner | empty | empty | empty |
|
|
148
|
+
| `blocked` | canonical owner | both nonempty owned partial evidence | empty | nonempty blocker |
|
|
149
|
+
| `covered` | canonical owner | both nonempty | empty | empty |
|
|
150
|
+
| `candidate` | canonical owner | both nonempty | nonempty | optional |
|
|
151
|
+
|
|
152
|
+
Canonical agent IDs match `^[a-z0-9][a-z0-9_-]{0,63}$` and are not Windows device names. Lowercase is mandatory, so one ledger cannot contain case-fold aliases. The unit `agent_id` records the assignment owner. Every check records its own `agent_id` and nonempty `reviewed_paths`; the unit-level `reviewed_paths` is exactly their union. A source-only check uses `artifact: null`. A local check requires a regular file promoted only by trusted parent-side code under exactly `agents/<check.agent_id>/artifacts/`. This lets hunter and verifier checks coexist in one unit. Scratch paths, output-root files, symlinks, special files, and another check owner's artifacts are not evidence.
|
|
153
|
+
|
|
154
|
+
The ledger is the coverage claim. An architecture summary, agent count, or generic "auth reviewed" sentence is not coverage evidence. Phase 2 closes units only from the paths and checks in a hunter's structured result.
|
|
155
|
+
|
|
156
|
+
Run `node <skill-dir>/validate-coverage-ledger.cjs <output-dir>/coverage-ledger.json` after seeding, after every parent update, and before Phase 6. The validator rejects input beyond 5 MiB, 64 nesting levels, 10,000 units, 1,000 entries in a nested collection, or 500,000 traversed values, and caps reported validation errors at 100. In practice the 5 MiB byte limit holds roughly 2,000-5,000 realistic units, so it binds before the 10,000-unit cap. Fix every error before assigning work or making a coverage claim.
|
|
@@ -1,78 +1,78 @@
|
|
|
1
|
-
# Resource Exhaustion and Availability Hunting
|
|
2
|
-
|
|
3
|
-
#### When to use this file
|
|
4
|
-
|
|
5
|
-
Reach for this file when untrusted requests, messages, files, tenant state, or agent work can consume CPU, memory, disk, connections, worker slots, paid APIs, or queue capacity, or can deadlock/crash a shared service. This domain distinguishes a source-reviewable availability vulnerability from a general performance issue. Never validate by stressing a shared or live service.
|
|
6
|
-
|
|
7
|
-
Use `MEMORY-SAFETY-AND-BINARY.md` for memory-integrity defects and `PROTOCOLS-RPC-AND-MESSAGING.md` for broker delivery logic. A reachable fatal error belongs here for shared impact even when the underlying parser is covered elsewhere.
|
|
8
|
-
|
|
9
|
-
## Core discipline (include in every agent prompt for this domain)
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
- Require an input-to-cost path, a missing effective bound, and impact on another user, shared service, safety function, or operator-owned spend. Self-limiting work in the requester's own process is not a service vulnerability.
|
|
13
|
-
- A missing rate limit is not enough. Check body/message/file caps, concurrency, queues, deadlines, database constraints, upstream gateways, and per-tenant quotas before calling a path unbounded.
|
|
14
|
-
- Do not run stress, saturation, or production tests. Use asymptotic analysis, small boundary fixtures, mocked paid calls, strict local resource limits, and deterministic cancellation tests.
|
|
15
|
-
- State attacker cost, service work, persistence, scope, and recovery. One bounded input with superlinear or persistent shared effect is materially different from sustained volume.
|
|
16
|
-
- Use `confirmed` for source-visible bounds failures demonstrated safely. Use `needs_validation` when upstream caps, deployed topology, autoscaling, paid quota, or recovery behavior is outside the repository.
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## Computational amplification attack classes (subagent_type: `general`)
|
|
20
|
-
|
|
21
|
-
**Superlinear parsing, matching, or evaluation**
|
|
22
|
-
Small accepted input drives catastrophic regex backtracking, nested parsing, recursive validation, symbolic evaluation, graph traversal, template expansion, or adversarial sort/hash behavior. Derive accepted depth/cardinality and complexity, then demonstrate a bounded growth curve locally.
|
|
23
|
-
|
|
24
|
-
**Decompression and representation amplification**
|
|
25
|
-
Compressed, sparse, nested, aliased, or encoded input expands far beyond the checked transfer or file size. Verify limits after every expansion and across parser stages, including archives, images, fonts, structured documents, and protocol compression tables.
|
|
26
|
-
|
|
27
|
-
**Database and downstream query amplification**
|
|
28
|
-
A small request creates broad scans, pathological joins, fan-out, unbounded sort/aggregation, or many downstream calls because query depth, filter cardinality, pagination, or expansion fields are not bounded. Confirm authorization does not intentionally permit the same resource scope.
|
|
29
|
-
|
|
30
|
-
## Resource accumulation attack classes (subagent_type: `general`)
|
|
31
|
-
|
|
32
|
-
**Unbounded buffering and cardinality**
|
|
33
|
-
Bodies, out-of-order streams, uploads, sessions, unique cache keys, metrics labels, log fields, subscriptions, or pending jobs accumulate without per-item and aggregate limits. Find cleanup and expiration on disconnect, timeout, cancellation, and partial parse.
|
|
34
|
-
|
|
35
|
-
**File descriptor, handle, and temporary-resource leaks**
|
|
36
|
-
Malformed or canceled work misses cleanup and retains sockets, files, database cursors, timers, subprocesses, temporary files, or object references. Confirm the leak repeats through bounded local iterations and affects a shared pool.
|
|
37
|
-
|
|
38
|
-
**Detached work after cancellation**
|
|
39
|
-
Client timeout, disconnect, canceled job, or failed authorization returns control but leaves database, model, network, or worker work running. Trace cancellation and deadline propagation through every layer.
|
|
40
|
-
|
|
41
|
-
## Quota and scheduling attack classes (subagent_type: `general`)
|
|
42
|
-
|
|
43
|
-
**Pre-authentication work imbalance**
|
|
44
|
-
Expensive parsing, key lookup, cryptography, decompression, or external requests happen before authentication and the earliest size/rate gate. Compare minimal requester effort to shared service cost and check upstream limits.
|
|
45
|
-
|
|
46
|
-
**Quota-accounting scope and reset gaps**
|
|
47
|
-
Accounting uses attacker-influenceable IP, route, tenant, key prefix, task ID, or other dimension, allowing one principal's work to escape its intended budget or consume another principal's allocation. Review integer overflow, distributed races, retries, reconnects, and account switching.
|
|
48
|
-
|
|
49
|
-
**Worker, pool, and priority starvation**
|
|
50
|
-
Low-priority or attacker-controlled jobs hold shared locks, workers, database pools, event-loop turns, or scheduler priority needed by unrelated users. Require a path that bypasses queue/concurrency fairness or retains a slot beyond its deadline.
|
|
51
|
-
|
|
52
|
-
## Failure and recovery attack classes (subagent_type: `general`)
|
|
53
|
-
|
|
54
|
-
**Reachable fatal error or deadlock**
|
|
55
|
-
An untrusted input reaches `panic`, abort, fatal assertion, unhandled exception, process exit, lock cycle, or infinite loop in a shared process. Confirm supervisor scope and whether one worker or the whole service becomes unavailable. A restarted isolated worker may reduce impact but does not erase the defect.
|
|
56
|
-
|
|
57
|
-
**Retry storm and fail-open amplification**
|
|
58
|
-
Timeouts, dependency errors, partially processed messages, or health-check failures trigger synchronized or unbounded retries without jitter, ceilings, circuit breaking, or deduplication. Verify one bounded failure source can create persistent aggregate work.
|
|
59
|
-
|
|
60
|
-
**Poison-record and head-of-line blocking**
|
|
61
|
-
One malformed record or message repeatedly fails at the front of a shared queue, partition, startup scan, migration, or recovery loop. Review skip/quarantine policy, offsets, and whether other tenants share the blocked unit.
|
|
62
|
-
|
|
63
|
-
**Unsafe recovery and capacity rollback**
|
|
64
|
-
A restart, restore, fallback, or cleanup path rebuilds unbounded state, ignores current quotas, or restores the input that immediately repeats failure. Recovery correctness is part of availability.
|
|
65
|
-
|
|
66
|
-
## Universal moves (apply across the above)
|
|
67
|
-
|
|
68
|
-
- Build an input-to-resource table: earliest accepted size/cardinality, work before auth, downstream fan-out, persistence, shared pool, limit and cleanup owner, recovery.
|
|
69
|
-
- Compare aggregate limits with per-object limits. Ten thousand valid one-byte items may evade a per-message cap while exhausting tenant-wide or process-wide state.
|
|
70
|
-
- Validate only in an isolated fixture with strict CPU/memory/time limits and small growth points. Mock external and paid calls and stop once the missing bound or cancellation is observable.
|
|
71
|
-
|
|
72
|
-
## Validation rules (apply before reporting ANY finding here)
|
|
73
|
-
|
|
74
|
-
1. Name untrusted input, requester work, service amplification or retained resource, shared blast radius, and recovery. Missing limits without concrete shared impact are hardening.
|
|
75
|
-
2. Confirm no source-visible upstream, parser, queue, tenant, or framework bound prevents the path. Unknown deployed controls require `needs_validation`.
|
|
76
|
-
3. For superlinear behavior, establish the accepted complexity and bounded local growth. For leaks, show repeatable retention after cleanup should occur. For fatal paths, identify process/supervisor isolation.
|
|
77
|
-
4. Prioritize by low requester work, unauthenticated reachability, cross-tenant scope, persistence, and poor recovery; do not validate with availability impact.
|
|
78
|
-
5. Return `confirmed` only with safe local proof and meaningful shared effect. Return `needs_validation` with the exact upstream limit, topology, quota, or recovery observation an owner must check.
|
|
1
|
+
# Resource Exhaustion and Availability Hunting
|
|
2
|
+
|
|
3
|
+
#### When to use this file
|
|
4
|
+
|
|
5
|
+
Reach for this file when untrusted requests, messages, files, tenant state, or agent work can consume CPU, memory, disk, connections, worker slots, paid APIs, or queue capacity, or can deadlock/crash a shared service. This domain distinguishes a source-reviewable availability vulnerability from a general performance issue. Never validate by stressing a shared or live service.
|
|
6
|
+
|
|
7
|
+
Use `MEMORY-SAFETY-AND-BINARY.md` for memory-integrity defects and `PROTOCOLS-RPC-AND-MESSAGING.md` for broker delivery logic. A reachable fatal error belongs here for shared impact even when the underlying parser is covered elsewhere.
|
|
8
|
+
|
|
9
|
+
## Core discipline (include in every agent prompt for this domain)
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
- Require an input-to-cost path, a missing effective bound, and impact on another user, shared service, safety function, or operator-owned spend. Self-limiting work in the requester's own process is not a service vulnerability.
|
|
13
|
+
- A missing rate limit is not enough. Check body/message/file caps, concurrency, queues, deadlines, database constraints, upstream gateways, and per-tenant quotas before calling a path unbounded.
|
|
14
|
+
- Do not run stress, saturation, or production tests. Use asymptotic analysis, small boundary fixtures, mocked paid calls, strict local resource limits, and deterministic cancellation tests.
|
|
15
|
+
- State attacker cost, service work, persistence, scope, and recovery. One bounded input with superlinear or persistent shared effect is materially different from sustained volume.
|
|
16
|
+
- Use `confirmed` for source-visible bounds failures demonstrated safely. Use `needs_validation` when upstream caps, deployed topology, autoscaling, paid quota, or recovery behavior is outside the repository.
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Computational amplification attack classes (subagent_type: `general`)
|
|
20
|
+
|
|
21
|
+
**Superlinear parsing, matching, or evaluation**
|
|
22
|
+
Small accepted input drives catastrophic regex backtracking, nested parsing, recursive validation, symbolic evaluation, graph traversal, template expansion, or adversarial sort/hash behavior. Derive accepted depth/cardinality and complexity, then demonstrate a bounded growth curve locally.
|
|
23
|
+
|
|
24
|
+
**Decompression and representation amplification**
|
|
25
|
+
Compressed, sparse, nested, aliased, or encoded input expands far beyond the checked transfer or file size. Verify limits after every expansion and across parser stages, including archives, images, fonts, structured documents, and protocol compression tables.
|
|
26
|
+
|
|
27
|
+
**Database and downstream query amplification**
|
|
28
|
+
A small request creates broad scans, pathological joins, fan-out, unbounded sort/aggregation, or many downstream calls because query depth, filter cardinality, pagination, or expansion fields are not bounded. Confirm authorization does not intentionally permit the same resource scope.
|
|
29
|
+
|
|
30
|
+
## Resource accumulation attack classes (subagent_type: `general`)
|
|
31
|
+
|
|
32
|
+
**Unbounded buffering and cardinality**
|
|
33
|
+
Bodies, out-of-order streams, uploads, sessions, unique cache keys, metrics labels, log fields, subscriptions, or pending jobs accumulate without per-item and aggregate limits. Find cleanup and expiration on disconnect, timeout, cancellation, and partial parse.
|
|
34
|
+
|
|
35
|
+
**File descriptor, handle, and temporary-resource leaks**
|
|
36
|
+
Malformed or canceled work misses cleanup and retains sockets, files, database cursors, timers, subprocesses, temporary files, or object references. Confirm the leak repeats through bounded local iterations and affects a shared pool.
|
|
37
|
+
|
|
38
|
+
**Detached work after cancellation**
|
|
39
|
+
Client timeout, disconnect, canceled job, or failed authorization returns control but leaves database, model, network, or worker work running. Trace cancellation and deadline propagation through every layer.
|
|
40
|
+
|
|
41
|
+
## Quota and scheduling attack classes (subagent_type: `general`)
|
|
42
|
+
|
|
43
|
+
**Pre-authentication work imbalance**
|
|
44
|
+
Expensive parsing, key lookup, cryptography, decompression, or external requests happen before authentication and the earliest size/rate gate. Compare minimal requester effort to shared service cost and check upstream limits.
|
|
45
|
+
|
|
46
|
+
**Quota-accounting scope and reset gaps**
|
|
47
|
+
Accounting uses attacker-influenceable IP, route, tenant, key prefix, task ID, or other dimension, allowing one principal's work to escape its intended budget or consume another principal's allocation. Review integer overflow, distributed races, retries, reconnects, and account switching.
|
|
48
|
+
|
|
49
|
+
**Worker, pool, and priority starvation**
|
|
50
|
+
Low-priority or attacker-controlled jobs hold shared locks, workers, database pools, event-loop turns, or scheduler priority needed by unrelated users. Require a path that bypasses queue/concurrency fairness or retains a slot beyond its deadline.
|
|
51
|
+
|
|
52
|
+
## Failure and recovery attack classes (subagent_type: `general`)
|
|
53
|
+
|
|
54
|
+
**Reachable fatal error or deadlock**
|
|
55
|
+
An untrusted input reaches `panic`, abort, fatal assertion, unhandled exception, process exit, lock cycle, or infinite loop in a shared process. Confirm supervisor scope and whether one worker or the whole service becomes unavailable. A restarted isolated worker may reduce impact but does not erase the defect.
|
|
56
|
+
|
|
57
|
+
**Retry storm and fail-open amplification**
|
|
58
|
+
Timeouts, dependency errors, partially processed messages, or health-check failures trigger synchronized or unbounded retries without jitter, ceilings, circuit breaking, or deduplication. Verify one bounded failure source can create persistent aggregate work.
|
|
59
|
+
|
|
60
|
+
**Poison-record and head-of-line blocking**
|
|
61
|
+
One malformed record or message repeatedly fails at the front of a shared queue, partition, startup scan, migration, or recovery loop. Review skip/quarantine policy, offsets, and whether other tenants share the blocked unit.
|
|
62
|
+
|
|
63
|
+
**Unsafe recovery and capacity rollback**
|
|
64
|
+
A restart, restore, fallback, or cleanup path rebuilds unbounded state, ignores current quotas, or restores the input that immediately repeats failure. Recovery correctness is part of availability.
|
|
65
|
+
|
|
66
|
+
## Universal moves (apply across the above)
|
|
67
|
+
|
|
68
|
+
- Build an input-to-resource table: earliest accepted size/cardinality, work before auth, downstream fan-out, persistence, shared pool, limit and cleanup owner, recovery.
|
|
69
|
+
- Compare aggregate limits with per-object limits. Ten thousand valid one-byte items may evade a per-message cap while exhausting tenant-wide or process-wide state.
|
|
70
|
+
- Validate only in an isolated fixture with strict CPU/memory/time limits and small growth points. Mock external and paid calls and stop once the missing bound or cancellation is observable.
|
|
71
|
+
|
|
72
|
+
## Validation rules (apply before reporting ANY finding here)
|
|
73
|
+
|
|
74
|
+
1. Name untrusted input, requester work, service amplification or retained resource, shared blast radius, and recovery. Missing limits without concrete shared impact are hardening.
|
|
75
|
+
2. Confirm no source-visible upstream, parser, queue, tenant, or framework bound prevents the path. Unknown deployed controls require `needs_validation`.
|
|
76
|
+
3. For superlinear behavior, establish the accepted complexity and bounded local growth. For leaks, show repeatable retention after cleanup should occur. For fatal paths, identify process/supervisor isolation.
|
|
77
|
+
4. Prioritize by low requester work, unauthenticated reachability, cross-tenant scope, persistence, and poor recovery; do not validate with availability impact.
|
|
78
|
+
5. Return `confirmed` only with safe local proof and meaningful shared effect. Return `needs_validation` with the exact upstream limit, topology, quota, or recovery observation an owner must check.
|