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 init creates an ordinary, portable workspace containing the starter corpus, capability catalog, configuration, and local state database. Re-running it is safe and never overwrites existing corpus or capability 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.

How it works

flowchart TB
    subgraph Inputs["Inputs"]
        direction LR
        K["Community knowledge"]
        S["Scope and campaign"]
        C["Agent capabilities"]
    end

    T["1 · Ingest and trust<br/>Preserve sources · compile playbooks · review versions"]
    P["2 · Compose and plan<br/>Match artifacts · capabilities · scope · budgets"]
    D["3 · Dispatch and discover<br/>Lease typed work · run explicit adapters"]
    V["4 · Verify and remember<br/>Bind evidence · test causality · retain negatives"]
    O["Verified findings<br/>Reproducible reports · reusable learning"]

    K --> T
    S --> P
    C --> P
    T --> P --> D --> V --> O
    O -. reviewed learning .-> T

    classDef input fill:#f8fafc,stroke:#64748b,color:#0f172a,stroke-width:1px;
    classDef core fill:#eff6ff,stroke:#2563eb,color:#0f172a,stroke-width:2px;
    classDef output fill:#ecfdf5,stroke:#059669,color:#064e3b,stroke-width:2px;
    class K,S,C input;
    class T,P,D,V core;
    class O output;

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, corpus, capabilities, scope, campaign, fleet, evidence, and discovery

• MCP: 37 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, scope evaluator, opportunity ranking, SQLite fleet, evidence store, adaptive discovery kernel, MCP server, schemas, and deterministic fixtures are implemented. The repository does not yet ship autonomous Internet discovery or scanner adapters. Live 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

• Roadmap

• Threat model

• Governance

• Security reporting

• Contributing

• Maintainers

Licensed under Apache-2.0.