HunterX v7 Safe Vulnerability Discovery & Validation Engine

Status: Ratified (Sprint 019 / Wave 13) Version: 1.0.0 Owner: HunterX Architecture Council

1. Purpose / Scope

The Safe Vulnerability Discovery & Validation Engine is the capability that safely transforms:

OBSERVATION → HYPOTHESIS → VALIDATION PLAN → SAFE TEST → OBSERVATION → EVIDENCE → VERDICT

It consumes the intelligence produced by Waves 07–12 (web, JavaScript, API, authentication, authorization, cloud & SaaS, technology, asset and vulnerability knowledge & risk correlation), formalizes testable vulnerability hypotheses, selects a safe validation strategy, produces a deterministic validation plan, executes approved non-destructive checks through the Tool Integration SDK, normalizes tool output into canonical observations, collects provenance-backed evidence, evaluates a deterministic verdict, persists everything to the TIDB, updates the knowledge graph, reports the outcome and diffs it against previous missions.

Hard constraints:

• Not an exploit engine. No RCE, destructive commands, data deletion, database modification, credential dumping, password spraying, credential stuffing, persistence, privilege escalation, lateral movement, malware deployment, reverse shells, shell payload execution, denial-of-service, resource exhaustion, data exfiltration, production-impacting exploitation or weaponized exploit execution is ever scheduled.
• Scope-gated execution. Before every validation action the engine resolves target, asset, endpoint, mission scope, authorization, exclusions, tool permission and validation permission. If any required scope decision is UNKNOWN, the action is refused with SCOPE_BLOCKED.
• SDK-only execution. Every probe flows through the guarded ExecutionEngine lifecycle — no validation code invokes subprocess directly.
• Raw output is never a verdict. Tool output is parsed and normalized into canonical observations before the verdict engine may consume it.
• Detection never equals validation; validation never equals exploitation. A CONFIRMED state requires an explicit validation rule that permits confirmation plus sufficient, consistent evidence.

Scope: src/hunterx/domain/vulnerability_validation/, src/hunterx/application/vulnerability_validation.py, src/hunterx/tools/safe_validation/, src/hunterx/reporting/validation.py, the vulnerability.validation.* event catalog, the tidb_validation_*/tidb_vulnerability_hypotheses TIDB entity set and the platform wiring in src/hunterx/platform/assembler.py.

Out of scope: weaponized exploitation, remediation automation (a future controlled capability), and any second workflow engine — validation steps run through the existing Mission/Workflow/Execution infrastructure.

2. Design Goals

• Deterministic. Identical input produces identical hypotheses, plans, evidence, verdicts and differentials.
• Explainable. Every verdict carries a reason, evidence ids, confidence, rule ids and the analysis version.
• Reproducible. Validation version, rule version, tool version, tool configuration hash, input/output hashes, target state and timestamps are all persisted.
• Scope-aware and safety-aware. Fail-closed gates refuse unknown scope and any unsafe action.
• Fully auditable. Policy decisions, evidence provenance, verdicts and history are all persisted; every gate decision is recorded.
• Non-confirming by default. Only explicit validation rules may grant a CONFIRMED verdict.

3. Architecture

domain/vulnerability_validation/        Pure domain (models, enums, state machine,
                                        rules, scope/safety gates, planner, tool
                                        selection, normalizer, evidence, verdict,
                                        history/differential).
application/vulnerability_validation.py Orchestration service (the engine loop).
tools/safe_validation/                  Safe-probe tool adapters + registry.
domain/entities/tidb/validation.py      TIDB system-of-record entities.
infrastructure/db/sql/tidb_models/validation_models.py  ORM projection.
alembic/versions/…                      Migration a1b2c3d4e5f6.
domain/events/catalog.py + types.py     vulnerability.validation.* event stream.
reporting/validation.py                 Validation report views and builder.
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

