Metadata-Version: 2.4
Name: asmhunter-mcp
Version: 0.1.1
Summary: MCP server for ASMHunter — drive bug-bounty recon, monitoring, triage and reporting from an AI agent.
Project-URL: Homepage, https://asmhunter.app
License-Expression: MIT
License-File: LICENSE
Keywords: asmhunter,attack-surface-management,bug-bounty,mcp,recon,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.28.0
Description-Content-Type: text/markdown

# asmhunter-mcp

Local stdio MCP server for [ASMHunter](https://asmhunter.app) — drive your
bug-bounty recon, monitoring, triage and reporting from an AI agent (Claude Code,
Claude Desktop, Cursor, …).

**What it is honestly good at:** automating the ~80% grind — discovering fresh
scope, spinning up targets, running recon + automated scans, reading back the
attack surface and findings, organizing a hunt, and drafting reports. It puts you
**first on newly-added scope** and never lets you miss a change. It does **not**
find the high-value manual bugs for you (IDOR, business logic, auth bypass) —
that's still your job; this tool buys you the time to do it.

## Tools (34)

**Intel** — `search_programs`, `get_program`, `recommend_programs`, `get_watchlist`, `get_scope_changes`

**Scanner (the ASMHunter edge)** — `list_targets`, `create_target`, `list_workflows`, `trigger_scan` (pro+, confirm gate), `get_scan_status`, `get_findings`, `list_assets`

**Hunt sessions** — `create_session`, `list_sessions`, `get_session`, `update_session`, `delete_session`

**Entries** — `add_lead`, `add_finding`, `add_tested`, `add_note`, `bulk_add_entries`, `list_entries`, `update_entry`, `delete_entry`, `promote_entry`

**Reports** — `draft_report`, `list_reports`, `update_report`, `delete_report`

**Stats & attribution** — `get_my_stats`, `get_value_receipt`, `list_wins`, `add_win`

## Requirements

- Python 3.12+
- An ASMHunter **pro+** account (Personal Access Tokens and the scanner tools are pro-gated)
- A Personal Access Token — mint one at **asmhunter.app → Settings → API Tokens** (`asm_live_…`)

## Install

```bash
uv tool install asmhunter-mcp
# or:  pip install asmhunter-mcp
```

## Connect from Claude Code

Add via the CLI:

```bash
claude mcp add asmhunter \
  --env ASMHUNTER_TOKEN=asm_live_YOUR_TOKEN_HERE \
  -- uvx asmhunter-mcp
```

Or add to your MCP config (`~/.claude/claude_desktop_config.json` or Claude Code MCP settings):

```json
{
  "mcpServers": {
    "asmhunter": {
      "command": "uvx",
      "args": ["asmhunter-mcp"],
      "env": {
        "ASMHUNTER_TOKEN": "asm_live_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

`ASMHUNTER_API_URL` defaults to `https://asmhunter.app` — only set it to override
(e.g. a self-hosted or staging instance).

## Environment variables

| Variable | Description | Default |
|---|---|---|
| `ASMHUNTER_TOKEN` | Personal Access Token (`asm_live_…`) | **required** |
| `ASMHUNTER_API_URL` | API base URL | `https://asmhunter.app` |

## Drive a hunt — example prompt

Once connected, in Claude Code just ask for the loop in plain language:

> "Show me programs with recent scope changes. Pick one with genuinely fresh
> scope, add its new domain as a target, list the available scan workflows and
> run a recon + subdomain-enum scan (confirm it). When it finishes, summarize the
> newly-discovered assets and any findings by severity, flag which ones are worth
> manual testing, and draft a report skeleton for the most promising one."

Claude will chain `get_scope_changes → create_target → list_workflows →
trigger_scan(confirm=true) → get_scan_status → list_assets / get_findings →
add_lead / draft_report`. You then do the creative manual testing on the surface
it prioritized. Ongoing, keep targets under continuous monitoring and let the
alerts (Telegram/email) tell you when something changed.

## Run directly

```bash
ASMHUNTER_TOKEN=asm_live_... asmhunter-mcp
```

## Architecture

- `client.py` — httpx-only async client, no fastmcp dependency (unit-testable standalone; rejects path-traversal in interpolated ids)
- `server.py` — FastMCP tool wrappers (thin, no business logic; tiers/quota/RLS enforced server-side)
- `__main__.py` — entrypoint (`mcp.run()`)

All tier enforcement, quota checks, and RLS live in the orchestrator — the MCP
layer is a pure passthrough except for `trigger_scan`'s local confirm gate.
