diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6529eec..638be6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,21 @@ -# Contributing to FuzzForge 🀝 +# Contributing to FuzzForge OSS -Thank you for your interest in contributing to FuzzForge! We welcome contributions from the community and are excited to collaborate with you. +Thank you for your interest in contributing to FuzzForge OSS! We welcome contributions from the community and are excited to collaborate with you. -## 🌟 Ways to Contribute +**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. -- πŸ› **Bug Reports** - Help us identify and fix issues -- πŸ’‘ **Feature Requests** - Suggest new capabilities and improvements -- πŸ”§ **Code Contributions** - Submit bug fixes, features, and enhancements -- πŸ“š **Documentation** - Improve guides, tutorials, and API documentation -- πŸ§ͺ **Testing** - Help test new features and report issues -- πŸ›‘οΈ **Security Workflows** - Contribute new security analysis workflows +## Ways to Contribute -## πŸ“‹ Contribution Guidelines +- **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 @@ -44,9 +48,10 @@ We use conventional commits for clear history: **Examples:** ``` -feat(workflows): add new static analysis workflow for Go -fix(api): resolve authentication timeout issue -docs(readme): update installation instructions +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 @@ -65,9 +70,14 @@ docs(readme): update installation instructions 3. **Test Your Changes** ```bash - # Test workflows - cd test_projects/vulnerable_app/ - ff workflow security_assessment . + # 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** @@ -76,65 +86,353 @@ docs(readme): update installation instructions - Link related issues using `Fixes #123` or `Closes #123` - Ensure all CI checks pass -## πŸ›‘οΈ Security Workflow Development +## Module Development -### Creating New Workflows +FuzzForge uses a modular architecture where security tools run as isolated containers. The `fuzzforge-modules-sdk` provides everything you need to create new modules. -1. **Workflow Structure** - ``` - backend/toolbox/workflows/your_workflow/ - β”œβ”€β”€ __init__.py - β”œβ”€β”€ workflow.py # Main Temporal workflow - β”œβ”€β”€ activities.py # Workflow activities (optional) - β”œβ”€β”€ metadata.yaml # Workflow metadata (includes vertical field) - └── requirements.txt # Additional dependencies (optional) +**Documentation:** +- [Module SDK Documentation](fuzzforge-modules/fuzzforge-modules-sdk/README.md) - Complete SDK reference +- [Module Template](fuzzforge-modules/fuzzforge-module-template/) - Starting point for new modules +- [USAGE Guide](USAGE.md) - Setup and installation instructions + +### Creating a New Module + +1. **Use the Module Template** + ```bash + # Generate a new module from template + cd fuzzforge-modules/ + cp -r fuzzforge-module-template my-new-module + cd my-new-module ``` -2. **Register Your Workflow** - Add your workflow to `backend/toolbox/workflows/registry.py`: +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`: ```python - # Import your workflow - from .your_workflow.workflow import main_flow as your_workflow_flow - - # Add to registry - WORKFLOW_REGISTRY["your_workflow"] = { - "flow": your_workflow_flow, - "module_path": "toolbox.workflows.your_workflow.workflow", - "function_name": "main_flow", - "description": "Description of your workflow", - "version": "1.0.0", - "author": "Your Name", - "tags": ["tag1", "tag2"] - } + 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" + ) + ) ``` -3. **Testing Workflows** - - Create test cases in `test_projects/vulnerable_app/` - - Ensure SARIF output format compliance - - Test with various input scenarios +4. **Define Configuration Models** + + Edit `src/module/models.py`: + ```python + 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** + ```bash + # 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** + ```bash + # 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](fuzzforge-modules/fuzzforge-modules-sdk/src/fuzzforge_modules_sdk/api/) +- [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/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 + +```python +# 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/`: +```python +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: +```bash +uv run pytest +``` ### Security Guidelines -- πŸ” Never commit secrets, API keys, or credentials -- πŸ›‘οΈ Focus on **defensive security** tools and analysis -- ⚠️ Do not create tools for malicious purposes -- πŸ§ͺ Test workflows thoroughly before submission -- πŸ“‹ Follow responsible disclosure for security issues +**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 -## πŸ› Bug Reports +**Security Resources:** +- [OWASP Container Security](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html) +- [CIS Docker Benchmarks](https://www.cisecurity.org/benchmark/docker) + +## Contributing to Core Features + +Beyond modules, you can contribute to FuzzForge's core components. + +**Useful Resources:** +- [Project Structure](README.md) - Overview of the codebase +- [USAGE Guide](USAGE.md) - Installation and setup +- Python best practices: [PEP 8](https://pep8.org/) + +### 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** + ```bash + git clone https://github.com/FuzzingLabs/fuzzforge-oss.git + cd fuzzforge-oss + uv sync --all-extras + ``` + +2. **Run Tests** + ```bash + # Run all tests + make test + + # Run specific package tests + cd fuzzforge-mcp + uv run pytest + ``` + +3. **Type Checking** + ```bash + # Type check all packages + make typecheck + + # Type check specific package + cd fuzzforge-runner + uv run mypy . + ``` + +4. **Linting and Formatting** + ```bash + # Format code + make format + + # Lint code + make lint + ``` + +## Bug Reports When reporting bugs, please include: -- **Environment**: OS, Python version, Docker version +- **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 -Use our [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md). +**Example:** +```markdown +**Environment:** +- OS: Ubuntu 22.04 +- Python: 3.14.2 +- Docker: 24.0.7 +- uv: 0.5.13 -## πŸ’‘ Feature Requests +**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: @@ -142,33 +440,124 @@ For new features, please provide: - **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? -Use our [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md). +**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 +## Documentation Help improve our documentation: +- **Module Documentation**: Document your modules in their README.md - **API Documentation**: Update docstrings and type hints -- **User Guides**: Create tutorials and how-to guides -- **Workflow Documentation**: Document new security workflows -- **Examples**: Add practical usage examples +- **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 -## πŸ™ Recognition +### 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 + +```markdown +# 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](CONTRIBUTORS.md) file - Mentioned in release notes for significant contributions -- Invited to join our Discord community -- Eligible for FuzzingLabs Academy courses and swag +- Credited in module documentation (for module authors) +- Invited to join our [Discord community](https://discord.gg/8XEX33UUwZ) -## πŸ“œ License +## Module Submission Checklist -By contributing to FuzzForge, you agree that your contributions will be licensed under the same [Business Source License 1.1](LICENSE) as the project. +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](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 --- -**Thank you for making FuzzForge better! πŸš€** +## Getting Help -Every contribution, no matter how small, helps build a stronger security community. +Need help contributing? + +- Join our [Discord](https://discord.gg/8XEX33UUwZ) +- Read the [Module SDK Documentation](fuzzforge-modules/fuzzforge-modules-sdk/README.md) +- 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! diff --git a/README.md b/README.md index 9e26401..2f76ee1 100644 --- a/README.md +++ b/README.md @@ -72,8 +72,8 @@ Instead of manually running security tools, describe what you want and let your If you find FuzzForge useful, please **star the repo** to support development! πŸš€ - - GitHub Stars + + GitHub Stars --- @@ -135,8 +135,8 @@ If you find FuzzForge useful, please **star the repo** to support development! ```bash # Clone the repository -git clone https://github.com/FuzzingLabs/fuzzforge-oss.git -cd fuzzforge-oss +git clone https://github.com/FuzzingLabs/fuzzforge_ai.git +cd fuzzforge_ai # Install dependencies uv sync @@ -246,7 +246,7 @@ class MySecurityModule(FuzzForgeModule): ## πŸ“ Project Structure ``` -fuzzforge-oss/ +fuzzforge_ai/ β”œβ”€β”€ fuzzforge-cli/ # Command-line interface β”œβ”€β”€ fuzzforge-common/ # Shared abstractions (containers, storage) β”œβ”€β”€ fuzzforge-mcp/ # MCP server for AI agents