OBSERVE   → consume Wave 07–12 intelligence
HYPOTHESIZE → create a VulnerabilityHypothesis
PLAN      → ValidationPlanner produces a ValidationPlan of safe steps
SCOPE CHECK → ValidationScopeEnforcer (fail-closed)
SAFETY CHECK → SafetyEnforcer (destructive/forbidden refused)
SELECT TOOL → ValidationToolSelector via TIP + SDK registration/health
SAFE PROBE → ExecutionEngine.execute (guarded SDK lifecycle)
NORMALIZE → ValidationNormalizer → canonical observations
COLLECT EVIDENCE → EvidenceBuilder (provenance + hashes + redaction)
VERIFY    → VerdictEngine (deterministic, rule-driven)
SCORE CONFIDENCE → verdict.confidence (deterministic)
PERSIST   → TIDB validation entities
GRAPH     → KnowledgeGraphPort relationships
REPORT    → ValidationReportBuilder
DIFF      → ValidationDifferencer (temporal)

4. Vulnerability State Machine

Canonical states: UNKNOWN → OBSERVED → SUSPECTED → HYPOTHESIS → VALIDATION_PLANNED → VALIDATION_RUNNING → VALIDATED → CONFIRMED → FALSE_POSITIVE → INCONCLUSIVE → RESOLVED → REOPENED.

Rules (enforced by VulnerabilityStateMachine):

• Detection (OBSERVED/SUSPECTED) never transitions directly to VALIDATED/CONFIRMED.
• CONFIRMED requires a validation rule that permits confirmation.
• FALSE_POSITIVE refutes a hypothesis; INCONCLUSIVE keeps it open with insufficient or conflicting evidence — the two are never conflated.
• RESOLVED and REOPENED manage the remediation lifecycle.

5. Vulnerability Hypothesis

VulnerabilityHypothesis (domain/vulnerability_validation/models.py) carries: hypothesis_id, mission_id, target_id, asset_id, finding_id, vulnerability_id, technology_id, type, description, preconditions, expected_behavior, unexpected_behavior, confidence, priority, scope, safety_class, validation_strategy, created_at, created_by, analysis_version and the current state. Its canonical deduplication key is hypothesis:<asset>|<vulnerability_id>|<technology_id>.

Hypotheses are created by VulnerabilityValidationService.create_hypothesis, persisted to tidb_vulnerability_hypotheses and announced via vulnerability.hypothesis.created.

6. Validation Contract & Rules

Every supported vulnerability class has a deterministic ValidationRule (ValidationRuleSet): strategy, required/confirmation evidence, permits_confirmation, safe checks, forbidden actions, expected/unexpected behavior, inconclusive conditions, explicit false-positive predicates, risk level and scope requirements. The built-in rule set covers known-vulnerable software/components, security misconfiguration, broken access control, authentication, injection family, SSRF, XSS, path traversal, file inclusion, deserialization, command injection, CORS, CSRF, open redirect, sensitive information exposure, cloud/container exposure, API authorization/authentication, cryptographic failures and dependency vulnerabilities.

The forbidden-action set is universal: rce, shell-payload-execution, reverse-shell, credential-dumping, password-spraying, credential-stuffing, data-deletion, database-modification, persistence, privilege-escalation, lateral-movement, malware-deployment, denial-of-service, resource-exhaustion, data-exfiltration, weaponized-exploit-execution.

7. Validation Plan

ValidationPlanner.plan turns a hypothesis into a ValidationPlan of ValidationSteps. Each step is a safe check derived from the rule’s safe checks (or the strategy default), with per-step timeout, retryability, rate limit and safety class. Plans are persisted to tidb_validation_plans / tidb_validation_steps and announced via vulnerability.validation.planned.

8. Execution

VulnerabilityValidationService.run_validation walks the phases:

1. Scope validation — ValidationScopeEnforcer.decides (fail-closed).
2. Target readiness — scope not expired, no stop condition.
3. Evidence review — preconditions/evidence review.
4. Preconditions — rule requirements satisfied.
5. Safe probe selection — ValidationToolSelector via TIP + SDK registration/health.
6. Execution — ExecutionContextBuilder + ExecutionEngine.execute with bounded permissions derived from the step’s safety class (PASSIVE → ("none",), READ_ONLY/BENIGN_MARKER/CONTROLLED → ("network",)).
7. Response collection — ExecutionResult.output.json.
8. Normalization — ValidationNormalizer → canonical ValidationObservations.
9. Evidence correlation — EvidenceBuilder (concrete expected vs observed).
10. Verdict — VerdictEngine.evaluate.
11. Persistence — TIDB.
12. Reporting — ValidationReportBuilder.

