diff --git a/docs/docs/ai/prompts.md b/docs/docs/ai/prompts.md index 7ac5859..5669cad 100644 --- a/docs/docs/ai/prompts.md +++ b/docs/docs/ai/prompts.md @@ -20,7 +20,7 @@ Use the `fuzzforge ai agent` shell to mix structured slash commands with natural You> list available fuzzforge workflows Assistant> [returns workflow names, descriptions, and required parameters] -You> run fuzzforge workflow static_analysis_scan on ./backend with target_branch=main +You> run fuzzforge workflow security_assessment on ./backend Assistant> Submits the run, emits TaskStatusUpdateEvent entries, and links the SARIF artifact when complete. You> show findings for that run once it finishes diff --git a/docs/docs/how-to/create-module.md b/docs/docs/how-to/create-module.md index 7e9d7c4..8d88f47 100644 --- a/docs/docs/how-to/create-module.md +++ b/docs/docs/how-to/create-module.md @@ -25,7 +25,7 @@ All FuzzForge modules inherit from a common `BaseModule` interface and use Pydan - `ModuleResult`: Standardized result format for module execution - `ModuleMetadata`: Describes module capabilities and requirements -Modules are located in `backend/src/toolbox/modules/`. +Modules are located in `backend/toolbox/modules/`. --- @@ -34,7 +34,7 @@ Modules are located in `backend/src/toolbox/modules/`. Let’s create a simple example: a **License Scanner** module that detects license files and extracts license information. Create a new file: -`backend/src/toolbox/modules/license_scanner.py` +`backend/toolbox/modules/license_scanner.py` ```python import re @@ -98,7 +98,7 @@ class LicenseScanner(BaseModule): ## Step 3: Register Your Module -Add your module to `backend/src/toolbox/modules/__init__.py`: +Add your module to `backend/toolbox/modules/__init__.py`: ```python from .license_scanner import LicenseScanner @@ -115,7 +115,7 @@ Create a test file (e.g., `test_license_scanner.py`) and run your module against ```python import asyncio from pathlib import Path -from backend.src.toolbox.modules.license_scanner import LicenseScanner +from toolbox.modules.license_scanner import LicenseScanner async def main(): workspace = Path("/path/to/your/test/project") diff --git a/docs/docs/how-to/mcp-integration.md b/docs/docs/how-to/mcp-integration.md index 3470bd9..f22123b 100644 --- a/docs/docs/how-to/mcp-integration.md +++ b/docs/docs/how-to/mcp-integration.md @@ -81,14 +81,17 @@ You should see status responses and endpoint listings. { "tool": "submit_security_scan_mcp", "parameters": { - "workflow_name": "infrastructure_scan", + "workflow_name": "security_assessment", "target_path": "/path/to/your/project", "parameters": { - "checkov_config": { - "severity": ["HIGH", "MEDIUM", "LOW"] + "scanner_config": { + "patterns": ["*"], + "check_sensitive": true }, - "hadolint_config": { - "severity": ["error", "warning", "info", "style"] + "analyzer_config": { + "file_extensions": [".py", ".js", ".java"], + "check_secrets": true, + "check_sql": true } } } @@ -110,13 +113,17 @@ You should see status responses and endpoint listings. ## 6. Available Workflows -You can trigger these workflows via MCP: +You can trigger these production-ready workflows via MCP: -1. **infrastructure_scan** — Docker/Kubernetes/Terraform security analysis -2. **static_analysis_scan** — Code vulnerability detection -3. **secret_detection_scan** — Credential and secret scanning -4. **penetration_testing_scan** — Network and web app testing -5. **security_assessment** — Comprehensive security evaluation +1. **security_assessment** — Comprehensive security analysis (secrets, SQL, dangerous functions) +2. **gitleaks_detection** — Pattern-based secret scanning +3. **trufflehog_detection** — Pattern-based secret scanning +4. **llm_secret_detection** — AI-powered secret detection (requires API key) + +Development workflows (early stages): +- **atheris_fuzzing** — Python fuzzing +- **cargo_fuzzing** — Rust fuzzing +- **ossfuzz_campaign** — OSS-Fuzz integration List all workflows: diff --git a/docs/docs/reference/cli-ai.md b/docs/docs/reference/cli-ai.md index a821235..2e69613 100644 --- a/docs/docs/reference/cli-ai.md +++ b/docs/docs/reference/cli-ai.md @@ -134,14 +134,16 @@ FuzzForge supports the Model Context Protocol (MCP), allowing LLM clients and AI { "tool": "submit_security_scan_mcp", "parameters": { - "workflow_name": "infrastructure_scan", + "workflow_name": "security_assessment", "target_path": "/path/to/your/project", "parameters": { - "checkov_config": { - "severity": ["HIGH", "MEDIUM", "LOW"] + "scanner_config": { + "patterns": ["*"], + "check_sensitive": true }, - "hadolint_config": { - "severity": ["error", "warning", "info", "style"] + "analyzer_config": { + "file_extensions": [".py", ".js"], + "check_secrets": true } } } @@ -161,11 +163,16 @@ FuzzForge supports the Model Context Protocol (MCP), allowing LLM clients and AI ### Available Workflows -1. **infrastructure_scan** — Docker/Kubernetes/Terraform security analysis -2. **static_analysis_scan** — Code vulnerability detection -3. **secret_detection_scan** — Credential and secret scanning -4. **penetration_testing_scan** — Network and web app testing -5. **security_assessment** — Comprehensive security evaluation +**Production-ready:** +1. **security_assessment** — Comprehensive security analysis (secrets, SQL, dangerous functions) +2. **gitleaks_detection** — Pattern-based secret scanning +3. **trufflehog_detection** — Pattern-based secret scanning +4. **llm_secret_detection** — AI-powered secret detection (requires API key) + +**In development:** +- **atheris_fuzzing** — Python fuzzing +- **cargo_fuzzing** — Rust fuzzing +- **ossfuzz_campaign** — OSS-Fuzz integration ### MCP Client Configuration Example @@ -192,7 +199,7 @@ FuzzForge supports the Model Context Protocol (MCP), allowing LLM clients and AI `curl http://localhost:8000/workflows/` - **Scan Submission Errors:** - `curl -X POST http://localhost:8000/workflows/infrastructure_scan/submit -H "Content-Type: application/json" -d '{"target_path": "/your/path"}'` + `curl -X POST http://localhost:8000/workflows/security_assessment/submit -H "Content-Type: application/json" -d '{"target_path": "/your/path"}'` - **General Support:** - Check Docker Compose logs: `docker compose logs fuzzforge-backend` diff --git a/docs/docs/reference/workflows/static-analysis.md b/docs/docs/reference/workflows/static-analysis.md deleted file mode 100644 index 48624aa..0000000 --- a/docs/docs/reference/workflows/static-analysis.md +++ /dev/null @@ -1,257 +0,0 @@ -# Static Analysis Workflow Reference - -The Static Analysis workflow in FuzzForge helps you find vulnerabilities, code quality issues, and compliance problems—before they reach production. This workflow uses multiple Static Application Security Testing (SAST) tools to analyze your source code without executing it, providing fast, actionable feedback in a standardized format. - ---- - -## What Does This Workflow Do? - -- **Workflow ID:** `static_analysis_scan` -- **Primary Tools:** Semgrep (multi-language), Bandit (Python) -- **Supported Languages:** Python, JavaScript, Java, Go, C/C++, PHP, Ruby, and more -- **Typical Duration:** 1–5 minutes (varies by codebase size) -- **Output Format:** SARIF 2.1.0 (industry standard) - ---- - -## How Does It Work? - -The workflow orchestrates multiple SAST tools in a containerized environment: - -- **Semgrep:** Pattern-based static analysis for 30+ languages, with rule sets for OWASP Top 10, CWE Top 25, and more. -- **Bandit:** Python-specific security scanner, focused on issues like hardcoded secrets, injection, and unsafe code patterns. - -Each tool runs independently, and their findings are merged and normalized into a single SARIF report. - ---- - -## How to Use the Static Analysis Workflow - -### Basic Usage - -**CLI:** -```bash -fuzzforge runs submit static_analysis_scan /path/to/your/project -``` - -**API:** -```bash -curl -X POST "http://localhost:8000/workflows/static_analysis_scan/submit" \ - -H "Content-Type: application/json" \ - -d '{"target_path": "/path/to/your/project"}' -``` - -### Advanced Configuration - -You can fine-tune the workflow by passing parameters for each tool: - -**CLI:** -```bash -fuzzforge runs submit static_analysis_scan /path/to/project \ - --parameters '{ - "semgrep_config": { - "rules": ["p/security-audit", "owasp-top-ten"], - "severity": ["ERROR", "WARNING"], - "exclude_patterns": ["test/*", "vendor/*", "node_modules/*"] - }, - "bandit_config": { - "confidence": "MEDIUM", - "severity": "MEDIUM", - "exclude_dirs": ["tests", "migrations"] - } - }' -``` - -**API:** -```json -{ - "target_path": "/path/to/project", - "parameters": { - "semgrep_config": { - "rules": ["p/security-audit"], - "languages": ["python", "javascript"], - "severity": ["ERROR", "WARNING"], - "exclude_patterns": ["*.test.js", "test_*.py", "vendor/*"] - }, - "bandit_config": { - "confidence": "MEDIUM", - "severity": "LOW", - "tests": ["B201", "B301"], - "exclude_dirs": ["tests", ".git"] - } - } -} -``` - ---- - -## Configuration Reference - -### Semgrep Parameters - -| Parameter | Type | Default | Description | -|-------------------|-----------|-------------------------------|---------------------------------------------| -| `rules` | array | `"auto"` | Rule sets to use (e.g., `"p/security-audit"`)| -| `languages` | array | `null` | Languages to analyze | -| `severity` | array | `["ERROR", "WARNING", "INFO"]`| Severities to include | -| `exclude_patterns`| array | `[]` | File patterns to exclude | -| `include_patterns`| array | `[]` | File patterns to include | -| `max_target_bytes`| integer | `1000000` | Max file size to analyze (bytes) | -| `timeout` | integer | `300` | Tool timeout (seconds) | - -### Bandit Parameters - -| Parameter | Type | Default | Description | -|-------------------|-----------|-------------------------------|---------------------------------------------| -| `confidence` | string | `"LOW"` | Minimum confidence (`"LOW"`, `"MEDIUM"`, `"HIGH"`) | -| `severity` | string | `"LOW"` | Minimum severity (`"LOW"`, `"MEDIUM"`, `"HIGH"`) | -| `tests` | array | `null` | Specific test IDs to run | -| `exclude_dirs` | array | `["tests", ".git"]` | Directories to exclude | -| `aggregate` | string | `"file"` | Aggregation mode (`"file"`, `"vuln"`) | -| `context_lines` | integer | `3` | Context lines around findings | - ---- - -## What Can It Detect? - -### Vulnerability Categories - -- **OWASP Top 10:** Broken Access Control, Injection, Security Misconfiguration, etc. -- **CWE Top 25:** SQL Injection, XSS, Command Injection, Information Exposure, etc. -- **Language-Specific:** Python (unsafe eval, Django/Flask issues), JavaScript (XSS, prototype pollution), Java (deserialization), Go (race conditions), C/C++ (buffer overflows). - -### Example Detections - -**SQL Injection (Python)** -```python -query = f"SELECT * FROM users WHERE id = {user_id}" # CWE-89 -``` -*Recommendation: Use parameterized queries.* - -**Command Injection (Python)** -```python -os.system(f"cp {filename} backup/") # CWE-78 -``` -*Recommendation: Use subprocess with argument arrays.* - -**XSS (JavaScript)** -```javascript -element.innerHTML = userInput; // CWE-79 -``` -*Recommendation: Use textContent or sanitize input.* - ---- - -## Output Format - -All results are returned in SARIF 2.1.0 format, which is supported by many IDEs and security tools. - -**Summary Example:** -```json -{ - "workflow": "static_analysis_scan", - "status": "completed", - "total_findings": 18, - "severity_counts": { - "critical": 0, - "high": 6, - "medium": 5, - "low": 7 - }, - "tool_counts": { - "semgrep": 12, - "bandit": 6 - } -} -``` - -**Finding Example:** -```json -{ - "ruleId": "bandit.B608", - "level": "error", - "message": { - "text": "Possible SQL injection vector through string-based query construction" - }, - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "src/database.py" - }, - "region": { - "startLine": 42, - "startColumn": 15, - "endLine": 42, - "endColumn": 65 - } - } - } - ], - "properties": { - "severity": "high", - "category": "sql_injection", - "cwe": "CWE-89", - "confidence": "high", - "tool": "bandit" - } -} -``` - ---- - -## Performance Tips - -- For large codebases, increase `max_target_bytes` and `timeout` as needed. -- Exclude large generated or dependency directories (`vendor/`, `node_modules/`, `dist/`). -- Run focused scans on changed files for faster CI/CD feedback. - ---- - -## Integration Examples - -### GitHub Actions - -```yaml -- name: Run Static Analysis - run: | - curl -X POST "${{ secrets.FUZZFORGE_URL }}/workflows/static_analysis_scan/submit" \ - -H "Content-Type: application/json" \ - -d '{ - "target_path": "${{ github.workspace }}", - "parameters": { - "semgrep_config": {"severity": ["ERROR", "WARNING"]}, - "bandit_config": {"confidence": "MEDIUM"} - } - }' -``` - -### Pre-commit Hook - -```bash -fuzzforge runs submit static_analysis_scan . --wait --json > /tmp/analysis.json -HIGH_ISSUES=$(jq '.sarif.severity_counts.high // 0' /tmp/analysis.json) -if [ "$HIGH_ISSUES" -gt 0 ]; then - echo "❌ Found $HIGH_ISSUES high-severity security issues. Commit blocked." - exit 1 -fi -``` - ---- - -## Best Practices - -- **Target the right code:** Focus on your main source directories, not dependencies or build artifacts. -- **Start broad, then refine:** Use default rule sets first, then add exclusions or custom rules as needed. -- **Triage findings:** Address high-severity issues first, and document false positives for future runs. -- **Monitor trends:** Track your security posture over time to measure improvement. -- **Optimize for speed:** Use file size limits and timeouts for very large projects. - ---- - -## Troubleshooting - -- **No Python files found:** Bandit will report zero findings if your project isn’t Python, this is normal. -- **High memory usage:** Exclude large files and directories, or increase Docker memory limits. -- **Slow scans:** Use inclusion/exclusion patterns and increase timeouts for big repos. -- **Workflow errors:** See the [Troubleshooting Guide](/how-to/troubleshooting.md) for help with registry, Docker, or workflow issues. diff --git a/docs/docs/tutorial/getting-started.md b/docs/docs/tutorial/getting-started.md index 6c0e9a5..135bb2a 100644 --- a/docs/docs/tutorial/getting-started.md +++ b/docs/docs/tutorial/getting-started.md @@ -124,13 +124,16 @@ fuzzforge workflows list curl http://localhost:8000/workflows | jq . ``` -You should see 6 production workflows: -- `static_analysis_scan` -- `secret_detection_scan` -- `infrastructure_scan` -- `penetration_testing_scan` -- `language_fuzzing` -- `security_assessment` +You should see production-ready workflows: +- `security_assessment` - Comprehensive security analysis (secrets, SQL, dangerous functions) +- `gitleaks_detection` - Pattern-based secret detection +- `trufflehog_detection` - Pattern-based secret detection +- `llm_secret_detection` - AI-powered secret detection (requires API key) + +And development workflows: +- `atheris_fuzzing` - Python fuzzing (early development) +- `cargo_fuzzing` - Rust fuzzing (early development) +- `ossfuzz_campaign` - OSS-Fuzz integration (heavy development) ## Step 6: Run Your First Workflow @@ -183,19 +186,19 @@ curl "http://localhost:8000/runs/{run-id}/findings" The workflow will complete in 30-60 seconds and return results in SARIF format. For the test project, you should see: - **Total findings**: 15-20 security issues -- **Tools used**: OpenGrep (Semgrep) and Bandit +- **Analysis modules**: FileScanner and SecurityAnalyzer (regex-based detection) - **Severity levels**: High, Medium, and Low vulnerabilities - **Categories**: SQL injection, command injection, hardcoded secrets, etc. Example output: ```json { - "workflow": "static_analysis_scan", + "workflow": "security_assessment", "status": "completed", "total_findings": 18, "scan_status": { - "opengrep": "success", - "bandit": "success" + "file_scanner": "success", + "security_analyzer": "success" }, "severity_counts": { "high": 6, diff --git a/docs/index.md b/docs/index.md index a5a3a24..dc0a13e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,16 +8,13 @@ Welcome to FuzzForge, a comprehensive security analysis platform built on Tempor Perfect for newcomers who want to learn FuzzForge step by step. - [**Getting Started**](tutorials/getting-started.md) - Complete setup from installation to first workflow -- [**First Workflow**](tutorials/first-workflow.md) - Run your first security workflow -- [**Building Custom Workflows**](tutorials/building-custom-workflow.md) - Create and deploy custom workflows ### 🛠️ **How-To Guides** - *Problem-focused solutions* Step-by-step guides for specific tasks and common problems. -- [**Installation**](how-to/installation.md) - Install FuzzForge with proper Docker setup -- [**Docker Setup**](how-to/docker-setup.md) - Configure Docker with insecure registry (required) -- [**Running Workflows**](how-to/running-workflows.md) - Execute different workflow types -- [**CLI Usage**](how-to/cli-usage.md) - Command-line interface patterns +- [**Docker Setup**](how-to/docker-setup.md) - Docker requirements and worker profiles +- [**Create Workflow**](how-to/create-workflow.md) - Build custom security workflows +- [**Create Module**](how-to/create-module.md) - Develop security analysis modules - [**API Integration**](how-to/api-integration.md) - REST API usage and integration - [**MCP Integration**](how-to/mcp-integration.md) - AI assistant integration setup - [**Troubleshooting**](how-to/troubleshooting.md) - Common issues and solutions @@ -59,16 +56,19 @@ Technical reference materials and specifications. ## 🎯 FuzzForge at a Glance -**6 Production Workflows:** -- Static Analysis (Semgrep, Bandit, CodeQL) -- Secret Detection (TruffleHog, Gitleaks, detect-secrets) -- Infrastructure Scan (Checkov, Hadolint, Kubesec) -- Penetration Testing (Nuclei, Nmap, SQLMap, Nikto) -- Language Fuzzing (AFL++, libFuzzer, Cargo Fuzz) -- Security Assessment (Comprehensive multi-tool analysis) +**Production-Ready Workflows:** +- Security Assessment - Regex-based analysis for secrets, SQL injection, dangerous functions +- Gitleaks Detection - Pattern-based secret scanning +- TruffleHog Detection - Pattern-based secret scanning +- LLM Secret Detection - AI-powered secret detection (requires API key) + +**Development Workflows:** +- Atheris Fuzzing - Python fuzzing (early development) +- Cargo Fuzzing - Rust fuzzing (early development) +- OSS-Fuzz Campaign - OSS-Fuzz integration (heavy development) **Multiple Interfaces:** -- 💻 **CLI**: `fuzzforge runs submit static_analysis_scan /path/to/code` +- 💻 **CLI**: `fuzzforge workflow run security_assessment /path/to/code` - 🐍 **Python SDK**: Programmatic workflow integration - 🌐 **REST API**: HTTP-based workflow management - 🤖 **MCP**: AI assistant integration (Claude, ChatGPT)