# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

SurfaceMap is an LLM-driven attack surface discovery tool. Given a company name or domain, it runs 30+ discovery modules concurrently to enumerate subdomains, IPs, ports, cloud buckets, certificates, and more. Results are deduplicated, risk-scored, and output as terminal trees, JSON, CSV, HTML mindmaps, or Mermaid diagrams.

## Build & Run Commands

```bash
# Install (editable, all extras)
pip install -e ".[all]"

# Install core only (no API/LLM/Slack)
pip install -e .

# Run CLI
surfacemap discover "Target Corp" --domain target.com --tree --json

# Run API server
uvicorn surfacemap.api.server:app --host 0.0.0.0 --port 8000

# Run config viewer
surfacemap config
```

There is no test suite, linter, or formatter configured yet. The `tests/` directory exists but is empty.

## Architecture

### Execution Flow

CLI (`cli/main.py`) or API (`api/server.py`) → `DiscoveryEngine` → 4-phase pipeline:
1. **Phase 0**: LLM Brainstorm (optional) — identifies subsidiaries, infrastructure hints
2. **Phase 1**: Passive Recon — 15 modules run concurrently via `asyncio.gather()`
3. **Phase 2**: Active Probing — 14 modules (CORS checks, sensitive paths, JS analysis)
4. **Phase 3**: LLM Analysis — risk scoring, attack path generation

### Module System

All discovery modules extend `DiscoveryModule` ABC in `discovery/base.py`:
- Must implement `name`, `description` properties and `discover(target, result)` async method
- `safe_discover()` wraps execution with timeout (120s default) and error handling
- Module failures are isolated — they don't crash the pipeline

Modules are organized by category across files in `discovery/`:
- `dns.py` — DNS records, subdomains, zone transfers, cloud detection, subdomain takeover
- `http.py` — HTTP probing, port scanning (nmap)
- `web.py` — Wayback, cert transparency, URL scanning, web tech detection
- `osint.py` — WHOIS, ASN, reverse DNS, SSL analysis, email security
- `active.py` — Sensitive paths, JS analysis, CORS, cookie security
- `enrichment.py` — VirusTotal, Shodan, GitHub dorks, email harvesting

### Data Model

`core/models.py` defines the asset-centric model:
- **Asset**: type (16 `AssetType` enums), value, status, severity, metadata dict
- **ScanResult**: container with fingerprint-based deduplication (SHA256 of type:value)
- Assets are added via `ScanResult.add_asset()` which handles dedup automatically

### LLM Integration

`core/llm.py` — `LLMBrain` class with provider fallback chain: Gemini → Anthropic → OpenAI. Used for brainstorming targets, risk scoring, and false-positive filtering. Entirely optional — tool works without any LLM key.

### Configuration

`core/config.py` — `SurfaceMapConfig` dataclass, singleton via `get_config()`. All settings come from environment variables (auto-loads `.env` file). Key prefixes: `SURFACEMAP_*` for tool settings, plus `GEMINI_API_KEY`, `VIRUSTOTAL_API_KEY`, `SHODAN_API_KEY`, `GITHUB_TOKEN`, `HUNTER_API_KEY` for external services.

### Storage & Output

- `storage/db.py` — async SQLite via aiosqlite, stores scans and assets
- `output/mindmap.py` — generates standalone HTML with D3.js force-directed graph
- `output/formatters.py` — JSON, CSV, Rich tree, Mermaid export

## Key Conventions

- **Async-first**: All discovery, HTTP, DNS, and DB operations are async. Use `asyncio` patterns.
- **Fault tolerance**: Every module runs inside `safe_discover()` with per-module timeouts. Never let one module failure affect others.
- **No secrets in code**: All API keys via env vars. The `.env` file is gitignored.
- **External tools are optional**: `dig`, `nmap`, `subfinder` enhance results but the tool must work without them (check availability before calling).
- Python 3.11+ required. Build system is Hatch/Hatchling.
