HunterX v7 Vulnerability Proof Strategy Library & Proof Validator

Status: Ratified (Sprint 022 / Wave 15) Version: 1.0.0 Owner: HunterX Architecture Council

1. Purpose / Scope

The Vulnerability Proof Strategy Library is the vulnerability-specific intelligence layer that teaches HunterX HOW to prove each vulnerability class correctly. It does not redesign Sprint 021 — it extends the existing proof contracts, evidence engine, PoC engine, replay engine, confidence engine, scope engine and Tool Integration SDK. A vulnerability class is not a proof, a scanner result is not proof and a payload succeeding once is not automatically proof. The strategy library defines the evidence contract for each vulnerability class and the Proof Validator deterministically decides whether a proof satisfies that contract.

Canonical flow:

Vulnerability Candidate
        ↓
Proof Strategy Selection
        ↓
Precondition Validation
        ↓
Minimal Test
        ↓
Observation
        ↓
Evidence Evaluation
        ↓
Proof Validation
        ↓
Replay
        ↓
Impact Validation
        ↓
Finding State Transition

Scope: src/hunterx/domain/vulnerability_proof/ (strategy.py, registry.py, selector.py, validator.py, matrix.py, library.py), src/hunterx/application/vulnerability_proof_strategy.py, src/hunterx/reporting/strategy.py, the proof.strategy.*/proof.validation.* event catalog, the tidb_proof_strategy_*/tidb_proof_validation_results/ tidb_proof_manual_instructions TIDB entity set, the migration e1f2a3b4c5d6, the capability manifest capabilities/vulnerability-proof-strategy.json and the platform wiring in src/hunterx/platform/assembler.py.

Out of scope: any second finding, evidence, PoC, replay, confidence or scope system; weaponized exploitation; unrestricted exploit generation; destructive proof strategies; scope bypass; arbitrary executable PoC pipelines.

2. Core Principle

The strategy library answers, per vulnerability class:

1. What security property is being tested?
2. What evidence is required?
3. What is the safest proof strategy?
4. What preconditions are required?
5. What tools can perform the proof?
6. What observations constitute proof?
7. What observations are insufficient?
8. What observations are contradictory?
9. How should the proof be replayed?
10. What impact can legitimately be claimed?
11. When must HunterX stop?
12. When must HunterX classify the result as INCONCLUSIVE?
13. When is the finding eligible for REPORT_READY?

Evidence dominates model belief. A numerical confidence score never bypasses evidence requirements: 99% AI confidence without required proof remains NOT_PROVEN, and low AI confidence with strong deterministic proof triggers a confidence reassessment. Contradictory evidence is never averaged into a confidence percentage — it is investigated.

3. ProofStrategy Contract

A ProofStrategy is the canonical contract with:

strategy_id, strategy_version, vulnerability_class, security_property, description, preconditions, required_inputs, allowed_actions, forbidden_actions, required_evidence, optional_evidence, expected_observations, negative_observations, inconclusive_conditions, confirmation_conditions, replay_requirements, impact_requirements, required_capabilities, preferred_tools, fallback_strategies, safety_class, scope_requirements, confidence_policy, stop_conditions, abort_conditions, provenance, permits_confirmation, reportable, execution and an EvidenceRule contract.

Every strategy defines the evidence contract:

• MINIMUM_REQUIRED_EVIDENCE — must be present for VALID.
• STRONG_EVIDENCE — substantially strengthens the proof.
• SUPPORTING_EVIDENCE — marginally supports the proof.
• NEGATIVE_EVIDENCE — indicates the hypothesis is wrong.
• CONTRADICTORY_EVIDENCE — actively refutes the hypothesis.
• INSUFFICIENT_EVIDENCE — never satisfies the contract alone (e.g. a scanner signature).

Example ladder: a scanner signature alone is INSUFFICIENT; a scanner signature + behavioral confirmation is STRONGER; behavioral confirmation + successful replay is PROOF-QUALITY EVIDENCE; proof + impact evidence is a REPORT-READY CANDIDATE.

4. Strategy Registry

ProofStrategyRegistry provides register(), get(), resolve(), list(), supports(), find_best_strategy(), validate_strategy(), version() and deprecate(). Strategies are immutable after registration — an update always creates a new version; registering the same (id, version) raises StrategyConflictError. Deprecated strategies are excluded from resolution but remain retrievable for audit.

5. Strategy Selection

