blitzstrike 1.0.41 → 1.0.42

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.42] — 2026-09-13
+
+### Added
+
+- **Phase 7 — MCP Orchestration** (`src/orchestration.ts`, wired into `run_engagement`):
+  - A data-driven **state machine** (10 states: scope_check → plan → recon →
+    analyze → hypothesis → select_chain → validate → evidence → finding → report).
+  - A deterministic **planner** (`buildPlan`) that emits an ordered plan with
+    per-step tool, risk level, evidence requirements, and done/pending/blocked status.
+  - A **risk policy** (`actionPermitted`) that gates high-risk actions
+    (strike_verify, confirm_finding) behind scope.
+  - **§34 agent guidance** (`computeGuidance`) — every result now exposes
+    current_state / confidence / blocking_reason / required_evidence /
+    recommended_next_action / recommended_tool.
+  - `run_engagement` output now includes `state`, `plan`, `guidance`, and
+    `risk_policy` (no new MCP tools added — the surface was deepened, not widened).
+
 ## [1.0.41] — 2026-09-13
 
 ### Added

package/dist/index.js

@@ -30238,6 +30238,87 @@ function rejectFinding(finding, status, reason, evidence) {
   };
 }
 
+// src/orchestration.ts
+var STATE_MACHINE = [
+  { state: "scope_check", description: "Validate target against scope + risk policy.", recommended_tools: ["scope_check"], required_evidence: ["scope_decision"], next: ["plan"], confidence: "high" },
+  { state: "plan", description: "Derive the engagement plan from surface + scope.", recommended_tools: ["list_chains"], required_evidence: ["plan_steps"], next: ["recon"], confidence: "high" },
+  { state: "recon", description: "Map the attack surface (endpoints, tech, WAF).", recommended_tools: ["blitz_scan", "active_scan", "fofa_search", "detect_waf"], required_evidence: ["attack_surface"], next: ["analyze"], confidence: "medium" },
+  { state: "analyze", description: "Trace source→sink flows (interprocedural taint).", recommended_tools: ["eagle_eye2", "blitz_scan", "blitz_file"], required_evidence: ["sink_hits", "taint_flow"], next: ["hypothesis"], confidence: "medium" },
+  { state: "hypothesis", description: "Form defensible hypotheses (static finding).", recommended_tools: ["blitz_file", "enrich_scan"], required_evidence: ["static_finding"], next: ["select_chain"], blocking: "live_validation_required", confidence: "high" },
+  { state: "select_chain", description: "Match the hypothesis to an escalation chain.", recommended_tools: ["list_chains", "read_playbook"], required_evidence: ["matched_chain"], next: ["validate"], confidence: "high" },
+  { state: "validate", description: "Verify live with baseline + marker + negative control.", recommended_tools: ["strike_verify", "browser_validate"], required_evidence: ["baseline", "marker_reflection", "negative_control"], next: ["evidence"], confidence: "medium" },
+  { state: "evidence", description: "Attach hashable, provenance-bound evidence.", recommended_tools: ["finding_attach_evidence"], required_evidence: ["evidence_artifact"], next: ["finding"], confidence: "high" },
+  { state: "finding", description: "Confirm the finding (invariants enforced).", recommended_tools: ["confirm_finding"], required_evidence: ["confirmed_finding"], next: ["report"], confidence: "high" },
+  { state: "report", description: "Produce a reproducible report.", recommended_tools: ["report", "security-report"], required_evidence: ["report"], next: [], confidence: "high" }
+];
+function stateDefinition(state) {
+  return STATE_MACHINE.find((s) => s.state === state);
+}
+var RISK_POLICY = [
+  { action: "scope_check", risk: "low", requires_scope: false, destructive: false },
+  { action: "blitz_scan", risk: "low", requires_scope: false, destructive: false },
+  { action: "blitz_file", risk: "low", requires_scope: false, destructive: false },
+  { action: "eagle_eye2", risk: "low", requires_scope: false, destructive: false },
+  { action: "enrich_scan", risk: "low", requires_scope: false, destructive: false },
+  { action: "detect_waf", risk: "low", requires_scope: false, destructive: false },
+  { action: "fofa_search", risk: "low", requires_scope: false, destructive: false },
+  { action: "list_chains", risk: "low", requires_scope: false, destructive: false },
+  { action: "read_playbook", risk: "low", requires_scope: false, destructive: false },
+  { action: "active_scan", risk: "medium", requires_scope: true, destructive: false },
+  { action: "browser_validate", risk: "medium", requires_scope: true, destructive: false },
+  { action: "strike_verify", risk: "high", requires_scope: true, destructive: false },
+  { action: "confirm_finding", risk: "high", requires_scope: true, destructive: false }
+];
+function riskOf(action) {
+  return RISK_POLICY.find((r) => r.action === action) ?? null;
+}
+function actionPermitted(action, scopeAllowed, mode) {
+  const rule = riskOf(action);
+  if (!rule)
+    return true;
+  if (mode === "ctf" || mode === "offensive" || mode === "reverse-engineering")
+    return true;
+  if (rule.requires_scope && !scopeAllowed)
+    return false;
+  return true;
+}
+function buildPlan(scopeAllowed, mode, executedState) {
+  const order = ["scope_check", "plan", "recon", "analyze", "hypothesis", "select_chain", "validate", "evidence", "finding", "report"];
+  const executedIdx = order.indexOf(executedState);
+  return order.map((state, i) => {
+    const def = stateDefinition(state);
+    const tool = def.recommended_tools[0] ?? "";
+    const rule = riskOf(tool);
+    const permitted = actionPermitted(tool, scopeAllowed, mode);
+    const status = i <= executedIdx ? "done" : permitted ? "pending" : "blocked";
+    return {
+      order: i + 1,
+      state,
+      action: def.description,
+      tool,
+      evidence_required: def.required_evidence,
+      risk: rule?.risk ?? "low",
+      permitted,
+      status
+    };
+  });
+}
+function computeGuidance(state, scopeAllowed) {
+  const def = stateDefinition(state);
+  const next = def.next[0];
+  const nextDef = next ? stateDefinition(next) : null;
+  const tool = nextDef?.recommended_tools[0] ?? "";
+  const permitted = actionPermitted(tool, scopeAllowed, "bug-bounty");
+  return {
+    state,
+    confidence: def.confidence,
+    blocking_reason: !scopeAllowed && nextDef && riskOf(tool)?.requires_scope ? "scope_required" : def.blocking ?? null,
+    required_evidence: def.required_evidence,
+    recommended_next_action: nextDef?.description ?? "complete",
+    recommended_tool: permitted ? tool : ""
+  };
+}
+
 // src/orchestrator.ts
 var _chainsCache = null;
 function loadChains() {
@@ -30451,6 +30532,17 @@ function runEngagement(target, scope = "", mode = "bug-bounty", maxFiles = 2000,
   }));
   report.status = "COMPLETE";
   report.note = "All findings are HYPOTHESES until verified live with strike_verify. " + "Apply each chain's negative_control before reporting. Confidence reflects static evidence only.";
+  const executedState = "select_chain";
+  const scopeAllowed = report.scope?.allowed ?? false;
+  const plan = buildPlan(scopeAllowed, mode, executedState);
+  report.state = executedState;
+  report.state_description = stateDefinition(executedState).description;
+  report.plan = plan;
+  report.guidance = computeGuidance(executedState, scopeAllowed);
+  report.risk_policy = {
+    note: "High-risk actions (strike_verify, confirm_finding) require scope + are never run server-side automatically.",
+    gated: plan.filter((p) => !p.permitted).map((p) => p.tool)
+  };
   if (remember) {
     let captured = 0;
     for (const mc of blitz.matched_chains) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blitzstrike",
-  "version": "1.0.41",
+  "version": "1.0.42",
   "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": {