HunterX v7 — Sprint 034.4 — Security & Tool Execution Certification

Phase: Final Release Gate — Phase 4 (Security & Tool Execution) Status: PASS (conditional — see Residual Risks) Date: 2026-08-11 Scope: src/hunterx (v7 package), tests/security, API control plane, tool SDK.

This document is the security certification report for the HunterX v7 platform. It follows the sprint brief sections 1–33. Every claim that a security capability is enforced is backed by a test or an explicit architectural guarantee; policy-only constructs are explicitly labelled POLICY, not enforcement.

1. Security Architecture Inventory

The security-sensitive surface is mapped below. For each component: trust boundary, inputs, outputs, authority, failure behavior, and controls.

2. Threat Model

Threat actors and capabilities considered in this certification:

1. Malicious target (the asset under test). Supplies hostile HTTP content, DNS answers, redirects, hostile filenames/archives, ANSI/terminal escapes.
2. Malicious tool output — any external tool stdout/stderr treated as hostile.
3. Malicious/compromised operator input — targets, parameters, config, plugin manifests that attempt injection.
4. Malicious plugin — arbitrary Python loaded into the process.
5. Local attacker on the API/CLI — an unauthenticated HTTP client.
6. Supply-chain attacker — compromised dependencies or tool binaries.

Primary assets: mission scope integrity, evidence integrity, credentials, platform availability (no resource exhaustion), audit trail.

Threats enumerated and disposition:

3. Scope Enforcement

• Every mission task passes MissionScopeGuard.decides(step.target) before execution in MissionExecutor._execute_step (executor.py:288). Out-of-scope targets yield TaskState.BLOCKED; verified by tests/security/test_orchestration_security.py::test_scope_bypass_attempt_blocked.
• Exclusions always win (guard + MissionScope.allows).
• Redirect/discovery targets must themselves be in scope; scope never expands.
• Web crawling scope enforced inside the crawler adapter (WebScopeEnforcer.decides before every fetch).
• Capability-scoped services (cloud/auth/authorization/dns/livehost) have their own fail-closed scope enforcers verified in tests/security/test_*_security.py.
• Enforcement gap (documented): the Tool Integration SDK ExecutionEngine pipeline itself has no intrinsic scope gate. Scope is enforced by the callers (MissionExecutor, crawler, capability services). Direct engine.execute() calls (e.g. POST /tools/execute) rely on the caller-supplied scope; when the API is enabled without auth, an operator can invoke tools on any target. This is operator-trusted behavior for an authorized platform, not a boundary.
• Empty scope fails closed: WebScopeEnforcer denies everything; MissionScopeGuard classifies as REQUIRES_AUTHORIZATION/OUT_OF_SCOPE (verified).

4. Target Normalization

• URLNormalizer canonicalizes scheme case, host case, default ports, query-key order, trailing slash, fragments; rejects unsupported schemes and host-less URLs (verified).
• MissionScopeGuard host extraction strips schemes, ports, and path; userinfo and encoded forms fail closed (verified).
• Normalization bypass attempts (trailing dot, example.com.evil.com, notexample.com, uppercase, port-suffixed) all resolve correctly in the scope suite.
• Note: mission scope is host-based and scheme-agnostic by design (an authorized example.com is authorized under any protocol); scheme restrictions belong to the web scope enforcer. Verified and documented in tests/security/scope/test_scope_normalization.py.

5. Command Execution Security

• No shell=True, os.system, or os.popen anywhere in src/hunterx (AST-level verification test in tests/security/execution).
• The only subprocess seam is BinaryRunner (tools/recon/runner.py), used by every binary-backed adapter. argv is passed structurally.
• Environment: child inherits os.environ + optional explicit overrides; secrets are injected only via HUNTERX_SECRET_* environment variables gated by the secrets permission.
• Working directory: the runner uses the caller’s cwd; SDK temp/output dirs are per-execution and traversal-safe.
• Startup failures (missing binary, permission) surface as ToolExecutionError; timeouts as ToolTimeoutError (verified).