ProofStrategySelector consumes vulnerability class, target type, asset type, protocol, application type, available evidence, available tools, scope, mission type, safety policy, authorization level and existing validation result, and produces a ProofStrategySelection (selected strategy, alternatives, selection reasoning, missing prerequisites, blocked strategies, required capabilities, risk level, executability and capability coverage).

Priority order (deterministic):

1. Existing evidence
2. Lowest-risk proof
3. Highest reproducibility
4. Lowest target impact
5. Existing authorized capability
6. Strongest independent verification
7. Lowest execution complexity

A more invasive strategy is never selected when a lower-impact strategy can establish the same security property.

Tool capability matching

Every strategy declares required_capabilities (e.g. http_request, http_replay, dns_lookup, tls_analysis, controlled_callback, api_request, browser_execution, configuration_query, cloud_metadata, dependency_analysis). The selector maps these canonical capabilities to the Tool Integration SDK capability vocabulary and resolves concrete tools only through the Tool Intelligence port — never hard-coded executables. If no compatible tool exists the selection returns PROOF_NOT_EXECUTABLE; if automation cannot safely establish proof it returns MANUAL_REQUIRED. HunterX never fabricates proof.

6. Proof Validator

ProofValidator.validate(strategy, context) validates proof structure, strategy compatibility, prerequisites, evidence requirements, scope, safety, expected observations, contradictory evidence, reproducibility, replay results and impact evidence, and produces a deterministic, explained verdict:

• VALID — the evidence contract is satisfied and reproducible.
• INVALID — structurally invalid, incompatible or refuted.
• INCOMPLETE — evidence/replay/impact gates not yet met.
• INCONCLUSIVE — target changed, preconditions changed or evidence ambiguous.
• BLOCKED — scope/safety/proof-policy block.
• UNSAFE — destructive or forbidden action observed.
• OUT_OF_SCOPE — scope requirement not satisfied.
• CONTRADICTED — contradictory evidence present; never averaged.
• INSUFFICIENT_EVIDENCE — the evidence contract is not satisfied.

The validator also records target state. If the target state changes between proof generation and replay the replay is marked REPLAY_INVALIDATED and the verdict is INCONCLUSIVE — the change is never silently accepted.

Proof quality levels

P0 Candidate → P1 Observed → P2 Verified → P3 Proven → P4 Confirmed → P5 Report Ready. A single successful replay is never REPRODUCIBLE; P3 requires the minimum reproducible proof, P4 requires confirmation conditions and P5 requires the reportability contract (evidence + replay + impact + scope).

7. Evidence Matrix

EvidenceMatrix is a versioned, machine-readable matrix:

Vulnerability Class
→ Required Evidence
→ Optional Evidence
→ Disqualifying Evidence
→ Replay Requirement
→ Impact Requirement
→ Confirmation Rule

The matrix is derived deterministically from the strategy library and carries its own schema version (matrix.version()).

8. Built-in Strategy Families

The library covers: SQL/NoSQL injection, XSS, SSRF, LFI / path traversal, IDOR / BOLA, authentication bypass, authorization (API) bypass, command injection / RCE (impact-safe proof), open redirect, CORS, CSRF, sensitive data exposure, security misconfiguration, dependency vulnerability, known vulnerable component/software, cloud misconfiguration, template injection, deserialization and UNKNOWN_BEHAVIOR (novel).

Per-class proof objectives are deliberately conservative:

• SQL injection proves injection behavior is demonstrated, never “database contents were extracted”.
• XSS prefers minimal non-persistent markers; persistent testing requires explicit authorization.
• SSRF prefers controlled-callback validation; never cloud metadata / internal panels / localhost services without explicit authorization.
• LFI / path traversal prefers controlled test resources; never arbitrary sensitive host files.
• IDOR / BOLA uses controlled identities/resources (Subject A/Resource A vs Subject B/Resource A); never broad enumeration.
• Command injection / RCE uses controlled canaries and non-destructive deterministic markers; the default proof never executes arbitrary system commands. No reverse shells, persistence, credential dumping or data destruction.
• CORS distinguishes configuration observation, origin reflection, credentialed behavior and actual exploitable impact — never claims exploitable CORS from Access-Control-Allow-Origin exists.
• Security misconfiguration prevents configuration-only findings from being auto-promoted to confirmed vulnerabilities without exploitable-condition evidence.
• Dependency / known vulnerable component verifies identity, version, affected range, reachability and applicability — public exploits are never executed automatically.

9. Novel Vulnerabilities & Strategy Learning

