Hera - MCP Red Teaming Server

A comprehensive Model Context Protocol (MCP) server for conducting red teaming exercises with AI-powered vulnerability analysis and multi-tool integration.

Features

Multi-Provider AI Integration: OpenAI, Perplexity, and Manus for intelligent vulnerability analysis
Burp Suite Professional Integration: Full REST API support for automated scanning
Open Source Security Tools: Nmap, OWASP ZAP, Metasploit integration
Comprehensive Red Teaming Modules:
- Web Application Security (OWASP Top 10, API testing)
- Network Infrastructure Reconnaissance
- Social Engineering Simulation
Security Controls: Token-based authentication, scope validation, audit logging
AI-Powered Analysis: Vulnerability assessment, attack vector suggestions, report generation

Architecture

hera/
├── src/
│   ├── server.ts                 # MCP server entry point
│   ├── tools/                    # Red teaming modules
│   │   ├── web-security.ts       # Web app security testing
│   │   ├── network-recon.ts      # Network enumeration
│   │   └── social-engineering.ts # Social engineering simulation
│   ├── providers/                # AI provider clients
│   │   ├── openai-client.ts
│   │   ├── perplexity-client.ts
│   │   ├── manus-client.ts
│   │   └── ai-router.ts          # Smart provider selection
│   ├── integrations/             # External tool integrations
│   │   ├── burp-suite.ts         # Burp REST API client
│   │   ├── nmap.ts
│   │   └── owasp-zap.ts
│   ├── auth/                     # Authentication & authorization
│   │   ├── token-manager.ts
│   │   └── scope-validator.ts
│   ├── audit/                    # Audit logging
│   │   └── logger.ts
│   └── types/                    # TypeScript definitions
├── config/                       # Configuration files
├── tests/                        # Test suite
└── logs/                         # Audit and error logs

Installation

Clone the repository:

git clone <repository-url>
cd hera

Install dependencies:

npm install

Configure environment variables:

cp env.example .env

Edit .env with your API keys and configuration:

# AI Provider API Keys
OPENAI_API_KEY=your_openai_api_key_here
PERPLEXITY_API_KEY=your_perplexity_api_key_here
MANUS_API_KEY=your_manus_api_key_here

# Burp Suite Professional Configuration
BURP_API_URL=http://localhost:8090
BURP_API_KEY=your_burp_api_key_here

# Authentication & Security
AUTH_SECRET=your_jwt_secret_here
JWT_EXPIRY=24h

# Logging Configuration
LOG_LEVEL=info
AUDIT_LOG_PATH=./logs/audit.log
ERROR_LOG_PATH=./logs/error.log

Configure approved targets: Edit config/approved-targets.json to define your testing scope:

