Share 
## https://sploitus.com/exploit?id=94E07749-2E3B-5055-A6CE-12ABD0B09A88
# πŸ€– XBOW-Metascan: AI-Powered Autonomous Pentesting Platform

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](https://www.docker.com/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

> **AI-driven autonomous penetration testing platform inspired by XBOW, tailored for Metascan's vulnerability scanning ecosystem**

## 🎯 Overview

XBOW-Metascan is an enterprise-grade autonomous penetration testing platform that combines:
- **Multi-Agent AI Architecture** for distributed vulnerability discovery
- **LLM-Powered Exploit Generation** with OpenAI/Anthropic/Local models
- **Real-time Integration** with Metascan's scanning infrastructure
- **Automated PoC Generation** with curl/Docker command outputs
- **Intelligent Orchestration** for coordinated attack campaigns

### Key Differentiators vs XBOW

| Feature | XBOW (Commercial) | XBOW-Metascan (Open Source) |
|---------|-------------------|-----------------------------|
| Agent Architecture | Proprietary closed-source | Open multi-agent framework with LangChain/CrewAI |
| Exploit Database | 1092+ proprietary vulns | Integration with Metascan's 29 engines + OSS databases |
| Target Scope | Generic web/API | Optimized for Russian/CIS infrastructure |
| Pricing | Enterprise SaaS | Self-hosted, free for unlimited assets |
| Integration | Standalone platform | Deep Metascan API integration |
| Validation | AI-driven PoC | curl/docker cmdline generation for DevSecOps |

---

## πŸ“‹ Table of Contents

- [Architecture](#-architecture)
- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [AI Agents](#-ai-agents)
- [Integration with Metascan](#-integration-with-metascan)
- [Development](#-development)
- [Roadmap](#-roadmap)
- [Contributing](#-contributing)
- [License](#-license)

---

## πŸ—οΈ Architecture

See [ARCHITECTURE.md](./ARCHITECTURE.md) for comprehensive technical design.

```mermaid
graph TB
    subgraph "Control Plane"
        API[FastAPI REST API]
        WS[WebSocket Server]
        ORCH[Orchestrator Engine]
    end
    
    subgraph "AI Agent Layer"
        RECON[Reconnaissance Agent]
        VULN[Vulnerability Scanner Agent]
        EXPLOIT[Exploit Generator Agent]
        VALID[Validation Agent]
        REPORT[Reporting Agent]
    end
    
    subgraph "LLM Providers"
        GPT4[GPT-4 Turbo]
        CLAUDE[Claude 3.5 Sonnet]
        OLLAMA[Ollama Local]
    end
    
    subgraph "External Integrations"
        METASCAN[Metascan API]
        NVD[NVD Database]
        EXPLOITDB[ExploitDB]
    end
    
    API --> ORCH
    WS --> ORCH
    ORCH --> RECON
    ORCH --> VULN
    ORCH --> EXPLOIT
    ORCH --> VALID
    ORCH --> REPORT
    
    RECON -.LLM.-> GPT4
    VULN -.LLM.-> CLAUDE
    EXPLOIT -.LLM.-> OLLAMA
    
    RECON --> METASCAN
    VULN --> NVD
    EXPLOIT --> EXPLOITDB
```

### Core Components

1. **Orchestrator Engine** - Central coordinator using state machines
2. **AI Agent Framework** - LangChain/CrewAI-based autonomous agents
3. **Exploit Repository** - Versioned library of PoCs and exploits
4. **Validation Engine** - Safe sandbox for exploit testing
5. **Integration Layer** - Metascan API client with webhook support

---

## ✨ Features

### πŸ” Autonomous Discovery
- **Asset enumeration** via Metascan's 5 domain discovery mechanisms
- **Port scanning** integration with Metascan's 0-65535 full-range scanners
- **Service fingerprinting** using AI-enhanced signature matching
- **Attack surface mapping** with knowledge graph construction

### 🧠 AI-Powered Analysis
- **Multi-model LLM support** (GPT-4, Claude, LLaMA, Mistral via Ollama)
- **Chain-of-thought reasoning** for complex vulnerability chains
- **Self-healing exploits** that adapt to target responses
- **Context-aware payloads** generated based on target tech stack

### πŸ’₯ Exploit Automation
- **Zero-day research** using mutation-based fuzzing guided by LLMs
- **N-day weaponization** with CVE-to-PoC automation
- **Exploit chaining** for privilege escalation paths
- **Payload obfuscation** to evade WAF/IDS

### βœ… Validation & Reporting
- **PoC generation** as curl commands and Docker one-liners
- **Evidence collection** with screenshots and HTTP captures
- **CVSS scoring** with automated severity calculation
- **JSON/PDF reports** compatible with Metascan's dashboard

### πŸ”— Metascan Integration
- **Bidirectional sync** with Metascan's vulnerability database
- **Scheduled scanning** triggered by Metascan's daily checks
- **Lua script generation** for custom Metascan probes
- **ASN/RIPE integration** for automatic target expansion

---

## πŸš€ Installation

### Prerequisites

- **Python 3.11+** (async/await features required)
- **Docker 24.0+** & Docker Compose v2
- **8GB RAM minimum** (16GB recommended for LLM inference)
- **PostgreSQL 15+** or use Docker container
- **Redis 7+** for task queue

### Option 1: Docker Compose (Recommended)

```bash
# Clone repository
git clone https://github.com/Teketkom/metascan-xbow-ai-pentester.git
cd metascan-xbow-ai-pentester

# Copy environment template
cp .env.example .env

# Edit configuration (add API keys)
vim .env

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f orchestrator
```

Services will be available at:
- **API**: http://localhost:8000
- **WebSocket**: ws://localhost:8000/ws
- **Swagger docs**: http://localhost:8000/docs
- **PostgreSQL**: localhost:5432
- **Redis**: localhost:6379

### Option 2: Manual Installation

```bash
# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Setup database
psql -U postgres -c "CREATE DATABASE xbow_metascan;"
alembic upgrade head

# Start services
# Terminal 1: Redis
redis-server

# Terminal 2: Celery worker
celery -A app.worker worker --loglevel=info

# Terminal 3: API server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

---

## ⚑ Quick Start

### 1. Configure LLM Provider

```yaml
# config/config.yaml
llm:
  provider: "openai"  # Options: openai, anthropic, ollama
  model: "gpt-4-turbo-preview"
  api_key: "${OPENAI_API_KEY}"
  temperature: 0.7
  max_tokens: 4096
```

### 2. Connect Metascan

```bash
# Add Metascan API credentials
export METASCAN_API_KEY="your_api_key_here"
export METASCAN_BASE_URL="https://api.metascan.ru"

# Test connection
python -m app.cli metascan test-connection
```

### 3. Launch Your First Campaign

```bash
# Via CLI
python -m app.cli campaign create \
  --target example.com \
  --scope "web,api" \
  --intensity medium

# Via API
curl -X POST http://localhost:8000/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "scope": ["web", "api"],
    "intensity": "medium"
  }'
```

### 4. Monitor Progress

```bash
# Watch campaign in real-time
python -m app.cli campaign watch 

# Or via WebSocket
wscat -c ws://localhost:8000/ws/campaigns/
```

### 5. Export Results

```bash
# Generate report
python -m app.cli report generate \
  --campaign  \
  --format json,pdf \
  --output ./reports/

# Push to Metascan
python -m app.cli metascan push-results 
```

---

## βš™οΈ Configuration

### Environment Variables

```bash
# Core Settings
APP_ENV=production
DEBUG=false
LOG_LEVEL=INFO

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/xbow_metascan
REDIS_URL=redis://localhost:6379/0

# LLM Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434

# Metascan Integration
METASCAN_API_KEY=your_key
METASCAN_BASE_URL=https://api.metascan.ru
METASCAN_WEBHOOK_SECRET=webhook_secret

# Security
JWT_SECRET_KEY=your_jwt_secret
ENCRYPTION_KEY=fernet_key_here

# Rate Limiting
RATE_LIMIT_PER_MINUTE=60
MAX_CONCURRENT_CAMPAIGNS=5
```

### Advanced Configuration

See [docs/configuration.md](./docs/configuration.md) for:
- Agent behavior tuning
- Custom exploit modules
- Webhook configuration
- Performance optimization

---

## πŸ“– Usage

### CLI Commands

```bash
# Campaign Management
app.cli campaign create --target TARGET
app.cli campaign list
app.cli campaign status 
app.cli campaign stop 

# Agent Control
app.cli agent list
app.cli agent spawn --type recon --count 3
app.cli agent kill 

# Metascan Integration
app.cli metascan sync
app.cli metascan import-scan 
app.cli metascan generate-lua --vuln CVE-2023-1234

# Reporting
app.cli report generate --campaign 
app.cli report list
app.cli report export --format pdf
```

### Python API

```python
from app.client import XBOWClient

# Initialize client
client = XBOWClient(
    api_url="http://localhost:8000",
    api_key="your_api_key"
)

# Create campaign
campaign = client.campaigns.create(
    target="example.com",
    scope=["web", "api"],
    intensity="high"
)

# Monitor progress
for update in client.campaigns.watch(campaign.id):
    print(f"Status: {update.status}")
    print(f"Findings: {len(update.vulnerabilities)}")

# Get results
results = client.campaigns.get_results(campaign.id)
for vuln in results.vulnerabilities:
    print(f"[{vuln.severity}] {vuln.title}")
    print(f"PoC: {vuln.proof_of_concept.curl_command}")
```

---

## πŸ€– AI Agents

### Agent Types

#### 1. Reconnaissance Agent
**Purpose**: Asset discovery and enumeration
**Tools**: Subfinder, Amass, DNSRecon, Shodan API
**LLM Tasks**: 
- Identify interesting subdomains
- Prioritize attack surface
- Correlate OSINT data

#### 2. Vulnerability Scanner Agent
**Purpose**: Detect known and unknown vulnerabilities
**Tools**: Nuclei, Nikto, SQLMap, custom probes
**LLM Tasks**:
- Analyze HTTP responses for anomalies
- Suggest custom scan configurations
- Identify zero-day patterns

#### 3. Exploit Generator Agent
**Purpose**: Create working exploits for discovered vulns
**Tools**: Metasploit, custom exploit templates
**LLM Tasks**:
- Generate exploit code in Python/Bash
- Create obfuscated payloads
- Adapt exploits to target environment

#### 4. Validation Agent
**Purpose**: Verify exploits work safely
**Tools**: Docker sandboxes, HTTP capture
**LLM Tasks**:
- Analyze exploit output
- Generate curl/docker commands
- Calculate CVSS scores

#### 5. Reporting Agent
**Purpose**: Compile findings into actionable reports
**LLM Tasks**:
- Write vulnerability descriptions
- Suggest remediation steps
- Generate executive summaries

### Agent Communication

Agents coordinate via:
1. **Shared Knowledge Graph** - Neo4j database of findings
2. **Message Queue** - Redis pub/sub for events
3. **LLM Context Sharing** - RAG-based memory system

---

## πŸ”— Integration with Metascan

### Bidirectional Sync

```python
# Import Metascan scan into XBOW campaign
client.metascan.import_scan(
    scan_id="metascan_123",
    campaign_id="xbow_456"
)

# Push XBOW findings back to Metascan
client.metascan.push_vulnerabilities(
    campaign_id="xbow_456",
    metascan_project="project_789"
)
```

### Webhook Integration

```yaml
# Metascan triggers XBOW on new assets
POST /api/v1/webhooks/metascan
{
  "event": "scan.completed",
  "scan_id": "123",
  "assets": ["example.com"],
  "findings_count": 42
}
```

### Lua Script Generation

```bash
# Generate Metascan probe for discovered vuln
app.cli metascan generate-lua \
  --vuln-id xbow_vuln_123 \
  --output probes/custom_xss.lua

# Output: Metascan-compatible Lua NSE script
```

---

## πŸ› οΈ Development

### Project Structure

```
metascan-xbow-ai-pentester/
β”œβ”€β”€ app/
β”‚   β”œβ”€β”€ agents/              # AI agent implementations
β”‚   β”œβ”€β”€ api/                 # FastAPI routes
β”‚   β”œβ”€β”€ core/                # Business logic
β”‚   β”œβ”€β”€ db/                  # Database models
β”‚   β”œβ”€β”€ integrations/        # External API clients
β”‚   β”œβ”€β”€ llm/                 # LLM provider abstractions
β”‚   └── worker/              # Celery tasks
β”œβ”€β”€ config/                  # Configuration files
β”œβ”€β”€ docker/                  # Dockerfiles
β”œβ”€β”€ docs/                    # Documentation
β”œβ”€β”€ exploits/                # Exploit templates
β”œβ”€β”€ probes/                  # Metascan Lua scripts
β”œβ”€β”€ tests/                   # Test suite
└── scripts/                 # Utility scripts
```

### Running Tests

```bash
# Unit tests
pytest tests/unit/

# Integration tests
pytest tests/integration/

# E2E tests (requires Docker)
pytest tests/e2e/

# Coverage
pytest --cov=app tests/
```

### Code Quality

```bash
# Linting
ruff check app/

# Formatting
black app/
isort app/

# Type checking
mypy app/
```

---

## πŸ—ΊοΈ Roadmap

### Phase 1: MVP (Q1 2025) βœ…
- [x] Core orchestrator engine
- [x] Basic agent framework
- [x] Metascan API integration
- [x] OpenAI/Anthropic LLM support

### Phase 2: Advanced Features (Q2 2025)
- [ ] Exploit chaining engine
- [ ] Local LLM support (Ollama)
- [ ] Neo4j knowledge graph
- [ ] Web UI dashboard

### Phase 3: Enterprise (Q3 2025)
- [ ] Multi-tenancy support
- [ ] RBAC and audit logs
- [ ] Custom agent development SDK
- [ ] Marketplace for exploits/probes

### Phase 4: Research (Q4 2025)
- [ ] Zero-day discovery using fuzzing
- [ ] Autonomous exploit development
- [ ] Adversarial ML for evasion
- [ ] Integration with Bug Bounty platforms

---

## 🀝 Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

### Areas for Contribution
1. **New Agents** - Implement specialized agents (e.g., mobile, IoT)
2. **Exploits** - Add PoCs to `exploits/` directory
3. **Integrations** - Connect with other security tools
4. **Documentation** - Improve guides and examples
5. **Bug Fixes** - Help maintain code quality

---

## πŸ“„ License

MIT License - see [LICENSE](./LICENSE) for details.

---

## πŸ™ Acknowledgments

- **XBOW** for inspiration and approach methodology
- **Metascan** for integration partnership
- **LangChain/CrewAI** for agent framework
- **OpenAI/Anthropic** for LLM access
- Open source security community

---

## πŸ“ž Contact

- **Author**: Dmitriy Shalimov (Teketkom)
- **GitHub**: [@Teketkom](https://github.com/Teketkom)
- **Email**: [Your contact]
- **Issues**: [GitHub Issues](https://github.com/Teketkom/metascan-xbow-ai-pentester/issues)

---

**Built with ❀️ for the security community**