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

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

• 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

• 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

# 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

# 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"}'

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

# 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

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

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

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

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

The Gemini CLI complements the existing spec-kit commands:

1. 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"

2. 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"

3. Implementation Verification

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

# 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

Project uses uv for fast, reliable dependency management:

• 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)

• 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

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

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

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