HunterX v7 Vulnerability Proof & PoC Validation Engine

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

1. Purpose / Scope

The Vulnerability Proof & PoC Validation Engine is the capability that safely transforms:

HYPOTHESIS → PROOF CONTRACT → REQUIRED EVIDENCE → MINIMAL PROOF STRATEGY →
PROOF CONSTRUCTION → SAFETY VALIDATION → SCOPE VALIDATION → EXECUTION →
REPLAY → EVIDENCE EVALUATION → IMPACT → CONFIDENCE → VALIDATED FINDING →
REPRODUCTION PACKAGE → REPORT

It consumes the validated vulnerability hypotheses produced by the Wave 13 Safe Vulnerability Discovery & Validation Engine, selects the vulnerability-specific proof contract, produces a deterministic proof plan, constructs a structured, machine-replayable Proof of Concept (PoC), executes and replays it through the Tool Integration SDK, captures provenance-backed evidence, evaluates the proof against the contract, assesses impact and evidence-driven confidence, advances the finding lifecycle, persists everything to the TIDB, updates the knowledge graph and produces a reproduction package suitable for authorized bug-bounty / pentest reporting.

The canonical capability model is:

AI-Assisted Vulnerability Discovery, Validation & Proof Engine

A vulnerability detection is NOT a validated finding. The engine maintains the distinction DETECTED → SUSPECTED → VALIDATING → VALIDATED → PROVEN → CONFIRMED → REPORT_READY and transforms a potential vulnerability into a validated finding that carries: Vulnerability + Evidence + Proof + Reproducibility + Impact + Confidence + Provenance.

Hard constraints:

• Not a weaponization engine. No data destruction, persistence, credential dumping, malware deployment, reverse shells, lateral movement, denial of service, resource exhaustion, mass data extraction, production-impacting exploitation, unrestricted database extraction, table dumping, credential attacks or weaponized exploit execution is ever scheduled. Proof means demonstrating the vulnerability with the minimum necessary interaction and minimum necessary impact.
• No unrestricted exploit generation. The engine never asks an LLM to “generate an exploit”; it derives a minimal, deterministic proof strategy from the proof contract.
• No arbitrary executable PoC pipeline. PoCs are structured artifacts (request templates, differential tests, configuration snapshots) — never arbitrary shell scripts, malware, persistence scripts or exploit chains.
• Scope-gated execution. Before every proof action the engine resolves scope, authorization, safety, proof policy and tool capability. If any required decision is UNKNOWN, the action is refused (BLOCKED).
• SDK-only execution. Proof replay flows through the guarded ExecutionEngine lifecycle — proof code never invokes subprocess directly.
• Raw tool output is never a verdict. Tool output is parsed and normalized into canonical observations before evidence → proof → replay → verdict.
• GENERATED does not mean VALIDATED; EXECUTED does not mean VALIDATED. A proof becomes VALIDATED only after successful replay and evidence evaluation against the proof contract.
• Impact is evidence-backed. Impact is never inferred merely because a vulnerability class is normally severe.

Scope: src/hunterx/domain/vulnerability_proof/, src/hunterx/application/vulnerability_proof.py, src/hunterx/tools/proof_replay/, src/hunterx/reporting/proof.py, the proof.*/poc.*/impact.assessed/confidence.calculated/finding.* event catalog, the tidb_proof_*/tidb_vulnerability_proofs/ tidb_finding_state_transitions TIDB entity set, the migration d4a5b6c7e8f0, the capability manifest capabilities/vulnerability-proof.json and the platform wiring in src/hunterx/platform/assembler.py.

Out of scope: weaponized exploitation, unrestricted exploit generation, autonomous exploit chains, arbitrary executable PoC scripts and any second finding, evidence or validation system — this capability extends the existing finding, evidence, validation, scope, safety, TIDB, event, graph and reporting foundations.

2. Design Goals

• Deterministic. Identical input produces identical proof plans, PoCs, replays, evidence, impact, confidence and findings.
• Explainable. Every confidence calculation and quality score is a weighted, auditable aggregate over named factors; every finding transition records its reason.
• Reproducible. A single successful replay never equals reproducible. Reproducibility is measured over repeated replays with consistent observation, stable preconditions and consistent evidence.
• Scope-aware and safety-aware. Fail-closed gates refuse unknown scope and any unsafe or non-minimal proof action.
• Evidence-driven. Confidence uses a versioned, configurable policy over factor scores — never a universal percentage or raw AI belief.
• Non-confirming by default. A finding becomes CONFIRMED only when its vulnerability-specific proof contract permits confirmation and confidence requirements are met.

