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).

Authorized use only. Run Gecko exclusively against assets you own or are explicitly permitted to test.

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.

If gecko isn't found after setup, open a new terminal (the installer may have added ~/.local/bin to your PATH) or run ./run.sh directly.

Configuration

All configuration is via environment variables. See .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