# Hunter

Hunter is an MCP-first framework for authorized security assessment. It separates
candidate discovery from reproducible verification, keeps HTTP execution behind a
single RequestBroker boundary, and records proof state through the Event Kernel.

The project is designed for controlled assessments, CTF environments, local labs,
and software or infrastructure you are authorized to test.

**179 core MCP tools · 105 reverse extensions (`re_*`) · 12 CVE-specific scanner ports**

## 🤖 One-Click Install

**Option A — single command (recommended, no AI review needed):**

```
bash <(curl -fsSL https://raw.githubusercontent.com/GeniusHu-tgty/Open-tgtylab/main/tgtylab-files/install.sh)
```

This installs both OpenTgtyLab and Hunter, wires them together, and verifies everything — fully automated. Run it yourself, or ask any AI assistant to run it.

**Option B — AI prompt (aihot-style):**

```
Install the OpenTgtyLab security research workbench and the Hunter security framework (they are one system, install and connect them together):
https://github.com/GeniusHu-tgty/Open-tgtylab
https://github.com/GeniusHu-tgty/Hunter
Tell me when it's done and whether I need to start a new session.
```

The AI will read [AI-INSTALL.md](AI-INSTALL.md) (the install protocol), detect your environment, install both projects, wire them together, and verify everything automatically.

**After install, verify with `tgty`** — the agent should reply with the exercise framework status:

```
「红队演习」
代号：Ghost | 战队：open-tgtylab
框架：ACTIVE
状态：READY
```

The repo also ships [install.sh](install.sh) — `bash install.sh --target claude` installs to `~/.agents/skills/hunter` (the shared Agent Skills directory that Claude Code discovers as MCP). It clones, validates, installs dependencies and external scanners, then atomically swaps into place.

## What Changed

The current architecture is evidence-oriented rather than scanner-oriented:

```text
discover -> low-cost candidate discovery and proxy audit
probe    -> baseline / probe / post-baseline through RequestBroker
verify   -> Experiment + Oracle + Event Kernel attestation
race     -> health precheck + RaceCoordinator + state oracle
```

`discover` does not create a full evidence chain. Verified findings require the
appropriate control path, durable artifacts, and a verdict recorded by the Event
Kernel.

## Core Architecture

### RequestBroker

All legacy auto tools use a requests-compatible
`LegacyRequestsAdapter(RequestBroker(...))`. The adapter preserves `get`, `post`,
and `request` call patterns while the broker owns:

- response projections for HTML and JSON;
- WAF, CAPTCHA, rate-limit, login redirect, and soft-ban classification;
- per-origin and identity-scoped cooldown state in SQLite/WAL;
- compact, content-addressed artifacts with retention and quota rules;
- baseline/probe/post-baseline control groups;
- isolated `IdentityPool` credentials and BrowserPool handoff data.

Runtime defaults live in [`config.yaml`](config.yaml). The broker reads its
`request_broker` section for cooldown, blocking, and artifact quota settings.

### Evidence And Workflows

The Event Kernel is the source of truth for workflow state, action attempts,
evidence manifests, attestations, verdicts, and recovery checkpoints. Raw network
bodies stay in Broker artifacts; the Event Kernel records canonical identifiers
and digests instead of copying unbounded response data.

Response-driven verification, OAST, authorization proof, and race experiments
all converge on the same evidence and verdict path. A WAF page, CAPTCHA, timeout,
or missing cleanup plan is inconclusive, not a vulnerability finding.

### Browser, MITM, And External Tools

Browser integration is optional (`hunter[browser]`). When a Playwright backend is
not available, browser workflows return a structured
`missing_inputs=["browser_pool_available"]` result without disabling other tools.

The MITM controller is fail-closed for protected external CLI work. Tool trust is
measured with a local HTTPS probe; untrusted tools remain `candidate_only` and do
not silently fall back to direct protected scanning.

## CVE-Specific Scanner Ports (v8.4)

12 bingo-derived CVE/technique scanners, all Broker-gated, evidence-first,
safe-probe only (never execute real RCE gadgets):

| Tool | Target | Verify |
|------|--------|--------|
| `hunter_cve_panos` | CVE-2025-0108 PAN-OS auth bypass | double-encoded path traversal → PHP exec |
| `hunter_cve_ingress` | CVE-2025-1974 K8s IngressNightmare | admission controller exposure + injection surface |
| `hunter_cve_druid` | CVE-2025-27888 Druid SSRF | proxy endpoint → cloud metadata / internal |
| `hunter_cve_ivanti` | CVE-2026-10520 Ivanti Sentry RCE | handleMessage commandexec (read-only) |
| `hunter_cve_mssql2025` | SQL2025 AI feature exfil | sp_invoke_external_rest_endpoint surface |
| `hunter_cve_redis_repl` | CVE-2026-23631 Redis UAF | version + permission detection (no UAF) |
| `hunter_cve_nextjs_sxss` | Next.js 0-click cache-poison SXSS | header reflection + cacheability |
| `hunter_cve_cswsh` | CSWSH + EXE exposure → 0-click RCE | EXE exposure + WS handshake |
| `hunter_cve_cf_acme` | Cloudflare ACME validation bypass | HTTP-01 validation differential |
| `hunter_cve_aruba_xxe` | ArubaOS pre-auth XXE→OOB SSRF | OOB callback → VERIFIED, else LIKELY |
| `hunter_cve_dompurify` | CVE-2026-41238 DOMPurify PP bypass | payload injection → reflection |
| `hunter_cve_copyfail` | CVE-2026-31431 Linux LPE | authencesn config writability (local/remote) |

