mirror of
https://github.com/FuzzingLabs/fuzzforge_ai.git
synced 2026-02-13 00:32:47 +00:00
feat: Complete Temporal migration cleanup and fixes
- Remove obsolete docker_logs.py module and container diagnostics from SDK - Fix security_assessment workflow metadata (vertical: rust -> python) - Remove all Prefect references from documentation - Add SDK exception handling test suite - Clean up old test artifacts
This commit is contained in:
tduhamel42
@@ -68,7 +68,7 @@ Response excerpt:
|
||||
- Call `POST /graph/query` to explore project knowledge.
|
||||
- Call `POST /project/files` to fetch raw files from the repository.
|
||||
- Download finished scan summaries with `GET /artifacts/{id}`.
|
||||
4. The AI module pushes Prefect workflow results into artifacts automatically, so remote agents can poll without re-running scans.
|
||||
4. The AI module pushes Temporal workflow results into artifacts automatically, so remote agents can poll without re-running scans.
|
||||
|
||||
## Registration Flow
|
||||
|
||||
@@ -129,7 +129,7 @@ sequenceDiagram
|
||||
participant Remote as Remote Agent
|
||||
participant HTTP as A2A Server
|
||||
participant Exec as Executor
|
||||
participant Workflow as Prefect Backend
|
||||
participant Workflow as Temporal Backend
|
||||
|
||||
Remote->>HTTP: POST / (message with tool request)
|
||||
HTTP->>Exec: Forward message
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# AI Architecture
|
||||
|
||||
FuzzForge AI is the orchestration layer that lets large language models drive the broader security platform. Built on the Google ADK runtime, the module coordinates local tools, remote Agent-to-Agent (A2A) peers, and Prefect-backed workflows while persisting long-running context for every project.
|
||||
FuzzForge AI is the orchestration layer that lets large language models drive the broader security platform. Built on the Google ADK runtime, the module coordinates local tools, remote Agent-to-Agent (A2A) peers, and Temporal-backed workflows while persisting long-running context for every project.
|
||||
|
||||
## System Diagram
|
||||
|
||||
@@ -27,7 +27,7 @@ graph TB
|
||||
Executor --> Prompts[Prompt Templates]
|
||||
|
||||
Router --> RemoteAgents[Registered A2A Agents]
|
||||
MCP --> Prefect[FuzzForge Backend]
|
||||
MCP --> Temporal[FuzzForge Backend]
|
||||
Memory --> SessionDB[Session Store]
|
||||
Memory --> Semantic[Semantic Recall]
|
||||
Memory --> Graphs[Cognee Graph]
|
||||
@@ -44,7 +44,7 @@ sequenceDiagram
|
||||
participant CLI as CLI / HTTP Surface
|
||||
participant Exec as FuzzForgeExecutor
|
||||
participant ADK as ADK Runner
|
||||
participant Prefect as Prefect Backend
|
||||
participant Temporal as Temporal Backend
|
||||
participant Cognee as Cognee
|
||||
participant Artifact as Artifact Cache
|
||||
|
||||
@@ -52,8 +52,8 @@ sequenceDiagram
|
||||
CLI->>Exec: Normalised request + context ID
|
||||
Exec->>ADK: Tool invocation (LiteLLM)
|
||||
ADK-->>Exec: Structured response / tool result
|
||||
Exec->>Prefect: (optional) submit workflow via MCP
|
||||
Prefect-->>Exec: Run status updates
|
||||
Exec->>Temporal: (optional) submit workflow via MCP
|
||||
Temporal-->>Exec: Run status updates
|
||||
Exec->>Cognee: (optional) knowledge query / ingestion
|
||||
Cognee-->>Exec: Graph results
|
||||
Exec->>Artifact: Persist generated files
|
||||
@@ -69,7 +69,7 @@ sequenceDiagram
|
||||
## Core Components
|
||||
|
||||
- **FuzzForgeAgent** (`ai/src/fuzzforge_ai/agent.py`) assembles the runtime: it loads environment variables, constructs the executor, and builds an ADK `Agent` backed by `LiteLlm`. The singleton accessor `get_fuzzforge_agent()` keeps CLI and server instances aligned and shares the generated agent card.
|
||||
- **FuzzForgeExecutor** (`ai/src/fuzzforge_ai/agent_executor.py`) is the brain. It registers tools, manages session storage (SQLite or in-memory via `DatabaseSessionService` / `InMemorySessionService`), and coordinates artifact storage. The executor also tracks long-running Prefect workflows inside `pending_runs`, produces `TaskStatusUpdateEvent` objects, and funnels every response through ADK’s `Runner` so traces include tool metadata.
|
||||
- **FuzzForgeExecutor** (`ai/src/fuzzforge_ai/agent_executor.py`) is the brain. It registers tools, manages session storage (SQLite or in-memory via `DatabaseSessionService` / `InMemorySessionService`), and coordinates artifact storage. The executor also tracks long-running Temporal workflows inside `pending_runs`, produces `TaskStatusUpdateEvent` objects, and funnels every response through ADK’s `Runner` so traces include tool metadata.
|
||||
- **Remote agent registry** (`ai/src/fuzzforge_ai/remote_agent.py`) holds metadata for downstream agents and handles capability discovery over HTTP. Auto-registration is configured by `ConfigManager` so known agents attach on startup.
|
||||
- **Memory services**:
|
||||
- `FuzzForgeMemoryService` and `HybridMemoryManager` (`ai/src/fuzzforge_ai/memory_service.py`) provide conversation recall and bridge to Cognee datasets when configured.
|
||||
@@ -77,15 +77,15 @@ sequenceDiagram
|
||||
|
||||
## Workflow Automation
|
||||
|
||||
The executor wraps Prefect MCP actions exposed by the backend:
|
||||
The executor wraps Temporal MCP actions exposed by the backend:
|
||||
|
||||
| Tool | Source | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `list_workflows_mcp` | `ai/src/fuzzforge_ai/agent_executor.py` | Enumerate available scans |
|
||||
| `submit_security_scan_mcp` | `agent_executor.py` | Launch a scan and persist run metadata |
|
||||
| `get_run_status_mcp` | `agent_executor.py` | Poll Prefect for status and push task events |
|
||||
| `get_run_status_mcp` | `agent_executor.py` | Poll Temporal for status and push task events |
|
||||
| `get_comprehensive_scan_summary` | `agent_executor.py` | Collect findings and bundle artifacts |
|
||||
| `get_backend_status_mcp` | `agent_executor.py` | Block submissions until Prefect reports `ready` |
|
||||
| `get_backend_status_mcp` | `agent_executor.py` | Block submissions until Temporal reports `ready` |
|
||||
|
||||
The CLI surface mirrors these helpers as natural-language prompts (`You> run fuzzforge workflow …`). ADK’s `Runner` handles retries and ensures each tool call yields structured `Event` objects for downstream instrumentation.
|
||||
|
||||
|
||||
@@ -87,7 +87,7 @@ If the Cognee variables are omitted, graph-specific tools remain available but r
|
||||
FUZZFORGE_MCP_URL=http://localhost:8010/mcp
|
||||
```
|
||||
|
||||
The agent uses this endpoint to list, launch, and monitor Prefect workflows.
|
||||
The agent uses this endpoint to list, launch, and monitor Temporal workflows.
|
||||
|
||||
## Tracing & Observability
|
||||
|
||||
|
||||
@@ -53,7 +53,7 @@ All runs automatically skip `.fuzzforge/**` and `.git/**` to avoid recursive ing
|
||||
You> refresh the project knowledge graph for ./backend
|
||||
Assistant> Kicks off `fuzzforge ingest` with recursive scan
|
||||
|
||||
You> search project knowledge for "prefect workflow" using INSIGHTS
|
||||
You> search project knowledge for "temporal workflow" using INSIGHTS
|
||||
Assistant> Routes to Cognee `search_project_knowledge`
|
||||
|
||||
You> ingest_to_dataset("Design doc for new scanner", "insights")
|
||||
@@ -70,7 +70,7 @@ LLM_PROVIDER=openai
|
||||
LITELLM_MODEL=gpt-5-mini
|
||||
OPENAI_API_KEY=sk-your-key
|
||||
|
||||
# FuzzForge backend (Prefect-powered)
|
||||
# FuzzForge backend (Temporal-powered)
|
||||
FUZZFORGE_MCP_URL=http://localhost:8010/mcp
|
||||
|
||||
# Optional: knowledge graph provider
|
||||
|
||||
@@ -4,7 +4,7 @@ sidebar_position: 1
|
||||
|
||||
# FuzzForge AI Module
|
||||
|
||||
FuzzForge AI is the multi-agent layer that lets you operate the FuzzForge security platform through natural language. It orchestrates local tooling, registered Agent-to-Agent (A2A) peers, and the Prefect-powered backend while keeping long-running context in memory and project knowledge graphs.
|
||||
FuzzForge AI is the multi-agent layer that lets you operate the FuzzForge security platform through natural language. It orchestrates local tooling, registered Agent-to-Agent (A2A) peers, and the Temporal-powered backend while keeping long-running context in memory and project knowledge graphs.
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -36,7 +36,7 @@ FuzzForge AI is the multi-agent layer that lets you operate the FuzzForge securi
|
||||
```bash
|
||||
fuzzforge ai agent
|
||||
```
|
||||
Keep the backend running (Prefect API at `FUZZFORGE_MCP_URL`) so workflow commands succeed.
|
||||
Keep the backend running (Temporal API at `FUZZFORGE_MCP_URL`) so workflow commands succeed.
|
||||
|
||||
## Everyday Workflow
|
||||
|
||||
@@ -65,7 +65,7 @@ Inside `fuzzforge ai agent` you can mix slash commands and free-form prompts:
|
||||
/sendfile SecurityAgent src/report.md "Please review"
|
||||
You> route_to SecurityAnalyzer: scan ./backend for secrets
|
||||
You> run fuzzforge workflow static_analysis_scan on ./test_projects/demo
|
||||
You> search project knowledge for "prefect status" using INSIGHTS
|
||||
You> search project knowledge for "temporal status" using INSIGHTS
|
||||
```
|
||||
|
||||
Artifacts created during the conversation are served from `.fuzzforge/artifacts/` and exposed through the A2A HTTP API.
|
||||
@@ -88,7 +88,7 @@ Use these to validate the setup once the agent shell is running:
|
||||
- `run fuzzforge workflow static_analysis_scan on ./backend with target_branch=main`
|
||||
- `show findings for that run once it finishes`
|
||||
- `refresh the project knowledge graph for ./backend`
|
||||
- `search project knowledge for "prefect readiness" using INSIGHTS`
|
||||
- `search project knowledge for "temporal readiness" using INSIGHTS`
|
||||
- `/recall terraform secrets`
|
||||
- `/memory status`
|
||||
- `ROUTE_TO SecurityAnalyzer: audit infrastructure_vulnerable`
|
||||
|
||||
@@ -33,7 +33,7 @@ Assistant> Streams the `get_comprehensive_scan_summary` output and attaches the
|
||||
You> refresh the project knowledge graph for ./backend
|
||||
Assistant> Launches `fuzzforge ingest --path ./backend --recursive` and reports file counts.
|
||||
|
||||
You> search project knowledge for "prefect readiness" using INSIGHTS
|
||||
You> search project knowledge for "temporal readiness" using INSIGHTS
|
||||
Assistant> Routes to Cognee via `query_project_knowledge_api` and returns the top matches.
|
||||
|
||||
You> recall "api key rotation"
|
||||
@@ -52,7 +52,7 @@ Assistant> Uploads the file as an artifact and notifies the remote agent.
|
||||
|
||||
## Prompt Tips
|
||||
|
||||
- Use explicit verbs (`list`, `run`, `search`) to trigger the Prefect workflow helpers.
|
||||
- Use explicit verbs (`list`, `run`, `search`) to trigger the Temporal workflow helpers.
|
||||
- Include parameter names inline (`with target_branch=main`) so the executor maps values to MCP tool inputs without additional clarification.
|
||||
- When referencing prior runs, reuse the assistant’s run IDs or ask for "the last run"—the session store tracks them per context ID.
|
||||
- If Cognee is not configured, graph queries return a friendly notice; set `LLM_COGNEE_*` variables to enable full answers.
|
||||
|
||||
@@ -25,9 +25,9 @@ At a glance, FuzzForge is organized into several layers, each with a clear respo
|
||||
|
||||
- **Client Layer:** Where users and external systems interact (CLI, API clients, MCP server).
|
||||
- **API Layer:** The FastAPI backend, which exposes REST endpoints and manages requests.
|
||||
- **Orchestration Layer:** Prefect server and workers, which schedule and execute workflows.
|
||||
- **Execution Layer:** Docker Engine and containers, where workflows actually run.
|
||||
- **Storage Layer:** PostgreSQL database, Docker volumes, and a result cache for persistence.
|
||||
- **Orchestration Layer:** Temporal server and vertical workers, which schedule and execute workflows.
|
||||
- **Execution Layer:** Long-lived vertical worker containers with pre-installed toolchains, where workflows run.
|
||||
- **Storage Layer:** PostgreSQL database, MinIO (S3-compatible storage), and worker cache for persistence.
|
||||
|
||||
Here’s a simplified view of how these layers fit together:
|
||||
|
||||
@@ -46,8 +46,8 @@ graph TB
|
||||
end
|
||||
|
||||
subgraph "Orchestration Layer"
|
||||
Prefect[Prefect Server]
|
||||
Workers[Prefect Workers]
|
||||
Temporal[Temporal Server]
|
||||
Workers[Vertical Workers]
|
||||
Scheduler[Workflow Scheduler]
|
||||
end
|
||||
|
||||
@@ -69,9 +69,9 @@ graph TB
|
||||
|
||||
FastAPI --> Router
|
||||
Router --> Middleware
|
||||
Middleware --> Prefect
|
||||
Middleware --> Temporal
|
||||
|
||||
Prefect --> Workers
|
||||
Temporal --> Workers
|
||||
Workers --> Scheduler
|
||||
Scheduler --> Docker
|
||||
|
||||
|
||||
@@ -363,12 +363,12 @@ class DependencyAnalysisWorkflow:
|
||||
return sarif_report
|
||||
```
|
||||
|
||||
**Key differences from Prefect:**
|
||||
- Use `@workflow.defn` class instead of `@flow` function
|
||||
- Use `@activity.defn` instead of `@task`
|
||||
- Must call `get_target` activity to download from MinIO with isolation mode
|
||||
**Key Temporal Workflow Concepts:**
|
||||
- Use `@workflow.defn` class decorator to define workflows
|
||||
- Use `@activity.defn` decorator for activity functions
|
||||
- Call `get_target` activity to download targets from MinIO with workspace isolation
|
||||
- Use `workflow.execute_activity()` with explicit timeouts and retry policies
|
||||
- Use `workflow.logger` for logging (appears in Temporal UI)
|
||||
- Use `workflow.logger` for logging (appears in Temporal UI and backend logs)
|
||||
- Call `cleanup_cache` activity at end to clean up workspace
|
||||
|
||||
---
|
||||
|
||||
@@ -204,7 +204,7 @@ curl -X POST http://localhost:8000/workflows/infrastructure_scan/submit \
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────┐ ┌─────────────────┐
|
||||
│ MCP Tools │ │ Prefect │
|
||||
│ MCP Tools │ │ Temporal │
|
||||
│ - scan submit │ │ Workflows │
|
||||
│ - results │ │ - Security │
|
||||
│ - analysis │ │ - Fuzzing │
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# FuzzForge Documentation
|
||||
|
||||
Welcome to FuzzForge, a comprehensive security analysis platform built on Prefect 3 that automates security testing workflows. FuzzForge provides 6 production-ready workflows that run static analysis, secret detection, infrastructure scanning, penetration testing, and custom fuzzing campaigns with Docker-based isolation and SARIF-compliant reporting.
|
||||
Welcome to FuzzForge, a comprehensive security analysis platform built on Temporal that automates security testing workflows. FuzzForge provides production-ready workflows that run static analysis, secret detection, infrastructure scanning, penetration testing, and custom fuzzing campaigns with Docker-based isolation and SARIF-compliant reporting.
|
||||
|
||||
## 🚀 Quick Navigation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user