Gecko

Passive reconnaissance and security-assessment platform. A FastAPI backend orchestrates a catalog of recon/scan stages and streams results to a static frontend over Server-Sent Events. Outbound traffic can be routed through Tor for OPSEC (always-on in Docker, optional on a bare-metal install). ## Project layout . ├── backend/ # FastAPI recon backend │ ├── app/ │ │ ├── main.py # API entrypoint + routes │ │ ├── recon.py # stage orchestrator │ │ ├── stages/ # individual recon/scan stages │ │ └── ... # session, cache, batch, triage, http_client, etc. │ ├── Dockerfile │ └── requirements.txt ├── frontend/ # static UI (HTML/CSS/JS) served by nginx │ ├── index.html │ ├── stage-*.html # per-stage detail pages │ ├── nginx.conf # static serving + /api reverse proxy │ └── Dockerfile ├── docker-compose.yml # tor + backend + frontend ├── setup.sh # bare-metal installer (Linux, no Docker) ├── run.sh # bare-metal launcher (the `gecko` command runs this) ├── .env.example # environment template (copy to .env) └── README.md ## Quick start (Docker) # 1. Configure environment cp .env.example .env # edit .env and add any API keys / LLM credentials you want # 2. Build and run the full stack docker compose up --build - Frontend: http://localhost:8080 - Backend API: proxied at http://localhost:8080/api (direct on :8000 inside the network) ## Run without Docker (Linux) If you'd rather run Gecko directly on a Linux host, the included bash scripts collapse the stack into a single Uvicorn process that serves both the API and the static frontend on the same port. Tor becomes optional (only privacy-mode scans need it), and `nuclei` / Playwright are auto-installed if possible — stages self-skip when their tools are missing. # 1. One-time setup: creates .venv, installs Python deps, optionally grabs # the nuclei binary + Playwright Chromium, and installs a `gecko` command. ./setup.sh # 2. Start it — from then on you can launch from anywhere by just typing: gecko `gecko` opens http://127.0.0.1:8080 in your browser. Useful flags: gecko --port 9000 # use a different port gecko --host 0.0.0.0 # bind all interfaces (no auth — trusted networks only) gecko --no-tor # never start a local Tor proxy gecko --no-browser # don't auto-open the browser gecko --reload # dev mode (uvicorn auto-reload) Setup flags: `./setup.sh --no-playwright` and/or `--no-nuclei` skip the heavy optional downloads. ## Configuration All configuration is via environment variables. See [`.env.example`](.env.example) for the full list. Most third-party API keys are optional — stages that lack a required key simply skip themselves and the scan continues. | Variable | Purpose | Required | | ------------------- | ---------------------------------------- | -------- | | `TOR_PROXY_URL` | SOCKS5 proxy for outbound traffic | no (default) | | `DOH_URL` | DNS-over-HTTPS resolver | no (default) | | `LLM_PROVIDER` | Triage LLM provider: `anthropic` \| `openai` \| `gemini` | no | | `LLM_MODEL` | Override the default model for the provider | no | | `LLM_BASE_URL` | Point at a compatible gateway (optional) | no | | `ANTHROPIC_API_KEY` | Triage LLM key — Anthropic (stage A.61) | no | | `OPENAI_API_KEY` | Triage LLM key — OpenAI | no | | `GEMINI_API_KEY` | Triage LLM key — Google Gemini (`GOOGLE_API_KEY` also accepted) | no | | `GITHUB_TOKEN` | GitHub leak scanning | no | | `SHODAN_API_KEY` | Shodan pivot | no | | ... | see `.env.example` | | ### AI triage providers The optional LLM triage layer (stage A.61, plus attack-chain and PoC enrichment) supports three providers via plain HTTP — no vendor SDKs. Pick one with `LLM_PROVIDER` and supply the matching key. If `LLM_PROVIDER` is left blank, the first configured key wins, in order: Anthropic → OpenAI → Gemini. When no key is set, triage simply no-ops and the scan still runs. ## API endpoints | Method | Path | Description | | ------ | ---------------------------- | ------------------------------------ | | GET | `/api/health` | Service + cache health | | GET | `/api/tor` | Verify Tor proxy and report exit IP | | GET | `/api/profiles` | List scan profile templates | | GET | `/api/stages` | List available stages | | GET | `/api/stage-methods` | Per-stage technique methods | | GET | `/api/session` | Check active/completed session | | POST | `/api/batch` | Create a batch scan | | GET | `/api/batch/{batch_id}` | Batch status | | GET | `/api/recon` | Run a recon scan (SSE stream) | | POST | `/api/scan/{sid}/confirm` | Resolve a confirm-required gate | | GET | `/api/scan/{sid}/pending` | List pending confirmations | | GET | `/api/export/{domain}` | Export dossier (json/...) | | GET | `/api/history` | Scan history |