Bug Bounty MCP Server

A clean, focused server containing bug bounty hunting workflows and REST API endpoints.

For AI coding assistants, see AGENTS.md for repository-specific guidance.

Features

Clean Architecture: Removed bloat and unnecessary dependencies while maintaining core functionality
Bug Bounty Focused: Specialized workflows for reconnaissance, vulnerability hunting, business logic testing, OSINT, and file upload testing
REST API Endpoints: Simple HTTP API for workflow generation and management
Comprehensive Assessments: Combine multiple workflows for complete bug bounty assessments

Architecture

Core Components

REST API Server (src/rest_api_server/app.py) - Flask-based HTTP API server with bug bounty workflow endpoints
MCP Server (src/mcp_server/app.py) - FastMCP-based server for AI agent communication
Bug Bounty Workflows (src/rest_api_server/workflows/) - Specialized workflow generation for different phases of testing
Tool Integration (src/rest_api_server/tools/) - Consolidated security tool wrappers
Shared Utilities (src/rest_api_server/utils/ & src/rest_api_server/logger.py) - Registry, logging, and helper utilities shared across endpoints

Quick Start

1. Install Dependencies & Start the Server

# Install dependencies with uv
uv sync

# Install development dependencies (optional)
uv sync --dev

# Set up pre-commit hooks (recommended for development)
uv run pre-commit install

# Start the server
uv run -m src.rest_api_server

# Or with environment variables
DEBUG=true BUGBOUNTY_MCP_PORT=8888 uv run -m src.rest_api_server

# Or use the launcher script
./start-server.sh --debug --port 8888

2. Test the API

# Create reconnaissance workflow
curl -X POST http://127.0.0.1:8888/api/bugbounty/reconnaissance-workflow \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "program_type": "web"}'

Configuration

Environment Variables

BUGBOUNTY_MCP_PORT: Server port (default: 8888)
BUGBOUNTY_MCP_HOST: Server host (default: 127.0.0.1)
DEBUG: Enable debug mode (default: false)

Usage Examples

# Start with default configuration
uv run -m src.rest_api_server

# Start with custom configuration
DEBUG=true BUGBOUNTY_MCP_PORT=9999 BUGBOUNTY_MCP_HOST=0.0.0.0 uv run -m src.rest_api_server

Key Features

Bug Bounty Workflow Management: Complete workflow generation for different phases of bug bounty hunting
Vulnerability Prioritization: Intelligence-driven prioritization based on impact and bounty potential
File Upload Testing: Specialized framework for file upload vulnerability testing
OSINT Integration: Comprehensive OSINT gathering workflows
Business Logic Testing: Structured approach to business logic vulnerability discovery

Spec-Kit Integration & AI-Assisted Development

This repository integrates with GitHub Spec-Kit for specification-driven development workflow, enhanced with AI assistance for codebase exploration, planning, and verification.

Gemini CLI Integration

The repository includes integration with Google's Gemini CLI for enhanced AI-powered development assistance:

# Install Gemini CLI (nightly version for latest features)
npx @google/gemini-cli@nightly

Key Use Cases

Codebase Exploration

Analyze complex bug bounty tool integrations and workflows
Understand relationships between MCP server components and REST API endpoints
Navigate through security tool configurations and vulnerability detection patterns

Planning & Specification

Generate comprehensive implementation plans for new bug bounty workflows
Create detailed specifications for security tool integrations
Plan testing strategies for vulnerability detection capabilities

Code Review & Verification

Validate implementation quality against security best practices
Review bug bounty workflow logic for completeness and accuracy
Verify API endpoint security and error handling
Analyze tool output parsing and vulnerability classification

Integration with Spec-Kit Workflow

The Gemini CLI complements the existing spec-kit commands:

Specify Phase (.claude/commands/specify.md)

# Use Gemini CLI to analyze requirements and generate specifications
npx @google/gemini-cli@nightly analyze-requirements --input "feature_description"

Planning Phase (.claude/commands/plan.md)

# Use Gemini CLI to validate and enhance implementation plans
npx @google/gemini-cli@nightly review-plan --spec-file "path/to/spec.md"

Implementation Verification

# Use Gemini CLI as a code reviewer and security auditor
npx @google/gemini-cli@nightly audit-security --focus bug-bounty-workflows

Recommended Workflow

# 1. Explore codebase before making changes
npx @google/gemini-cli@nightly explore --focus "bug bounty tools integration"

# 2. Plan new features with AI assistance
npx @google/gemini-cli@nightly plan --spec-driven --security-focused

# 3. Verify implementations against security standards
npx @google/gemini-cli@nightly verify --check-security --validate-workflows

Dependencies

Project uses uv for fast, reliable dependency management:

Core Dependencies

Flask: Web framework for REST API
FastMCP: MCP server framework
Requests: HTTP client library
Python 3.11+: Core runtime (supports Python 3.11, 3.12, 3.13)

Development Dependencies

Ruff: Fast Python linter and formatter
Bandit: Security vulnerability scanner
Pydocstyle: Documentation quality checker
Pyright: Static type checker
Pre-commit: Git pre-commit hooks framework

Install dependencies:

uv sync                # Core dependencies only
uv sync --dev         # Include development tools

Add new dependencies:

uv add package-name

Code Quality

This project enforces code quality through automated pre-commit hooks:

# Install pre-commit hooks
uv run pre-commit install

# Run checks on all files
uv run pre-commit run --all-files

# Run specific checks
uv run ruff check          # Linting
uv run ruff format         # Formatting
uv run bandit -c pyproject.toml # Security scan
uv run pydocstyle          # Documentation check

Standards:

Line length: 88 characters
Documentation: Google docstring convention
Type hints: Required for public APIs
Security: Bandit security scanning enabled

Contributing

We welcome contributions. Please see CONTRIBUTING.md for guidelines.

Using an AI coding assistant? Start with AGENTS.md for repository-specific guidance.