3. Architecture

domain/vulnerability_proof/       Pure domain (enums, models, contracts,
                                   planner, policy, generation, replay,
                                   confidence, impact, quality, state,
                                   reasoning, temporal, evidence).
application/vulnerability_proof.py Orchestration service (the engine loop).
tools/proof_replay/               Deterministic safe proof-replay adapters.
domain/entities/tidb/proof.py     TIDB system-of-record entities.
infrastructure/db/sql/tidb_models/proof_models.py  ORM projection.
alembic/versions/d4a5b6c7e8f0_…   Migration.
domain/events/catalog.py + types.py proof.* / poc.* / impact.* / confidence.* / finding.*
reporting/proof.py                Proof report views + reproduction package.
platform/assembler.py             Composition-root wiring.

All dependencies flow through approved ports: the application service depends on ExecutionEngine, TidbRepositoryFactory, EventBusPort, KnowledgeGraphPort and ToolIntelligencePort. The domain package depends on domain and shared only.

3.1 The engine loop

HYPOTHESIZE → consume the validated hypothesis
CAN_I_PROVE_THIS? → ProofReasoningLoop (8 explicit questions)
PLAN       → ProofPlanner produces a ProofPlan of minimal safe steps
SCOPE CHECK → ValidationScopeEnforcer (fail-closed)
SAFETY CHECK → SafetyEnforcer (destructive/forbidden refused)
PROOF POLICY → ProofPolicyEnforcer (types, replay budget, step budget, size)
CONSTRUCT  → SafeProofGenerator builds a structured PoC (bounded, redacted)
EXECUTE    → ExecutionEngine.execute (guarded SDK lifecycle)
OBSERVE    → ValidationNormalizer → canonical observations
EVIDENCE   → ProofEvidenceBuilder (provenance + hashes + redaction)
REPLAY     → ReplayEngine (deterministic verdict + reproducibility)
VALIDATE   → contract evaluation (evidence + replay + behavior)
IMPACT     → ImpactAssessor (evidence-backed)
CONFIDENCE → ConfidenceEngine (versioned weighted policy)
FINDING    → FindingLifecycleStateMachine (PROVEN/CONFIRMED/REPORT_READY)
PACKAGE    → ReproductionPackage
PERSIST    → TIDB proof entities
GRAPH      → KnowledgeGraphPort relationships
REPORT     → ProofReportView

4. Why Proof is a First-Class Capability

A scanner detects; an assessment validates; a proof demonstrates and reproduces. HunterX treats proof as a first-class capability so that every finding can answer:

• “I found it.”
• “I tested it.”
• “I proved it.”
• “I reproduced it.”
• “I know what evidence proves it.”
• “I know what impact was actually demonstrated.”
• “I can explain exactly how the result was obtained.”
• “Another authorized analyst can reproduce the result.”

Raw tool output can never produce CONFIRMED, PROVEN or REPORT_READY directly — it must pass the canonical pipeline tool output → parser → normalizer → observation → evidence → proof → replay → verdict.

5. Finding Lifecycle

The finding lifecycle is extended beyond detection:

DETECTED → SUSPECTED → VALIDATING → VALIDATED → PROVEN → CONFIRMED → REPORT_READY
                                                     ↘ FALSE_POSITIVE
                                                     ↘ INCONCLUSIVE → SUSPECTED/…

Rules (enforced by FindingLifecycleStateMachine):

• Detection (DETECTED/SUSPECTED/VALIDATING) never equals proof.
• PROVEN requires a valid, reproducible proof.
• CONFIRMED requires the proof contract to permit confirmation and the confidence state to reach VALIDATED/CONFIRMED — a universal confidence percentage is never the sole confirmation rule.
• REPORT_READY requires the reportability contract: finding identity, affected asset/component, classification, evidence, proof, reproducible PoC, impact, confidence, scope, timestamp, provenance and remediation context.
• FALSE_POSITIVE refutes the hypothesis; INCONCLUSIVE keeps it open with insufficient, conflicting or non-reproducible evidence. The two are never conflated, and a PoC that fails is never automatically a false positive.

Transitions are recorded as FindingStateTransition records.

6. VulnerabilityProof

A VulnerabilityProof is not the vulnerability itself — it is the reproducible technical demonstration that validates a specific vulnerability hypothesis. It carries: proof_id, finding_id, hypothesis_id, validation_id, mission_id, target_id, asset_id, vulnerability_id, proof_type, proof_strategy, proof_status, reproducibility_status, safety_class, scope, preconditions, steps, inputs, expected_behavior, observed_behavior, evidence_ids, impact_evidence_ids, replay_count, successful_replays, failed_replays, confidence, created_at, validated_at, analysis_version, proof_version and provenance.

