🎯 Worm AI - Advanced Offensive Security Orchestrator

An advanced AI-powered security testing platform that leverages specialized AI agents for OSINT reconnaissance, network scanning, and vulnerability analysis. Built with Express.js backend and React frontend.

Brief Summary

Worm AI is an enterprise-grade autonomous security assessment platform combining multiple AI models (DeepHat-V1-7B, GPT-3.5, DeepSeek, Mixtral) with 37+ integrated security tools across 15 categories. The platform orchestrates intelligent penetration testing workflows through specialized agents, providing comprehensive vulnerability assessment, exploitation, and professional reporting capabilities.

📋 Project Overview

This project provides an intelligent orchestration system for offensive security operations using AI agents powered by local AI models (Llama 3, Mixtral) via Ollama. The system includes:

• Specialized AI Agents: OSINT, Network Scanner, and Exploit agents with domain-specific capabilities
• Local AI Models: Run Llama 3 and Mixtral locally via Ollama (no API keys needed!)
• Real-time Progress Tracking: WebSocket-based live updates for task execution
• Multiple LLM Support: Choose between Llama 3, Mixtral, or DeepSeek (cloud)
• Real Security Tools Integration: Support for theHarvester, Amass, Subfinder, nmap, Masscan, RustScan, Nuclei
• Modern React Dashboard: Professional UI for task management and monitoring

🏗️ Project Structure

Worm AI/
├── server.js                    # Express server with Socket.IO
├── package.json                 # Backend dependencies
├── .env                         # Environment variables (API keys)
│
├── controllers/                 # Request handlers
│   ├── taskController.js       # Agent-based task execution
│   └── README.md               # Controller documentation
│
├── services/                    # AI services and agents
│   ├── Agent.js                # Base AI Agent class
│   ├── OsintAgent.js           # OSINT reconnaissance agent
│   ├── NetworkScannerAgent.js  # Network scanning agent
│   ├── ExploitAgent.js         # Vulnerability exploitation agent
│   ├── deepseekService.js      # DeepSeek API integration
│   ├── mixtralService.js       # Mixtral API integration
│   ├── offensiveTools.js       # 10 offensive security tools
│   └── README.md               # Service documentation
│
├── utils/                       # Utility functions
│   ├── osintTools.js           # OSINT tool simulations
│   ├── exploitTools.js         # Exploit tool simulations
│   ├── networkTools.js         # Network tool simulations
│   └── README.md               # Utils documentation
│
├── routes/                      # API routes
│   └── aiRoutes.js             # AI service endpoints
│
└── offensive-ai-frontend/       # React frontend
    ├── src/
    │   ├── pages/              # Page components
    │   ├── components/         # Reusable components
    │   ├── services/           # API & WebSocket clients
    │   └── styles/             # CSS styling
    └── package.json            # Frontend dependencies

🚀 Setup and Installation

Prerequisites

Before setting up the Offensive AI Orchestrator, ensure you have:

• Node.js (v18 or higher) - Download
• npm (comes with Node.js)
• Kali Linux (recommended) or any Linux distribution
• Git for cloning repositories
• 8GB+ RAM recommended for running local AI models

Local Model Setup (Recommended)

The Offensive AI Orchestrator now supports local AI models via Ollama, eliminating the need for cloud API keys and providing faster, private inference.

1. Install Ollama

On Kali Linux or any Linux system, run:

curl -fsSL https://ollama.com/install.sh | sh

This will:

• Download and install Ollama
• Set up Ollama as a systemd service
• Start the Ollama API server on http://localhost:11434

Verify installation:

ollama --version
systemctl status ollama

2. Pull AI Models

Download the models you want to use:

# Llama 3 8B - Recommended for balanced performance (4.7GB)
ollama pull llama3

# Mixtral 8x7B - Best quality, requires more resources (47GB)
ollama pull mixtral

# Optional: Smaller, faster models
ollama pull llama3.2:3b    # 2.0GB - Fast and efficient
ollama pull llama3.2:1b    # 1.3GB - Very fast
ollama pull phi3:3.8b      # 2.3GB - Good reasoning

Check downloaded models:

ollama list

3. Test Ollama

Verify models are working:

# Test Llama 3
ollama run llama3 "What is OSINT?"

# Test Mixtral
ollama run mixtral "Explain penetration testing"

# Test API endpoint
curl http://localhost:11434/api/version

4. Configure for Local Models

Your .env file should be configured for Ollama (this is the default):

# Server Configuration
PORT=3000
NODE_ENV=development

# Ollama Configuration (Local LLM)
USE_OLLAMA=true
OLLAMA_API_URL=http://localhost:11434
OLLAMA_BASE_URL=http://localhost:11434

# Optional: DeepSeek API (only if using cloud API)
# DEEPSEEK_API_KEY=your_deepseek_api_key_here

# Security Tools Configuration
ENABLE_REAL_TOOLS=false

Model Selection:

• Frontend can select between llama3, mixtral, or deepseek (if API key provided)
• Default model is llama3 (fast and efficient)
• Use mixtral for complex tasks requiring better reasoning
• Use deepseek only if you have an API key and prefer cloud inference

Backend Setup

1. Install dependencies:

npm install

2. Configure environment variables:

The .env file is already configured for Ollama by default. If you want to use cloud APIs instead:

