22 — Tool Integration Standard

Status: Ratified Version: 1.0.0 Applies to: Every integrated tool; checklist for tools/<tool-id>/

1. Definition

A tool is integrated into HunterX only when the complete integration package described in this document exists, passes all gates, and is merged. A “half-integrated” tool is not an integration — it is a defect.

2. Mandatory Components

Every integrated tool MUST contain all of the following:

3. Component Contracts (summary)

3.1 Knowledge File (knowledge.yaml)

• Validates against config/knowledge.schema.yaml.
• Declares: metadata, capabilities, CLI model (safe argv), profiles (≥ fast/thorough/stealth/quiet), modes, input/output contracts, dependencies, error mapping, performance, workflow position, mission rules, AI rules.
• No secrets; no shell templates.

3.2 Adapter (adapter.py)

• Implements at least one contract from 06 (ScannerAdapter, CrawlerAdapter, EnumeratorAdapter, AnalyzerAdapter, ReporterAdapter, ValidationAdapter).
• Implemented methods: execute, parse, normalize, validate, healthcheck, capabilities, describe.
• All execution through the sandboxed executor; never direct subprocess.

3.3 Parser (parser.py)

• Streams output (iterator); no unbounded buffering.
• Declares accepted formats (from knowledge output.formats).
• Never evaluates input; declarative only.

3.4 Normalizer (normalizer.py)

• Maps parsed items → canonical CanonicalEvents (08 §4).
• Applies canonicalization (FQDN, CIDR, dedup keys, severity mapping).
• Uses 08 entity/event types; no free-form dicts.

3.5 Workflow Rules (workflows.yaml)

• Phases where the tool participates.
• Prerequisites/produces (which canonical events feed which steps).
• Typical sequence position and blocking semantics.
• See 07 §14 and 10.

3.6 Mission Rules (mission_rules.yaml)

• Applicable mission profiles (12).
• Per-mission overrides (modes, approval).
• Approval level (auto/operator/destructive-approval).
• Auth profiles the tool accepts.
• See 07 §15.

3.7 Target Database Mapping

• Every produced entity maps to 08 tables and graph edges (09 §10).
• Every consumed input type is declared in knowledge inputs.accepts.
• No entity invented outside USS (schema change required otherwise).

3.8 AI Rules (ai_rules.yaml)

• allowed (bool) and purposes/disallowed lists.
• grounding context requirements and token budget.
• Output usage permissions.
• Hallucination warnings.
• See 07 §16 and 11.

3.9 Tests

Minimum test set:

• Adapter unit: execute with canned outputs; asserts ToolResult fields.
• Parser unit: parse fixtures (valid, malformed, empty) → ParsedItems.
• Normalizer unit: canonical events match expected 08 mapping.
• Golden: data/golden/tools/<id>/ input→expected events.
• Integration: run real binary (marked @pytest.mark.tools), assert end-to-end.
• Security: overscope argv rejected; injection neutralized; no secret leak; prompt-injection on poisoned output handled.
• Coverage: ≥ 80% of parser+normalizer+adapter (15 §9).

3.10 Documentation (README.md)

• What the tool does, installation, profiles, modes, example runs, limitations.
• How findings map into USS; how AI may use results.
• Rollback/cleanup notes for side effects (17 §6).

4. Workflow for Adding a Tool

proposal (tool + justification + capability gap)
  → knowledge.yaml draft
  → adapter/parser/normalizer implementation
  → fixtures + goldens
  → integration on sandboxed target
  → security tests
  → docs
  → PR → CI gates → Architecture + Security review
  → merge → registry index update (tools/index.yaml)

5. Registry Index

tools/index.yaml maintains the shared capability vocabulary and maps:

capabilities:
  - id: vulnerability-scan
    tools: [nuclei, nikto, openvas]
  - id: subdomain-enum
    tools: [subfinder, amass]

• New capability ids require a review (shared vocabulary stability).
• Tool removal: deprecate in index, quarantine adapters, honor retention.

6. Quality Gates (fail = no merge)

• knowledge.yaml schema-valid.
• Adapter passes 06 contract tests (abstract base test suite).
• Parser/normalizer golden tests pass.
• Real-binary integration passes or is explicitly skipped with justification.
• Security suite passes.
• Coverage thresholds met.
• Docs complete per 16.
• No secrets, no shell templates, no direct subprocess.

7. Tool Maintenance

• Versioned: tool_versions range in knowledge; adapter SemVer independent.
• Upstream changes: re-run golden regeneration, bump tool_versions, re-test.
• Deprecation: mark deprecated: true, warn on use, remove per retention policy.
• Health: hunterx tool health monitors availability; outages degrade gracefully (17 §7).

8. References

• 06 - Tool Adapter SDK.md — adapter contracts
• 07 - Tool Knowledge Base Specification.md — knowledge file
• 08 - Unified Security Schema.md — canonical mapping
• 15 - Testing Standards.md — test requirements
• 17 - Error Handling Standards.md — failure handling for tools