{
  "domains": [
    {
      "domain": "example.com",
      "description": "Test domain for red teaming exercises",
      "approvedBy": "security-team",
      "approvedAt": "2024-01-01T00:00:00Z",
      "scope": ["*.example.com", "api.example.com"]
    }
  ],
  "ipRanges": [
    {
      "range": "192.168.1.0/24",
      "description": "Internal test network",
      "approvedBy": "security-team",
      "approvedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Setup Requirements

Burp Suite Professional

Install Burp Suite Professional
Download and install the Burp REST API extension
Start Burp Suite with REST API enabled:

java --add-opens=java.desktop/javax.swing=ALL-UNNAMED \
     --add-opens=java.base/java.lang=ALL-UNNAMED \
     -cp "burpsuite_pro.jar:burp-rest-api-2.3.2.jar" \
     org.springframework.boot.loader.launch.JarLauncher

OWASP ZAP

Download and install OWASP ZAP
Start ZAP with API enabled:

zap.sh -daemon -host 0.0.0.0 -port 8080 -config api.key=your-api-key

Security Tools

Install required security tools:

# Nmap
sudo apt install nmap  # Ubuntu/Debian
brew install nmap      # macOS

# Other tools (optional)
sudo apt install nikto sqlmap

Usage

Starting the Server

# Development
npm run dev

# Production
npm run build
npm start

MCP Tools

The server provides the following MCP tools:

1. Web Application Security Scanning

{
  "name": "scan_web_app",
  "arguments": {
    "target": "https://example.com",
    "scanType": "active",
    "options": {
      "includeSubdomains": true,
      "authentication": {
        "type": "bearer",
        "credentials": "your-token"
      }
    }
  }
}

2. Network Reconnaissance

{
  "name": "enumerate_network",
  "arguments": {
    "target": "192.168.1.0/24",
    "scanType": "vulnerability",
    "options": {
      "ports": "1-1000",
      "timing": "T3",
      "scripts": ["vuln", "safe"]
    }
  }
}

3. API Security Testing

{
  "name": "test_api_security",
  "arguments": {
    "target": "https://api.example.com",
    "apiType": "rest",
    "endpoints": ["/users", "/posts"],
    "options": {
      "authentication": {
        "type": "api-key",
        "credentials": "your-api-key"
      }
    }
  }
}

4. Phishing Simulation

{
  "name": "simulate_phishing",
  "arguments": {
    "target": "example.com",
    "campaignType": "email",
    "template": "security-alert",
    "options": {
      "recipients": ["[email protected]"],
      "tracking": true
    }
  }
}

5. Burp Suite Results Analysis

{
  "name": "analyze_burp_results",
  "arguments": {
    "scanId": "scan-123",
    "analysisType": "vulnerabilities",
    "options": {
      "severityFilter": ["high", "critical"],
      "generateReport": true
    }
  }
}

6. Report Generation

{
  "name": "generate_report",
  "arguments": {
    "scanResults": ["scan-123", "scan-456"],
    "reportType": "executive",
    "options": {
      "includeRecommendations": true,
      "format": "html"
    }
  }
}

Security Features

Authentication & Authorization

JWT-based token authentication
Role-based permissions
Scope validation for targets
Rate limiting

Audit Logging

Comprehensive audit trail
Security event logging
Tool execution tracking
AI analysis logging

Safety Controls

Approved targets whitelist
Tool permission validation
Time window restrictions
Emergency stop capabilities

Testing

Run the test suite:

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

Configuration

AI Provider Configuration

Edit config/tool-configs.json to customize AI provider settings:

{
  "aiProviders": {
    "openai": {
      "model": "gpt-4-turbo-preview",
      "maxTokens": 4000,
      "temperature": 0.3
    },
    "perplexity": {
      "model": "llama-3.1-sonar-large-128k-online",
      "maxTokens": 4000,
      "temperature": 0.2
    }
  }
}

Tool Configuration

Configure security tool settings:

{
  "burpSuite": {
    "apiUrl": "http://localhost:8090",
    "timeout": 300000,
    "scanOptions": {
      "maxScanTime": 3600000,
      "scanSpeed": "thorough"
    }
  },
  "nmap": {
    "defaultTiming": "T3",
    "maxHosts": 1000,
    "timeout": 300
  }
}

API Documentation

MCP Protocol

This server implements the Model Context Protocol (MCP) specification. All tools are exposed through the standard MCP interface.

Tool Discovery

Use the list_tools MCP method to discover available tools and their schemas.

Tool Execution

Use the call_tool MCP method to execute tools with the provided arguments.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the documentation
Review the test cases
Open an issue on GitHub
Contact the security team

Disclaimer

This tool is designed for authorized security testing only. Ensure you have proper authorization before conducting any red teaming activities. The authors are not responsible for any misuse of this tool.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
api		api
config		config
src		src
tests		tests
ui		ui
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile.mcp		Dockerfile.mcp
README.md		README.md
docker-compose.yml		docker-compose.yml
env.example		env.example
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

1willF0llow/hera

Folders and files

Latest commit

History

Repository files navigation