# For cloud APIs (optional)
USE_OLLAMA=false
DEEPSEEK_API_KEY=your_deepseek_api_key_here

Getting API Keys (Optional):

• DeepSeek: Sign up at https://platform.deepseek.com/

3. Start the backend server:

# Production mode
npm start

# Development mode (with auto-reload)
npm run dev

The server will start on http://localhost:3000

Backend will automatically:

• Use Ollama for mixtral and llama3 model types
• Use DeepSeek API for deepseek model type (if configured)
• Default to Llama 3 on Ollama if no model specified

Frontend Setup

1. Navigate to frontend directory:

cd offensive-ai-frontend

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The frontend will start on http://localhost:5173

🔑 Environment Variables (.env)

The .env file contains sensitive configuration and API keys. Never commit this file to version control.

Required Variables:

• PORT: Server port (default: 3000)
• DEEPSEEK_API_KEY: API key for DeepSeek model
• MIXTRAL_API_KEY: API key for Mixtral model

Optional Variables:

• NODE_ENV: Environment mode (development/production)
• USE_OLLAMA: Use local Ollama instead of cloud APIs (true/false)
• OLLAMA_BASE_URL: Ollama server URL (default: http://localhost:11434)

Security Best Practices:

1. Use different API keys for development and production
2. Rotate keys regularly
3. Monitor API usage for suspicious activity
4. Consider using a key management service for production:
   • AWS Secrets Manager
   • Azure Key Vault
   • Google Cloud Secret Manager
   • HashiCorp Vault

📡 API Endpoints

Health Check

GET /health

Returns server health status.

AI Service Endpoints

POST /api/ai/deepseek
POST /api/ai/mixtral
POST /api/ai/ollama

Direct AI model API calls.

Task Execution

POST /api/start-task

Start a new AI agent task.

Request Body:

{
  "taskDescription": "Perform OSINT on example.com",
  "target": "example.com",
  "agentType": "osint",
  "modelType": "deepseek"
}

Agent Types:

• general - Base agent with general tools
• osint - OSINT reconnaissance specialist
• network - Network scanning specialist
• exploit - Vulnerability exploitation specialist

Model Types:

• llama3 - Llama 3 8B via Ollama (recommended, local, fast)
• mixtral - Mixtral 8x7B via Ollama (powerful, local, slower)
• deepseek - DeepSeek via cloud API (requires API key)

🔌 WebSocket Events

The server emits real-time progress updates via Socket.IO:

Event: task-progress

Data Structure:

{
  taskId: 'task_1703358000000',
  taskDescription: 'Perform OSINT on example.com',
  status: 'processing',
  progress: 45,
  message: 'Running theHarvester...',
  agentType: 'osint',
  modelType: 'deepseek',
  iterations: 3,
  answer: '...',
  error: null
}

🎯 Features

Specialized AI Agents

1. OSINT Agent 🔍

   • Subdomain enumeration
   • Email discovery
   • IP address resolution
   • theHarvester integration

2. Network Scanner Agent 🌐

   • Port scanning (nmap)
   • Service detection
   • Vulnerability scanning
   • Network mapping

3. Exploit Agent 🎯

   • Vulnerability analysis (Nuclei)
   • Payload generation (msfvenom)
   • Exploit development
   • PoC code generation

Security Tools Integration

The system supports both simulated (safe) and real security tools:

OSINT Tools:

• theHarvester - Email and subdomain discovery
• Amass - Deep subdomain enumeration
• Subfinder - Fast passive subdomain discovery
• DNSRecon - DNS record analysis

Network Scanning Tools:

• nmap - Comprehensive network scanner
• Masscan - Ultra-fast port scanner
• RustScan - Rapid port discovery

Exploitation Tools:

• Nuclei - Vulnerability scanner
• msfvenom - Payload generation (simulated only)

Tool Mode:

• Simulated (default): Safe, no actual scanning
• Real (optional): Actual tool execution (set ENABLE_REAL_TOOLS=true)
  • Requires tools to be installed on system
  • See tools/SETUP_*.md for installation instructions
  • Only use in authorized testing environments

📚 Documentation

• Services: See services/README.md for AI service documentation
• Agents: See services/AGENT_README.md for Agent class details
• OSINT Tools: See utils/README.md for OSINT tools documentation
• Controllers: See controllers/README.md for task controller info

🧪 Example Usage

// Start an OSINT task
const response = await fetch('http://localhost:3000/api/start-task', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    taskDescription: 'Perform OSINT reconnaissance on example.com',
    target: 'example.com',
    agentType: 'osint',
    modelType: 'deepseek'
  })
});

const data = await response.json();
console.log('Task started:', data.taskId);

⚠️ Important Notes

1. All security operations are SIMULATED - No actual scanning or exploitation occurs
2. For authorized testing only - Ensure you have permission before testing on real systems
3. API keys required - DeepSeek or Mixtral API keys needed for AI functionality
4. Educational purposes - This tool is for learning and authorized security testing

🛠️ Development

# Backend development
npm run dev

# Frontend development
cd offensive-ai-frontend
npm run dev

# Run example scripts
node services/osintAgentExample.js
node services/networkScannerExample.js
node services/exploitAgentExample.js

📝 License

ISC

🤝 Contributing

This is an educational project. Use responsibly and ethically.