A web reconnaissance dashboard and CLI for authorized passive intelligence gathering and active vulnerability checks — built for bug bounty hunters, security engineers, and auditors.

🚀 Try the live demo → — point it at a target you own and explore the recon report. No signup required.

• 📖 Overview
• ✨ Features
• 🛰️ Reconnaissance Modules
• 🧠 How It Works
• 📂 Repository Structure
• 🧰 Tech Stack
• 📋 Requirements
• 🛠️ Installation
  • Dashboard (web app)
  • CLI (npm package)
  • Production build
• ⚙️ Configuration
• 🛠️ Usage
  • Dashboard
  • Local CLI
  • Programmatic API
  • Screenshots
• 🧪 Testing
• 🔄 Project Flow
• 🔌 API Reference
  • GET /api/proxy
  • CLI JSON output
• 💡 Examples
  • Safe targets to try
  • What a finding looks like
• 🚀 Deployment
  • Vercel (recommended)
  • Docker production
  • Docker development
  • Self-hosted static hosting
• 🗺️ Roadmap
• 🤝 Contributing
• 📝 Changelog
• 🛟 Troubleshooting
• 🔐 Security and Legal Use
• 📄 License
• ❤️ Acknowledgements
• 👥 Contributors

Most public web attacks start with the same recon: a DNS lookup, a certificate transparency query, a port scan, a header review, and a handful of well-known payload checks. ABSpider Recon is a focused, opinionated recon toolkit that bundles those workflows behind one dashboard and one terminal command. It is built for:

• 🐛 Bug bounty hunters who need a fast first pass against an in-scope target.
• 🛡️ Security engineers running pre-audit reconnaissance on assets they own.
• 🎓 Students and educators teaching the structure of a modern web recon workflow.
• 🧰 Tooling authors who want a clean JSON recon payload to feed into other tools.

⚠️Authorization is non-negotiable. ABSpider Recon is a security testing tool. It does not grant permission to scan any system. Use it only on assets you own or have explicit written authorization to test. See 🔐 Security and Legal Use.

It is built on a clear split:

• 🖥️ Dashboard — a Vite + React + Supabase app with a polished UI, magic-link auth, persisted scan history, JSON/PDF report export, and per-user settings.
• 💻 CLI — a Node.js ESM script that runs the same recon modules from the terminal, with bounded payload counts, request delays, and thread controls. No Supabase session required.

Both surfaces share the same scanner engine. Pick whichever fits the engagement.

• 🛰️ 21 recon modules spanning passive intelligence, header analysis, fingerprinting, and bounded active checks.
• 🧠 Three scan styles — conservative, adaptive (default), and aggressive — for both dashboard and CLI workflows.
• 🛡️ Bounded by design — every active module has explicit payload counts, request delays, and concurrency limits. Nothing fires blindly.
• 💻 Local CLI — run the full scanner from your terminal with npx abspider <target>, or npm run cli -- <target> for local development.
• 🔐 Passwordless auth — Supabase magic-link sign-in protects dashboard history; the CLI runs without any account.
• 📊 Per-user scan history — Supabase PostgreSQL with row-level security, plus per-user API keys, preferences, and Discord webhook config.
• 📥 JSON + PDF reports — export a dashboard scan as JSON, a styled PDF (jsPDF + jspdf-autotable), or DOCX.
• 🧩 Optional third-party intel — Shodan, VirusTotal, SecurityTrails, Hunter.io, and Discord webhooks plug in when you bring your own keys.
• 🐳 Container-ready — production Dockerfile (Nginx) and dev Dockerfile.dev (Vite) ship in the repo; docker compose orchestrates both.
• ⏱️ Graceful shutdown — Ctrl+C aborts the CLI cleanly, preserves partial results, and finishes writing any --output JSON.
• 🧪 Strict pipeline — ESLint 9, strict TypeScript, Vitest, and npm audit (production only) run in CI on every push and PR.

🔎 Dashboard-only convenience modules (settings, preferences, key vault) live under src/services/ and are not part of the recon flow.

ABSpider Recon is a Vite SPA backed by Supabase. The browser is the only client; the scanner modules run inside the browser for the dashboard and inside Node.js for the CLI. Both surfaces share the same module contracts.

flowchart TD
    A[User enters a target] --> B{Dashboard or CLI?}
    B -- Dashboard --> D[React SPA]
    B -- CLI --> C[abspider-cli.mjs]
    D --> E[Supabase auth and per-user settings]
    D --> F[Scan service orchestrator]
    C --> M[CLI module runner]
    F --> X[Recon modules]
    M --> X
    X --> Y[External targets and intel sources]
    F --> R[PDF and JSON reports]
    C --> J[Terminal report and JSON export]
    F --> DB[(Supabase Postgres + Storage)]

Key design choices:

• Browser-first dashboard — the dashboard does the work in the browser using a small requestManager and per-module backoff. The Vercel Edge proxy at api/proxy.ts is available for CORS-limited flows.
• Bounded active modules — every active module reads payloads from src/payloads/*.json and respects the per-mode cap, delay, and concurrency settings.
• Deterministic payloads — the JSON payload files are version-controlled. You can audit, extend, or replace them without touching the runner.
• No telemetry — ABSpider Recon does not phone home. API keys never leave your browser session, and scan results are scoped to your Supabase row-level security policies.

abspider-recon/
├── api/
│   └── proxy.ts                      # Vercel Edge Runtime proxy endpoint
│
├── docs/
│   └── wiki/                         # Supplemental user, configuration, legal guides
│
├── packages/
│   └── cli/                          # Published npm package `abspider`
│       ├── package.json              # bin: abspider, abspider-recon
│       ├── README.md                 # npm-facing usage docs
│       └── scripts/abspider-cli.mjs  # CLI entry point bundled into the npm tarball
│
├── public/                           # Favicons, manifest, robots.txt, static assets
│
├── scripts/
│   ├── abspider-cli.mjs              # Local CLI runner (used by `npm run cli`)
│   └── generate-favicons.js         # Favicon regeneration helper
│
├── src/
│   ├── App.tsx                       # Router, providers, app shell
│   ├── main.tsx                      # Vite entry point
│   ├── SupabaseClient.ts             # Typed Supabase client
│   ├── components/                   # Dashboard UI components
│   │   ├── landing/                  # Landing-page sections (Hero, Features, Stats, CTA, ...)
│   │   └── ui/                       # shadcn-style primitives (button, card, dialog, sidebar, ...)
│   ├── contexts/                     # Theme + notification React contexts
│   ├── hooks/                        # Custom React hooks
│   ├── images/                       # Inline SVGs and brand assets
│   ├── lib/                          # Shared utilities
│   ├── pages/                        # React Router pages
│   ├── payloads/                     # SQLi, XSS, and LFI payload JSON files
│   ├── services/                     # 21 recon modules, report generation, settings, scan orchestrator
│   ├── shims/                        # Type shims
│   └── utils/                        # cn(), formatters, small helpers
│
├── supabase/
│   └── migrations/                   # 0001 init schema, 0002 RLS, 0003 storage
│
├── .env.example                      # Template for VITE_* env vars
├── components.json                   # shadcn/ui config
├── docker-compose.yml                # `app` and `dev` profiles
├── Dockerfile                        # Production Vite build served by Nginx on :8080
├── Dockerfile.dev                    # Vite dev server on :5000
├── eslint.config.js                  # ESLint 9 + typescript-eslint
├── LICENSE                           # MIT
├── nginx.conf                        # Nginx config for the production image
├── package.json                      # Scripts, dependencies, and CLI runner
├── postcss.config.js                 # Tailwind + Autoprefixer
├── README.md                         # You are here
├── SECURITY.md                       # Vulnerability reporting policy
├── tailwind.config.js                # Tailwind v3 design tokens
├── tsconfig.app.json                 # Strict TS config for the app
├── tsconfig.json                     # Root TS config
├── tsconfig.node.json                # TS config for Node scripts
└── vite.config.ts                    # Vite config and path aliases

• Node.js ≥ 20 (CI runs on Node 20; the published CLI requires Node ≥ 20).
• npm ≥ 9 with the committed package-lock.json (a bun.lock is also present for Bun users).
• Supabase project for the dashboard auth, persisted scan history, and per-user settings.
• Optional API keys for enhanced modules (Shodan, VirusTotal, SecurityTrails, Hunter.io, Discord).
• Docker, only if you want containerized deployment.

The CLI can run without Supabase or any third-party keys. Core passive modules (DNS, WHOIS, headers, SSL, ports) work out of the box on a fresh clone.

# 1. Clone the repository
git clone https://github.com/zanesense/abspider-recon.git
cd abspider-recon

# 2. Install dependencies
npm install

# 3. Copy and populate environment variables
cp .env.example .env
# Edit .env with your Supabase project URL and anon key (see Configuration below)

# 4. Apply Supabase migrations
supabase link --project-ref <YOUR_PROJECT_REF>
supabase db push

# 5. Start the dev server
npm run dev

The Vite dev server listens on port 5000 by default:

http://localhost:5000

The CLI is published as abspider and ships its own bundled abspider-cli.mjs plus the payload JSON files. Install it once and run it anywhere:

# One-off scan
npx abspider example.com

# Or install globally
npm install -g abspider
abspider example.com

For local development from this repository (uses the source tree under packages/cli):

npm run cli -- example.com

npm run build

npm run build runs the strict TypeScript project references (tsc -b) and then vite build, producing a static bundle in dist/. Serve dist/ from any static host, or use the production Docker image.

ABSpider Recon is configured entirely through environment variables. There is no separate config file to edit and no database to provision up front.

Vite only exposes variables prefixed with VITE_ to the browser bundle. Anything unprefixed stays server-side.

Copy the template to start:

cp .env.example .env
# .env is already in .gitignore

Apply the migrations in supabase/migrations/ before using the dashboard end to end:

supabase link --project-ref <YOUR_PROJECT_REF>
supabase db push

If you do not use the Supabase CLI, run these files in the Supabase SQL Editor in order:

1. supabase/migrations/0001_init_schema.sql
2. supabase/migrations/0002_rls_policies.sql
3. supabase/migrations/0003_storage_avatars.sql

See supabase/README.md for verification steps and a quick "expected tables" checklist.

The CLI only reads the VirusTotal key from your shell environment (it does not load .env):

export VIRUSTOTAL_API_KEY=<your-key>
abspider example.com --modules virustotal

All other CLI modules run without configuration.

npm run dev

Then:

1. Sign in with a Supabase magic link (no password to remember).
2. Open Settings and add any optional API keys, the proxy URL, and your Discord webhook.
3. Start a scan from the New Scan page by entering a target.
4. Watch per-module progress and review the structured results.
5. Export the report as JSON, PDF, or DOCX from the Reports page.

The CLI ships with a clean terminal UI, per-module progress bars, and immediate results. It runs without a Supabase session and without any third-party keys for the core modules.

# Default: passive recon only
abspider example.com

# Every passive and active CLI module
abspider https://example.com --all

# Only active checks, with conservative settings
abspider https://example.com --active --mode conservative

# Selected modules, save JSON for a downstream tool
abspider example.com --modules whois,dns,sslTls,ports,cors --output scan.json

# Aggressive mode with the common port profile
abspider https://example.com --all --mode aggressive --port-profile common

# Machine-readable JSON to stdout
abspider example.com --modules dns,sslTls --json --pretty

Operational notes:

• Press Ctrl+C to stop gracefully. The CLI aborts in-flight work, skips remaining modules, and preserves any partial JSON written via --output.
• The CLI runs in Node.js, so browser CORS restrictions do not apply.
• CDN/WAF protections (e.g. Cloudflare) are detected and reported when visible in headers, status codes, or challenge pages. The CLI does not evade access controls or bypass provider challenges.

There are two ways to consume ABSpider Recon programmatically:

1. The Vercel Edge proxy at GET /api/proxy?url=<encoded> — for browser-side CORS-bypass workflows.
2. The CLI JSON output — pipe --json into jq or another tool for automations.

See 🔌 API Reference for full details.

Landing page

Login

Dashboard

New scan

Running scan

CLI

ABSpider Recon ships with a strict quality pipeline. Run all of these locally before opening a PR:

# Lint
npm run lint

# Type check (strict TypeScript project references)
npm run typecheck

# Build the production bundle (catches many runtime issues at build time)
npm run build

# Unit tests (Vitest)
npm test

# Audit production dependencies for known CVEs
npm run audit

The GitHub Actions workflow runs lint, typecheck, build, and test on every push and pull request to main. npm run audit is intended for local pre-release checks; the lockfile is committed and package-lock.json is the source of truth.

End-to-end recon lifecycle (dashboard or CLI):

sequenceDiagram
    participant U as User
    participant W as Dashboard (Vite + React)
    participant C as CLI (abspider-cli.mjs)
    participant S as Supabase
    participant T as Target host and intel sources
    participant R as Recon modules (src/services)
    participant E as Report exporter

    U->>W: Sign in with magic link
    W->>S: Authenticate and load user settings
    U->>W: Enter a target
    W->>R: Run selected modules (bounded)
    R->>T: HTTP, DNS, TCP, TLS probes
    T-->>R: Responses and metadata
    R-->>W: Structured findings
    W->>E: Build JSON, PDF, DOCX
    W->>S: Persist scan history (RLS-scoped)
    W-->>U: Render report and exports

    U->>C: abspider example.com --all
    C->>R: Run selected modules
    R->>T: Same probes
    T-->>R: Responses
    R-->>C: Findings
    C-->>U: Terminal UI, JSON, --output file

A minimal Vercel Edge proxy used to bypass browser CORS for targets that reject cross-origin requests. The handler in api/proxy.ts:1 validates the url query parameter, forwards a curated set of request headers, and returns the target response with permissive CORS headers.

Request

GET /api/proxy?url=https%3A%2F%2Fexample.com%2Frobots.txt

Response

• 200 OK with the proxied body and Access-Control-Allow-Origin: *.
• 400 Bad Request if url is missing.
• 500 Internal Server Error on upstream failure.

CORS

The proxy itself responds to OPTIONS preflight with Allow: GET, POST, OPTIONS and the standard CORS response headers.

Use the proxy only for hosts you are authorized to test. It is not a generic web proxy.

Pass --json to print the full result tree, or --json --pretty for human-readable JSON. Use --output <file> to write it to disk. The shape is:

{
  "target": "example.com",
  "startedAt": "2026-06-07T10:00:00.000Z",
  "finishedAt": "2026-06-07T10:00:14.000Z",
  "durationMs": 14000,
  "mode": "adaptive",
  "modules": {
    "siteInfo": { "ok": true, "data": { "status": 200, "title": "Example Domain" } },
    "dns":      { "ok": true, "data": { "A": ["23.215.0.136"], "AAAA": ["2600:1408:..."] } },
    "whois":    { "ok": true, "data": { "registrar": "...", "createdAt": "..." } },
    "sslTls":   { "ok": true, "data": { "subject": "CN=example.com", "expiresAt": "..." } }
  },
  "summary": {
    "modulesRun": 4,
    "modulesOk": 4,
    "modulesFailed": 0,
    "findings": 0
  }
}

Field shape varies per module. Treat the JSON as additive — new fields may appear in future releases without a major version bump.

⚠️Authorization reminder. The targets below are commonly used for testing and are either owned by the named organization or explicitly offered for scanner demos. Do not run the active modules against any host without written permission.

For a deeper walkthrough, see docs/wiki/user-guide.md.

A corsMisconfig finding produced by the CLI in --json mode:

{
  "module": "corsMisconfig",
  "severity": "high",
  "title": "CORS reflects arbitrary Origin",
  "description": "The response includes Access-Control-Allow-Origin: <request-origin> with Access-Control-Allow-Credentials: true. This is a classic CORS misconfiguration.",
  "target": "https://staging.example.com",
  "evidence": {
    "requestOrigin": "https://evil.example",
    "responseHeaders": {
      "access-control-allow-origin": "https://evil.example",
      "access-control-allow-credentials": "true"
    },
    "status": 200
  },
  "remediation": "Reflect only a known allowlist of origins, or set Access-Control-Allow-Origin to a static value and never combine it with Access-Control-Allow-Credentials: true for dynamic origins."
}

The same finding in the dashboard renders as a card with a "Recheck" button, an evidence panel, and a copy-pasteable remediation block.

ABSpider Recon is a static Vite SPA plus a Vercel Edge function at api/proxy.ts. Every supported deployment path serves the production bundle in dist/ — never the Vite dev server. The Vite dev server (npm run dev, port 5000) is for local development only and is not exposed by any of the deployment recipes below.

Vercel reads vercel.json and runs the production pipeline:

• installCommand: npm ci
• buildCommand: npm run build (which is tsc -b && vite build)
• outputDirectory: dist/
• SPA rewrites: every path that does not match a static asset falls through to /index.html (so deep links like /dashboard and /scan/:id work after a refresh).
• Edge function: api/proxy.ts is auto-deployed as a Vercel Edge Function.

# Install the Vercel CLI if you do not have it
npm i -g vercel

# Deploy from the project root
vercel

In the Vercel project settings, add:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• Optional VITE_* integration keys

No vercel dev for the deployed environment. The platform always runs the production build, never the Vite dev server.

The production image is a multi-stage build: Node 20 builds the Vite bundle, then a distroless Nginx 1.27 alpine image serves dist/ on container port 8080. The Vite dev server is never started inside the image.

docker compose up --build app

Open:

http://localhost:3000

Verify the image is actually serving the production build:

# Should print "nginx" in the Server header
curl -sI http://localhost:3000 | grep -i server

This is the only path that runs the Vite dev server, and it is opt-in via a Compose profile.

docker compose --profile dev up --build dev

Open:

http://localhost:5000

npm start runs serve (Vercel's reference static file server) against dist/, with the SPA fallback flag (-s) so deep links resolve to index.html. The Vite preview server is not used.

npm ci
npm run build
VITE_SUPABASE_URL=https://YOUR-PROJECT-REF.supabase.co \
VITE_SUPABASE_ANON_KEY=replace-with-your-supabase-anon-key \
PORT=5000 \
npm start

PORT defaults to 5000 if unset.

npm run build
# Upload the contents of dist/ to your static host

If your static host supports edge functions (Cloudflare Workers, Netlify Edge Functions, Deno Deploy, Lambda@Edge), you can port the 92-line api/proxy.ts handler verbatim. Otherwise, run the dashboard without the proxy and rely on direct CORS-friendly targets or the CLI.

Planned and aspirational improvements:

• 📡 Multi-target batch scanning.
• 🧪 Custom payload libraries and per-engagement profiles.
• 🛡️ Advanced WAF fingerprinting and provider detection.
• 📄 Report templates for common assessment types.
• 🔌 Integrations with Burp Suite and OWASP ZAP.
• 👥 Team collaboration features (shared scan history, RBAC).
• 🏢 Backend API mode for enterprise deployments.
• 🌐 i18n for module output and report exports.
• 🪝 Webhook callbacks for scheduled scans.
• 🪪 License detection beyond VirusTotal metadata.

A separate ROADMAP.md is not currently checked in. The list above is the source of truth until it is.

Contributions are very welcome — especially new payload patterns, new recon modules, and per-provider fingerprinting rules.

1. Fork the repository on GitHub.
2. Clone your fork and create a feature branch:

   git checkout -b feat/wordpress-plugin-fingerprint

3. Install dependencies and start the dev server:

   npm install
   npm run dev

4. Make your changes.
   • Adding a new module? Create a service under src/services/ that follows the existing shape, then wire it into the dashboard orchestrator and the CLI runner.
   • Adding payloads? Edit the relevant JSON file in src/payloads/ and document each new pattern in a PR comment.
5. Run the quality checks before committing:

   npm run lint
   npm run typecheck
   npm run build
   npm test

6. Commit with a descriptive message:

   git commit -m "feat(services): add WordPress plugin fingerprinting"

7. Push your branch and open a pull request against main:

   git push origin feat/wordpress-plugin-fingerprint

Please open an issue first if your change is large or design-related.

Releases are tracked on the GitHub Releases page. The notable milestones so far:

• 2.0.1 — Current. Polished landing page, redesigned app shell, expanded module list, hardened CLI modes, Supabase row-level security across all dashboard tables.
• 2.0.0 — Major rewrite. Split the project into the dashboard SPA and the published abspider CLI package (packages/cli). Introduced the Vercel Edge proxy, persistent scan history, JSON/PDF/DOCX reports, and per-user settings.
• 1.x — Pre-split recon dashboard. Single Vite app with a smaller module set and no published CLI.

A standalone CHANGELOG.md is not currently committed. The GitHub Releases page is the source of truth until it is.

More guides are available in docs/wiki.

ABSpider Recon is a security testing tool. It does not grant permission to scan any system.

• ✅ Authorization first. Scan only assets you own or have explicit written permission to test.
• ✅ Keep authorization records. For professional assessments, retain the signed scope of work.
• ✅ Tune for production. Use conservative payload counts, delays, and port profiles against production systems.
• ✅ Treat keys as secrets. Webhook URLs and third-party API keys must never be committed to source control.
• ✅ Mind the local laws. Computer-misuse laws differ by jurisdiction. You are responsible for compliance.
• ❌ No evasion. ABSpider Recon detects and reports CDN/WAF behavior; it does not bypass access controls or provider challenges.
• ❌ No data exfiltration. The dashboard does not share your scan results with any third party.

To report a vulnerability in ABSpider Recon itself, use the GitHub Security Advisories flow or email security@zanesense.dev. Do not open a public issue for suspected vulnerabilities. See SECURITY.md for the full policy, supported versions, and response timeline.

ABSpider Recon is licensed under the MIT License.

• 🛰️ Recon patterns inspired by the public playbooks from OWASP, the Nmap project, and the bug-bounty community.
• 🎨 UI primitives adapted from the shadcn/ui patterns, locally authored and customised.
• 🖼️ Icons by Lucide.
• 🔔 Toasts by Sonner.
• 🧰 Build tooling by Vite, React, Tailwind CSS, and TypeScript.
• 🗄️ Auth and persistence by Supabase.
• 🧪 Testing by Vitest.
• 💛 Thanks to every researcher who reports a vulnerability responsibly and to every maintainer who documents their in-scope assets clearly.

Thanks to everyone who has contributed code, payloads, modules, documentation, and bug reports.

Want to see your avatar here? Open a pull request — see 🤝 Contributing.

⬆️ Back to top  ·  🌐 Live demo  ·  📦 Repository  ·  🐛 Report a bug  ·  📄 MIT License