The engine enforces rate limits (ValidationRateLimiter), stop conditions (stop_check) and mission cancellation before every action, and records every gate decision as a ValidationPolicyDecision.

9. Tool Selection

ValidationToolSelector selects tools by capability, target type, validation class, safety, health, version, rate limit and required privileges. Selection first consults the Tool Intelligence Platform; the deterministic fallback prefers registered, healthy safe-validation tools (passive-probe, version-probe, error-behavior-probe). The SDK health check is honored before execution; unregistered or unhealthy tools are never run.

10. Scope Enforcement

ValidationScopePolicy + ValidationScopeEnforcer are fail-closed:

• Unknown or empty scope → refuse (scope_blocked).
• Expired scope → refuse (scope-expired).
• Exclusions always win.
• The asset must resolve inside the authoritative targets and/or the explicit allow-list.
• Wildcard/dot-suffix attempts do not expand scope (app.example.com.evil.com and *.example.com are not wildcard matches).

11. Safety Enforcement

SafetyPolicy + SafetyEnforcer:

• DESTRUCTIVE safety class is always refused and can never be configured.
• Actions whose names match the forbidden set are refused.
• Parameters carrying forbidden markers (rm -rf, $(, -e /bin/sh, nc -e, eval(, os.system, …) are refused.
• Mission profiles (BUG_BOUNTY, PENTEST, RED_TEAM, SECURITY_ASSESSMENT) tighten (never loosen) allowed classes, concurrency and rate limits.

12. Evidence

Every evidence record preserves: evidence_id, mission/target/asset/hypothesis, tool id and version, request metadata (redacted), timestamp, input_hash / output_hash (SHA-256), the canonical observation, a redacted response excerpt, expected vs observed behavior, the EvidenceComparison (match, partial_match, mismatch, no_comparison), confidence, provenance and integrity metadata. Sensitive values are redacted before persistence.

The comparison is signal-driven: a concrete expected value comes from the observation metadata (expected); without one the comparison is no_comparison, so prose can never produce a false match or mismatch.

13. Verdict Engine

VerdictEngine.evaluate is fully deterministic:

• CONFIRMED only when the rule permits_confirmation, the confirmation evidence kinds are present, evidence is consistent (no conflicting match+mismatch) and confidence meets the rule minimum.
• VALIDATED when positive evidence supports the hypothesis but the rule does not permit confirmation.
• FALSE_POSITIVE when evidence mismatches the expected behavior and no positive evidence exists.
• INCONCLUSIVE for insufficient, ambiguous or conflicting evidence — never conflated with FALSE_POSITIVE.
• SCOPE_BLOCKED / SAFETY_BLOCKED / EXECUTION_FAILED are first-class verdicts for blocked runs.

14. False Positives

Explicit false-positive predicates are evaluated by the verdict engine and documented per rule: version-not-affected, fixed-version-observed, different-vendor/product, false-technology-detection, synthetic/proxy/WAF responses, authentication/authorization boundaries, non-production environments, insufficient evidence and scope mismatch. A mismatch between observed and concrete expected behavior refutes the hypothesis.

15. Temporal State & Differential Analysis

ValidationHistoryStore tracks per-target/hypothesis first-seen, last-seen, verdicts, confirmation and state. ValidationDifferencer compares current hypothesis snapshots against previous missions and emits ValidationDifferentials with DifferentialChange values: new, still_vulnerable, fixed, reappeared, changed_evidence, changed_technology, changed_version, changed_exposure, changed_confidence, changed_status.

16. Events

Typed events published on the bus (category EventCategory.VULNERABILITY):

vulnerability.hypothesis.created, vulnerability.validation.planned, vulnerability.validation.started, vulnerability.validation.step.started, vulnerability.validation.step.completed, vulnerability.validation.blocked, vulnerability.validation.failed, vulnerability.evidence.created, vulnerability.verdict.created, vulnerability.confirmed, vulnerability.false_positive, vulnerability.inconclusive, vulnerability.resolved, vulnerability.reopened, vulnerability.validation.completed.

17. Persistence

New TIDB entities (migration a1b2c3d4e5f6, down_revision ec9883419830): VulnerabilityHypothesis, ValidationRule, ValidationPlan, ValidationStep, ValidationExecution, ValidationEvidence, ValidationVerdict, ValidationHistory, ValidationDifferential, ValidationToolUsage, ValidationPolicyDecision — tables tidb_vulnerability_hypotheses and tidb_validation_*. All relationships are explicit through the entity fields; there is no separate validation database. Entities are registered in domain/entities/tidb/__init__.py, ORM models in infrastructure/db/sql/tidb_models/__init__.py (the only registry step), and persistence is generic via SqlCrudRepository/RowMapper/InMemoryCrudRepository.

18. Knowledge Graph

The engine updates the knowledge graph through KnowledgeGraphPort: has_hypothesis (Asset → Hypothesis), references_cve (Hypothesis → Vulnerability), has_validation_evidence (Hypothesis → Evidence) and has_validation_verdict (Hypothesis → Verdict).

19. Reporting

The engine’s PHASE 11 produces JSON-safe report data (aggregated verdicts, hypotheses, evidence, executions, tool usage, policy decisions and differentials) carried on ValidationRunResult.report; build_report replays persisted records into the same shape. The reporting layer (hunterx/reporting/validation.py) exposes ValidationReportBuilder / ValidationReportView for structured rendering, and ValidationReportView.from_data rebuilds a view from the engine’s report data. The report covers: validation summary, confirmed/validated/suspected vulnerabilities, false positives, inconclusive tests, scope-blocked and safety-blocked tests, evidence inventory, validation timeline, risk changes, remediation-relevant evidence, tool execution summary, confidence summary and reproducibility information.

20. Remediation Boundary

This capability explains why a vulnerability is relevant, what evidence demonstrates it, what component/version is affected and which security property appears violated. It never automatically modifies the target. Remediation automation is a future controlled capability.

21. Capability Manifest

22. Testing

• Unit — domain models, state machine, rules, scope/safety gates, planner, tool selection, normalizer, evidence, verdict, history/differential, TIDB registry/mapper (tests/unit/test_validation_*.py).
• Component — service pipeline through in-memory stores (tests/component/test_validation_service.py).
• Integration — platform wiring, TIDB persistence, events, graph, reports (tests/integration/test_validation_platform.py).
• Acceptance — golden-scenario verdicts, detection≠validation, persist/replay, temporal differential, scope/safety distinction (tests/acceptance/test_validation_acceptance.py).
• Golden — tests/golden/validation/scenarios.json (18 deterministic scenarios incl. WAF/proxy interference, cloud exposure, API authorization, dependency vulnerability, fixed/unknown versions).
• Security — scope bypass, wildcard/subdomain errors, redirect/dns-rebinding drift, command/shell injection via parameters, raw-output poisoning, evidence poisoning, verdict manipulation, cross-target/cross-mission leakage, secret redaction, report injection, resource exhaustion, unbounded loops (tests/security/test_validation_security.py).
• Performance — hypothesis creation, validation runs, verdict evaluation, large evidence/hypothesis sets, historical differential (tests/performance/test_validation_benchmarks.py).
• Architecture — layer resolution, import policy, cycles (tests/architecture/test_validation_architecture.py).

23. Security

The engine refuses scope bypass, wildcard and subdomain scope errors, redirect and DNS-rebinding-like scope changes, command/argument/shell injection through tool parameters, malformed or poisoned tool output, evidence/verdict manipulation, cross-target and cross-mission evidence leakage, credential and secret leakage, log/report injection and resource exhaustion. Conflicting evidence is never confirming; raw tool output is never a verdict.