fuzzforge_ai/CONTRIBUTING.md

Contributing to FuzzForge OSS

Thank you for your interest in contributing to FuzzForge OSS! We welcome contributions from the community and are excited to collaborate with you.

Our Vision: FuzzForge aims to be a universal platform for security research across all cybersecurity domains. Through our modular architecture, any security tool—from fuzzing engines to cloud scanners, from mobile app analyzers to IoT security tools—can be integrated as a containerized module and controlled via AI agents.

Ways to Contribute

• Security Modules - Create modules for any cybersecurity domain (AppSec, NetSec, Cloud, IoT, etc.)
• Bug Reports - Help us identify and fix issues
• Feature Requests - Suggest new capabilities and improvements
• Core Features - Contribute to the MCP server, runner, or CLI
• Documentation - Improve guides, tutorials, and module documentation
• Testing - Help test new features and report issues
• AI Integration - Improve MCP tools and AI agent interactions
• Tool Integrations - Wrap existing security tools as FuzzForge modules

Contribution Guidelines

Code Style

• Follow PEP 8 for Python code
• Use type hints where applicable
• Write clear, descriptive commit messages
• Include docstrings for all public functions and classes
• Add tests for new functionality

Commit Message Format

We use conventional commits for clear history:

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

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code formatting (no logic changes)
• refactor: Code restructuring without changing functionality
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(modules): add cloud security scanner module
fix(mcp): resolve module listing timeout
docs(sdk): update module development guide
test(runner): add container execution tests

Pull Request Process

1. Create a Branch

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-description
   

2. Make Your Changes

   • Write clean, well-documented code
   • Add tests for new functionality
   • Update documentation as needed

3. Test Your Changes

   # Test modules
   FUZZFORGE_MODULES_PATH=./fuzzforge-modules uv run fuzzforge modules list
   
   # Run a module
   uv run fuzzforge modules run your-module --assets ./test-assets
   
   # Test MCP integration (if applicable)
   uv run fuzzforge mcp status
   

4. Submit Pull Request

   • Use a clear, descriptive title
   • Provide detailed description of changes
   • Link related issues using Fixes #123 or Closes #123
   • Ensure all CI checks pass

Module Development

FuzzForge uses a modular architecture where security tools run as isolated containers. The fuzzforge-modules-sdk provides everything you need to create new modules.

Documentation:

• Module SDK Documentation - Complete SDK reference
• Module Template - Starting point for new modules
• USAGE Guide - Setup and installation instructions

Creating a New Module

1. Use the Module Template

   # Generate a new module from template
   cd fuzzforge-modules/
   cp -r fuzzforge-module-template my-new-module
   cd my-new-module
   

2. Module Structure

   my-new-module/
   ├── Dockerfile              # Container definition
   ├── Makefile                # Build commands
   ├── README.md               # Module documentation
   ├── pyproject.toml          # Python dependencies
   ├── mypy.ini                # Type checking config
   ├── ruff.toml               # Linting config
   └── src/
       └── module/
           ├── __init__.py
           ├── __main__.py     # Entry point
           ├── mod.py          # Main module logic
           ├── models.py       # Pydantic models
           └── settings.py     # Configuration
   

3. Implement Your Module

   Edit src/module/mod.py:

   from fuzzforge_modules_sdk.api.modules import BaseModule
   from fuzzforge_modules_sdk.api.models import ModuleResult
   from .models import MyModuleConfig, MyModuleOutput
   
   class MyModule(BaseModule[MyModuleConfig, MyModuleOutput]):
       """Your module description."""
   
       def execute(self) -> ModuleResult[MyModuleOutput]:
           """Main execution logic."""
           # Access input assets
           assets = self.input_path
   
           # Your security tool logic here
           results = self.run_analysis(assets)
   
           # Return structured results
           return ModuleResult(
               success=True,
               output=MyModuleOutput(
                   findings=results,
                   summary="Analysis complete"
               )
           )
   

4. Define Configuration Models

   Edit src/module/models.py:

   from pydantic import BaseModel, Field
   from fuzzforge_modules_sdk.api.models import BaseModuleConfig, BaseModuleOutput
   
   class MyModuleConfig(BaseModuleConfig):
       """Configuration for your module."""
       timeout: int = Field(default=300, description="Timeout in seconds")
       max_iterations: int = Field(default=1000, description="Max iterations")
   
   class MyModuleOutput(BaseModuleOutput):
       """Output from your module."""
       findings: list[dict] = Field(default_factory=list)
       coverage: float = Field(default=0.0)
   

