06 — Tool Adapter SDK

Status: Ratified Version: 1.0.0 Applies to: All tool integrations, tools/<tool-id>/adapter.py Schema: config/plugin.schema.yaml (adapter plugins), 07 - Tool Knowledge Base Specification.md

1. Purpose

The Tool Adapter SDK defines the contracts that every integrated tool must satisfy to be executable, parseable, and reasoned about by HunterX. Adapters are the bridge between the platform and an arbitrary external tool (binary, library, remote service).

An adapter has exactly one job: execute a tool in a standard, safe, and observable way and produce canonical output. Parsing/normalization happen in separate, adapter-owned components (parser.py, normalizer.py) so that the adapter stays focused.

2. Adapter Taxonomy

A single integration may implement multiple adapter types (e.g., nuclei as both ScannerAdapter and ValidationAdapter).

3. Common Contract (BaseAdapter)

Every adapter must implement:

Shared input/output types (defined in hunterx.plugins.sdk):

• ToolRequest: target_id, scope (envelope), args (safe argv), env_allowlist, timeout_s, resource_limits, correlation_id, profile (tool profile name).
• ToolResult: exit_code, stdout, stderr, duration_ms, outcome (SUCCESS/PARTIAL/FAILED/TIMEOUT/VIOLATED), artifacts (paths to raw outputs).
• ParsedItem: normalized seed structure with source_line, raw reference.
• CanonicalEvent: a typed event (finding.created, service.discovered, …) conforming to 08 - Unified Security Schema.md.

4. Adapter Lifecycle

discover (registry scan of tools/)
  → validate (knowledge.yaml + adapter import + healthcheck)
  → register (adapter catalog)
  → execute (per request)
       ├─ preflight (scope check, healthcheck, secret binding)
       ├─ sandbox run (process/container)
       ├─ capture output (streamed)
       ├─ parse
       ├─ normalize
       ├─ validate
       └─ emit CanonicalEvents + ToolResult
  → unload (on removal/update)

5. ScannerAdapter

Contract additions:

class ScannerAdapter(BaseAdapter):
    def scan(self, request: ScanRequest) -> ScanResult: ...   # convenience wrapper
    def discover(self, request: ScanRequest) -> Iterable[ServiceFinding]: ...

• Declares which detection classes it can confirm (from the tool knowledge file).
• ScanResult aggregates ToolResult + parsed findings + performance stats.
• Must honor request.scope (targets/ports/paths) exactly; overscope → VIOLATED.

6. CrawlerAdapter

Contract additions:

• crawl(seed_urls) -> Iterable[UrlDiscovered]
• Produces canonical URL, Endpoint, Directory, Parameter events.
• Respects robots/allow-rules per mission profile (configurable; default obey).
• Bounds: max_depth, max_pages, same_origin, concurrency.

7. EnumeratorAdapter

Contract additions:

• enumerate(target, mode) -> Iterable[AssetDiscovery]
• Produces Domain, Subdomain, Host, IP, Certificate events.
• mode values: passive, active-light, active-full, bruteforce — each gated by mission profile approval level.

8. AnalyzerAdapter

Contract additions:

• analyze(inputs: AnalyzeInput) -> Iterable[AnalysisFinding]
• inputs may be source code (SAST), container image, config, IaC.
• Produces Finding + optional Technology/Misconfiguration events.
• Never mutates inputs; read-only analysis.

9. ReporterAdapter

Contract additions:

• render(report_models: ReportBundle) -> ReportArtifact
• Consumes canonical report models only (never raw findings) to produce an output artifact (e.g., custom JSON-Lines export, CSV).
• Registered with the Reporting Engine renderer registry by format name.

10. ValidationAdapter

Contract additions:

• validate(finding: Finding, evidence: Evidence) -> ValidationVerdict
• Verdict: CONFIRMED, REFUTED, INCONCLUSIVE, PARTIAL.
• May run a PoC against a copy/lab or with explicit operator approval for destructive checks (per mission profile).
• Returns structured ValidationResult with reproduction steps + evidence refs.

11. Adapter & Tool Knowledge Integration

An adapter MUST be paired with a Tool Knowledge File (07 - Tool Knowledge Base Specification.md). The knowledge file is the contract of record for:

• Which CLI syntax to emit (safe argv builder).
• Supported modes/profiles the adapter can request.
• Expected output formats (which parsers to apply).
• Error code → outcome mapping (normalize errors).
• Performance expectations (rate limits, timeouts).
• AI usage rules (what the AI may do with this tool’s results).

The adapter references knowledge via describe()['knowledge_id'] and the ToolExecutor (see 02 - Architecture.md §5.9) resolves and binds them.

12. Safety Contract (mandatory for all adapters)

1. No direct subprocess from adapter code. All execution goes through tools/sandbox.py (the sandboxed executor).
2. Args are structured (argv lists), never shell strings. No sh -c.
3. Scope enforcement: adapter must check every target/port/path against the scope envelope before invocation; any deviation → VIOLATED outcome, no run.
4. Timeouts & limits are always applied (from request, not adapter defaults).
5. Secrets: credentials are injected by the sandbox from SecretPort by declared names; never accepted as free-form argv.
6. Destructive actions (sqlmap --dbs on live DB, payload writes) require the mission profile’s destructive_allowed flag; otherwise blocked at the executor.
7. Observability: every execution emits tool.started, tool.completed / tool.failed with correlation id, duration, outcome, and artifacts.
8. Isolation: untrusted tool output is never evaluated/executed; it is parsed by declarative parsers only.

13. Error Handling Contract

• Adapter raises AdapterError subclasses: ToolMissingError, ToolTimeoutError, ToolCrashedError, ScopeViolationError, ParseError, UnsupportedModeError.
• Each carries a machine code (see 17 - Error Handling Standards.md) and is mapped to a ToolResult.outcome.
• Retryability is declared per error class: transient (retryable) vs permanent.
• Healthcheck failures degrade gracefully: the tool is marked unavailable and the workflow routes around it (see 17 §Graceful Degradation).

14. Versioning & Compatibility

• Adapters use SemVer; a tool’s adapter version is independent of the tool’s version (the knowledge file binds tool_version ranges).
• healthcheck() reports tool version; executor compares against knowledge.tool.supported_versions and warns on mismatch.
• Adapter ABI is versioned via sdk_min in the manifest.

15. Packaging

Each adapter ships in tools/<tool-id>/:

adapter.py        # implements one or more contracts above
parser.py         # parser for tool output (streamed)
normalizer.py     # canonical mapping
knowledge.yaml    # Tool Knowledge File (mandatory)
workflows.yaml    # workflow position rules
mission_rules.yaml# mission applicability
ai_rules.yaml     # AI usage rules
tests/            # adapter/parser/normalizer tests
README.md         # tool documentation

Full checklist: 22 - Tool Integration Standard.md.

16. Testing an Adapter

• Unit: execute with canned outputs (fixtures), assert parse/normalize.
• Integration: run real tool binary (marked, skippable in CI without tools).
• Golden: known-good tool outputs → expected canonical events.
• Security: overscope argv rejected; shell injection attempt neutralized; secrets never leaked into stdout/errors.
• See 15 - Testing Standards.md.

17. References

• 02 - Architecture.md §5.9 (Tool SDK & Adapter Layer)
• 07 - Tool Knowledge Base Specification.md (paired knowledge contract)
• 22 - Tool Integration Standard.md (full integration checklist)
• 13 - Security Standards.md (sandbox & execution security)