HunterX v7 — Sprint 034.5 — Toolchain + Intelligence + Proof Certification

Phase: Final Release Gate — Phase 5 (Toolchain, Intelligence & Proof) Status: PASS (conditional — see Residual Risks) Date: 2026-08-11 Scope: src/hunterx (v7 package), the full tool registry, adapter/parser/ normalizer contracts, tool chaining, failure handling, findings/evidence/proof and the PoC engine. Continues from Sprint 034.4 (Security & Tool Execution).

This document certifies that HunterX can professionally operate its complete offensive-security toolchain — not merely launch binaries — and convert tool output into usable intelligence, evidence, findings and validated proof. Every claim is backed by a test or an explicit architectural guarantee; policy-only constructs are labelled POLICY, not enforcement.

1. Certification Method

The toolchain is NOT considered implemented merely because a binary can be launched. For every integrated tool the platform now holds a consolidated machine-readable contract covering: purpose, capabilities, prerequisites, version, input model, argument model, execution mode, scope requirements, output formats, stdout/stderr, exit codes, errors, timeouts, artifacts, parser, normalizer, canonical intelligence, downstream consumers and chaining opportunities.

Where a real binary is unavailable the complete adapter/parser/normalizer contract is validated with authoritative fixtures (see §15) and execution-dependent validation is clearly marked with the tools pytest marker (excluded by default; see tests/integration/tools/test_execution_dependent.py). No successful execution is faked to inflate coverage.

2. Tool Inventory

The certified registry now exposes 106 registered tools with 79 registered execution adapters (previously 41 adapter classes), classified by support level:

The complete tool list is generated by capabilities/full-toolchain-intelligence.json (92-tool arsenal manifest) plus the TIP-only capability adapters (API discovery, cloud/auth/authorization analyzers, safe-validation probes, proof-replay, knowledge providers). hunterx tools list / GET /tools and hunterx tools contracts / GET /tools/contracts expose the live inventory.

3. Tool Contract (machine-readable capability definition)

The consolidated contract is the single machine-readable definition every tool must expose. It is built by hunterx.tools.mastery.contract.build_contract from the authoritative master profile + relationship graph, and exposed via ToolchainService.contract/contracts, hunterx tools contract, and GET /tools/{tool_id}/contract.

Minimum dimensions (all verified non-empty for every registered tool by tests/tools/test_contracts.py):

Gate result: every registered tool has a defined contract — 0 missing dimensions across the 92-tool arsenal (tests/tools/test_contracts.py), and the 14 TIP-only capability tools receive a complete TIP-derived contract (contract_gaps() returns empty).

4. Tool Capability Matrix

Tools are selected by canonical capability ids (ToolIntelligenceAPI vocabulary). The full matrix (capability → primary tool → fallbacks → complementary tools, merge policy deduplicate) is generated by ToolchainService.strategies and persisted in capabilities/full-toolchain-intelligence.json. Representative rows:

Selection is mission-state-aware: ToolSequencePlanner/ToolSelector rank by capability, target type, mission profile, available inputs, authorization ceiling, reliability and performance (tests/tools/test_chaining.py, tests/acceptance/toolchain/). Tools are never executed blindly.

5. Execution Model

All subprocess-backed adapters (now 16+ of the 79) run exclusively through the single guarded seam BinaryRunner (src/hunterx/tools/recon/runner.py): structural argv, no shell=True, 32 MiB output cap with process-tree termination, wall-clock timeouts, option-injection guards (guard_positional_target / guard_option_value). In-process adapters (dnspython, tcp-connect, crawler, API/cloud/auth analyzers, providers, safe-validation probes, proof-replay, knowledge datasets) run inside the SDK pipeline without subprocess.

Every execution goes through the SDK lifecycle prepare → run → validate_output → normalize → cleanup and is recorded as an ExecutionResult with formats, artifacts, failure kind and retry count. Each family emits canonical records:

6. Parser Matrix

Parsing is adapter-driven online and engine-driven offline:

• Online: each adapter’s parse_output converts captured stdout into canonical records (JSONL/JSON/text). Hostile output is treated as data: malformed lines are skipped, never executed (tests/tools/test_failure_handling.py::TestMalformedAndEmptyOutput, tests/security/tools/).
• Offline: ToolchainService.parse(tool, raw) dispatches to the adapter parser when registered, else to ParserEngine’s format-driven default (tests/tools/test_parsers_normalizers.py). A non-JSON payload to the default parser fails with ToolExecutionError — never a silent success.
• The TIP registers versioned ToolParser records (parser id, input format, output mappings, error handling) resolved through ToolRuntimeRegistry (src/hunterx/tools/intelligence/parsers.py).

Representative fixture-validated parsers (see §15 golden fixtures): subfinder JSONL, dnsx JSONL, massdns JSON, shuffledns JSONL, naabu JSONL, rustscan JSON, nmap XML, httpx JSONL, katana JSONL, ffuf JSON, gobuster/feroxbuster JSONL, dirsearch JSON, arjun JSON, trufflehog JSONL, semgrep JSON, searchsploit JSON, nuclei JSONL, dalfox JSON, sqlmap/commix/sstImap text.

