bugbounty-mcp-server

# 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 ```bash # 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 ```bash # 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 ```bash # 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 1. **Bug Bounty Workflow Management**: Complete workflow generation for different phases of bug bounty hunting 2. **Vulnerability Prioritization**: Intelligence-driven prioritization based on impact and bounty potential 3. **File Upload Testing**: Specialized framework for file upload vulnerability testing 4. **OSINT Integration**: Comprehensive OSINT gathering workflows 5. **Business Logic Testing**: Structured approach to business logic vulnerability discovery ## Spec-Kit Integration & AI-Assisted Development This repository integrates with [GitHub Spec-Kit](https://github.com/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: ```bash # 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: 1. **Specify Phase** (`.claude/commands/specify.md`) ```bash # Use Gemini CLI to analyze requirements and generate specifications npx @google/gemini-cli@nightly analyze-requirements --input "feature_description" ``` 2. **Planning Phase** (`.claude/commands/plan.md`) ```bash # Use Gemini CLI to validate and enhance implementation plans npx @google/gemini-cli@nightly review-plan --spec-file "path/to/spec.md" ``` 3. **Implementation Verification** ```bash # Use Gemini CLI as a code reviewer and security auditor npx @google/gemini-cli@nightly audit-security --focus bug-bounty-workflows ``` #### Recommended Workflow ```bash # 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: ```bash uv sync # Core dependencies only uv sync --dev # Include development tools ``` Add new dependencies: ```bash uv add package-name ``` ## Code Quality This project enforces code quality through automated pre-commit hooks: ```bash # 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.