🔱 ReconForge

Automated passive security assessment for domains and IP addresses.

Point it at a domain, get a structured report across six recon modules in one parallel scan — then export it to PDF.

---

✨ What it does

Enter a domain or IP and ReconForge runs six passive reconnaissance modules concurrently, scores the findings by severity, and presents them in a dark, terminal-inspired dashboard you can export to a clean PDF.

Everything is passive — no port scanning, no intrusive probing. All data comes from public sources (certificate transparency logs, public DNS, standard HTTPS responses, WHOIS).

Module	What it checks	API key
Subdomains	Certificate transparency logs via crt.sh	—
DNS	A / AAAA / MX / TXT / NS records, plus SPF & DMARC posture	—
SSL / TLS	Cert validity, expiry, cipher suite, TLS version	—
HTTP headers	HSTS, CSP, X-Frame-Options… scored 0–100	—
WHOIS	Registrar, creation/expiry dates, name servers	—
IP reputation	AbuseIPDB confidence + VirusTotal detections	free tier

The first five modules work out of the box with zero configuration. IP reputation activates automatically once you add free API keys.

---

🚀 Highlights

• ⚡ Parallel execution — all six modules run concurrently via asyncio.gather(); a single scan finishes in seconds, not the sum of its parts.
• 🎯 Risk grade — every scan gets a weighted A–F grade so you can triage at a glance instead of counting severities.
• 📄 Client-side PDF export — generates a polished, paginated report entirely in the browser; nothing is stored server-side.
• 🧠 Smart fallbacks — handles crt.sh's quirks (404-as-empty, slow responses with retries + alternate query forms), and skips meaningless WHOIS lookups on dynamic-DNS subdomains.
• ⌨️ Keyboard-first UI — / to focus, 1–6 to switch tabs, ↑/↓ to recall scan history, Esc to reset.
• 💾 Result caching & rate limiting — 15-minute in-memory cache avoids hammering public APIs; 10 scans/min per IP, no Redis required.
• ✅ 43 tests — pytest + asyncio, every external call mocked, fully offline-capable.
• 🐳 Dockerised — docker compose up --build and you're running.

---

📋 Table of contents

• Tech stack
• Quick start
• Enabling IP reputation
• API
• Architecture
• Project structure
• Running tests
• Security & disclaimer
• License

---

🛠 Tech stack

Layer	Technology
Backend	Python 3.12 · FastAPI · httpx (async) · dnspython · python-whois
Frontend	React 18 · Vite · html2pdf.js · JetBrains Mono
Infra	Docker · Docker Compose · nginx
Tooling	pytest · pytest-asyncio · ruff · GitHub Actions CI
External APIs	crt.sh · AbuseIPDB · VirusTotal

---

⚡ Quick start

Prerequisites

• Python 3.12+
• Node 20+

1. Clone & configure

git clone https://github.com/JoseGlezHerrera/reconforge.git
cd reconforge
cp .env.example backend/.env   # optional: add API keys (see below)

2. Backend

cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

→ API docs (Swagger UI) at http://localhost:8000/docs

3. Frontend

cd frontend
npm install
npm run dev

→ App at http://localhost:3000

…or run everything with Docker

docker compose up --build
# Backend  → http://localhost:8000
# Frontend → http://localhost:3000

---

🔑 Enabling IP reputation (optional)

The IP reputation module needs two free API keys (no credit card required):

Service	Get a key	Free tier
AbuseIPDB	https://www.abuseipdb.com/account/api	1,000 checks/day
VirusTotal	https://www.virustotal.com/gui/my-apikey	4 requests/min

Add them to backend/.env:

ABUSEIPDB_KEY=your_key_here
VT_KEY=your_key_here

Restart the backend — the module activates automatically, no code changes needed. Without keys, the module simply reports as skipped and the other five run normally.

⚠️ Never commit your .env. It's already in .gitignore.

---

🔌 API

POST /scan

{ "target": "example.com" }

Response (abridged):

{
  "target": "example.com",
  "timestamp": "2026-06-16T23:56:00Z",
  "duration_seconds": 8.24,
  "cached": false,
  "summary": { "critical": 0, "high": 0, "medium": 3, "low": 2, "info": 6 },
  "total_findings": 11,
  "modules": [
    {
      "module": "dns",
      "status": "ok",
      "data": { "...": "..." },
      "findings": [
        {
          "title": "Missing DMARC policy",
          "description": "No DMARC policy found. Domain has no email spoofing enforcement.",
          "severity": "medium"
        }
      ]
    }
  ]
}

Interactive docs are auto-generated at /docs (Swagger UI) and /redoc.

Other endpoints: GET / (info + metrics) · GET /health (health check).

---

🏗 Architecture

                         Browser (React + Vite)
                                  │
                                  │  POST /scan
                                  ▼
                        FastAPI orchestrator
                   ┌──────────────────────────────┐
                   │  rate limiter (10/min/IP)     │
                   │  TTL cache (15 min)           │
                   └──────────────┬───────────────┘
                                  │  asyncio.gather()  — all run in parallel
        ┌────────────┬───────────┼───────────┬────────────┬────────────┐
        ▼            ▼           ▼           ▼            ▼            ▼
   Subdomains      DNS        SSL/TLS     Headers      IP check      WHOIS
    (crt.sh)   (dnspython)  (ssl mod)    (httpx)   (AbuseIPDB·VT)  (whois)
        │            │           │           │            │            │
        └────────────┴───────────┴─────┬─────┴────────────┴────────────┘
                                       │
                              structured findings
                                       │
                          React dashboard + PDF export

The orchestrator fans out to all modules at once and waits for the slowest, so total scan time ≈ the single slowest module rather than the sum. A failure in any one module is isolated — it surfaces as an error/skip in that module's panel without sinking the rest of the scan.

---

📁 Project structure

reconforge/
├── .github/workflows/ci.yml    # CI: lint + tests + Docker build
├── backend/
│   ├── main.py                 # FastAPI app, /scan, rate limiter, cache
│   ├── models.py               # Pydantic schemas
│   ├── modules/
│   │   ├── subdomains.py        # crt.sh certificate transparency
│   │   ├── dns_lookup.py        # DNS records + SPF/DMARC analysis
│   │   ├── ssl_check.py         # TLS certificate audit
│   │   ├── headers.py           # HTTP security headers (0–100 score)
│   │   ├── ip_check.py          # AbuseIPDB + VirusTotal
│   │   └── whois_lookup.py      # WHOIS registration data
│   ├── tests/                  # pytest suite (43 tests, all mocked)
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.jsx             # Full UI: idle / scanning / results
│   │   ├── api.js              # Backend API client
│   │   └── report.js           # Client-side PDF generator
│   ├── nginx.conf             # Production reverse proxy
│   └── Dockerfile
├── docker-compose.yml
└── .env.example

---

🧪 Running tests

cd backend
pytest tests/ -v          # 43 tests
ruff check .              # lint

All external HTTP calls are mocked, so the suite runs fully offline and fast.

---

🔒 Security & disclaimer

ReconForge performs passive reconnaissance only. It makes no active attacks and only queries public data sources. Only scan domains you own or have explicit written permission to assess. The authors are not responsible for misuse.

Found a vulnerability in ReconForge itself? See SECURITY.md.

---

📄 License

MIT © Jose González

---

Built by Jose González

_{FastAPI · React · Docker · asyncio}