Metadata-Version: 2.4
Name: specter-recon
Version: 0.1.0
Summary: Autonomous AI security-reconnaissance agent — Claude drives recon, analysis, and reporting through scope-guarded tools.
Project-URL: Homepage, https://github.com/nadirzhon/specter
Project-URL: Repository, https://github.com/nadirzhon/specter
Author: nadirzhon
License: MIT
License-File: LICENSE
Keywords: ai-agent,anthropic,autonomous,claude,llm,offensive-security,pentesting,recon,reconnaissance,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.109
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🕵️ Specter

**Autonomous AI security-reconnaissance agent — powered by Claude.**

Give it a target. Specter *plans and runs its own recon* — enumerating subdomains, resolving
DNS, fingerprinting live hosts, cross-referencing CVEs — then writes a severity-graded findings
report. Claude drives the loop; your tools are its hands; an authorization scope keeps it honest.

![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
![Agent](https://img.shields.io/badge/AI-agent-8A63D2)
![CI](https://github.com/nadirzhon/specter/actions/workflows/ci.yml/badge.svg)
![License](https://img.shields.io/badge/License-MIT-green)

</div>

---

## What makes it different

Most recon tools are scripts *you* orchestrate. Specter is an **agent**: Claude decides what to
do next based on what it has found so far. Discover a subdomain running Confluence? It looks up
Confluence CVEs. Find a live host? It audits its security headers. It stops when it has enough
to report — no fixed playbook.

It's the third piece of an AI-security stack: [offsec-mcp](https://github.com/nadirzhon/offsec-mcp)
gives agents the tools, [vigil](https://github.com/nadirzhon/vigil) reviews code, and **Specter is
the agent that autonomously *uses* the tools.**

## Guardrails first

Autonomy without limits is a footgun, so Specter is bounded in code:

- **Passive by default.** Subdomain/DNS/RDAP/CVE lookups never touch the target.
- **Active tools are scope-gated.** `http_probe`, `security_headers`, and `port_scan` refuse to
  run unless the host is in `--scope`. Out-of-scope calls return an error the agent is told *not
  to retry* — it notes the host and moves on.
- **Step budget.** `--max-steps` bounds how long the agent runs.
- Read-mostly: it observes and reports; it does not exploit.

## Install & run

```bash
export ANTHROPIC_API_KEY=...

# passive-only recon (safe against any domain you're allowed to research)
uvx specter-agent example.com

# authorize active probing of specific hosts
uvx specter-agent example.com --scope "example.com,*.example.com" --out report.md
```

Live tool activity streams to stderr; the Markdown report goes to stdout (or `--out`).

## Options

| Flag | Default | Description |
|------|---------|-------------|
| `--scope` | (passive only) | Hosts/CIDRs the agent may actively probe (domains, wildcards, CIDRs) |
| `--model` | `claude-opus-5` | Claude model driving the agent |
| `--max-steps` | `24` | Maximum agent steps |
| `--out` | (stdout) | Write the report to a file |
| `--quiet` | off | Don't stream tool activity |

## The agent's tools

| Tool | Type | What it does |
|------|------|--------------|
| `recon_subdomains` | passive | Sub-domains from Certificate Transparency |
| `dns_lookup` | passive | A/AAAA/MX/NS/TXT/CNAME via DoH |
| `whois` | passive | Registration data via RDAP |
| `cve_search` | passive | High-severity CVEs by product (NVD) |
| `http_probe` | **active** | Status, headers, tech fingerprint |
| `security_headers` | **active** | Security-header audit |
| `port_scan` | **active** | Common-port TCP scan |

## Example report (shape)

```markdown
# 🕵️ Specter — recon report: `example.com`
_Model: claude-opus-5 · 11 steps · 8 tool calls (2×http_probe, 1×recon_subdomains, ...)_

## Executive summary
Mapped 37 subdomains; 12 live. One host runs an outdated component with a critical CVE...

## Attack surface
- api.example.com (200, nginx), staging.example.com (401), ...

## Findings
### Critical
- `wiki.example.com` runs Confluence, matching CVE-2024-XXXX (CVSS 9.8) ...
### Medium
- `example.com` is missing Content-Security-Policy and HSTS ...

## Recommendations
1. Patch Confluence on wiki.example.com immediately ...
```

## How it works

Specter uses the Anthropic SDK's **tool runner** — Claude's agentic loop — with the tools above
exposed as functions. Each turn, Claude reasons about prior results and calls the next tool; the
loop ends when it stops calling tools and writes the report. Tool errors (including scope
refusals) are fed back so the agent adapts instead of crashing.

## Development

```bash
uv pip install -e ".[dev]"
pytest          # scope guard, tool gating, and agent orchestration (mocked client)
ruff check .
```

## Part of an AI × Security toolkit

- [offsec-mcp](https://github.com/nadirzhon/offsec-mcp) — MCP server giving AI agents offensive-security tools (recon, CVE, JS analysis)
- **specter** — autonomous AI recon agent that drives those tools end-to-end · *(this repo)*
- [vigil](https://github.com/nadirzhon/vigil) — AI security review for every pull request
- [mcpscan](https://github.com/nadirzhon/mcpscan) — security scanner for MCP servers (tool poisoning, injection surfaces)
- [State of MCP Security](https://github.com/nadirzhon/state-of-mcp-security) — research: 87% of scanned MCP servers expose a medium+ hardening issue

## License & use

MIT — see [LICENSE](LICENSE). For **authorized** security assessment only. You are responsible
for having permission to assess any target; the scope guard is a safeguard, not a substitute for
authorization. See [SECURITY.md](SECURITY.md).
