# 🤝 Contributing to Bug Bounty Hunter MCP
Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
---
## 🎯 Ways to Contribute
### 1. Report Bugs
- Use GitHub Issues
- Include detailed reproduction steps
- Provide system information
- Include error messages/logs
### 2. Suggest Features
- Open a feature request
- Explain the use case
- Describe expected behavior
- Discuss implementation approach
### 3. Improve Documentation
- Fix typos and errors
- Add examples
- Improve clarity
- Translate to other languages
### 4. Add New Tools
- Implement new security tool integrations
- Follow existing patterns
- Add tests
- Update documentation
### 5. Fix Bugs
- Check existing issues
- Create a pull request
- Include tests
- Update changelog
---
## 🔧 Development Setup
### 1. Fork and Clone
```bash
git clone https://github.com/yourusername/bugbounty-hunter-mcp.git
cd bugbounty-hunter-mcp
```
### 2. Create Virtual Environment
```bash
python3 -m venv bb_venv
source bb_venv/bin/activate
```
### 3. Install Development Dependencies
```bash
pip install -e ".[dev]"
```
### 4. Create Feature Branch
```bash
git checkout -b feature/your-feature-name
```
---
## 📝 Code Style
### Python Style Guide
Follow PEP 8 with these additions:
```python
# Use type hints
def my_function(param: str) -> dict:
"""
Function description
Args:
param: Parameter description
Returns:
Description of return value
"""
return {"result": param}
# Use async/await for I/O operations
async def async_function() -> dict:
result = await some_async_operation()
return result
# Organize imports
import os # stdlib first
import sys
import httpx # third-party second
import pydantic
from src.utils import helpers # local third
```
### Format Code
```bash
# Auto-format with black
black .
# Sort imports
isort .
# Check with flake8
flake8 .
# Type check with mypy
mypy src/
```
---
## 🧪 Testing
### Write Tests
```python
# tests/test_validators.py
import pytest
from src.utils.validators import validate_url
def test_validate_url():
assert validate_url("https://example.com") == True
assert validate_url("not-a-url") == False
@pytest.mark.asyncio
async def test_async_function():
result = await my_async_function()
assert result["success"] == True
```
### Run Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html
# Run specific test
pytest tests/test_validators.py::test_validate_url
```
---
## 📚 Documentation
### Docstring Format
```python
def function_name(param1: str, param2: int = 10) -> dict:
"""
Brief one-line description.
Longer description if needed. Explain what the function does,
any important details, edge cases, etc.
Args:
param1: Description of param1
param2: Description of param2 (default: 10)
Returns:
Dictionary with:
- key1: Description of key1
- key2: Description of key2
Raises:
ValueError: When param1 is invalid
HTTPError: When request fails
Example:
>>> result = function_name("test", 20)
>>> print(result)
{'key1': 'value1', 'key2': 'value2'}
"""
pass
```
### Update Documentation
When adding features:
1. Update README.md
2. Update INSTALL.md if needed
3. Add examples to examples/
4. Update docstrings
5. Add to CHANGELOG.md
---
## 🔀 Pull Request Process
### 1. Before Submitting
- [ ] Code follows style guide
- [ ] Tests pass
- [ ] New tests added for new features
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] No merge conflicts
### 2. Pull Request Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guide
- [ ] Self-reviewed code
- [ ] Commented complex code
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests added/updated
```
### 3. Review Process
1. Submit PR
2. Automated checks run
3. Code review by maintainers
4. Address feedback
5. Approval and merge
---
## 🏗️ Project Structure
```
BugBountyHunterMCP/
├── bug_bounty_mcp.py # Main MCP server
├── src/
│ ├── core/ # Core functionality
│ │ ├── tool_manager.py
│ │ └── reporter.py
│ ├── tools/ # Tool implementations
│ │ ├── recon/
│ │ ├── vuln_scan/
│ │ ├── fuzzing/
│ │ └── ...
│ ├── utils/ # Utilities
│ │ ├── validators.py
│ │ └── helpers.py
│ └── workflows/ # Automation workflows
├── tests/ # Test files
├── docs/ # Documentation
└── examples/ # Usage examples
```
---
## 🎨 Adding a New Tool
### Step 1: Create Tool Module
```python
# src/tools/category/new_tool.py
from typing import Dict
from src.utils.helpers import run_command, get_timestamp
async def run_new_tool(
target: str,
option: str = "default"
) -> Dict:
"""
Run new tool
Args:
target: Target to scan
option: Tool option
Returns:
Results dictionary
"""
cmd = f"newtool --target {target} --option {option}"
result = await run_command(cmd, timeout=300)
return {
"target": target,
"timestamp": get_timestamp(),
"findings": parse_output(result['stdout']),
"success": result['success']
}
```
### Step 2: Add MCP Tool
```python
# bug_bounty_mcp.py
@mcp.tool()
async def new_tool_scan(
target: str,
option: str = "default"
) -> dict:
"""
Scan target using new tool
Args:
target: Target URL/domain
option: Scan option
Returns:
Scan results
"""
from src.tools.category.new_tool import run_new_tool
result = await run_new_tool(target, option)
return result
```
### Step 3: Add Tests
```python
# tests/test_new_tool.py
import pytest
from src.tools.category.new_tool import run_new_tool
@pytest.mark.asyncio
async def test_run_new_tool():
result = await run_new_tool("example.com", "quick")
assert result["success"] == True
assert "findings" in result
```
### Step 4: Update Documentation
- Add to README.md tool list
- Add example in examples/
- Update INSTALL.md if external tool needed
---
## 📋 Commit Message Guidelines
### Format
```
type(scope): subject
body (optional)
footer (optional)
```
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Code style (formatting)
- `refactor`: Code refactoring
- `test`: Tests
- `chore`: Maintenance
### Examples
```bash
feat(recon): add certificate transparency tool
Add tool to query CT logs for subdomain discovery.
Integrates with crt.sh API.
Closes #123
---
fix(nuclei): handle timeout errors properly
Nuclei scans were failing silently on timeout.
Now properly catches and reports timeout errors.
---
docs(install): update Go installation steps
Added instructions for macOS users.
```
---
## 🐛 Reporting Security Issues
**DO NOT** open public issues for security vulnerabilities.
Instead:
1. Email: security@example.com
2. Include detailed description
3. Provide steps to reproduce
4. Wait for response before disclosure
---
## 📜 Code of Conduct
### Our Pledge
We pledge to make participation in our project a harassment-free experience for everyone.
### Our Standards
**Positive behavior:**
- Using welcoming language
- Respecting differing viewpoints
- Accepting constructive criticism
- Focusing on what's best for the community
**Unacceptable behavior:**
- Harassment or discrimination
- Trolling or insulting comments
- Personal or political attacks
- Publishing private information
---
## 📞 Questions?
- **GitHub Discussions**: For general questions
- **GitHub Issues**: For bug reports and feature requests
- **Discord**: [Join our server](https://discord.gg/example)
- **Email**: dev@example.com
---
## 🙏 Recognition
Contributors will be:
- Listed in CONTRIBUTORS.md
- Mentioned in release notes
- Credited in documentation
---
**Thank you for contributing to Bug Bounty Hunter MCP!** 🎯🔐