5. Build Your Module

   # Build the SDK first (if not already done)
   cd ../fuzzforge-modules-sdk
   uv build
   mkdir -p .wheels
   cp ../../dist/fuzzforge_modules_sdk-*.whl .wheels/
   cd ../..
   docker build -t localhost/fuzzforge-modules-sdk:0.1.0 fuzzforge-modules/fuzzforge-modules-sdk/
   
   # Build your module
   cd fuzzforge-modules/my-new-module
   docker build -t fuzzforge-my-new-module:0.1.0 .
   

6. Test Your Module

   # Run with test assets
   uv run fuzzforge modules run my-new-module --assets ./test-assets
   
   # Check module info
   uv run fuzzforge modules info my-new-module
   

Module Development Guidelines

Important Conventions:

• Input/Output: Use /fuzzforge/input for assets and /fuzzforge/output for results
• Configuration: Support JSON configuration via stdin or file
• Logging: Use structured logging (structlog is pre-configured)
• Error Handling: Return proper exit codes and error messages
• Security: Run as non-root user when possible
• Documentation: Include clear README with usage examples
• Dependencies: Minimize container size, use multi-stage builds

See also:

• Module SDK API Reference
• Dockerfile Best Practices

Module Types

FuzzForge is designed to support modules across all cybersecurity domains. The modular architecture allows any security tool to be containerized and integrated. Here are the main categories:

Application Security

• Fuzzing engines (coverage-guided, grammar-based, mutation-based)
• Static analysis (SAST, code quality, dependency scanning)
• Dynamic analysis (DAST, runtime analysis, instrumentation)
• Test validation and coverage analysis
• Crash analysis and exploit detection

Network & Infrastructure Security

• Network scanning and service enumeration
• Protocol analysis and fuzzing
• Firewall and configuration testing
• Cloud security (AWS/Azure/GCP misconfiguration detection, IAM analysis)
• Container security (image scanning, Kubernetes security)

Web & API Security

• Web vulnerability scanners (XSS, SQL injection, CSRF)
• Authentication and session testing
• API security (REST/GraphQL/gRPC testing, fuzzing)
• SSL/TLS analysis

Binary & Reverse Engineering

• Binary analysis and disassembly
• Malware sandboxing and behavior analysis
• Exploit development tools
• Firmware extraction and analysis

Mobile & IoT Security

• Mobile app analysis (Android/iOS static/dynamic analysis)
• IoT device security and firmware analysis
• SCADA/ICS and industrial protocol testing
• Automotive security (CAN bus, ECU testing)

Data & Compliance

• Database security testing
• Encryption and cryptography analysis
• Secrets and credential detection
• Privacy tools (PII detection, GDPR compliance)
• Compliance checkers (PCI-DSS, HIPAA, SOC2, ISO27001)

Threat Intelligence & Risk

• OSINT and reconnaissance tools
• Threat hunting and IOC correlation
• Risk assessment and attack surface mapping
• Security audit and policy validation

Emerging Technologies

• AI/ML security (model poisoning, adversarial testing)
• Blockchain and smart contract analysis
• Quantum-safe cryptography testing

Custom & Integration

• Domain-specific security tools
• Bridges to existing security tools
• Multi-tool orchestration and result aggregation

Example: Simple Security Scanner Module

# src/module/mod.py
from pathlib import Path
from fuzzforge_modules_sdk.api.modules import BaseModule
from fuzzforge_modules_sdk.api.models import ModuleResult
from .models import ScannerConfig, ScannerOutput

class SecurityScanner(BaseModule[ScannerConfig, ScannerOutput]):
    """Scans for common security issues in code."""
    
    def execute(self) -> ModuleResult[ScannerOutput]:
        findings = []
        
        # Scan all source files
        for file_path in self.input_path.rglob("*"):
            if file_path.is_file():
                findings.extend(self.scan_file(file_path))
        
        return ModuleResult(
            success=True,
            output=ScannerOutput(
                findings=findings,
                files_scanned=len(list(self.input_path.rglob("*")))
            )
        )
    
    def scan_file(self, path: Path) -> list[dict]:
        """Scan a single file for security issues."""
        # Your scanning logic here
        return []

Testing Modules

Create tests in tests/:

import pytest
from module.mod import MyModule
from module.models import MyModuleConfig

def test_module_execution():
    config = MyModuleConfig(timeout=60)
    module = MyModule(config=config, input_path=Path("test_assets"))
    result = module.execute()
    
    assert result.success
    assert len(result.output.findings) >= 0

Run tests:

uv run pytest

Security Guidelines

Critical Requirements:

• Never commit secrets, API keys, or credentials
• Focus on defensive security tools and analysis
• Do not create tools for malicious purposes
• Test modules thoroughly before submission
• Follow responsible disclosure for security issues
• Use minimal, secure base images for containers
• Avoid running containers as root when possible

Security Resources:

• OWASP Container Security
• CIS Docker Benchmarks

Contributing to Core Features

Beyond modules, you can contribute to FuzzForge's core components.

