CalvinBackup/fuzzforge_ai
1
0
Fork 0
mirror of https://github.com/FuzzingLabs/fuzzforge_ai.git synced 2026-02-12 17:12:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Fix workflow references and module paths for v0.7.0

Browse Source 
Updated all documentation to reflect actual v0.7.0 workflow implementation:

Workflow name changes:
- Removed all references to non-existent workflows (static_analysis_scan,
  secret_detection_scan, infrastructure_scan, penetration_testing_scan)
- Updated examples to use actual workflows (security_assessment, gitleaks_detection,
  trufflehog_detection, llm_secret_detection)
- Deleted docs/docs/reference/workflows/static-analysis.md (described non-existent workflow)

Content corrections:
- Fixed workflow tool descriptions (removed incorrect Semgrep/Bandit references,
  documented actual SecurityAnalyzer and FileScanner modules)
- Updated all workflow lists to show production-ready vs development status
- Fixed all example configurations to match actual workflow parameters

Module creation guide fixes:
- Fixed 4 path references: backend/src/toolbox → backend/toolbox
- Updated import statements in example code

Files updated:
- docs/index.md - workflow list, CLI example, broken tutorial links
- docs/docs/tutorial/getting-started.md - workflow list, example output, tool descriptions
- docs/docs/how-to/create-module.md - module paths and imports
- docs/docs/how-to/mcp-integration.md - workflow examples and list
- docs/docs/ai/prompts.md - workflow example
- docs/docs/reference/cli-ai.md - 3 workflow references
This commit is contained in:
tduhamel42
2025-10-17 10:48:48 +02:00
parent f14bec9410
commit 187b171360
7 changed files with 69 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/docs/ai/prompts.md
View File

@@ -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

8
docs/docs/how-to/create-module.md
View File

@@ -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")

29
docs/docs/how-to/mcp-integration.md
View File

@@ -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:

29
docs/docs/reference/cli-ai.md
View File

@@ -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`

257
docs/docs/reference/workflows/static-analysis.md
View File

@@ -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.

25
docs/docs/tutorial/getting-started.md
View File

@@ -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,

28
docs/index.md
View File

@@ -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)