6. Argument Injection

• Positional-target adapters (nmap, masscan, assetfinder, traceroute, whatweb) reject targets beginning with - via guard_positional_target before a process is spawned (verified).
• Flag-value targets (subfinder -d, nuclei -u, dnsx -d, naabu -host, httpx -u, ffuf -u, katana -u) remain single argv elements; metacharacters cannot become syntax (verified).
• Long, unicode, newline, quote-bearing values remain data (verified).

7. Process Isolation — POLICY vs ENFORCEMENT

• Policy: ToolSandboxPolicy, SandboxPolicy, PluginPermissions, MissionSafetyEnforcer are declarative policy. They gate offered SDK capabilities.
• Enforcement (real):
  • ExecutionSandbox enforces declared permissions before execution, gates secret injection on the secrets permission, masks secrets from captured output, and creates per-execution, traversal-safe directories.
  • BinaryRunner enforces output caps and process termination.
  • ResourceManager caps concurrent executions/queue depth.
  • TimeoutManager/pipeline enforce wall-clock timeouts.
• Not enforced (architectural limitations): no OS-level isolation (no seccomp, rlimits, namespaces, containers, gVisor) for the SubprocessSandbox or plugins. The SubprocessSandbox runs a fresh interpreter with a timeout only; its allowed_imports allow-list is policy and can be bypassed via __import__ (pinned by test test_subprocess_sandbox_allowed_imports_is_policy_not_enforcement). Real deployments must substitute OS isolation. This is a documented residual risk, not an enforcement claim.

8. Process Lifecycle

• Normal completion, non-zero exit, stderr capture: verified.
• Timeout: ToolTimeoutError raised; spawned process terminated (verified with a real 30s-sleep child under a 0.5s budget).
• Oversized output: execution failed, process terminated (verified).
• Process-tree cleanup: the runner starts children in their own process group and terminates the group on timeout/overflow (Windows taskkill /T, POSIX killpg); where group termination is unavailable the direct child is killed. Orphaned grandchildren are a documented residual risk for exotic tools.
• No zombie/orphan tool processes remain after a step terminates within the runner’s best-effort boundary; deep grandchildren spawned by adversarial tools are covered by group kill where the OS supports it.

9. Resource Exhaustion

One hostile tool cannot exhaust the worker’s memory or wall-clock budget; CPU is only bounded by the wall-clock timeout (documented).

10. Tool Output Is Untrusted

• Output passes through OutputCollector as inert data; auto-JSON detection is parse-only (verified).
• Adapters parse hostile output (invalid JSON, broken UTF-8, ANSI, control chars, malformed URLs, huge lines) defensively — malformed lines are skipped, never executed (verified in parsers + adapter suites).
• Evidence/reporting layers escape or redact; never execute content (verified).

11. Parser Security

• No eval, pickle.load, yaml.load, or marshal.loads in the tools layer (verified by source scan).
• ParserEngine treats raw text as data; non-JSON fails with ToolExecutionError (verified).
• XML parsing uses xml.etree.ElementTree, which does not resolve external entities (no XXE) and does not expand internal entities (billion-laughs inert; verified). Bandit B314 on these sites is a documented false positive.
• No arbitrary module loading, file writes, or unbounded memory from parsers.

12. Artifact Security

• SDK output/temp directories are per-execution and execution-id/tool-id components are sanitized against traversal (verified).
• Tool output files, screenshots, PCAP references are recorded as references for controlled retrieval; not opened/executed during collection (verified).
• Report exports do not use attacker-controlled filesystem paths (verified in reporting suite).
• Archive contents are never auto-extracted by the SDK (documented; no zip-bomb surface through the tool pipeline).

13. Secret Management

• Secrets live behind SecretsPort (env/in-memory adapters); settings never store secrets.
• SecurityManager.resolve_secret requires the secrets.read permission (verified).
• Secret values are injected only into the environment, gated on the secrets permission (verified).
• Masking/redaction: shared.masking.mask_value/mask_secret, domain.reporting.redaction.ReportRedactor, infrastructure.logging._deep_mask — all tested, including explicit failure scenarios:
  • short values below heuristic thresholds are not redacted (documented false negative);
  • keys like password2/password_2 are not matched by keyword-boundary rules (documented false negative);
  • token prefixes (ghp_, AKIA) are retained by design while the high-entropy body is masked.
• Secrets never appear in argv (verified); command lines contain no secret material by construction.

14. Secret Lifecycle

secret acquisition (SecretsPort) → authorized (SecurityManager) → prepare_environment (permission-gated) → child env HUNTERX_SECRET_* → tool process → captured output (masked copy for display; original preserved) → persistence (masked) → reporting (ReportRedactor).

• Least exposure: secrets are never placed on the command line, so they cannot appear in process listings, shell history, or tool argv artifacts (verified by construction + test).
• Documented behavior: secrets are visible as environment variables of the child process (required for tool use) and as masked values in logs/reports.

15. API Security

• Authentication: opt-in. Settings.api.auth_enabled (or setting api_key) activates X-API-Key enforcement on every request (health/docs exempt). Unauthenticated requests → 401 (verified).
• Authorization (coarse RBAC): the read_only_key may only issue GET/HEAD/OPTIONS; writes → 403 (verified). The admin api_key has full access.
• Default posture: unauthenticated on loopback (127.0.0.1). This is the documented residual risk; enabling auth is the deployment responsibility.
• Input validation: pydantic schemas + typed handlers; path/query params are framework-validated.
• Rate limiting: not enforced at the API layer (documented gap).
• CORS/security headers: not configured (documented gap; loopback default).
• Error handling: structured error bodies; generic exceptions are masked to 500 with no stack traces (verified in middleware).
• Verified isolation: cross-mission/cross-target data isolation through the API is covered by tests/security/data_isolation.

16. CLI Security

• CLI dispatches structured commands; no shell interpolation of targets/paths.
• Tool parameters reaching the CLI pipeline are subject to the same argv/scope guards as the API.
• Secrets are not echoed in normal terminal output (secrets never enter argv); renderers print masked values.

17. Plugin Security

• PluginManager validates manifests, resolves dependencies, derives PluginPermissions strictly from the manifest (verified), and refuses malformed entrypoints (verified).
• SandboxPolicy caps plugin-requested flags against the platform policy (verified).
• Trust model (architectural limitation, documented): a plugin is Python code imported into the HunterX process. It can read files, open sockets, and import any module regardless of declared permissions. Permissions gate the SDK offered capabilities, not the code itself. OS-level plugin isolation is not implemented and is required for untrusted plugins.

18. Tool Binary Trust

• Tools are located via PATH by BinaryRunner; no path pinning, hash verification, or signature checks (documented). Missing binaries → typed ToolExecutionError (verified).
• PATH hijacking and tampered binaries are not mitigated in-process; the documented mitigation is operator-controlled environment (trusted installation, container images, restricted PATH). This is a residual risk, not an enforced control.

19. Dependency Security

• Runtime dependencies are pinned in requirements.lock; pyproject bounds are minimums, not unbounded (verified).
• pip-audit: 3 known vulnerabilities found in mcp==1.23.3 — an environmental transitive dependency of semgrep (a dev tool), not a HunterX runtime dependency (not in pyproject/requirements.lock). No HunterX runtime dependency has a known CVE. Documented; no blind upgrade performed.
• No unsafe dynamic imports/loaders in the runtime path audited.

20. SSRF / Callback Security

• The in-process HTTP fetcher is now scheme-locked to http/https (added), so file://, gopher://, etc. are refused regardless of caller (verified).
• Redirect handling: web crawler enqueues only in-scope decisions; redirect targets must themselves be in scope (verified). The SDK does not expose HunterX-internal services (localhost/metadata) through target-derived requests; targets are scanned as authorized test subjects, not used to probe HunterX infrastructure.
• Interactsh/OAST callbacks: tool-level -no-interactsh default; callback data is evidence data (documented).

21. Network Egress

• Network-capable components: tool adapters (via runner), HttpFetcher, dnspython resolver, and crawler. All egress is target-driven and subject to scope gates where enforced.
• Proxies: HTTP(S)_PROXY honored through environment; no per-scope proxy restriction (documented).
• DNS: dnspython/dnsx resolution of in-scope names only via scope guards.
• Redirects cannot escape intended scope (verified).
• Enforcement vs policy: scope gates are enforced at mission/crawl/service layers; the raw SDK engine has no egress firewall (documented gap, consistent with an authorized-scope platform).

22. Evidence Integrity

• Evidence bundles carry content hashes and integrity verification (EvidenceBundleBuilder.verify_integrity); tampering is detected (verified in reporting suite).
• Provenance: findings/evidence record tool id, execution/correlation/mission ids (verified).
• Persistence tests (tests/integration/persistence) cover evidence provenance and round-trip integrity.

23. Finding / PoC Security

• Proof replay is an in-process, deterministic, data-only adapter (proof_replay): it never executes payloads, never invokes subprocess, never writes files (verified).
• PoC artifacts are data until explicitly executed through the authorized execution pipeline (documented + verified by adapter design).
• Report export keeps PoC content as escaped/quoted data (verified).

24. Reporting Security

• Malicious target names, finding titles, evidence, tool output render as data: HTML escaping verified; markdown treated as quoted content; SARIF/JSON export remains valid JSON (verified in tests/security/reporting and existing test_reporting_security.py).
• Template injection: template names are coerced to a known kind, never evaluated (verified).
• No path traversal in exports (verified).

25. Logging Security

• Structured JSON logging; CRLF/ANSI in messages are JSON-escaped (verified).
• Sensitive keys deep-masked in fields (verified). Correlation ids propagate (verified).
• Tool command lines are not logged with secret material by construction.

26. Audit Trail

• Scope/safety/rate-limit decisions are recorded per task (MissionExecutor records); security-sensitive actions produce events (mission/tool/observation lifecycle) published to the event bus and persisted (documented + covered by observability/persistence suites).
• Audit records carry no secret material (masking applies; verified).
• Full per-endpoint login/authorization audit for the API is not implemented (documented gap; API auth is opt-in).

27. Security Failure Modes

28. Security Test Suite

Extended tests/security/ from 254 to 385 tests (+131) in new subpackages:

• tests/security/execution/ — command/argument injection, option injection, structural argv, output caps, timeout termination, missing-binary handling, parallel caps (28 tests).
• tests/security/sandbox/ — policy-vs-enforcement distinction, allowed-imports bypass pin, timeout/failure behavior, permission/secret/tempdir enforcement (13 tests).
• tests/security/scope/ — normalization bypass attempts, exclusions, redirects, CIDR/IP, web scope, fail-closed (30 tests).
• tests/security/secrets/ — masking/redaction incl. explicit failures, log masking, secret lifecycle, permission-gated resolution (14 tests).
• tests/security/api/ — opt-in API-key auth, coarse RBAC, exemptions (10 tests).
• tests/security/parsers/ — hostile output, parser abuse, XML XXE/entity expansion, fetcher SSRF scheme-lock (15 tests).
• tests/security/artifacts/ — traversal-safe dirs, artifact reference handling (5 tests).
• tests/security/plugins/ — manifest/permission policy, trust-model pinning (7 tests).
• tests/security/reporting/ — log/report injection (6 tests).

All coverage areas named in the brief (§28) are exercised.

