RECON7 DOCS

Platform Overview & Architecture

Recon7 is an autonomous security reconnaissance engine for authorized assessments. It discovers exposed assets, maps their relationships, and turns the findings into actionable security intelligence.

Local Quickstart (2-Terminal Workflow)

Running Recon7 locally in development requires only two terminal windows: one for the combined API & Web Console server, and one for the async pipeline worker.

Step 1: Clone & Configure Environment

# 1. Clone repository
git clone https://github.com/johnojabo2/recon7.git
cd Recon7

# 2. Setup Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install core dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env

Step 2: Launch Web Console & API Server

python main.py
# Server starts at: http://127.0.0.1:8080
# Interactive Portal: http://127.0.0.1:8080/portal
# Operator Console: http://127.0.0.1:8080

Step 3: Launch Async Recon Worker

python worker.py
# Worker starts polling database for queued scan jobs

Docker & Compose Production Deployment

Recon7 is packaged into an all-in-one container image containing all scanning binaries (Nmap, Masscan, Amass, Sublist3r, Nuclei templates) alongside the web application. Production uses Docker Compose to orchestrate PostgreSQL, the Web/API Server (r7-app on port 8000), and the Async Pipeline Worker (r7-worker).

# Launch PostgreSQL + API Server + Recon Worker
docker-compose up -d

# Check live logs
docker-compose logs -f app worker

Complete docker-compose.yml Configuration

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: r7-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: recon7
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: reconpassword123
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d recon7"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    image: johnojabo1/recon7:latest
    build: .
    container_name: r7-app
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://postgres:reconpassword123@postgres:5432/recon7
      ALLOW_ALL_SCOPES_DEV: ${ALLOW_ALL_SCOPES_DEV:-false}
      GITHUB_TOKEN: ${GITHUB_TOKEN:-}
      GOOGLE_SEARCH_API_KEY: ${GOOGLE_SEARCH_API_KEY:-}
      GOOGLE_SEARCH_ENGINE_ID: ${GOOGLE_SEARCH_ENGINE_ID:-}
    ports:
      - "8000:8000"
    command: uvicorn main:app --host 0.0.0.0 --port 8000

  worker:
    image: johnojabo1/recon7:latest
    build: .
    container_name: r7-worker
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://postgres:reconpassword123@postgres:5432/recon7
      ALLOW_ALL_SCOPES_DEV: ${ALLOW_ALL_SCOPES_DEV:-false}
      GITHUB_TOKEN: ${GITHUB_TOKEN:-}
      GOOGLE_SEARCH_API_KEY: ${GOOGLE_SEARCH_API_KEY:-}
      GOOGLE_SEARCH_ENGINE_ID: ${GOOGLE_SEARCH_ENGINE_ID:-}
    command: python worker.py

volumes:
  postgres_data:

Setup Wizard & First-Time Onboarding

When you start Recon7 on a clean database, navigating to / automatically routes you to the setup onboarding wizard.

10-Stage DAG Reconnaissance Pipeline

The pipeline executes an ordered, non-linear Directed Acyclic Graph (DAG) designed to minimize scanning noise while maximizing correlated threat discovery.

Evidence Graph & Path Tracing Engine

The interactive graph canvas visualizes relational connections between discovered infrastructure, personnel, identities, and vulnerabilities.

Multi-Cloud Storage & Exposure Hunting

Discovers orphaned or misconfigured cloud storage repositories across four major cloud providers using domain permutations and wordlists.

Zero-Trust Local Triage & Offline Privacy

Recon7 is designed with a strict zero-leak architecture. All reconnaissance data, hostnames, and credentials remain on your host infrastructure.

Scope Enforcement & Legal Governance

To maintain adherence to the Computer Fraud and Abuse Act (CFAA), GDPR, and professional red-teaming standards, every scan requires explicit target authorization.

Security Engineering & Hardening Controls

Hardened backend security architecture protecting system integrity in hostile network environments:

• Anti-Lockout Safeguards: Root and IAM user passwords must satisfy length and complexity checks, preventing common, easily guessed keys.
• Timing Attack Mitigation: Failed login lookups execute constant-time dummy bcrypt hashes (DUMMY_TIMING_HASH) to prevent user enumeration.
• Brute-Force Rate Limiting: In-memory sliding-window limiter blocks IP addresses after consecutive failed authentication attempts.
• Strict JWT Validation: Cryptographically signed HS256 tokens with short expiration windows and tenant isolation claims.

Administrator Password Recovery CLI

If an operator forgets their administrator password, Recon7 provides a standalone emergency recovery CLI that can be executed directly on the host or inside a running container.

Interactive Reset Prompt

python scripts/reset_password.py

Automated Non-Interactive CLI Reset

# Reset password directly
python scripts/reset_password.py --email [email protected] --password "NewSecurePass!2026"

# List all registered users
python scripts/reset_password.py --list

Inside Docker Container

docker exec -it r7-app python scripts/reset_password.py --email [email protected] --password "NewSecurePass!2026"

OpenAPI REST Endpoints

All API routes are mounted strictly under the /api prefix with Bearer JWT authentication: