White Hat Agent Core

A model-neutral cyber capability brain for AI agents and human researchers.

Turn community knowledge, exact program scope, adapter capabilities, evidence, and agent fleets into one composable application layer—available through MCP, JSON Schema, Python, or the wha CLI.

Install or update in one command

macOS, Linux, and WSL

curl -LsSf https://raw.githubusercontent.com/kappa9999/white-hat-agent/main/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/kappa9999/white-hat-agent/main/install.ps1 | iex

Run the same command again whenever you want to update. The installer is idempotent: it finds or installs uv, provisions an isolated Python 3.12 runtime, refreshes White Hat Agent from GitHub, and places wha on the user tool path. It does not require administrator privileges or modify an existing project.

Prefer to inspect remote scripts before running them? Read install.sh or install.ps1, then follow the audited and source-install options in the installation guide.

Related MCP server: Qdrant Neo4j Crawl4AI MCP Server

Start in 60 seconds

wha init white-hat-workspace
cd white-hat-workspace
wha doctor
wha corpus search "http differential"
wha adapter list reverse
wha adapter status ghidra

wha init creates an ordinary, portable workspace containing the starter corpus, capability and adapter catalogs, configuration, and local state. Re-running it is safe and never overwrites existing public catalog files.

Connect the installed CLI to any stdio MCP client:

{
  "mcpServers": {
    "white-hat-agent": {
      "command": "wha",
      "args": [
        "serve",
        "--workspace",
        "/absolute/path/to/white-hat-workspace",
        "--transport",
        "stdio"
      ]
    }
  }
}

See MCP integration for Streamable HTTP, PATH troubleshooting, and client-neutral configuration.

Give an agent the tools it needs

White Hat Agent maps concrete tools and knowledge sources to the existing provider-neutral capability vocabulary. It prefers healthy tools already on the host and never installs as a side effect of search, planning, or fleet work.

# Resolve the smallest provider set and expose any install/conformance gap.
wha adapter resolve --kind tool \
  --capability artifact.inspect --capability binary.behavior-identify

# Resolve, update, provision dependencies, and fixture-conform in one explicit call.
# This selects Ghidra for native RE and OWASP WSTG for experiment design.
wha adapter ensure --yes \
  --capability binary.static-inspect --capability experiment.design

# Inspect the exact official release and SHA-256 without changing the host.
wha adapter plan ghidra --out ghidra-plan.json

# Explicit provider-specific install/update remains available for manual control.
wha adapter install ghidra --yes

# Prove one exact operation before agents can claim its capability.
# Fixed command-backed version checks run only here, inside the offline sandbox.
wha adapter conform ghidra
wha adapter status ghidra
wha adapter resolve --capability binary.static-inspect

# Give a mobile-analysis agent a reviewed Android static map.
wha adapter install jadx --yes
wha adapter conform jadx
wha adapter resolve --capability mobile.static-inspect

# Recover Go build, function, type, source, and string metadata from local binaries.
wha adapter ensure --yes --capability binary.go-symbol-recover
wha adapter conform goresym
wha adapter resolve --capability binary.go-symbol-recover

# Recursively map archives, firmware containers, filesystems, and compressed streams.
wha adapter ensure --yes --capability artifact.recursive-unpack
wha adapter resolve --capability artifact.recursive-unpack

# Evaluate a standalone signature against one immutable artifact.
wha adapter install yara-x --yes
wha adapter conform yara-x
wha adapter resolve --capability artifact.signature-match

# Turn an existing PCAP or PCAPNG into a bounded protocol and stream map.
wha adapter conform tshark
wha adapter resolve --capability network.capture-inspect

# Install current standalone Frida and map one local executable before main.
wha adapter install frida --yes
wha adapter conform frida --operation frida.executable-runtime-map
wha adapter resolve --capability binary.runtime-inspect

# Add and query exact, revision-bound machine-readable knowledge on demand.
wha adapter install mitre-attack --yes
wha adapter search mitre-attack T1059.001
wha adapter ensure --kind knowledge --capability weakness.lookup --yes
wha adapter search mitre-cwe CWE-79
wha adapter ensure --kind knowledge --capability experiment.design --yes
wha adapter search owasp-wstg "Test Objectives"