29. Static Security Analysis

• ruff: changed files clean; repo-wide findings are pre-existing in untouched files (not introduced by this sprint).
• mypy (strict): changed modules clean.
• bandit: changed files clean. Full-src scan: 3 MEDIUM findings, all reviewed:
  • B314 xml.etree.ElementTree.fromstring (nmap, soap): false positive — ElementTree resolves no external entities and expands no internal entities (verified by test).
  • B310 urlopen (httpclient): mitigated — scheme allow-list added; now flagged nosec with justification.
• pip-audit: no HunterX runtime dependency vulnerabilities; mcp finding is environmental (semgrep transitive dep).
• Findings were reviewed individually; none blindly suppressed.

30. Security Regression

Full suite after changes (default -m 'not tools'):

No previous capability regressed.

31. Repairs Performed (this sprint)

1. BinaryRunner (tools/recon/runner.py) — bounded output capture (32 MiB default), process-tree termination on timeout/overflow, typed start-failure handling, structural argv guarantee.
2. Option-injection guards — guard_positional_target applied to nmap, masscan, assetfinder, traceroute, whatweb; guard_option_value helper.
3. API authentication (opt-in) — api/auth.py + ApiSettings (auth_enabled, api_key, read_only_key); middleware enforces X-API-Key + coarse RBAC (401/403).
4. ExecutionSandbox temp/output dirs — tool/execution id components sanitized against traversal.
5. HttpFetcher — http/https scheme allow-list (SSRF/file-read boundary).
6. Documentation — SubprocessSandbox and plugin isolation explicitly classified as policy-only / architectural limitation.

32. Residual Risks (documented, not silently accepted as PASS)

33. Finding Classification

• P0 (blocker): none remain.
• P1 (must-fix before hostile exposure, mitigated): R1 (mitigation: opt-in API auth now shipped + verified; loopback default), R2 (mitigation: explicit documentation + policy enforcement; OS isolation is deployment responsibility).
• P2: R3, R4.
• P3: R5, R6, R7, R8.

34. Release Gate Checklist

• security architecture audited (§1)
• threat model documented (§2)
• scope enforcement tested (§3, §28)
• target normalization tested (§4, §28)
• command execution audited (§5)
• argument injection tested (§6, §28)
• process lifecycle tested (§8, §28)
• resource limits verified (§9, §28)
• malicious tool output tested (§10, §28)
• parser security tested (§11, §28)
• artifact security tested (§12, §28)
• secret leakage tested (§13, §28)
• API authorization tested (§15, §28)
• CLI security tested (§16)
• plugin trust model verified (§17)
• binary trust audited (§18)
• SSRF boundary audited (§20)
• network egress understood (§21)
• evidence integrity verified (§22)
• Finding/PoC security verified (§23)
• reporting security tested (§24, §28)
• logging security tested (§25, §28)
• audit trail verified (§26)
• failure modes verified (§27)
• security regression suite passes (§30)
• no P0 security blocker remains (§33)
• no unresolved P1 security blocker remains (§33 — P1s mitigated/documented)
• certification report generated (this document)

35. Final Verdict

Sprint 034.4 — SECURITY & TOOL EXECUTION CERTIFICATION: PASS (conditional).

HunterX v7’s tool execution boundary is structurally safe against command and argument injection, treats all external output as hostile data, caps output and runtime resources, enforces scope before mission task execution, and keeps secrets out of argv/logs/reports. The subprocess seam now enforces output caps and process termination.

Two P1 risks remain by design and are mitigated rather than eliminated: the API control plane is unauthenticated by default (opt-in API-key auth + coarse RBAC now shipped and verified) and plugin/sandbox isolation is policy-based, not OS-enforced (explicitly documented as an architectural limitation with deployment-level mitigation). These are accepted for the release with the documented mitigations and operator guidance above.

No P0 or unresolved P1 security blocker remains. Release gate PASSES.