Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
307 lines (229 loc) · 7.75 KB

CONTRIBUTING.md

File metadata and controls

307 lines (229 loc) · 7.75 KB

Contributing to Worker OSINT Toolkit

Thank you for your interest in contributing! This toolkit exists to empower workers and support labor advocacy. Every contribution helps level the playing field.

🎯 Project Values

Before contributing, please understand our core values:

  1. Worker Safety First - Never compromise OPSEC or worker privacy
  2. Ethical Use Only - Tools must be used for legitimate advocacy
  3. Legal Boundaries - Respect laws while pushing for workers' rights
  4. Solidarity - Improvements benefit all workers, not just some
  5. Open Source - Keep the toolkit free and accessible

🤝 Ways to Contribute

Code Contributions

  • New OSINT tools or data sources
  • OPSEC improvements and privacy features
  • Performance optimizations
  • Bug fixes
  • Documentation improvements

Non-Code Contributions

  • User guides and tutorials
  • Jurisdiction-specific legal guidance
  • Use case examples and workflows
  • Translation to other languages
  • Testing and bug reports

🚀 Getting Started

1. Fork and Clone

git clone https://github.com/[your-username]/osint-mcp-server.git
cd osint-mcp-server

2. Set Up Development Environment

# Install dependencies
pip install -r requirements.txt

# Build Docker image
docker build -t worker-osint-mcp:dev .

# Run tests
python -m pytest tests/

3. Create a Branch

git checkout -b feature/your-feature-name

📝 Contribution Guidelines

Code Standards

Python Style

  • Follow PEP 8
  • Use type hints where appropriate
  • Add docstrings to all functions
  • Keep functions focused and testable

Security & Privacy

  • Never log sensitive investigation data
  • Use secure defaults (conservative privacy level)
  • Include OPSEC warnings where needed
  • Validate all external input
  • Never include API keys or credentials

Tool Development

async def new_osint_tool(
    target: str,
    privacy_level: str = "moderate"
) -> Dict[str, Any]:
    """
    Brief description of what the tool does.
    
    Args:
        target: What to investigate (domain, company, etc.)
        privacy_level: conservative, moderate, or aggressive
        
    Returns:
        Dict with results and metadata
        
    OPSEC Considerations:
        - Describe what traces this leaves
        - Warn about detection risks
        - Note any legal concerns
    """
    # Implementation

Commit Messages

Use clear, descriptive commit messages:

feat: Add LinkedIn company research tool
fix: Correct DNS query timeout handling  
docs: Update OPSEC guidance for subdomain scanning
security: Improve API key handling in config

Format: type: description

Types: feat, fix, docs, security, test, refactor, perf

Pull Request Process

  1. Before Submitting

    • Run all tests and ensure they pass
    • Update documentation if needed
    • Add OPSEC considerations for new tools
    • Test with different privacy levels
    • Check no secrets are committed

  2. PR Description

    ## What does this PR do?
Brief description

## Why is this needed?
Worker advocacy use case

## How was this tested?
Testing approach

## OPSEC Implications
Any new traces or detection risks

## Legal Considerations
Any jurisdiction-specific concerns

  3. Review Process

    • Maintainers will review for security/privacy
    • May request changes or clarifications
    • Must pass CI/CD checks
    • Requires approval from 1 maintainer

🛡️ Security & Privacy

Reporting Security Issues

DO NOT open public issues for security vulnerabilities.

Instead, email: [your-security-email@example.com]

Include:

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

We will respond within 48 hours and credit you in the fix (if desired).

Privacy Considerations

When adding features:

  • Minimize data collection
  • Prefer local processing over external APIs
  • Document what data leaves the user's machine
  • Provide options for maximum privacy
  • Never build features that could identify workers

🔍 Testing

Writing Tests

import pytest
from osint_server import new_tool

@pytest.mark.asyncio
async def test_new_tool_basic():
    """Test basic functionality"""
    result = await new_tool("example.com")
    assert "results" in result
    assert result["privacy_level"] == "moderate"

@pytest.mark.asyncio  
async def test_new_tool_privacy_levels():
    """Test all privacy levels work"""
    for level in ["conservative", "moderate", "aggressive"]:
        result = await new_tool("example.com", privacy_level=level)
        assert result["privacy_level"] == level

Running Tests

# All tests
pytest

# Specific test file
pytest tests/test_osint_tools.py

# With coverage
pytest --cov=osint_server tests/

📚 Documentation

What to Document

  1. Tool Purpose - Why workers need this
  2. How to Use - Clear examples
  3. OPSEC Warnings - What traces it leaves
  4. Legal Status - Permitted/prohibited/grey areas
  5. Use Cases - Real-world worker advocacy scenarios

Documentation Structure

Update these files as needed:

  • README.md - Project overview and quick start
  • docs/USAGE_GUIDE.md - Comprehensive tool documentation
  • docs/QUICK_REFERENCE.md - Fast command reference
  • docs/OPSEC_ADVANCED.md - Advanced privacy guidance

🌍 Jurisdiction-Specific Contributions

Adding support for new jurisdictions (countries/regions)?

Required:

  1. Business registry integration
  2. Local legal considerations
  3. Jurisdiction-specific use cases
  4. Relevant labor law resources
  5. Local privacy/surveillance laws

Example: Adding UK support

  • Companies House API integration
  • ACAS guidance for disputes
  • UK-specific OPSEC considerations
  • Employment tribunal procedures

🚫 What We Won't Accept

  • Tools that could be used to identify or harm workers
  • Features that encourage illegal activity
  • Anti-union or employer surveillance capabilities
  • Contributions from union-busting firms or consultants
  • Code that compromises user privacy or security
  • Anything that violates our ethical use clause

📞 Getting Help

  • Questions: Open a GitHub Discussion
  • Bugs: Open an issue with [BUG] prefix
  • Features: Open an issue with [FEATURE] prefix
  • Security: Email [security-email]

🎓 Learning Resources

New to OSINT? These resources help:

New to Python?

  • Python.org tutorials
  • Real Python for beginners
  • Automate the Boring Stuff

👥 Code of Conduct

Expected Behavior

  • Be respectful and inclusive
  • Focus on what's best for workers
  • Accept constructive criticism gracefully
  • Support other contributors

Unacceptable Behavior

  • Harassment or discrimination
  • Trolling or insulting comments
  • Publishing others' private information
  • Anti-worker or anti-union rhetoric
  • Any behavior inappropriate in a professional setting

Enforcement

Violations will result in:

  1. Warning
  2. Temporary ban
  3. Permanent ban

Report issues to: [conduct-email]

📜 License

By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.0, with the additional ethical use clause.

🙏 Recognition

Contributors will be recognized in:

  • GitHub contributors list
  • Release notes
  • Annual acknowledgments

Significant contributions may be highlighted in README.md

Remember: Every contribution helps workers fight for their rights. Your code could help document wage theft, expose safety violations, or support union organizing. That's powerful. Thank you for being part of this. ✊