The initial nonredundant tool set covers Ghidra, GoReSym, Frida, LLVM, YARA-X, TShark, capa, and JADX. Ghidra and JADX reuse a valid host Java runtime when one passes conformance; otherwise the explicit ensure path installs a checksum-bound, workspace-local Eclipse Temurin JDK 21 and retries once. Reviewed typed drivers execute Ghidra summaries and native-code maps, Go-specific symbol and runtime metadata recovery, a fixed Frida pre-main executable runtime map, YARA-X signature evaluation, capa behavior identification, LLVM object inspection, JADX Android mapping, and TShark packet-capture mapping on Linux/WSL. Frida is provisioned from the exact current standalone official release asset and exposes no remote target, process, script, argument, or environment field. The TShark result retains packet order, protocol chains, transport streams, selected DNS/HTTP/TLS/QUIC/WebSocket metadata, and explicit truncation without exposing live capture or caller-defined decoder settings. All typed drivers run without network access over immutable fleet-task evidence. Status and resolution never execute discovered binaries; fixed command-backed version checks run only during explicit sandboxed conformance, and a version result alone grants no executable capability. Knowledge adapters cover MITRE ATT&CK STIX, the canonical MITRE CWE catalog, capa rules, and the revision-bound OWASP Web Security Testing Guide; CVE List V5, NVD 2.0, CISA KEV, OSV, and EPSS ingestion remains in the intelligence layer. See tools and knowledge adapters.

Start the production public-intelligence loop with bounded official sources:

wha intelligence sync \
  --source cisa-kev --source osv \
  --since-hours 48 --limit-per-source 1000 --enrich-epss --require-success
wha intelligence sync \
  --source cve-list-v5 \
  --since-hours 6 --limit-per-source 5000 --require-success
wha intelligence sync \
  --source nvd \
  --since-hours 6 --limit-per-source 5000 --require-success
wha intelligence brief --source osv --source cve-list-v5 --source nvd --limit 25
wha intelligence epss-history CVE-2023-44487 --as-of 2026-07-01

Every selected upstream record is backed by an immutable raw snapshot and transparent priority factors. Intelligence collection does not interact with affected targets; it produces evidence-backed leads for local or explicitly scoped investigation. EPSS history is stored outside normalized advisories so date-aware queries do not inflate every CVE record. See the production loop.

How it works

The diagram focuses on the campaign and discovery execution path; public intelligence feeds opportunity selection before the scope gate.

Models, tools, and adapter providers remain replaceable. Exact target identity, scope, evidence provenance, and replayable state remain durable.

Contribute knowledge without learning a schema

Write the method in your own language and let the intake boundary preserve it:

wha knowledge ingest \
  --file my-technique.md \
  --language es \
  --rights original-contribution \
  --playbook-yaml draft-playbook.yaml

The compiler keeps the exact source, segments likely steps, and lists unresolved questions. A generated file is a draft, not a claim that the method has been validated. Contributors can submit plain-language knowledge through the Knowledge contribution issue form without knowing Python, MCP, AI prompting, or the playbook schema.

See CONTRIBUTING.md, knowledge intake, and playbook authoring.

Compose and plan

The repository includes reproducible examples for composition, scope evaluation, campaign planning, fleet leasing, evidence binding, and discovery replay:

git clone https://github.com/kappa9999/white-hat-agent.git
cd white-hat-agent
uv sync --locked --extra dev

uv run wha playbook compose \
  --workspace . \
  --request examples/composition/web-to-verified.yaml

uv run wha campaign plan \
  --workspace . \
  --request examples/campaigns/planning-request.yaml

An incomplete or out-of-scope plan returns machine-readable blockers. It is never silently made executable. The bundled fixtures use reserved .test targets and perform no network operation.

Interfaces

• CLI: nested wha commands for workspace, intelligence, corpus, capabilities, adapters, scope, campaign, fleet, evidence, and discovery

• MCP: bounded, namespaced tools plus resources and prompts over stdio or stateless Streamable HTTP

• Python: typed models and deterministic planning/composition primitives

• JSON Schema: generated public contracts for every durable interchange object

Start a local Streamable HTTP server when a client needs it:

wha serve --workspace /absolute/path/to/white-hat-workspace --transport http --host 127.0.0.1 --port 8000
# endpoint: http://127.0.0.1:8000/mcp

Project status

Alpha: the knowledge compiler, composition engine, public vulnerability-intelligence monitor, scope evaluator, opportunity ranking, concrete adapter registry/provisioning and typed offline execution, SQLite fleet, evidence store, adaptive discovery kernel, MCP server, schemas, and deterministic fixtures are implemented. Network access is limited to fixed public intelligence sources and explicit official adapter upstreams. The repository does not ship a general target scanner; live target capability belongs in explicit adapters with exact campaign scope, not hidden inside the planner.

Corpus trust is earned per version:

draft → proposed → reviewed → validated → deprecated

Original text, technical validity, authorship, rights, target authorization, execution side effects, and disclosure status are separate facts. Untrusted submissions are data, never executable instructions.

Development

uv sync --locked --extra dev
uv run ruff format --check .
uv run ruff check .
uv run pytest
uv run wha corpus validate --workspace .
uv run wha capability validate --workspace .
uv run python scripts/check_builtin_assets.py
uv run python scripts/export_schemas.py
uv build

Project links

• Architecture

• Installation and updates

• MCP integration

• Tools and knowledge adapters

• Production intelligence and research loop

• Release provenance and recovery

• Changelog

• Roadmap

• Threat model

• Governance

• Security reporting

• Contributing

• Maintainers

Licensed under Apache-2.0.