When no strategy matches, the flow is: unknown behavior → generic proof strategy (strategy.unknown_behavior / strategy.unknown_class) → evidence discovery → minimal reproducible proof → StrategyCandidate → human/AI review → strategy proposal. Candidates move PROPOSED → UNDER_REVIEW → APPROVED (or REJECTED / DEPRECATED); only APPROVED candidates become production strategies. Novel strategies are never automatically promoted and UNKNOWN_BEHAVIOR never permits confirmation on its own.

10. Manual Validation

When automation cannot safely establish proof the system supports MANUAL_REQUIRED and produces a ManualProofInstruction (objective, preconditions, steps, expected observation, evidence to capture, safety notes, scope, completion criteria). This lets HunterX assist a human pentester without falsely claiming automatic validation.

11. Persistence (TIDB)

New TIDB entities (migration e1f2a3b4c5d6, down_revision d4a5b6c7e8f0): ProofStrategy, ProofStrategyVersion, ProofStrategyRequirement, ProofStrategyEvidenceRule, ProofStrategyToolRequirement, ProofStrategyCandidate, ProofValidationResult, ProofManualInstruction — tables tidb_proof_strategies, tidb_proof_strategy_* and tidb_proof_validation_results/tidb_proof_manual_instructions. There is no second database. Persistence is generic via SqlCrudRepository / RowMapper / InMemoryCrudRepository.

Security boundary: these tables store strategy contracts, canonical evidence rules and validation results — never exploit payloads, credentials, unrestricted executable PoC scripts or out-of-scope request material.

12. Knowledge Graph

The service updates the graph through KnowledgeGraphPort: uses_strategy (ValidationResult → Strategy), has_validation_result (Proof → ValidationResult), requires_capability (Strategy → Capability) and has_strategy_candidate (Candidate node).

13. Events

Typed events on the bus (category EventCategory.VULNERABILITY): proof.strategy.selected, proof.strategy.blocked, proof.strategy.missing_evidence, proof.validation.started, proof.validation.completed, proof.validation.failed, proof.validation.inconclusive, proof.validation.contradicted, proof.manual_required, proof.strategy.candidate_created, proof.strategy.approved, proof.strategy.rejected.

14. Reporting

StrategyReportBuilder produces a StrategyReportView that explains WHY a proof was (or was not) validated: the security property, the selected strategy, required/present/missing/contradictory evidence, replay results and the impact legitimately claimed. Reports never expose secrets.

15. Capability Manifest

16. Testing

• Unit — domain models, registry (immutability/versioning/deprecation), selector (evidence/safety/scope/capability), validator (all verdicts, contradiction, target-state, evidence contract, quality levels), TIDB mapping (tests/unit/test_proof_strategy_*.py).
• Component — full service pipeline through in-memory stores (tests/component/test_proof_strategy_service.py).
• Integration — platform wiring, event catalog, TIDB persistence (tests/integration/test_proof_strategy_platform.py).
• Acceptance — the 45 sprint acceptance criteria end-to-end (tests/acceptance/test_proof_strategy_acceptance.py).
• Golden — tests/golden/proof_strategy/scenarios.json (26 deterministic scenarios: confirmed SQLi, non-vulnerable SQLi, scanner-only false positive, XSS, SSRF callback/mismatch, LFI, IDOR, BOLA, safe RCE canary, auth bypass, CORS exploitable/header-only, CSRF, open redirect, dependency, cloud misconfiguration, novel behavior, replay mismatch, target changed, scope mismatch, unsafe proof, missing evidence).
• Security — strategy poisoning, malicious strategies, evidence poisoning, target-content injection, contradictory-marker injection, cross-mission / cross-target contamination, unsafe escalation, scope bypass, tool capability spoofing (tests/security/test_proof_strategy_security.py).
• Performance — large registry, large evidence matrix, validation throughput, large finding sets, concurrent selection (tests/performance/test_proof_strategy_benchmarks.py).
• Architecture — layer resolution, domain purity, no concrete tools, no cycles, application port policy, reporting purity, strategies never execute tools directly (tests/architecture/test_proof_strategy_architecture.py).

17. Security

The strategy layer refuses strategy poisoning, malicious strategies, destructive safety classes, allowed/forbidden overlaps, evidence poisoning, target-content prompt injection, contradictory-marker injection, cross-mission and cross-target contamination, unsafe strategy escalation, scope bypass and tool capability spoofing. Evidence dominates model belief; contradictory evidence is never confirming; PROOF_NOT_EXECUTABLE never fabricates proof; manual validation is never falsely claimed as automatic.