7. Normalizer Matrix

Normalization projects parsed records into canonical objects. Two layers:

1. Legacy NormalizerEngine converts records into FindingResult / EvidenceResult / assets (tests/tools/test_parsers_normalizers.py).
2. TIP ToolNormalizer (normalizer id, schema, observation mappings, migration) maps records into CanonicalObservation with auto correlation_key ({kind}:{target}:{normalized}) and provenance (src/hunterx/tools/intelligence/normalizers.py).

ToolchainService.normalize exposes offline normalization; the chain executor and target-intelligence store consume the canonical observations (tests/acceptance/toolchain/).

Canonical intelligence kinds (ObservationKind): domains, subdomains, IPs, ports, services, technologies, URLs, endpoints, parameters, secrets, vulnerabilities, evidence, findings, attack-path nodes, cloud resources.

8. Provenance

Every canonical observation carries: source tool, tool version, execution id, mission id, target id, timestamp, raw-artifact reference, normalized value, confidence, correlation key and provenance dict. This is enforced by CanonicalObservation and ToolExecutionRecord, written by the chain executor and TargetIntelligenceStore, and verified in tests/tools/test_chaining.py and tests/acceptance/toolchain/.

9. Tool Chaining

Gap closed this sprint: planning existed but no generic chain executor. POST /tools/chain planned only; multi-step execution existed solely in the vulnerability-validation path. Added ChainExecutor (src/hunterx/tools/intelligence/chaining.py) and ToolchainService.execute_chain / POST /tools/chain/execute / hunterx tools chain-execute.

ChainExecutor:

• runs steps in dependency (topological) order from a planned ToolChain;
• skips tools with no registered adapter (never faked) with a clear reason;
• feeds discovered hosts/URLs from predecessor steps into dependent steps;
• extracts canonical observations with full provenance per step;
• classifies failures and attempts a capability-equivalent fallback once;
• preserves partial results in ToolChainResult.

Certified end-to-end chains (tests/acceptance/toolchain/test_end_to_end_chains.py):

1. Recon → DNS → probe → crawl → content → vuln: subfinder/amass → dnsx → httpx → katana → ffuf → nuclei
2. API: api-graphql discovery → inql/graphqlmap → nuclei
3. Secrets / repository: gitleaks → trufflehog → semgrep
4. Web vulnerabilities: nuclei → dalfox → sqlmap → verification → evidence
5. Cloud/SaaS: prowler / cloud-analysis

Intelligence reuse across missions is certified: observations from one chain feed a later chain without losing provenance (test_intelligence_reuse_across_chains).

10. Failure Handling

Certified failure modes and disposition (tests/tools/test_failure_handling.py, tests/security/tools/):

Fallback selection is never blind: _select_fallback requires a capability-equivalent tool with a registered adapter (tests/acceptance/toolchain/test_chain_failure_falls_back_to_equivalent_tool).

11. Intelligence Mapping

Every tool result becomes reusable target intelligence through TargetIntelligenceStore / ToolExecutionRecord / CanonicalObservation, keyed by target, carrying full provenance so a later mission can reuse previous intelligence. has_executed(target, tool) prevents blind re-runs. Certified by tests/acceptance/toolchain/test_intelligence_reuse_across_chains and the existing target-intelligence suites.

12. Evidence Mapping

Tool output does NOT automatically equal evidence. Each tool’s contract declares capability → observation kind → evidence type → requires_validation (validation-required set: sqli, xss, ssti, command-injection, xxe, vulnerability-scan, oob). Scanner output is a candidate (bounded confidence, provenance.validated=False); the Proof/Validation subsystems own the verdict. Certified by tests/security/tools/ and the golden finding suite (tests/golden/findings/).

13. Finding Mapping

The finding flow is certified end-to-end:

DISCOVER → HYPOTHESIZE → TEST → VERIFY → PROVE → FINDING

FindingLifecycleStateMachine gates every transition on evidence (FindingState: candidate → supported → validation_required → validating → validated → proof_required → proving → proved → report_ready). A detection without reproducible evidence never becomes a fully validated finding (tests/golden/findings/scenarios.json). FindingPackage preserves: vulnerability, affected asset, endpoint, parameter, evidence, verification, impact, PoC availability, reproduction, confidence, provenance and report-readiness. Known vulnerabilities, variants and application-specific/ novel behavior are supported (classify_unknown).

14. PoC Architecture

PocLifecycleState: generated → static_validated → execution_ready → replayed → behavior_confirmed → evidence_captured → proof_validated / rejected. A PoC is minimal (minimal=True), reproducible, linked to evidence and finding, traceable to execution (content_hash, deterministic, scope_bound, redacted), and replayed through the authorized execution pipeline (ProofReplayAdapter, in-process deterministic, never executes payloads). Refutation is preserved: ReplayVerdict (confirmed / not_reproducible / different_behavior / different_target / out_of_scope / different_hypothesis / stale) regresses the finding and never proves it (tests/golden/poc/scenarios.json).