All CVE tools go through `_safe_auto_json_tool` (HITL gate + auto_gate + dual-ledger writeback), self-produce verdict dicts, and register in `_tool_to_type`.

## MCP Server

Hunter exposes one FastMCP server:

```text
server: hunter_tools
entrypoint: mcp_server.py
contract: integration-contract.json
```

`hunter_tools_mcp.py` is a compatibility launcher only. ReverseLab tools are
loaded internally when `REVERSELAB_MCP_PATH` points to a valid extension, then
registered with the `re_` namespace. Existing Hunter MCP tool names and legacy
workflow files remain compatible.

Useful diagnostics:

- `hunter_healthcheck`
- `hunter_capabilities`
- `hunter_contract_check`
- `hunter_config_audit`
- `hunter_runtime_status`
- `hunter_doctor`
- `hunter_broker_benchmark`

## Install

```bash
git clone https://github.com/GeniusHu-tgty/Hunter.git
cd Hunter
python -m pip install -e .
```

Or use the skill installer (aihot-style, validated + atomic swap):

```bash
bash install.sh --target claude    # Claude Code: ~/.agents/skills/hunter
```

Install optional transports only when needed:

```bash
python -m pip install -e ".[stealth,browser]"
```

The browser extra provides Playwright support. Install browser binaries separately
when running a local Playwright backend:

```bash
python -m playwright install
```

## MCP Configuration

Register only `hunter_tools`; do not register a second standalone ReverseLab
server for the same Hunter process.

```toml
[mcp_servers.hunter_tools]
type = "stdio"
command = "python"
args = ["/absolute/path/to/Hunter/mcp_server.py"]

[mcp_servers.hunter_tools.env]
OPEN_TGTYLAB_ROOT = "/absolute/path/to/Open-tgtylab"
REVERSELAB_MCP_PATH = "/absolute/path/to/ReverseLabToolsMCP/reverse_lab_tools_mcp.py"
```

`REVERSELAB_MCP_PATH` is optional. If it is absent or invalid, Hunter continues
with the core tool contract and reports the missing extension through diagnostics.

## Typical Assessment Flow

1. Open or resume a case and read its next steps.
2. Run `hunter_healthcheck` and `hunter_capabilities`.
3. Query the project knowledge base for the target technology or test class.
4. Use reconnaissance or passive discovery to produce candidates.
5. Route a candidate to `probe`, then a bounded verification workflow when
   controls and an oracle are available.
6. Register evidence, record a verdict, checkpoint the workflow, and publish a
   report or note.

For HTTP execution, the project preference remains:

```text
Burp send_http2_request -> http_probe -> documented local fallback
```

## Development

Run the complete suite:

```bash
python -m pytest -q
```

Run the Broker-focused checks:

```bash
python -m pytest -q \
  tests/test_request_broker.py \
  tests/test_request_broker_boundary.py \
  tests/test_mitm_controller.py \
  tests/test_broker_benchmark.py \
  tests/test_oast_verifier.py
```

The request-boundary test rejects direct `requests`, `httpx`, or `aiohttp` use in
legacy auto scanners. The pre-commit hook runs the same guard.

## Repository Layout

```text
core/request_broker/          Request policy, projections, artifacts, OAST, MITM
core/workflow/event_kernel/   Event-sourced workflow and evidence authority
core/browser/                 Browser MCP planning and encrypted session store
core/evidence/                Normalization and verdict integration
core/auto_cve_*.py            CVE-specific scanner ports (12)
tests/                        Unit, integration, and Event Kernel acceptance tests
config.yaml                   Broker runtime defaults
integration-contract.json     MCP compatibility contract
```

## Related Projects

- [Open-tgtylab](https://github.com/GeniusHu-tgty/Open-tgtylab) — 安全研究工作台，集成逆向工程、CTF、移动安全、Web安全于一体

## License

GPL-3.0-only. See [LICENSE](LICENSE) for details.

## Disclaimer

本项目仅用于教育和授权安全研究目的。用户必须确保在合法授权范围内操作。使用本项目产生的任何后果由用户自行承担。

See [DISCLAIMER.md](DISCLAIMER.md) for the full disclaimer.