6.1 Proof states

NOT_AVAILABLE → CANDIDATE → PLANNED → GENERATED → EXECUTED → REPLAYED →
VALIDATED → SUPERSEDED
                          ↘ BLOCKED → CANDIDATE/PLANNED/GENERATED
                          ↘ FAILED → CANDIDATE/PLANNED/INVALIDATED
                          ↘ INCONCLUSIVE → CANDIDATE/PLANNED/GENERATED
VALIDATED → INVALIDATED / SUPERSEDED

Rules: GENERATED does not mean VALIDATED; EXECUTED does not mean VALIDATED. A proof becomes VALIDATED only after successful replay and evidence evaluation according to the proof contract. The ProofStateMachine rejects a direct EXECUTED → VALIDATED transition.

7. Proof Contracts

Every supported vulnerability class has a deterministic ProofContract that defines: required preconditions, allowed and forbidden actions, required evidence, expected result, failure/inconclusive conditions, replay requirements, impact requirements, minimum confidence, safety class, scope requirements, whether confirmation is permitted and whether the finding is reportable. The built-in registry covers SQL/NoSQL injection, XSS, SSRF, path traversal, file inclusion, broken access control, API authorization/authentication, authentication, open redirect, CORS, sensitive information exposure, security misconfiguration, dependency vulnerabilities, known vulnerable components, cloud exposure, command-injection indicators and UNKNOWN_BEHAVIOR (novel).

The universal forbidden-action set is: data-destruction, persistence, credential-dumping, malware-deployment, reverse-shell, lateral-movement, denial-of-service, resource-exhaustion, mass-data-extraction, production-impacting-exploitation, unrestricted-database-extraction, table-dumping, credential-attack and weaponized-exploit-execution.

Per-class emphasis:

• SQL injection: baseline request vs comparison request, behavioral difference, reproducible observation — prove injection, never extract data.
• XSS: input location, reflection context, encoding behavior, minimal proof markers.
• SSRF: controlled callback infrastructure, correlation token + timestamp match; never cloud metadata unless explicitly authorized.
• LFI / path traversal: controlled proof resources, expected vs observed content; never unrelated sensitive system files.
• IDOR / BOLA: authorized test identities; Subject A/Resource A vs Subject B/Resource A comparison; no broad enumeration.
• Authentication: controlled identities and credentials, minimal requests, state comparison.
• Authorization: authorized vs unauthorized request comparison.
• Known vulnerable component: component identity, version, vendor, affected range, exposure, independent evidence; a public exploit is never executed merely because a CVE exists.

8. Proof Planning

ProofPlanner.plan turns a proof + hypothesis into a ProofPlan of minimal safe ProofSteps derived from the contract’s allowed actions (or a deterministic proof-type default). Plans carry preconditions, required_tools, scope, safety_policy, expected_observations, evidence_requirements, stop_conditions, abort_conditions, replay_requirements and impact_requirements. The plan is executed through the existing Tool Integration SDK — the proof engine never creates a second execution engine.

9. Safe Proof Generation

SafeProofGenerator.generate constructs a structured ProofOfConcept from the plan and contract. Generation is deterministic and safety-validated:

• inputs are bounded (_MAX_INPUT_LENGTH), refuse forbidden markers (rm -rf, $( , -e /bin/sh, eval( , INSERT INTO, …) via UnsafeProofInputError, and redact secret-looking values (secret/token/ password keys, sk-, ghp_, bearer, …) before the PoC is returned;
• the expected result is derived deterministically from the proof inputs (expected, then marker, then contract prose);
• the PoC is a structured artifact with steps, inputs, replay_policy and safety_policy — never an arbitrary executable script.

PoCs are immutable artifacts: a changed PoC becomes a new version (version, parent_version, reason, changes) via SafeProofGenerator.new_version.

10. Proof Policy

ProofPolicy + ProofPolicyEnforcer bound every proof action: allowed safety classes (never destructive), allowed proof types, a replay budget (bounded by ABSOLUTE_MAX_REPLAYS), a step budget, a maximum input size and a reportability default. Proof policy is additive on top of scope + safety and can only ever tighten (never loosen) the mission-profile defaults.

Every proof action passes:

Scope → Authorization → Safety Policy → Proof Policy → Tool Capability → Execution

If any required condition is unknown the engine BLOCKS.

11. Proof Execution

execute_proof walks: scope gate → safety gate → proof-policy gate → stop check → SDK execution (ExecutionContextBuilder + ExecutionEngine.execute with bounded permissions derived from the step’s safety class) → normalization → evidence capture. proof-replay is the deterministic in-process replay adapter; it only ever emits canonical observations from already-gated inputs.

Proof execution always flows through the Tool Integration SDK — proof code never invokes subprocess directly.

12. Replay

ReplayEngine.replay evaluates one deterministic replay: it hashes the inputs, configuration and evidence, and computes a ReplayVerdict (SUCCESS/FAILED/ INCONCLUSIVE/BLOCKED) by comparing observed vs expected behavior. replay_proof replays the PoC up to the proof-policy budget (bounded; replay loops are impossible by construction) and records ProofReplay records with replay_id, poc_version, proof_version, tool_id/tool_version, target_state, input_hash, configuration_hash, evidence_hash, expected/ observed behavior, result and timestamp.

Reproducibility (reproducibility_status) is measured over repeated replays: REPRODUCIBLE requires at least two successful replays with no failures; PARTIAL for mixed outcomes; NOT_REPRODUCIBLE when nothing reproduced; NOT_ASSESSED when no replay ran. A single “executed once” is never “reproducible”.

13. Evidence Integration

Proof evidence reuses the existing validation evidence engine — there is no second evidence system. ProofEvidenceBuilder wraps EvidenceBuilder with the vulnerability.proof producer provenance and links every record to the proof via ProofEvidence. The canonical pipeline is always: tool output → parser → normalizer → observation → evidence → proof → replay → verdict. Raw tool output never becomes proof.

14. Impact Assessment

ImpactAssessor classifies impact strictly from captured evidence. Categories: CONFIDENTIALITY, INTEGRITY, AVAILABILITY, AUTHORIZATION, AUTHENTICATION, DATA_EXPOSURE, ACCOUNT_IMPACT, RESOURCE_ACCESS, BUSINESS_LOGIC, CLOUD_RESOURCE_EXPOSURE. Level is derived from the strongest positive comparison and evidence confidence — impact is never inferred merely because a vulnerability class is normally severe. ImpactAssessment records the evidence ids, reasoning, confidence, scope and assessment version.

15. Confidence Model

ConfidenceEngine computes evidence-driven confidence over named factors: detection evidence, behavioral evidence, independent verification, impact evidence, PoC reproducibility, evidence quality, scope certainty and target stability. Weights are configurable through a versioned ConfidencePolicy (policy id confidence-policy/1.0.0); the conceptual example weights are never hard-coded into the engine. Every ConfidenceAssessment records the policy id, factor scores, weights, calculation version and evidence references. Confidence states (LOW/MEDIUM/HIGH/VALIDATED/CONFIRMED) come from configurable thresholds, and CONFIRMED can never be reached unless the proof contract permits confirmation.

16. Novel Vulnerabilities (UNKNOWN_BEHAVIOR)

The engine supports novel/unknown behavior:

Unknown Behavior → Observation → Hypothesis → Experiment → Unexpected Result →
New Hypothesis → Minimal Proof Strategy → Replay → Evidence → Candidate Novel Finding

A novel finding remains CANDIDATE until sufficient evidence exists. The unknown_behavior proof contract never permits confirmation and is not reportable — a novel finding must be independently validated before it can enter the normal finding lifecycle.

17. CAN_I_PROVE_THIS?

ProofReasoningLoop.can_prove asks eight explicit questions for every validated hypothesis:

1. What exact security property is violated?
2. What is the minimum evidence needed?
3. Can the evidence be obtained safely?
4. What is the smallest reproducible proof?
5. Can the proof be replayed?
6. What impact can actually be demonstrated?
7. What uncertainty remains?
8. Is the evidence sufficient for confirmation?

If any gate fails the loop resolves to INCONCLUSIVE, NOT_PROVABLE or BLOCKED.

18. Temporal Proof & PoC Versioning

ProofTemporalDifferencer compares proof snapshots over time and detects: FIRST_PROVEN, STILL_PROVEN, INVALIDATED, FIXED, REAPPEARED, CHANGED_BEHAVIOR, CHANGED_EVIDENCE, CHANGED_POC. ProofHistory records per-proof state over time.

PoCs are immutable; a changed PoC becomes a new version (parent_version records the lineage, reason/changes describe the change, validation_state tracks it).

19. False Positives & Inconclusive

A PoC that fails must NOT automatically create a false positive. The engine returns INCONCLUSIVE when the target changed, preconditions changed, WAF changed behavior, network was unstable, the authentication state changed, the tool failed or evidence was insufficient. FALSE_POSITIVE requires evidence that the original hypothesis was incorrect. INVALIDATED is reserved for a proof that was refuted or superseded.

20. Persistence (TIDB)

New TIDB entities (migration d4a5b6c7e8f0, down_revision c7d3e9f1a4b8): VulnerabilityProof, ProofContract, ProofPlan, ProofStep, ProofExecution, ProofOfConcept, ProofReplay, ProofEvidence, ProofPolicyDecision, ImpactAssessment, ConfidenceAssessment, ProofQuality, FindingStateTransition, ProofHistory — tables tidb_vulnerability_proofs, tidb_proof_* and tidb_finding_state_transitions. There is no second database. All relationships are explicit through the entity fields; persistence is generic via SqlCrudRepository/RowMapper/InMemoryCrudRepository.

Security boundary: these tables store safe-proof metadata, canonical observations and redacted evidence only — never exploit payloads, never credentials, never arbitrary executable PoC scripts.

21. Knowledge Graph

The engine updates the knowledge graph through KnowledgeGraphPort: has_proof (Hypothesis → Proof), has_poc (Proof → PoC), has_proof_evidence (Proof → Evidence), has_replay (Proof → Replay), has_impact (Proof → Impact), has_confidence (Proof → Confidence) and finding_transition (Proof → Transition).

22. Events

Typed events published on the bus (category EventCategory.VULNERABILITY): proof.created, proof.planned, proof.started, proof.step.started, proof.step.completed, proof.generated, proof.executed, proof.replay.started, proof.replay.completed, proof.validated, proof.failed, proof.blocked, proof.inconclusive, proof.invalidated, poc.created, poc.validated, impact.assessed, confidence.calculated, finding.proven, finding.confirmed, finding.report_ready.

23. Reporting

The final finding report answers WHAT is vulnerable, WHERE, WHY, HOW it was validated, WHAT evidence proves it, WHAT PoC demonstrates it, CAN the PoC be reproduced, WHAT impact was demonstrated, WHAT confidence exists, WHAT assumptions remain, WHAT tool produced the evidence, WHEN it was validated and WHAT scope authorized the test. Reports never expose secrets.

The ReproductionPackage is a structured artifact containing the finding summary, affected asset, preconditions, PoC, replay instructions, expected and observed results, evidence references, impact evidence, tool information, validation timestamp, scope information and version information — suitable for authorized bug-bounty/pentest reporting.

24. Capability Manifest

25. Testing

• Unit — domain enums/models, state machines, contracts, planner, safe generation, replay verdicts, reproducibility, impact, confidence, quality, reasoning, temporal, TIDB registry/mapper (tests/unit/test_proof_*.py).
• Component — full service pipeline through in-memory stores (tests/component/test_proof_service.py).
• Integration — platform wiring, TIDB persistence, events, graph, report (tests/integration/test_proof_platform.py).
• Acceptance — golden scenarios incl. scope/safety-blocked proofs and the end-to-end report-ready package (tests/acceptance/test_proof_acceptance.py).
• Golden — tests/golden/proof/scenarios.json (21 deterministic scenarios: confirmed SQL injection, non-vulnerable SQL, XSS candidate, controlled XSS, SSRF callback, SSRF false positive, IDOR comparison, authorization false positive, path traversal, fixed/vulnerable dependency, authentication bypass, insufficient evidence, conflicting evidence, replay success/failure, target changed, PoC invalidated, novel behavior, scope blocked, safety blocked).
• Security — scope bypass, wildcard/subdomain errors, redirect-like target drift, DNS-rebinding stop condition, shell-marker inputs, destructive safety class, forbidden actions, replay budget, wrong-target replay, failed-replay ≠ false-positive, secret redaction, cross-target leakage, raw-output never confirms, bounded inputs, no unbounded loops (tests/security/test_proof_security.py).
• Performance — proof creation, full runs, replay evaluation, confidence calculation, large evidence/proof sets, large temporal differentials (tests/performance/test_proof_benchmarks.py).
• Architecture — layer resolution, import policy, cycles, source parsing (tests/architecture/test_proof_architecture.py).

26. Security

The engine refuses scope bypass, wildcard and subdomain scope errors, redirect and DNS-rebinding-like scope changes, command/argument/shell injection through proof inputs, malformed or poisoned tool output, evidence poisoning, cross-target and cross-mission evidence leakage, secret and credential leakage, replay loops, unbounded proof generation, resource exhaustion and report injection. Conflicting evidence is never confirming; raw tool output is never a verdict; GENERATED/EXECUTED never equal VALIDATED; and a finding reaches REPORT_READY only when the reportability contract is satisfied.