15. Tests

New suites added for the certification (all pass in the default run):

Golden fixtures under tests/golden/tools/<family>/ cover every tool family (massdns, shuffledns, rustscan, gau, waybackurls, urlfinder, gospider, hakrawler, gobuster, feroxbuster, dirsearch, arjun, paramspider, kiterunner, linkfinder, secretfinder, xnlinkfinder, dalfox, xssstrike, sqlmap, ghauri, commix, tplmap, sstimap, xxeinjector, interactsh, graphqlmap, inql, trufflehog, semgrep, zap, searchsploit, exploitdb, metasploit).

Regression: full default suite (-m 'not tools') after the sprint: 3474 passed, 8 skipped, 2 deselected — no previous capability regressed.

16. Added Tools (capability-gap justified)

38 adapters added across 4 new families (parameter, sast, proxy, exploit, knowledge) and 9 existing families, closing these gaps:

• DNS brute-force / bulk resolution: massdns, shuffledns
• Fast port discovery: rustscan
• Crawl + URL/history discovery: gospider, hakrawler, gau, waybackurls, urlfinder
• Content discovery: gobuster, feroxbuster, dirsearch
• Parameter discovery: arjun, paramspider, kiterunner
• JavaScript endpoint/secret extraction: linkfinder, secretfinder, xnlinkfinder
• Web injection testing: dalfox, xssstrike, sqlmap, ghauri, commix, interactsh (OAST), tplmap, sstimap, xxeinjector
• GraphQL testing: graphqlmap, inql
• Secrets: trufflehog
• SAST: semgrep
• Proxy/interception: zap (baseline), mitmproxy
• Exploit intelligence: metasploit (execution-only), searchsploit, exploitdb
• Knowledge datasets: payloadsallthethings, seclists, fuzzdb (in-process reference adapters)

The API-discovery adapters (api-openapi, api-graphql, …) were previously registered but never wired into the execution engine; they are now registered in the assembler.

17. Repairs (this sprint)

1. Generic ChainExecutor — end-to-end chaining with provenance, fallback and partial-result preservation (P0 gap closed).
2. ToolContract — consolidated machine-readable contract for every tool covering all 20 minimum dimensions; exposed via CLI/API.
3. API adapters wired into the engine — register_api_adapters was never called by the assembler.
4. Masking regression (mask_value) — reveal_tail=0 leaked the full secret because value[-0:] returns the whole string. Fixed and pinned in tests/security/tools/.
5. Arsenal support-level alignment — tools with real adapters upgraded from knowledge-only/partial-support to their true executable support level and adapter/parser/normalizer ids (specs._ADAPTER_UPGRADES), so the contract never under-reports executability.
6. TIP-only tools now receive complete contracts (scope/error/retry/ evidence dimensions derived from TIP knowledge).
7. contract_gaps redefined on the minimum-dimension gate (was flagging optional informational fields).

18. Coverage Gaps (documented, no P0/P1 blocker)

19. Residual Risks (not silently accepted)

20. P0/P1/P2/P3 Summary

• P0 (blocker): none remain.
• P1 (must-fix before hostile exposure, mitigated): R1 (opt-in API-key auth shipped + verified), R2 (documented policy + deployment mitigation). Both carried from 034.4 with mitigations.
• P2: R3, R4, R5.
• P3: R6, R7.

21. Gate Checklist

• every registered tool has a defined contract (§3, tests/tools/test_contracts.py)
• tool inputs are structured (§5, typed argv/input schemas)
• outputs are parsed (§6, fixture-validated parsers)
• outputs are normalized (§7, canonical observations)
• provenance is preserved (§8)
• tool failures are classified (§10)
• chaining works (§9, ChainExecutor + end-to-end acceptance chains)
• target intelligence is reusable (§11)
• evidence survives the pipeline (§12, §13)
• validated findings preserve proof (§13, §14)
• PoC lifecycle is represented (§14)
• representative end-to-end chains pass (§9, §15)
• no P0/P1 toolchain blocker remains (§20)
• certification report generated (this document)

22. Final Verdict

Sprint 034.5 — TOOLCHAIN + INTELLIGENCE + PROOF CERTIFICATION: PASS (conditional).

HunterX v7 now operates its toolchain professionally: 106 tools with complete machine-readable contracts, 79 registered adapters (38 added this sprint), fixture-validated parsers/normalizers for every family, provenance-preserving canonical intelligence, real end-to-end chain execution with capability-aware selection, classified failure handling with fallback, an evidence-gated finding lifecycle and a replay-validated PoC engine. A detection without reproducible evidence never becomes a validated finding.

The two P1 risks (opt-in API auth default and policy-only plugin isolation) are mitigated and carried from Sprint 034.4 with documented deployment guidance. No P0 or unresolved P1 toolchain blocker remains. Release gate PASSES.