Cerberus Recon Engine v1

A modular reconnaissance engine for OSINT and security research. This engine provides modules for username, breach, and domain reconnaissance with JSON logging and optional LLM summarization.

🔧 Features

• Modular Design: Three recon modules (username, breach, domain)
• JSON Logging: Structured logging for all operations
• FastAPI Endpoints: RESTful API for integration
• CLI Runner: Command-line interface for quick recon tasks
• Ollama Integration: Optional LLM summarization of results

🚀 Quick Setup

Prerequisites

• Python 3.8+
• Optional: Ollama for LLM summarization

Installation

1. Clone or extract this directory

2. Create a virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Create your environment file

   cp .env.example .env

   Edit the .env file to customize your setup if needed.

📡 Usage

CLI Usage

The recon.py script provides a command-line interface for running recon tasks:

# Run username reconnaissance
python recon.py --username johndoe

# Run breach reconnaissance for an email
python recon.py --breach email@example.com --type email

# Run domain reconnaissance with subdomain enumeration
python recon.py --domain example.com --subdomains

# Run username reconnaissance with specific platforms
python recon.py --username johndoe --platforms twitter,github,linkedin

# Generate a summary of results (requires OLLAMA_HOST)
python recon.py --username johndoe --summarize

# Save results to a file
python recon.py --domain example.com --output results.json

API Usage

Start the API server:

cd recon_engine/api
uvicorn app:app --reload

Or use the built-in runner:

python -m recon_engine.api.app

API Endpoints

• Health Check: GET /health
• Username Recon: POST /username
• Breach Recon: POST /breach
• Domain Recon: POST /domain
• Ingest Target: POST /ingest
• Generate Summary: POST /summary

Example API request:

curl -X POST http://localhost:8000/username \
  -H "Content-Type: application/json" \
  -d '{"username": "johndoe", "platforms": ["twitter", "github", "linkedin"]}'

📁 Module Structure

• Username Recon: Searches for username across various platforms
• Breach Recon: Checks for email or domain in breach databases
• Domain Recon: Gathers information about domains including DNS, technologies, and security

🔄 JSON Logging

All operations are logged in structured JSON format in the logs directory:

• Run Logs: logs/recon_YYYYMMDD_HHMMSS.json
• Result Logs: logs/result_MODULE_YYYYMMDD_HHMMSS.json

🧠 Ollama Integration

To enable LLM summarization of results:

1. Install and run Ollama: https://ollama.ai/
2. Pull the llama3 model: ollama pull llama3
3. Set the OLLAMA_HOST environment variable in your .env file:

   OLLAMA_HOST=http://localhost:11434
   

🛠️ Extending the Engine

Adding a New Module

1. Create a new Python file in the modules directory
2. Implement the module's functionality
3. Add the module to the ReconEngine class in engine.py
4. Update the API and CLI interfaces as needed

Customizing Logging

The logging system can be customized by modifying the logger.py file.

🔒 Security Notes

• This is a reconnaissance tool intended for legitimate security research and OSINT
• Always ensure you have proper authorization before scanning targets
• The tool includes mock data for demonstration purposes
• Replace mock implementations with real API calls for production use

📝 License

This project is part of the Cerberus suite of security tools.