blitzstrike 1.0.75 → 1.0.77

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to Blitz Strike are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.77] — 2026-09-13
+
+### Fixed — explicit tool argument names in doctrine
+
+- `bs-source-audit` now documents the exact argument convention: all
+  source-analysis tools take `path` (file or directory); only `run_engagement`
+  takes `target` (path or URL). Workflow steps now show `{path}` explicitly.
+- `bs-orchestrate-engagement` tells sub-agents to load `source-audit` for the
+  argument names instead of guessing `target` vs `path`.
+
+## [1.0.76] — 2026-09-13
+
+### Changed — native plan + sub-agent orchestration doctrine
+
+- `bs-orchestrate-engagement` now instructs the driving agent to use its
+  platform's native planning + delegation (e.g. Hermes `plan`/`todo` +
+  `delegate_task`) to run the engagement in parallel — recon / analyze /
+  deep-classes as sub-agents, then collect → verify → report — instead of
+  serial tool calls.
+
 ## [1.0.75] — 2026-09-13
 
 ### Added — plan checklist in the engagement banner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blitzstrike",
-  "version": "1.0.75",
+  "version": "1.0.77",
   "description": "Blitz Strike — a universal MCP security-audit toolbelt. BLITZ sweeps the attack surface, EAGLE-EYE traces source-to-sink, STRIKE verifies live. 57 attack chains, 130-tool catalog, intelligence data layer. One server, every agent.",
   "type": "module",
   "bin": {

package/skills/bs-orchestrate-engagement.md

@@ -37,6 +37,34 @@ deterministic MCP tools; never guess a finding — produce it from tool output.
 
 6. **Report.** Emit `generate_report` + `cvss_score` + `write-report`.
 
+## Orchestration pattern (native plan + sub-agents)
+
+You are the orchestrator — use your platform's native planning and delegation
+mechanisms (e.g. Hermes `plan`/`todo` + `delegate_task`) to run the engagement
+in parallel, instead of serial tool calls. This is what makes the flow
+no-babysitting, not a single `run_engagement` call:
+
+1. **Plan.** Lay out the stages as a todo/plan: scope → recon → analyze →
+   verify → review → report. Assign each independent workstream to a sub-agent.
+2. **Delegate (parallel).** Spawn sub-agents for independent workstreams:
+   - *Recon* → `blitz_scan` + `live_recon` + `detect_framework` + `list_chains`.
+   - *Analyze* → `eagle_eye2` + `taint_scan` + `trace_data_flow` (source→sink).
+   - *Deep classes* → `complex_scan` (POP/type-juggling/mass-assignment) +
+     `route_scan` (route confusion).
+   Source-analysis tools take a `path` argument (file or directory); only
+   `run_engagement` takes `target` (path or URL). Point each sub-agent at the
+   `source-audit` skill so it knows the exact argument names — do not let it
+   guess `target` vs `path`.
+   Each sub-agent returns deterministic findings — give it the target, the
+   exact tools to call, and require evidence (file:line, sink, chain), never prose.
+3. **Collect + verify.** Merge sub-agent findings, `dedup_findings` by root
+   cause, then prove each hypothesis with `strike_verify` (baseline + marker +
+   negative control) before it becomes a finding.
+4. **Report.** `generate_report` + `cvss_score` + `write-report`.
+
+Announce the takeover banner and progress (`blitz_status`) between steps so the
+user sees you working, not a silent tool call.
+
 ## The skill chain (load the right one per phase)
 
 | Phase | Skill |

package/skills/bs-source-audit.md

@@ -8,27 +8,37 @@ description: Use when auditing source code (PHP/JS/Python/Java/etc.) for vulnera
 Drive Blitz Strike's static analyzers over a source tree and turn each hit into a
 hypothesis. Do not hand-guess; let the tools produce the source→sink evidence.
 
+## Tool argument convention (read this first)
+
+- **All source-analysis tools take `path`** (a file or directory):
+  `blitz_scan`, `eagle_eye2`, `taint_scan`, `taint_file`, `blitz_file`,
+  `trace_data_flow`, `eagle_grep`, `variant_analysis`, `enrich_scan`,
+  `route_scan`, `complex_scan`, `detect_framework`.
+  Example: `blitz_scan {path: "/repo/app"}`.
+- **Only `run_engagement` takes `target`** (accepts either a source path OR a
+  live URL). Do not pass `target` to the source-analysis tools — it is ignored.
+
 ## Workflow
 
-1. **Map the tree.** `blitz_scan <root>` — entry points (nopriv hooks, REST
-   routes, controllers) + sink inventory per file. `detect_framework` per file
-   to know what conventions apply.
+1. **Map the tree.** `blitz_scan {path}` — entry points (nopriv hooks, REST
+   routes, controllers) + sink inventory per file. `detect_framework {path}` per
+   file to know what conventions apply.
 
 2. **Trace data flow.** For each source→sink candidate:
-   - `taint_file` / `taint_scan` — variable-level taint tracking per file.
-   - `eagle_eye2` — whole-program interprocedural taint (PHP, method-call aware).
-   - `trace_data_flow` — classify sources vs sinks across a file.
+   - `taint_file {path}` / `taint_scan {path}` — variable-level taint tracking.
+   - `eagle_eye2 {path}` — whole-program interprocedural taint (PHP, method-aware).
+   - `trace_data_flow {path}` — classify sources vs sinks across a file.
    - `variant_analysis` — group data-flow candidates by shared root cause.
 
-3. **Escalate.** `enrich_scan` — match detected sinks to escalation chains
-   (SQLi → RCE, upload → shell, LFI → RCE). `list_chains` to see the full
+3. **Escalate.** `enrich_scan {path}` — match detected sinks to escalation
+   chains (SQLi → RCE, upload → shell, LFI → RCE). `list_chains` to see the full
    escalation taxonomy. `tech_correlation` for framework-specific weaknesses.
 
 4. **Deep/complex classes.** Beyond plain taint, drive the dedicated detectors:
-   - `route_scan <file>` — route confusion / dispatch abuse (`call_user_func`,
+   - `route_scan {path}` — route confusion / dispatch abuse (`call_user_func`,
      `$obj->$method()`, batch/proxy forwarding, dynamic include, route match
      without path normalization).
-   - `complex_scan <file>` — deserialization→POP chain (`unserialize` +
+   - `complex_scan {path}` — deserialization→POP chain (`unserialize` +
      `__destruct`/`__wakeup`/`__toString`), type juggling (loose `==`/`!=` vs
      hash/secret), mass assignment (`extract()`/`parse_str()` without a safe flag).