Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
317 lines (223 loc) · 6.39 KB

CONTRIBUTING.md

File metadata and controls

317 lines (223 loc) · 6.39 KB

Contributing to ShadowHunter

First off, thank you for considering contributing to ShadowHunter! 🕵️

📋 Table of Contents

📜 Code of Conduct

This project adheres to ethical security research principles:

  1. Legal Compliance — Only contribute code for lawful purposes
  2. Responsible Disclosure — Report vulnerabilities ethically
  3. Privacy Respect — Never include real personal data in tests
  4. No Malicious Code — All contributions must be benign
  5. Attribution — Credit sources and prior work appropriately

🚀 Getting Started

Prerequisites

  • Python 3.9+
  • Neo4j 4.4+ (optional, for graph features)
  • Tor (optional, for dark web features)
  • Node.js 18+ (for frontend development)

Quick Setup

# Clone the repository
git clone https://github.com/yourusername/ShadowHunter.git
cd ShadowHunter

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

# Start the API server
python main.py api

🛠️ Development Setup

Environment Variables

Create a .env file (never commit this):

# API Keys (use test/dummy values for development)
HIBP_API_KEY=your_test_key
SHODAN_API_KEY=your_test_key

# Telegram (optional)
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your_hash

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Tor
TOR_PROXY=socks5://127.0.0.1:9050

Running in Development Mode

# Run with hot reload
uvicorn shadowhunter_api:app --reload --port 8000

# Run CLI in verbose mode
python main.py --verbose scan --domain example.com

✨ Making Changes

Branch Naming

  • feature/ — New features (e.g., feature/discord-monitor)
  • fix/ — Bug fixes (e.g., fix/telegram-parser)
  • docs/ — Documentation (e.g., docs/api-reference)
  • refactor/ — Code refactoring (e.g., refactor/crawler-async)

Workflow

  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes
  4. Write/update tests
  5. Update documentation
  6. Submit a pull request

📝 Coding Standards

Python Style

We follow PEP 8 with these additions:

# Use type hints
def process_credential(email: str, password: str) -> Credential:
    ...

# Use dataclasses for data structures
@dataclass
class ThreatAlert:
    severity: str
    message: str
    timestamp: datetime

# Async where appropriate
async def fetch_data(url: str) -> dict:
    ...

# Descriptive variable names
ransomware_leak_sites = []  # Good
rls = []  # Bad

Docstrings

Use Google-style docstrings:

def analyze_credential(email: str, password: str) -> dict:
    """Analyze a credential pair for security risks.
    
    Args:
        email: The email address to analyze.
        password: The password to check.
    
    Returns:
        A dictionary containing:
            - risk_score: Float from 0-100
            - issues: List of identified problems
            - recommendations: Suggested actions
    
    Raises:
        ValueError: If email format is invalid.
    
    Example:
        >>> result = analyze_credential("user@example.com", "password123")
        >>> print(result['risk_score'])
        85.0
    """

File Organization

shadowhunter/
├── core/           # Core functionality
├── monitors/       # Data source monitors
├── parsers/        # Data parsers
├── intelligence/   # Analysis modules
├── api/            # FastAPI routes
├── ui/             # Frontend components
└── utils/          # Utility functions

💬 Commit Guidelines

We use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

  • feat — New feature
  • fix — Bug fix
  • docs — Documentation only
  • style — Formatting, no code change
  • refactor — Code refactoring
  • test — Adding tests
  • chore — Maintenance tasks

Examples

feat(telegram): add support for private group monitoring
fix(crawler): handle timeout errors gracefully
docs(api): add authentication examples
refactor(core): extract credential parsing to separate module

🔄 Pull Request Process

Before Submitting

  • Code follows style guidelines
  • Tests pass locally (pytest)
  • Linting passes (flake8, mypy)
  • Documentation updated
  • No sensitive data in code
  • Branch is up to date with main

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
Describe how you tested the changes

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Code follows project style
- [ ] Tests added/updated
- [ ] Documentation updated

Review Process

  1. Automated checks must pass
  2. At least one maintainer review required
  3. All comments addressed
  4. Squash and merge preferred

🔒 Security Considerations

What NOT to Include

  • Real API keys or credentials
  • Actual dark web URLs
  • Personal identifying information
  • Malicious code or exploits
  • Copyrighted material

Sensitive Code Review

When working on:

  • Authentication (shadowhunter_auth.py)
  • Tor integration (shadowhunter_tor.py)
  • Credential parsing (shadowhunter_core.py)

Extra scrutiny is required. Tag security-sensitive PRs with security-review.

Reporting Vulnerabilities

Found a security issue? Do NOT open a public issue.

Email: security@shadowhunter.example.com

Include:

  • Description of the vulnerability
  • Steps to reproduce
  • Potential impact
  • Suggested fix (if any)

🎁 Recognition

Contributors will be recognized in:

  • CONTRIBUTORS.md
  • Release notes
  • Project README

📞 Getting Help

  • Discord: Join our server
  • GitHub Discussions: For questions and ideas
  • Issues: For bug reports and feature requests

Thank you for helping make ShadowHunter better! 🚀