Useful Resources:

• Project Structure - Overview of the codebase
• USAGE Guide - Installation and setup
• Python best practices: PEP 8

Core Components

• fuzzforge-mcp - MCP server for AI agent integration
• fuzzforge-runner - Module execution engine
• fuzzforge-cli - Command-line interface
• fuzzforge-common - Shared utilities and sandbox engines
• fuzzforge-types - Type definitions and schemas

Development Setup

1. Clone and Install

   git clone https://github.com/FuzzingLabs/fuzzforge-oss.git
   cd fuzzforge-oss
   uv sync --all-extras
   

2. Run Tests

   # Run all tests
   make test
   
   # Run specific package tests
   cd fuzzforge-mcp
   uv run pytest
   

3. Type Checking

   # Type check all packages
   make typecheck
   
   # Type check specific package
   cd fuzzforge-runner
   uv run mypy .
   

4. Linting and Formatting

   # Format code
   make format
   
   # Lint code
   make lint
   

Bug Reports

When reporting bugs, please include:

• Environment: OS, Python version, Docker version, uv version
• FuzzForge Version: Output of uv run fuzzforge --version
• Module: Which module or component is affected
• Steps to Reproduce: Clear steps to recreate the issue
• Expected Behavior: What should happen
• Actual Behavior: What actually happens
• Logs: Relevant error messages and stack traces
• Container Logs: For module issues, include Docker/Podman logs
• Screenshots: If applicable

Example:

**Environment:**
- OS: Ubuntu 22.04
- Python: 3.14.2
- Docker: 24.0.7
- uv: 0.5.13

**Module:** my-custom-scanner

**Steps to Reproduce:**
1. Run `uv run fuzzforge modules run my-scanner --assets ./test-target`
2. Module fails with timeout error

**Expected:** Module completes analysis
**Actual:** Times out after 30 seconds

**Logs:**

ERROR: Module execution timeout ...

Feature Requests

For new features, please provide:

• Use Case: Why is this feature needed?
• Proposed Solution: How should it work?
• Alternatives: Other approaches considered
• Implementation: Technical considerations (optional)
• Module vs Core: Should this be a module or core feature?

Example Feature Requests:

• New module for cloud security posture management (CSPM)
• Module for analyzing smart contract vulnerabilities
• MCP tool for orchestrating multi-module workflows
• CLI command for batch module execution across multiple targets
• Support for distributed fuzzing campaigns
• Integration with CI/CD pipelines
• Module marketplace/registry features

Documentation

Help improve our documentation:

• Module Documentation: Document your modules in their README.md
• API Documentation: Update docstrings and type hints
• User Guides: Improve USAGE.md and tutorial content
• Module SDK Guides: Help document the SDK for module developers
• MCP Integration: Document AI agent integration patterns
• Examples: Add practical usage examples and workflows

Documentation Standards

• Use clear, concise language
• Include code examples
• Add command-line examples with expected output
• Document all configuration options
• Explain error messages and troubleshooting

Module README Template

# Module Name

Brief description of what this module does.

## Features

- Feature 1
- Feature 2

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| timeout   | int  | 300     | Timeout in seconds |

## Usage

\`\`\`bash
uv run fuzzforge modules run module-name --assets ./path/to/assets
\`\`\`

## Output

Describes the output structure and format.

## Examples

Practical usage examples.

Recognition

Contributors will be:

• Listed in our Contributors file
• Mentioned in release notes for significant contributions
• Credited in module documentation (for module authors)
• Invited to join our Discord community

Module Submission Checklist

Before submitting a new module:

• Module follows SDK structure and conventions
• Dockerfile builds successfully
• Module executes without errors
• Configuration options are documented
• README.md is complete with examples
• Tests are included (pytest)
• Type hints are used throughout
• Linting passes (ruff)
• Security best practices followed
• No secrets or credentials in code
• License headers included

Review Process

1. Initial Review - Maintainers review for completeness
2. Technical Review - Code quality and security assessment
3. Testing - Module tested in isolated environment
4. Documentation Review - Ensure docs are clear and complete
5. Approval - Module merged and included in next release

License

By contributing to FuzzForge OSS, you agree that your contributions will be licensed under the same license as the project (see LICENSE).

For module contributions:

• Modules you create remain under the project license
• You retain credit as the module author
• Your module may be used by others under the project license terms

---

Getting Help

Need help contributing?

• Join our Discord
• Read the Module SDK Documentation
• Check the module template for examples
• Contact: contact@fuzzinglabs.com

---

Thank you for making FuzzForge better!

Every contribution, no matter how small, helps build a stronger security research platform. Whether you're creating a module for web security, cloud scanning, mobile analysis, or any other cybersecurity domain, your work makes FuzzForge more powerful and versatile for the entire security community!