Initial commit

backend/src/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+

backend/src/api/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+

backend/src/api/fuzzing.py

@@ -0,0 +1,325 @@
+"""
+API endpoints for fuzzing workflow management and real-time monitoring
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import logging
+from typing import List, Dict, Any
+from fastapi import APIRouter, HTTPException, Depends, WebSocket, WebSocketDisconnect
+from fastapi.responses import StreamingResponse
+import asyncio
+import json
+from datetime import datetime
+
+from src.models.findings import (
+    FuzzingStats,
+    CrashReport
+)
+from src.core.workflow_discovery import WorkflowDiscovery
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/fuzzing", tags=["fuzzing"])
+
+# In-memory storage for real-time stats (in production, use Redis or similar)
+fuzzing_stats: Dict[str, FuzzingStats] = {}
+crash_reports: Dict[str, List[CrashReport]] = {}
+active_connections: Dict[str, List[WebSocket]] = {}
+
+
+def initialize_fuzzing_tracking(run_id: str, workflow_name: str):
+    """
+    Initialize fuzzing tracking for a new run.
+
+    This function should be called when a workflow is submitted to enable
+    real-time monitoring and stats collection.
+
+    Args:
+        run_id: The run identifier
+        workflow_name: Name of the workflow
+    """
+    fuzzing_stats[run_id] = FuzzingStats(
+        run_id=run_id,
+        workflow=workflow_name
+    )
+    crash_reports[run_id] = []
+    active_connections[run_id] = []
+
+
+@router.get("/{run_id}/stats", response_model=FuzzingStats)
+async def get_fuzzing_stats(run_id: str) -> FuzzingStats:
+    """
+    Get current fuzzing statistics for a run.
+
+    Args:
+        run_id: The fuzzing run ID
+
+    Returns:
+        Current fuzzing statistics
+
+    Raises:
+        HTTPException: 404 if run not found
+    """
+    if run_id not in fuzzing_stats:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Fuzzing run not found: {run_id}"
+        )
+
+    return fuzzing_stats[run_id]
+
+
+@router.get("/{run_id}/crashes", response_model=List[CrashReport])
+async def get_crash_reports(run_id: str) -> List[CrashReport]:
+    """
+    Get crash reports for a fuzzing run.
+
+    Args:
+        run_id: The fuzzing run ID
+
+    Returns:
+        List of crash reports
+
+    Raises:
+        HTTPException: 404 if run not found
+    """
+    if run_id not in crash_reports:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Fuzzing run not found: {run_id}"
+        )
+
+    return crash_reports[run_id]
+
+
+@router.post("/{run_id}/stats")
+async def update_fuzzing_stats(run_id: str, stats: FuzzingStats):
+    """
+    Update fuzzing statistics (called by fuzzing workflows).
+
+    Args:
+        run_id: The fuzzing run ID
+        stats: Updated statistics
+
+    Raises:
+        HTTPException: 404 if run not found
+    """
+    if run_id not in fuzzing_stats:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Fuzzing run not found: {run_id}"
+        )
+
+    # Update stats
+    fuzzing_stats[run_id] = stats
+
+    # Debug: log reception for live instrumentation
+    try:
+        logger.info(
+            "Received fuzzing stats update: run_id=%s exec=%s eps=%.2f crashes=%s corpus=%s elapsed=%ss",
+            run_id,
+            stats.executions,
+            stats.executions_per_sec,
+            stats.crashes,
+            stats.corpus_size,
+            stats.elapsed_time,
+        )
+    except Exception:
+        pass
+
+    # Notify connected WebSocket clients
+    if run_id in active_connections:
+        message = {
+            "type": "stats_update",
+            "data": stats.model_dump()
+        }
+        for websocket in active_connections[run_id][:]:  # Copy to avoid modification during iteration
+            try:
+                await websocket.send_text(json.dumps(message))
+            except Exception:
+                # Remove disconnected clients
+                active_connections[run_id].remove(websocket)
+
+
+@router.post("/{run_id}/crash")
+async def report_crash(run_id: str, crash: CrashReport):
+    """
+    Report a new crash (called by fuzzing workflows).
+
+    Args:
+        run_id: The fuzzing run ID
+        crash: Crash report details
+    """
+    if run_id not in crash_reports:
+        crash_reports[run_id] = []
+
+    # Add crash report
+    crash_reports[run_id].append(crash)
+
+    # Update stats
+    if run_id in fuzzing_stats:
+        fuzzing_stats[run_id].crashes += 1
+        fuzzing_stats[run_id].last_crash_time = crash.timestamp
+
+    # Notify connected WebSocket clients
+    if run_id in active_connections:
+        message = {
+            "type": "crash_report",
+            "data": crash.model_dump()
+        }
+        for websocket in active_connections[run_id][:]:
+            try:
+                await websocket.send_text(json.dumps(message))
+            except Exception:
+                active_connections[run_id].remove(websocket)
+
+
+@router.websocket("/{run_id}/live")
+async def websocket_endpoint(websocket: WebSocket, run_id: str):
+    """
+    WebSocket endpoint for real-time fuzzing updates.
+
+    Args:
+        websocket: WebSocket connection
+        run_id: The fuzzing run ID to monitor
+    """
+    await websocket.accept()
+
+    # Initialize connection tracking
+    if run_id not in active_connections:
+        active_connections[run_id] = []
+    active_connections[run_id].append(websocket)
+
+    try:
+        # Send current stats on connection
+        if run_id in fuzzing_stats:
+            current = fuzzing_stats[run_id]
+            if isinstance(current, dict):
+                payload = current
+            elif hasattr(current, "model_dump"):
+                payload = current.model_dump()
+            elif hasattr(current, "dict"):
+                payload = current.dict()
+            else:
+                payload = getattr(current, "__dict__", {"run_id": run_id})
+            message = {"type": "stats_update", "data": payload}
+            await websocket.send_text(json.dumps(message))
+
+        # Keep connection alive
+        while True:
+            try:
+                # Wait for ping or handle disconnect
+                data = await asyncio.wait_for(websocket.receive_text(), timeout=30.0)
+                # Echo back for ping-pong
+                if data == "ping":
+                    await websocket.send_text("pong")
+            except asyncio.TimeoutError:
+                # Send periodic heartbeat
+                await websocket.send_text(json.dumps({"type": "heartbeat"}))
+
+    except WebSocketDisconnect:
+        # Clean up connection
+        if run_id in active_connections and websocket in active_connections[run_id]:
+            active_connections[run_id].remove(websocket)
+    except Exception as e:
+        logger.error(f"WebSocket error for run {run_id}: {e}")
+        if run_id in active_connections and websocket in active_connections[run_id]:
+            active_connections[run_id].remove(websocket)
+
+
+@router.get("/{run_id}/stream")
+async def stream_fuzzing_updates(run_id: str):
+    """
+    Server-Sent Events endpoint for real-time fuzzing updates.
+
+    Args:
+        run_id: The fuzzing run ID to monitor
+
+    Returns:
+        Streaming response with real-time updates
+    """
+    if run_id not in fuzzing_stats:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Fuzzing run not found: {run_id}"
+        )
+
+    async def event_stream():
+        """Generate server-sent events for fuzzing updates"""
+        last_stats_time = datetime.utcnow()
+
+        while True:
+            try:
+                # Send current stats
+                if run_id in fuzzing_stats:
+                    current_stats = fuzzing_stats[run_id]
+                    if isinstance(current_stats, dict):
+                        stats_payload = current_stats
+                    elif hasattr(current_stats, "model_dump"):
+                        stats_payload = current_stats.model_dump()
+                    elif hasattr(current_stats, "dict"):
+                        stats_payload = current_stats.dict()
+                    else:
+                        stats_payload = getattr(current_stats, "__dict__", {"run_id": run_id})
+                    event_data = f"data: {json.dumps({'type': 'stats', 'data': stats_payload})}\n\n"
+                    yield event_data
+
+                # Send recent crashes
+                if run_id in crash_reports:
+                    recent_crashes = [
+                        crash for crash in crash_reports[run_id]
+                        if crash.timestamp > last_stats_time
+                    ]
+                    for crash in recent_crashes:
+                        event_data = f"data: {json.dumps({'type': 'crash', 'data': crash.model_dump()})}\n\n"
+                        yield event_data
+
+                last_stats_time = datetime.utcnow()
+                await asyncio.sleep(5)  # Update every 5 seconds
+
+            except Exception as e:
+                logger.error(f"Error in event stream for run {run_id}: {e}")
+                break
+
+    return StreamingResponse(
+        event_stream(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )
+
+
+@router.delete("/{run_id}")
+async def cleanup_fuzzing_run(run_id: str):
+    """
+    Clean up fuzzing run data.
+
+    Args:
+        run_id: The fuzzing run ID to clean up
+    """
+    # Clean up tracking data
+    fuzzing_stats.pop(run_id, None)
+    crash_reports.pop(run_id, None)
+
+    # Close any active WebSocket connections
+    if run_id in active_connections:
+        for websocket in active_connections[run_id]:
+            try:
+                await websocket.close()
+            except Exception:
+                pass
+        del active_connections[run_id]
+
+    return {"message": f"Cleaned up fuzzing run {run_id}"}

backend/src/api/runs.py

@@ -0,0 +1,184 @@
+"""
+API endpoints for workflow run management and findings retrieval
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import logging
+from typing import Dict, Any
+from fastapi import APIRouter, HTTPException, Depends
+
+from src.models.findings import WorkflowFindings, WorkflowStatus
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/runs", tags=["runs"])
+
+
+def get_prefect_manager():
+    """Dependency to get the Prefect manager instance"""
+    from src.main import prefect_mgr
+    return prefect_mgr
+
+
+@router.get("/{run_id}/status", response_model=WorkflowStatus)
+async def get_run_status(
+    run_id: str,
+    prefect_mgr=Depends(get_prefect_manager)
+) -> WorkflowStatus:
+    """
+    Get the current status of a workflow run.
+
+    Args:
+        run_id: The flow run ID
+
+    Returns:
+        Status information including state, timestamps, and completion flags
+
+    Raises:
+        HTTPException: 404 if run not found
+    """
+    try:
+        status = await prefect_mgr.get_flow_run_status(run_id)
+
+        # Find workflow name from deployment
+        workflow_name = "unknown"
+        workflow_deployment_id = status.get("workflow", "")
+        for name, deployment_id in prefect_mgr.deployments.items():
+            if str(deployment_id) == str(workflow_deployment_id):
+                workflow_name = name
+                break
+
+        return WorkflowStatus(
+            run_id=status["run_id"],
+            workflow=workflow_name,
+            status=status["status"],
+            is_completed=status["is_completed"],
+            is_failed=status["is_failed"],
+            is_running=status["is_running"],
+            created_at=status["created_at"],
+            updated_at=status["updated_at"]
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get status for run {run_id}: {e}")
+        raise HTTPException(
+            status_code=404,
+            detail=f"Run not found: {run_id}"
+        )
+
+
+@router.get("/{run_id}/findings", response_model=WorkflowFindings)
+async def get_run_findings(
+    run_id: str,
+    prefect_mgr=Depends(get_prefect_manager)
+) -> WorkflowFindings:
+    """
+    Get the findings from a completed workflow run.
+
+    Args:
+        run_id: The flow run ID
+
+    Returns:
+        SARIF-formatted findings from the workflow execution
+
+    Raises:
+        HTTPException: 404 if run not found, 400 if run not completed
+    """
+    try:
+        # Get run status first
+        status = await prefect_mgr.get_flow_run_status(run_id)
+
+        if not status["is_completed"]:
+            if status["is_running"]:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Run {run_id} is still running. Current status: {status['status']}"
+                )
+            elif status["is_failed"]:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Run {run_id} failed. Status: {status['status']}"
+                )
+            else:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Run {run_id} not completed. Status: {status['status']}"
+                )
+
+        # Get the findings
+        findings = await prefect_mgr.get_flow_run_findings(run_id)
+
+        # Find workflow name
+        workflow_name = "unknown"
+        workflow_deployment_id = status.get("workflow", "")
+        for name, deployment_id in prefect_mgr.deployments.items():
+            if str(deployment_id) == str(workflow_deployment_id):
+                workflow_name = name
+                break
+
+        # Get workflow version if available
+        metadata = {
+            "completion_time": status["updated_at"],
+            "workflow_version": "unknown"
+        }
+
+        if workflow_name in prefect_mgr.workflows:
+            workflow_info = prefect_mgr.workflows[workflow_name]
+            metadata["workflow_version"] = workflow_info.metadata.get("version", "unknown")
+
+        return WorkflowFindings(
+            workflow=workflow_name,
+            run_id=run_id,
+            sarif=findings,
+            metadata=metadata
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get findings for run {run_id}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to retrieve findings: {str(e)}"
+        )
+
+
+@router.get("/{workflow_name}/findings/{run_id}", response_model=WorkflowFindings)
+async def get_workflow_findings(
+    workflow_name: str,
+    run_id: str,
+    prefect_mgr=Depends(get_prefect_manager)
+) -> WorkflowFindings:
+    """
+    Get findings for a specific workflow run.
+
+    Alternative endpoint that includes workflow name in the path for clarity.
+
+    Args:
+        workflow_name: Name of the workflow
+        run_id: The flow run ID
+
+    Returns:
+        SARIF-formatted findings from the workflow execution
+
+    Raises:
+        HTTPException: 404 if workflow or run not found, 400 if run not completed
+    """
+    if workflow_name not in prefect_mgr.workflows:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Workflow not found: {workflow_name}"
+        )
+
+    # Delegate to the main findings endpoint
+    return await get_run_findings(run_id, prefect_mgr)

backend/src/api/workflows.py

@@ -0,0 +1,386 @@
+"""
+API endpoints for workflow management with enhanced error handling
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import logging
+import traceback
+from typing import List, Dict, Any, Optional
+from fastapi import APIRouter, HTTPException, Depends
+from pathlib import Path
+
+from src.models.findings import (
+    WorkflowSubmission,
+    WorkflowMetadata,
+    WorkflowListItem,
+    RunSubmissionResponse
+)
+from src.core.workflow_discovery import WorkflowDiscovery
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/workflows", tags=["workflows"])
+
+
+def create_structured_error_response(
+    error_type: str,
+    message: str,
+    workflow_name: Optional[str] = None,
+    run_id: Optional[str] = None,
+    container_info: Optional[Dict[str, Any]] = None,
+    deployment_info: Optional[Dict[str, Any]] = None,
+    suggestions: Optional[List[str]] = None
+) -> Dict[str, Any]:
+    """Create a structured error response with rich context."""
+    error_response = {
+        "error": {
+            "type": error_type,
+            "message": message,
+            "timestamp": __import__("datetime").datetime.utcnow().isoformat() + "Z"
+        }
+    }
+
+    if workflow_name:
+        error_response["error"]["workflow_name"] = workflow_name
+
+    if run_id:
+        error_response["error"]["run_id"] = run_id
+
+    if container_info:
+        error_response["error"]["container"] = container_info
+
+    if deployment_info:
+        error_response["error"]["deployment"] = deployment_info
+
+    if suggestions:
+        error_response["error"]["suggestions"] = suggestions
+
+    return error_response
+
+
+def get_prefect_manager():
+    """Dependency to get the Prefect manager instance"""
+    from src.main import prefect_mgr
+    return prefect_mgr
+
+
+@router.get("/", response_model=List[WorkflowListItem])
+async def list_workflows(
+    prefect_mgr=Depends(get_prefect_manager)
+) -> List[WorkflowListItem]:
+    """
+    List all discovered workflows with their metadata.
+
+    Returns a summary of each workflow including name, version, description,
+    author, and tags.
+    """
+    workflows = []
+    for name, info in prefect_mgr.workflows.items():
+        workflows.append(WorkflowListItem(
+            name=name,
+            version=info.metadata.get("version", "0.6.0"),
+            description=info.metadata.get("description", ""),
+            author=info.metadata.get("author"),
+            tags=info.metadata.get("tags", [])
+        ))
+
+    return workflows
+
+
+@router.get("/metadata/schema")
+async def get_metadata_schema() -> Dict[str, Any]:
+    """
+    Get the JSON schema for workflow metadata files.
+
+    This schema defines the structure and requirements for metadata.yaml files
+    that must accompany each workflow.
+    """
+    return WorkflowDiscovery.get_metadata_schema()
+
+
+@router.get("/{workflow_name}/metadata", response_model=WorkflowMetadata)
+async def get_workflow_metadata(
+    workflow_name: str,
+    prefect_mgr=Depends(get_prefect_manager)
+) -> WorkflowMetadata:
+    """
+    Get complete metadata for a specific workflow.
+
+    Args:
+        workflow_name: Name of the workflow
+
+    Returns:
+        Complete metadata including parameters schema, supported volume modes,
+        required modules, and more.
+
+    Raises:
+        HTTPException: 404 if workflow not found
+    """
+    if workflow_name not in prefect_mgr.workflows:
+        available_workflows = list(prefect_mgr.workflows.keys())
+        error_response = create_structured_error_response(
+            error_type="WorkflowNotFound",
+            message=f"Workflow '{workflow_name}' not found",
+            workflow_name=workflow_name,
+            suggestions=[
+                f"Available workflows: {', '.join(available_workflows)}",
+                "Use GET /workflows/ to see all available workflows",
+                "Check workflow name spelling and case sensitivity"
+            ]
+        )
+        raise HTTPException(
+            status_code=404,
+            detail=error_response
+        )
+
+    info = prefect_mgr.workflows[workflow_name]
+    metadata = info.metadata
+
+    return WorkflowMetadata(
+        name=workflow_name,
+        version=metadata.get("version", "0.6.0"),
+        description=metadata.get("description", ""),
+        author=metadata.get("author"),
+        tags=metadata.get("tags", []),
+        parameters=metadata.get("parameters", {}),
+        default_parameters=metadata.get("default_parameters", {}),
+        required_modules=metadata.get("required_modules", []),
+        supported_volume_modes=metadata.get("supported_volume_modes", ["ro", "rw"]),
+        has_custom_docker=info.has_docker
+    )
+
+
+@router.post("/{workflow_name}/submit", response_model=RunSubmissionResponse)
+async def submit_workflow(
+    workflow_name: str,
+    submission: WorkflowSubmission,
+    prefect_mgr=Depends(get_prefect_manager)
+) -> RunSubmissionResponse:
+    """
+    Submit a workflow for execution with volume mounting.
+
+    Args:
+        workflow_name: Name of the workflow to execute
+        submission: Submission parameters including target path and volume mode
+
+    Returns:
+        Run submission response with run_id and initial status
+
+    Raises:
+        HTTPException: 404 if workflow not found, 400 for invalid parameters
+    """
+    if workflow_name not in prefect_mgr.workflows:
+        available_workflows = list(prefect_mgr.workflows.keys())
+        error_response = create_structured_error_response(
+            error_type="WorkflowNotFound",
+            message=f"Workflow '{workflow_name}' not found",
+            workflow_name=workflow_name,
+            suggestions=[
+                f"Available workflows: {', '.join(available_workflows)}",
+                "Use GET /workflows/ to see all available workflows",
+                "Check workflow name spelling and case sensitivity"
+            ]
+        )
+        raise HTTPException(
+            status_code=404,
+            detail=error_response
+        )
+
+    try:
+        # Convert ResourceLimits to dict if provided
+        resource_limits_dict = None
+        if submission.resource_limits:
+            resource_limits_dict = {
+                "cpu_limit": submission.resource_limits.cpu_limit,
+                "memory_limit": submission.resource_limits.memory_limit,
+                "cpu_request": submission.resource_limits.cpu_request,
+                "memory_request": submission.resource_limits.memory_request
+            }
+
+        # Submit the workflow with enhanced parameters
+        flow_run = await prefect_mgr.submit_workflow(
+            workflow_name=workflow_name,
+            target_path=submission.target_path,
+            volume_mode=submission.volume_mode,
+            parameters=submission.parameters,
+            resource_limits=resource_limits_dict,
+            additional_volumes=submission.additional_volumes,
+            timeout=submission.timeout
+        )
+
+        run_id = str(flow_run.id)
+
+        # Initialize fuzzing tracking if this looks like a fuzzing workflow
+        workflow_info = prefect_mgr.workflows.get(workflow_name, {})
+        workflow_tags = workflow_info.metadata.get("tags", []) if hasattr(workflow_info, 'metadata') else []
+        if "fuzzing" in workflow_tags or "fuzz" in workflow_name.lower():
+            from src.api.fuzzing import initialize_fuzzing_tracking
+            initialize_fuzzing_tracking(run_id, workflow_name)
+
+        return RunSubmissionResponse(
+            run_id=run_id,
+            status=flow_run.state.name if flow_run.state else "PENDING",
+            workflow=workflow_name,
+            message=f"Workflow '{workflow_name}' submitted successfully"
+        )
+
+    except ValueError as e:
+        # Parameter validation errors
+        error_response = create_structured_error_response(
+            error_type="ValidationError",
+            message=str(e),
+            workflow_name=workflow_name,
+            suggestions=[
+                "Check parameter types and values",
+                "Use GET /workflows/{workflow_name}/parameters for schema",
+                "Ensure all required parameters are provided"
+            ]
+        )
+        raise HTTPException(status_code=400, detail=error_response)
+
+    except Exception as e:
+        logger.error(f"Failed to submit workflow '{workflow_name}': {e}")
+        logger.error(f"Traceback: {traceback.format_exc()}")
+
+        # Try to get more context about the error
+        container_info = None
+        deployment_info = None
+        suggestions = []
+
+        error_message = str(e)
+        error_type = "WorkflowSubmissionError"
+
+        # Detect specific error patterns
+        if "deployment" in error_message.lower():
+            error_type = "DeploymentError"
+            deployment_info = {
+                "status": "failed",
+                "error": error_message
+            }
+            suggestions.extend([
+                "Check if Prefect server is running and accessible",
+                "Verify Docker is running and has sufficient resources",
+                "Check container image availability",
+                "Ensure volume paths exist and are accessible"
+            ])
+
+        elif "volume" in error_message.lower() or "mount" in error_message.lower():
+            error_type = "VolumeError"
+            suggestions.extend([
+                "Check if the target path exists and is accessible",
+                "Verify file permissions (Docker needs read access)",
+                "Ensure the path is not in use by another process",
+                "Try using an absolute path instead of relative path"
+            ])
+
+        elif "memory" in error_message.lower() or "resource" in error_message.lower():
+            error_type = "ResourceError"
+            suggestions.extend([
+                "Check system memory and CPU availability",
+                "Consider reducing resource limits or dataset size",
+                "Monitor Docker resource usage",
+                "Increase Docker memory limits if needed"
+            ])
+
+        elif "image" in error_message.lower():
+            error_type = "ImageError"
+            suggestions.extend([
+                "Check if the workflow image exists",
+                "Verify Docker registry access",
+                "Try rebuilding the workflow image",
+                "Check network connectivity to registries"
+            ])
+
+        else:
+            suggestions.extend([
+                "Check FuzzForge backend logs for details",
+                "Verify all services are running (docker-compose up -d)",
+                "Try restarting the workflow deployment",
+                "Contact support if the issue persists"
+            ])
+
+        error_response = create_structured_error_response(
+            error_type=error_type,
+            message=f"Failed to submit workflow: {error_message}",
+            workflow_name=workflow_name,
+            container_info=container_info,
+            deployment_info=deployment_info,
+            suggestions=suggestions
+        )
+
+        raise HTTPException(
+            status_code=500,
+            detail=error_response
+        )
+
+
+@router.get("/{workflow_name}/parameters")
+async def get_workflow_parameters(
+    workflow_name: str,
+    prefect_mgr=Depends(get_prefect_manager)
+) -> Dict[str, Any]:
+    """
+    Get the parameters schema for a workflow.
+
+    Args:
+        workflow_name: Name of the workflow
+
+    Returns:
+        Parameters schema with types, descriptions, and defaults
+
+    Raises:
+        HTTPException: 404 if workflow not found
+    """
+    if workflow_name not in prefect_mgr.workflows:
+        available_workflows = list(prefect_mgr.workflows.keys())
+        error_response = create_structured_error_response(
+            error_type="WorkflowNotFound",
+            message=f"Workflow '{workflow_name}' not found",
+            workflow_name=workflow_name,
+            suggestions=[
+                f"Available workflows: {', '.join(available_workflows)}",
+                "Use GET /workflows/ to see all available workflows"
+            ]
+        )
+        raise HTTPException(
+            status_code=404,
+            detail=error_response
+        )
+
+    info = prefect_mgr.workflows[workflow_name]
+    metadata = info.metadata
+
+    # Return parameters with enhanced schema information
+    parameters_schema = metadata.get("parameters", {})
+
+    # Extract the actual parameter definitions from JSON schema structure
+    if "properties" in parameters_schema:
+        param_definitions = parameters_schema["properties"]
+    else:
+        param_definitions = parameters_schema
+
+    # Add default values to the schema
+    default_params = metadata.get("default_parameters", {})
+    for param_name, param_schema in param_definitions.items():
+        if isinstance(param_schema, dict) and param_name in default_params:
+            param_schema["default"] = default_params[param_name]
+
+    return {
+        "workflow": workflow_name,
+        "parameters": param_definitions,
+        "default_parameters": default_params,
+        "required_parameters": [
+            name for name, schema in param_definitions.items()
+            if isinstance(schema, dict) and schema.get("required", False)
+        ]
+    }

backend/src/core/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+

backend/src/core/prefect_manager.py

@@ -0,0 +1,770 @@
+"""
+Prefect Manager - Core orchestration for workflow deployment and execution
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import logging
+import os
+import platform
+import re
+from pathlib import Path
+from typing import Dict, Optional, Any
+from prefect import get_client
+from prefect.docker import DockerImage
+from prefect.client.schemas import FlowRun
+
+from src.core.workflow_discovery import WorkflowDiscovery, WorkflowInfo
+
+logger = logging.getLogger(__name__)
+
+
+def get_registry_url(context: str = "default") -> str:
+    """
+    Get the container registry URL to use for a given operation context.
+
+    Goals:
+    - Work reliably across Linux and macOS Docker Desktop
+    - Prefer in-network service discovery when running inside containers
+    - Allow full override via env vars from docker-compose
+
+    Env overrides:
+      - FUZZFORGE_REGISTRY_PUSH_URL: used for image builds/pushes
+      - FUZZFORGE_REGISTRY_PULL_URL: used for workers to pull images
+    """
+    # Normalize context
+    ctx = (context or "default").lower()
+
+    # Always honor explicit overrides first
+    if ctx in ("push", "build"):
+        push_url = os.getenv("FUZZFORGE_REGISTRY_PUSH_URL")
+        if push_url:
+            logger.debug("Using FUZZFORGE_REGISTRY_PUSH_URL: %s", push_url)
+            return push_url
+        # Default to host-published registry for Docker daemon operations
+        return "localhost:5001"
+
+    if ctx == "pull":
+        pull_url = os.getenv("FUZZFORGE_REGISTRY_PULL_URL")
+        if pull_url:
+            logger.debug("Using FUZZFORGE_REGISTRY_PULL_URL: %s", pull_url)
+            return pull_url
+        # Prefect worker pulls via host Docker daemon as well
+        return "localhost:5001"
+
+    # Default/fallback
+    return os.getenv("FUZZFORGE_REGISTRY_PULL_URL", os.getenv("FUZZFORGE_REGISTRY_PUSH_URL", "localhost:5001"))
+
+
+def _compose_project_name(default: str = "fuzzforge_alpha") -> str:
+    """Return the docker-compose project name used for network/volume naming.
+
+    Honors COMPOSE_PROJECT_NAME if present; falls back to a sensible default.
+    """
+    return os.getenv("COMPOSE_PROJECT_NAME", default)
+
+
+class PrefectManager:
+    """
+    Manages Prefect deployments and flow runs for discovered workflows.
+
+    This class handles:
+    - Workflow discovery and registration
+    - Docker image building through Prefect
+    - Deployment creation and management
+    - Flow run submission with volume mounting
+    - Findings retrieval from completed runs
+    """
+
+    def __init__(self, workflows_dir: Path = None):
+        """
+        Initialize the Prefect manager.
+
+        Args:
+            workflows_dir: Path to the workflows directory (default: toolbox/workflows)
+        """
+        if workflows_dir is None:
+            workflows_dir = Path("toolbox/workflows")
+
+        self.discovery = WorkflowDiscovery(workflows_dir)
+        self.workflows: Dict[str, WorkflowInfo] = {}
+        self.deployments: Dict[str, str] = {}  # workflow_name -> deployment_id
+
+        # Security: Define allowed and forbidden paths for host mounting
+        self.allowed_base_paths = [
+            "/tmp",
+            "/home",
+            "/Users",  # macOS users
+            "/opt",
+            "/var/tmp",
+            "/workspace",  # Common container workspace
+            "/app"  # Container application directory (for test projects)
+        ]
+
+        self.forbidden_paths = [
+            "/etc",
+            "/root",
+            "/var/run",
+            "/sys",
+            "/proc",
+            "/dev",
+            "/boot",
+            "/var/lib/docker",  # Critical Docker data
+            "/var/log",  # System logs
+            "/usr/bin",  # System binaries
+            "/usr/sbin",
+            "/sbin",
+            "/bin"
+        ]
+
+    @staticmethod
+    def _parse_memory_to_bytes(memory_str: str) -> int:
+        """
+        Parse memory string (like '512Mi', '1Gi') to bytes.
+
+        Args:
+            memory_str: Memory string with unit suffix
+
+        Returns:
+            Memory in bytes
+
+        Raises:
+            ValueError: If format is invalid
+        """
+        if not memory_str:
+            return 0
+
+        match = re.match(r'^(\d+(?:\.\d+)?)\s*([GMK]i?)$', memory_str.strip())
+        if not match:
+            raise ValueError(f"Invalid memory format: {memory_str}. Expected format like '512Mi', '1Gi'")
+
+        value, unit = match.groups()
+        value = float(value)
+
+        # Convert to bytes based on unit (binary units: Ki, Mi, Gi)
+        if unit in ['K', 'Ki']:
+            multiplier = 1024
+        elif unit in ['M', 'Mi']:
+            multiplier = 1024 * 1024
+        elif unit in ['G', 'Gi']:
+            multiplier = 1024 * 1024 * 1024
+        else:
+            raise ValueError(f"Unsupported memory unit: {unit}")
+
+        return int(value * multiplier)
+
+    @staticmethod
+    def _parse_cpu_to_millicores(cpu_str: str) -> int:
+        """
+        Parse CPU string (like '500m', '1', '2.5') to millicores.
+
+        Args:
+            cpu_str: CPU string
+
+        Returns:
+            CPU in millicores (1 core = 1000 millicores)
+
+        Raises:
+            ValueError: If format is invalid
+        """
+        if not cpu_str:
+            return 0
+
+        cpu_str = cpu_str.strip()
+
+        # Handle millicores format (e.g., '500m')
+        if cpu_str.endswith('m'):
+            try:
+                return int(cpu_str[:-1])
+            except ValueError:
+                raise ValueError(f"Invalid CPU format: {cpu_str}")
+
+        # Handle core format (e.g., '1', '2.5')
+        try:
+            cores = float(cpu_str)
+            return int(cores * 1000)  # Convert to millicores
+        except ValueError:
+            raise ValueError(f"Invalid CPU format: {cpu_str}")
+
+    def _extract_resource_requirements(self, workflow_info: WorkflowInfo) -> Dict[str, str]:
+        """
+        Extract resource requirements from workflow metadata.
+
+        Args:
+            workflow_info: Workflow information with metadata
+
+        Returns:
+            Dictionary with resource requirements in Docker format
+        """
+        metadata = workflow_info.metadata
+        requirements = metadata.get("requirements", {})
+        resources = requirements.get("resources", {})
+
+        resource_config = {}
+
+        # Extract memory requirement
+        memory = resources.get("memory")
+        if memory:
+            try:
+                # Validate memory format and store original string for Docker
+                self._parse_memory_to_bytes(memory)
+                resource_config["memory"] = memory
+            except ValueError as e:
+                logger.warning(f"Invalid memory requirement in {workflow_info.name}: {e}")
+
+        # Extract CPU requirement
+        cpu = resources.get("cpu")
+        if cpu:
+            try:
+                # Validate CPU format and store original string for Docker
+                self._parse_cpu_to_millicores(cpu)
+                resource_config["cpus"] = cpu
+            except ValueError as e:
+                logger.warning(f"Invalid CPU requirement in {workflow_info.name}: {e}")
+
+        # Extract timeout
+        timeout = resources.get("timeout")
+        if timeout and isinstance(timeout, int):
+            resource_config["timeout"] = str(timeout)
+
+        return resource_config
+
+    async def initialize(self):
+        """
+        Initialize the manager by discovering and deploying all workflows.
+
+        This method:
+        1. Discovers all valid workflows in the workflows directory
+        2. Validates their metadata
+        3. Deploys each workflow to Prefect with Docker images
+        """
+        try:
+            # Discover workflows
+            self.workflows = await self.discovery.discover_workflows()
+
+            if not self.workflows:
+                logger.warning("No workflows discovered")
+                return
+
+            logger.info(f"Discovered {len(self.workflows)} workflows: {list(self.workflows.keys())}")
+
+            # Deploy each workflow
+            for name, info in self.workflows.items():
+                try:
+                    await self._deploy_workflow(name, info)
+                except Exception as e:
+                    logger.error(f"Failed to deploy workflow '{name}': {e}")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize Prefect manager: {e}")
+            raise
+
+    async def _deploy_workflow(self, name: str, info: WorkflowInfo):
+        """
+        Deploy a single workflow to Prefect with Docker image.
+
+        Args:
+            name: Workflow name
+            info: Workflow information including metadata and paths
+        """
+        logger.info(f"Deploying workflow '{name}'...")
+
+        # Get the flow function from registry
+        flow_func = self.discovery.get_flow_function(name)
+        if not flow_func:
+            logger.error(
+                f"Failed to get flow function for '{name}' from registry. "
+                f"Ensure the workflow is properly registered in toolbox/workflows/registry.py"
+            )
+            return
+
+        # Use the mandatory Dockerfile with absolute paths for Docker Compose
+        # Get absolute paths for build context and dockerfile
+        toolbox_path = info.path.parent.parent.resolve()
+        dockerfile_abs_path = info.dockerfile.resolve()
+
+        # Calculate relative dockerfile path from toolbox context
+        try:
+            dockerfile_rel_path = dockerfile_abs_path.relative_to(toolbox_path)
+        except ValueError:
+            # If relative path fails, use the workflow-specific path
+            dockerfile_rel_path = Path("workflows") / name / "Dockerfile"
+
+        # Determine deployment strategy based on Dockerfile presence
+        base_image = "prefecthq/prefect:3-python3.11"
+        has_custom_dockerfile = info.has_docker and info.dockerfile.exists()
+
+        logger.info(f"=== DEPLOYMENT DEBUG for '{name}' ===")
+        logger.info(f"info.has_docker: {info.has_docker}")
+        logger.info(f"info.dockerfile: {info.dockerfile}")
+        logger.info(f"info.dockerfile.exists(): {info.dockerfile.exists()}")
+        logger.info(f"has_custom_dockerfile: {has_custom_dockerfile}")
+        logger.info(f"toolbox_path: {toolbox_path}")
+        logger.info(f"dockerfile_rel_path: {dockerfile_rel_path}")
+
+        if has_custom_dockerfile:
+            logger.info(f"Workflow '{name}' has custom Dockerfile - building custom image")
+            # Decide whether to use registry or keep images local to host engine
+            import os
+            # Default to using the local registry; set FUZZFORGE_USE_REGISTRY=false to bypass (not recommended)
+            use_registry = os.getenv("FUZZFORGE_USE_REGISTRY", "true").lower() == "true"
+
+            if use_registry:
+                registry_url = get_registry_url(context="push")
+                image_spec = DockerImage(
+                    name=f"{registry_url}/fuzzforge/{name}",
+                    tag="latest",
+                    dockerfile=str(dockerfile_rel_path),
+                    context=str(toolbox_path)
+                )
+                deploy_image = f"{registry_url}/fuzzforge/{name}:latest"
+                build_custom = True
+                push_custom = True
+                logger.info(f"Using registry: {registry_url} for '{name}'")
+            else:
+                # Single-host mode: build into host engine cache; no push required
+                image_spec = DockerImage(
+                    name=f"fuzzforge/{name}",
+                    tag="latest",
+                    dockerfile=str(dockerfile_rel_path),
+                    context=str(toolbox_path)
+                )
+                deploy_image = f"fuzzforge/{name}:latest"
+                build_custom = True
+                push_custom = False
+                logger.info("Using single-host image (no registry push): %s", deploy_image)
+        else:
+            logger.info(f"Workflow '{name}' using base image - no custom dependencies needed")
+            deploy_image = base_image
+            build_custom = False
+            push_custom = False
+
+        # Pre-validate registry connectivity when pushing
+        if push_custom:
+            try:
+                from .setup import validate_registry_connectivity
+                await validate_registry_connectivity(registry_url)
+                logger.info(f"Registry connectivity validated for {registry_url}")
+            except Exception as e:
+                logger.error(f"Registry connectivity validation failed for {registry_url}: {e}")
+                raise RuntimeError(f"Cannot deploy workflow '{name}': Registry {registry_url} is not accessible. {e}")
+
+        # Deploy the workflow
+        try:
+            # Ensure any previous deployment is removed so job variables are updated
+            try:
+                async with get_client() as client:
+                    existing = await client.read_deployment_by_name(
+                        f"{name}/{name}-deployment"
+                    )
+                    if existing:
+                        logger.info(f"Removing existing deployment for '{name}' to refresh settings...")
+                        await client.delete_deployment(existing.id)
+            except Exception:
+                # If not found or deletion fails, continue with deployment
+                pass
+
+            # Extract resource requirements from metadata
+            workflow_resource_requirements = self._extract_resource_requirements(info)
+            logger.info(f"Workflow '{name}' resource requirements: {workflow_resource_requirements}")
+
+            # Build job variables with resource requirements
+            job_variables = {
+                "image": deploy_image,  # Use the worker-accessible registry name
+                "volumes": [],  # Populated at run submission with toolbox mount
+                "env": {
+                    "PYTHONPATH": "/opt/prefect/toolbox:/opt/prefect/toolbox/workflows",
+                    "WORKFLOW_NAME": name
+                }
+            }
+
+            # Add resource requirements to job variables if present
+            if workflow_resource_requirements:
+                job_variables["resources"] = workflow_resource_requirements
+
+            # Prepare deployment parameters
+            deploy_params = {
+                "name": f"{name}-deployment",
+                "work_pool_name": "docker-pool",
+                "image": image_spec if has_custom_dockerfile else deploy_image,
+                "push": push_custom,
+                "build": build_custom,
+                "job_variables": job_variables
+            }
+
+            deployment = await flow_func.deploy(**deploy_params)
+
+            self.deployments[name] = str(deployment.id) if hasattr(deployment, 'id') else name
+            logger.info(f"Successfully deployed workflow '{name}'")
+
+        except Exception as e:
+            # Enhanced error reporting with more context
+            import traceback
+            logger.error(f"Failed to deploy workflow '{name}': {e}")
+            logger.error(f"Deployment traceback: {traceback.format_exc()}")
+
+            # Try to capture Docker-specific context
+            error_context = {
+                "workflow_name": name,
+                "has_dockerfile": has_custom_dockerfile,
+                "image_name": deploy_image if 'deploy_image' in locals() else "unknown",
+                "registry_url": registry_url if 'registry_url' in locals() else "unknown",
+                "error_type": type(e).__name__,
+                "error_message": str(e)
+            }
+
+            # Check for specific error patterns with detailed categorization
+            error_msg_lower = str(e).lower()
+            if "registry" in error_msg_lower and ("no such host" in error_msg_lower or "connection" in error_msg_lower):
+                error_context["category"] = "registry_connectivity_error"
+                error_context["solution"] = f"Cannot reach registry at {error_context['registry_url']}. Check Docker network and registry service."
+            elif "docker" in error_msg_lower:
+                error_context["category"] = "docker_error"
+                if "build" in error_msg_lower:
+                    error_context["subcategory"] = "image_build_failed"
+                    error_context["solution"] = "Check Dockerfile syntax and dependencies."
+                elif "pull" in error_msg_lower:
+                    error_context["subcategory"] = "image_pull_failed"
+                    error_context["solution"] = "Check if image exists in registry and network connectivity."
+                elif "push" in error_msg_lower:
+                    error_context["subcategory"] = "image_push_failed"
+                    error_context["solution"] = f"Check registry connectivity and push permissions to {error_context['registry_url']}."
+            elif "registry" in error_msg_lower:
+                error_context["category"] = "registry_error"
+                error_context["solution"] = "Check registry configuration and accessibility."
+            elif "prefect" in error_msg_lower:
+                error_context["category"] = "prefect_error"
+                error_context["solution"] = "Check Prefect server connectivity and deployment configuration."
+            else:
+                error_context["category"] = "unknown_deployment_error"
+                error_context["solution"] = "Check logs for more specific error details."
+
+            logger.error(f"Deployment error context: {error_context}")
+
+            # Raise enhanced exception with context
+            enhanced_error = Exception(f"Deployment failed for workflow '{name}': {str(e)} | Context: {error_context}")
+            enhanced_error.original_error = e
+            enhanced_error.context = error_context
+            raise enhanced_error
+
+    async def submit_workflow(
+        self,
+        workflow_name: str,
+        target_path: str,
+        volume_mode: str = "ro",
+        parameters: Dict[str, Any] = None,
+        resource_limits: Dict[str, str] = None,
+        additional_volumes: list = None,
+        timeout: int = None
+    ) -> FlowRun:
+        """
+        Submit a workflow for execution with volume mounting.
+
+        Args:
+            workflow_name: Name of the workflow to execute
+            target_path: Host path to mount as volume
+            volume_mode: Volume mount mode ("ro" for read-only, "rw" for read-write)
+            parameters: Workflow-specific parameters
+            resource_limits: CPU/memory limits for container
+            additional_volumes: List of additional volume mounts
+            timeout: Timeout in seconds
+
+        Returns:
+            FlowRun object with run information
+
+        Raises:
+            ValueError: If workflow not found or volume mode not supported
+        """
+        if workflow_name not in self.workflows:
+            raise ValueError(f"Unknown workflow: {workflow_name}")
+
+        # Validate volume mode
+        workflow_info = self.workflows[workflow_name]
+        supported_modes = workflow_info.metadata.get("supported_volume_modes", ["ro", "rw"])
+
+        if volume_mode not in supported_modes:
+            raise ValueError(
+                f"Workflow '{workflow_name}' doesn't support volume mode '{volume_mode}'. "
+                f"Supported modes: {supported_modes}"
+            )
+
+        # Validate target path with security checks
+        self._validate_target_path(target_path)
+
+        # Validate additional volumes if provided
+        if additional_volumes:
+            for volume in additional_volumes:
+                self._validate_target_path(volume.host_path)
+
+        async with get_client() as client:
+            # Get the deployment, auto-redeploy once if missing
+            try:
+                deployment = await client.read_deployment_by_name(
+                    f"{workflow_name}/{workflow_name}-deployment"
+                )
+            except Exception as e:
+                import traceback
+                logger.error(f"Failed to find deployment for workflow '{workflow_name}': {e}")
+                logger.error(f"Deployment lookup traceback: {traceback.format_exc()}")
+
+                # Attempt a one-time auto-deploy to recover from startup races
+                try:
+                    logger.info(f"Auto-deploying missing workflow '{workflow_name}' and retrying...")
+                    await self._deploy_workflow(workflow_name, workflow_info)
+                    deployment = await client.read_deployment_by_name(
+                        f"{workflow_name}/{workflow_name}-deployment"
+                    )
+                except Exception as redeploy_exc:
+                    # Enhanced error with context
+                    error_context = {
+                        "workflow_name": workflow_name,
+                        "error_type": type(e).__name__,
+                        "error_message": str(e),
+                        "redeploy_error": str(redeploy_exc),
+                        "available_deployments": list(self.deployments.keys()),
+                    }
+                    enhanced_error = ValueError(
+                        f"Deployment not found and redeploy failed for workflow '{workflow_name}': {e} | Context: {error_context}"
+                    )
+                    enhanced_error.context = error_context
+                    raise enhanced_error
+
+            # Determine the Docker Compose network name and volume names
+            # Docker Compose creates networks with pattern: {project_name}_default
+            import os
+            compose_project = _compose_project_name('fuzzforge_alpha')
+            docker_network = f"{compose_project}_default"
+
+            # Build volume mounts
+            # Add toolbox volume mount for workflow code access
+            backend_toolbox_path = "/app/toolbox"  # Path in backend container
+
+            # Use dynamic volume names based on Docker Compose project name
+            prefect_storage_volume = f"{compose_project}_prefect_storage"
+            toolbox_code_volume = f"{compose_project}_toolbox_code"
+
+            volumes = [
+                f"{target_path}:/workspace:{volume_mode}",
+                f"{prefect_storage_volume}:/prefect-storage",  # Shared storage for results
+                f"{toolbox_code_volume}:/opt/prefect/toolbox:ro"  # Mount workflow code
+            ]
+
+            # Add additional volumes if provided
+            if additional_volumes:
+                for volume in additional_volumes:
+                    volume_spec = f"{volume.host_path}:{volume.container_path}:{volume.mode}"
+                    volumes.append(volume_spec)
+
+            # Build environment variables
+            env_vars = {
+                "PREFECT_API_URL": "http://prefect-server:4200/api",  # Use internal network hostname
+                "PREFECT_LOGGING_LEVEL": "INFO",
+                "PREFECT_LOCAL_STORAGE_PATH": "/prefect-storage",  # Use shared storage
+                "PREFECT_RESULTS_PERSIST_BY_DEFAULT": "true",  # Enable result persistence
+                "PREFECT_DEFAULT_RESULT_STORAGE_BLOCK": "local-file-system/fuzzforge-results",  # Use our storage block
+                "WORKSPACE_PATH": "/workspace",
+                "VOLUME_MODE": volume_mode,
+                "WORKFLOW_NAME": workflow_name
+            }
+
+            # Add additional volume paths to environment for easy access
+            if additional_volumes:
+                for i, volume in enumerate(additional_volumes):
+                    env_vars[f"ADDITIONAL_VOLUME_{i}_PATH"] = volume.container_path
+
+            # Determine which image to use based on workflow configuration
+            workflow_info = self.workflows[workflow_name]
+            has_custom_dockerfile = workflow_info.has_docker and workflow_info.dockerfile.exists()
+            # Use pull context for worker to pull from registry
+            registry_url = get_registry_url(context="pull")
+            workflow_image = f"{registry_url}/fuzzforge/{workflow_name}:latest" if has_custom_dockerfile else "prefecthq/prefect:3-python3.11"
+            logger.debug(f"Worker will pull image: {workflow_image} (Registry: {registry_url})")
+
+            # Configure job variables with volume mounting and network access
+            job_variables = {
+                # Use custom image if available, otherwise base Prefect image
+                "image": workflow_image,
+                "volumes": volumes,
+                "networks": [docker_network],  # Connect to Docker Compose network
+                "env": {
+                    **env_vars,
+                    "PYTHONPATH": "/opt/prefect/toolbox:/opt/prefect/toolbox/workflows",
+                    "WORKFLOW_NAME": workflow_name
+                }
+            }
+
+            # Apply resource requirements from workflow metadata and user overrides
+            workflow_resource_requirements = self._extract_resource_requirements(workflow_info)
+            final_resource_config = {}
+
+            # Start with workflow requirements as base
+            if workflow_resource_requirements:
+                final_resource_config.update(workflow_resource_requirements)
+
+            # Apply user-provided resource limits (overrides workflow defaults)
+            if resource_limits:
+                user_resource_config = {}
+                if resource_limits.get("cpu_limit"):
+                    user_resource_config["cpus"] = resource_limits["cpu_limit"]
+                if resource_limits.get("memory_limit"):
+                    user_resource_config["memory"] = resource_limits["memory_limit"]
+                # Note: cpu_request and memory_request are not directly supported by Docker
+                # but could be used for Kubernetes in the future
+
+                # User overrides take precedence
+                final_resource_config.update(user_resource_config)
+
+            # Apply final resource configuration
+            if final_resource_config:
+                job_variables["resources"] = final_resource_config
+                logger.info(f"Applied resource limits: {final_resource_config}")
+
+            # Merge parameters with defaults from metadata
+            default_params = workflow_info.metadata.get("default_parameters", {})
+            final_params = {**default_params, **(parameters or {})}
+
+            # Set flow parameters that match the flow signature
+            final_params["target_path"] = "/workspace"  # Container path where volume is mounted
+            final_params["volume_mode"] = volume_mode
+
+            # Create and submit the flow run
+            # Pass job_variables to ensure network, volumes, and environment are configured
+            logger.info(f"Submitting flow with job_variables: {job_variables}")
+            logger.info(f"Submitting flow with parameters: {final_params}")
+
+            # Prepare flow run creation parameters
+            flow_run_params = {
+                "deployment_id": deployment.id,
+                "parameters": final_params,
+                "job_variables": job_variables
+            }
+
+            # Note: Timeout is handled through workflow-level configuration
+            # Additional timeout configuration can be added to deployment metadata if needed
+
+            flow_run = await client.create_flow_run_from_deployment(**flow_run_params)
+
+            logger.info(
+                f"Submitted workflow '{workflow_name}' with run_id: {flow_run.id}, "
+                f"target: {target_path}, mode: {volume_mode}"
+            )
+
+            return flow_run
+
+    async def get_flow_run_findings(self, run_id: str) -> Dict[str, Any]:
+        """
+        Retrieve findings from a completed flow run.
+
+        Args:
+            run_id: The flow run ID
+
+        Returns:
+            Dictionary containing SARIF-formatted findings
+
+        Raises:
+            ValueError: If run not completed or not found
+        """
+        async with get_client() as client:
+            flow_run = await client.read_flow_run(run_id)
+
+            if not flow_run.state.is_completed():
+                raise ValueError(
+                    f"Flow run {run_id} not completed. Current status: {flow_run.state.name}"
+                )
+
+            # Get the findings from the flow run result
+            try:
+                findings = await flow_run.state.result()
+                return findings
+            except Exception as e:
+                logger.error(f"Failed to retrieve findings for run {run_id}: {e}")
+                raise ValueError(f"Failed to retrieve findings: {e}")
+
+    async def get_flow_run_status(self, run_id: str) -> Dict[str, Any]:
+        """
+        Get the current status of a flow run.
+
+        Args:
+            run_id: The flow run ID
+
+        Returns:
+            Dictionary with status information
+        """
+        async with get_client() as client:
+            flow_run = await client.read_flow_run(run_id)
+
+            return {
+                "run_id": str(flow_run.id),
+                "workflow": flow_run.deployment_id,
+                "status": flow_run.state.name,
+                "is_completed": flow_run.state.is_completed(),
+                "is_failed": flow_run.state.is_failed(),
+                "is_running": flow_run.state.is_running(),
+                "created_at": flow_run.created,
+                "updated_at": flow_run.updated
+            }
+
+    def _validate_target_path(self, target_path: str) -> None:
+        """
+        Validate target path for security before mounting as volume.
+
+        Args:
+            target_path: Host path to validate
+
+        Raises:
+            ValueError: If path is not allowed for security reasons
+        """
+        target = Path(target_path)
+
+        # Path must be absolute
+        if not target.is_absolute():
+            raise ValueError(f"Target path must be absolute: {target_path}")
+
+        # Resolve path to handle symlinks and relative components
+        try:
+            resolved_path = target.resolve()
+        except (OSError, RuntimeError) as e:
+            raise ValueError(f"Cannot resolve target path: {target_path} - {e}")
+
+        resolved_str = str(resolved_path)
+
+        # Check against forbidden paths first (more restrictive)
+        for forbidden in self.forbidden_paths:
+            if resolved_str.startswith(forbidden):
+                raise ValueError(
+                    f"Access denied: Path '{target_path}' resolves to forbidden directory '{forbidden}'. "
+                    f"This path contains sensitive system files and cannot be mounted."
+                )
+
+        # Check if path starts with any allowed base path
+        path_allowed = False
+        for allowed in self.allowed_base_paths:
+            if resolved_str.startswith(allowed):
+                path_allowed = True
+                break
+
+        if not path_allowed:
+            allowed_list = ", ".join(self.allowed_base_paths)
+            raise ValueError(
+                f"Access denied: Path '{target_path}' is not in allowed directories. "
+                f"Allowed base paths: {allowed_list}"
+            )
+
+        # Additional security checks
+        if resolved_str == "/":
+            raise ValueError("Cannot mount root filesystem")
+
+        # Warn if path doesn't exist (but don't block - it might be created later)
+        if not resolved_path.exists():
+            logger.warning(f"Target path does not exist: {target_path}")
+
+        logger.info(f"Path validation passed for: {target_path} -> {resolved_str}")

backend/src/core/setup.py

@@ -0,0 +1,402 @@
+"""
+Setup utilities for Prefect infrastructure
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import logging
+from prefect import get_client
+from prefect.client.schemas.actions import WorkPoolCreate
+from prefect.client.schemas.objects import WorkPool
+from .prefect_manager import get_registry_url
+
+logger = logging.getLogger(__name__)
+
+
+async def setup_docker_pool():
+    """
+    Create or update the Docker work pool for container execution.
+
+    This work pool is configured to:
+    - Connect to the local Docker daemon
+    - Support volume mounting at runtime
+    - Clean up containers after execution
+    - Use bridge networking by default
+    """
+    import os
+
+    async with get_client() as client:
+        pool_name = "docker-pool"
+
+        # Add force recreation flag for debugging fresh install issues
+        force_recreate = os.getenv('FORCE_RECREATE_WORK_POOL', 'false').lower() == 'true'
+        debug_setup = os.getenv('DEBUG_WORK_POOL_SETUP', 'false').lower() == 'true'
+
+        if force_recreate:
+            logger.warning(f"FORCE_RECREATE_WORK_POOL=true - Will recreate work pool regardless of existing configuration")
+        if debug_setup:
+            logger.warning(f"DEBUG_WORK_POOL_SETUP=true - Enhanced logging enabled")
+            # Temporarily set logging level to DEBUG for this function
+            original_level = logger.level
+            logger.setLevel(logging.DEBUG)
+
+        try:
+            # Check if pool already exists and supports custom images
+            existing_pools = await client.read_work_pools()
+            existing_pool = None
+            for pool in existing_pools:
+                if pool.name == pool_name:
+                    existing_pool = pool
+                    break
+
+            if existing_pool and not force_recreate:
+                logger.info(f"Found existing work pool '{pool_name}' - validating configuration...")
+
+                # Check if the existing pool has the correct configuration
+                base_template = existing_pool.base_job_template or {}
+                logger.debug(f"Base template keys: {list(base_template.keys())}")
+
+                job_config = base_template.get("job_configuration", {})
+                logger.debug(f"Job config keys: {list(job_config.keys())}")
+
+                image_config = job_config.get("image", "")
+                has_image_variable = "{{ image }}" in str(image_config)
+                logger.debug(f"Image config: '{image_config}' -> has_image_variable: {has_image_variable}")
+
+                # Check if volume defaults include toolbox mount
+                variables = base_template.get("variables", {})
+                properties = variables.get("properties", {})
+                volume_config = properties.get("volumes", {})
+                volume_defaults = volume_config.get("default", [])
+                has_toolbox_volume = any("toolbox_code" in str(vol) for vol in volume_defaults) if volume_defaults else False
+                logger.debug(f"Volume defaults: {volume_defaults}")
+                logger.debug(f"Has toolbox volume: {has_toolbox_volume}")
+
+                # Check if environment defaults include required settings
+                env_config = properties.get("env", {})
+                env_defaults = env_config.get("default", {})
+                has_api_url = "PREFECT_API_URL" in env_defaults
+                has_storage_path = "PREFECT_LOCAL_STORAGE_PATH" in env_defaults
+                has_results_persist = "PREFECT_RESULTS_PERSIST_BY_DEFAULT" in env_defaults
+                has_required_env = has_api_url and has_storage_path and has_results_persist
+                logger.debug(f"Environment defaults: {env_defaults}")
+                logger.debug(f"Has API URL: {has_api_url}, Has storage path: {has_storage_path}, Has results persist: {has_results_persist}")
+                logger.debug(f"Has required env: {has_required_env}")
+
+                # Log the full validation result
+                logger.info(f"Work pool validation - Image: {has_image_variable}, Toolbox: {has_toolbox_volume}, Environment: {has_required_env}")
+
+                if has_image_variable and has_toolbox_volume and has_required_env:
+                    logger.info(f"Docker work pool '{pool_name}' already exists with correct configuration")
+                    return
+                else:
+                    reasons = []
+                    if not has_image_variable:
+                        reasons.append("missing image template")
+                    if not has_toolbox_volume:
+                        reasons.append("missing toolbox volume mount")
+                    if not has_required_env:
+                        if not has_api_url:
+                            reasons.append("missing PREFECT_API_URL")
+                        if not has_storage_path:
+                            reasons.append("missing PREFECT_LOCAL_STORAGE_PATH")
+                        if not has_results_persist:
+                            reasons.append("missing PREFECT_RESULTS_PERSIST_BY_DEFAULT")
+
+                    logger.warning(f"Docker work pool '{pool_name}' exists but lacks: {', '.join(reasons)}. Recreating...")
+                    # Delete the old pool and recreate it
+                    try:
+                        await client.delete_work_pool(pool_name)
+                        logger.info(f"Deleted old work pool '{pool_name}'")
+                    except Exception as e:
+                        logger.warning(f"Failed to delete old work pool: {e}")
+            elif force_recreate and existing_pool:
+                logger.warning(f"Force recreation enabled - deleting existing work pool '{pool_name}'")
+                try:
+                    await client.delete_work_pool(pool_name)
+                    logger.info(f"Deleted existing work pool for force recreation")
+                except Exception as e:
+                    logger.warning(f"Failed to delete work pool for force recreation: {e}")
+
+            logger.info(f"Creating Docker work pool '{pool_name}' with custom image support...")
+
+            # Create the work pool with proper Docker configuration
+            work_pool = WorkPoolCreate(
+                name=pool_name,
+                type="docker",
+                description="Docker work pool for FuzzForge workflows with custom image support",
+                base_job_template={
+                    "job_configuration": {
+                        "image": "{{ image }}",  # Template variable for custom images
+                        "volumes": "{{ volumes }}",  # List of volume mounts
+                        "env": "{{ env }}",  # Environment variables
+                        "networks": "{{ networks }}",  # Docker networks
+                        "stream_output": True,
+                        "auto_remove": True,
+                        "privileged": False,
+                        "network_mode": None,  # Use networks instead
+                        "labels": {},
+                        "command": None  # Let the image's CMD/ENTRYPOINT run
+                    },
+                    "variables": {
+                        "type": "object",
+                        "properties": {
+                            "image": {
+                                "type": "string",
+                                "title": "Docker Image",
+                                "default": "prefecthq/prefect:3-python3.11",
+                                "description": "Docker image for the flow run"
+                            },
+                            "volumes": {
+                                "type": "array",
+                                "title": "Volume Mounts",
+                                "default": [
+                                    f"{get_actual_compose_project_name()}_prefect_storage:/prefect-storage",
+                                    f"{get_actual_compose_project_name()}_toolbox_code:/opt/prefect/toolbox:ro"
+                                ],
+                                "description": "Volume mounts in format 'host:container:mode'",
+                                "items": {
+                                    "type": "string"
+                                }
+                            },
+                            "networks": {
+                                "type": "array",
+                                "title": "Docker Networks",
+                                "default": [f"{get_actual_compose_project_name()}_default"],
+                                "description": "Docker networks to connect container to",
+                                "items": {
+                                    "type": "string"
+                                }
+                            },
+                            "env": {
+                                "type": "object",
+                                "title": "Environment Variables",
+                                "default": {
+                                    "PREFECT_API_URL": "http://prefect-server:4200/api",
+                                    "PREFECT_LOCAL_STORAGE_PATH": "/prefect-storage",
+                                    "PREFECT_RESULTS_PERSIST_BY_DEFAULT": "true"
+                                },
+                                "description": "Environment variables for the container",
+                                "additionalProperties": {
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+            )
+
+            await client.create_work_pool(work_pool)
+            logger.info(f"Created Docker work pool '{pool_name}'")
+
+        except Exception as e:
+            logger.error(f"Failed to setup Docker work pool: {e}")
+            raise
+        finally:
+            # Restore original logging level if debug mode was enabled
+            if debug_setup and 'original_level' in locals():
+                logger.setLevel(original_level)
+
+
+def get_actual_compose_project_name():
+    """
+    Return the hardcoded compose project name for FuzzForge.
+
+    Always returns 'fuzzforge_alpha' as per system requirements.
+    """
+    logger.info("Using hardcoded compose project name: fuzzforge_alpha")
+    return "fuzzforge_alpha"
+
+
+async def setup_result_storage():
+    """
+    Create or update Prefect result storage block for findings persistence.
+
+    This sets up a LocalFileSystem storage block pointing to the shared
+    /prefect-storage volume for result persistence.
+    """
+    from prefect.filesystems import LocalFileSystem
+
+    storage_name = "fuzzforge-results"
+
+    try:
+        # Create the storage block, overwrite if it exists
+        logger.info(f"Setting up storage block '{storage_name}'...")
+        storage = LocalFileSystem(basepath="/prefect-storage")
+
+        block_doc_id = await storage.save(name=storage_name, overwrite=True)
+        logger.info(f"Storage block '{storage_name}' configured successfully")
+        return str(block_doc_id)
+
+    except Exception as e:
+        logger.error(f"Failed to setup result storage: {e}")
+        # Don't raise the exception - continue without storage block
+        logger.warning("Continuing without result storage block - findings may not persist")
+        return None
+
+
+async def validate_docker_connection():
+    """
+    Validate that Docker is accessible and running.
+
+    Note: In containerized deployments with Docker socket proxy,
+    the backend doesn't need direct Docker access.
+
+    Raises:
+        RuntimeError: If Docker is not accessible
+    """
+    import os
+
+    # Skip Docker validation if running in container without socket access
+    if os.path.exists("/.dockerenv") and not os.path.exists("/var/run/docker.sock"):
+        logger.info("Running in container without Docker socket - skipping Docker validation")
+        return
+
+    try:
+        import docker
+        client = docker.from_env()
+        client.ping()
+        logger.info("Docker connection validated")
+    except Exception as e:
+        logger.error(f"Docker is not accessible: {e}")
+        raise RuntimeError(
+            "Docker is not running or not accessible. "
+            "Please ensure Docker is installed and running."
+        )
+
+
+async def validate_registry_connectivity(registry_url: str = None):
+    """
+    Validate that the Docker registry is accessible.
+
+    Args:
+        registry_url: URL of the Docker registry to validate (auto-detected if None)
+
+    Raises:
+        RuntimeError: If registry is not accessible
+    """
+    # Resolve a reachable test URL from within this process
+    if registry_url is None:
+        # If not specified, prefer internal service name in containers, host port on host
+        import os
+        if os.path.exists('/.dockerenv'):
+            registry_url = "registry:5000"
+        else:
+            registry_url = "localhost:5001"
+
+    # If we're running inside a container and asked to probe localhost:PORT,
+    # the probe would hit the container, not the host. Use host.docker.internal instead.
+    import os
+    try:
+        host_part, port_part = registry_url.split(":", 1)
+    except ValueError:
+        host_part, port_part = registry_url, "80"
+
+    if os.path.exists('/.dockerenv') and host_part in ("localhost", "127.0.0.1"):
+        test_host = "host.docker.internal"
+    else:
+        test_host = host_part
+    test_url = f"http://{test_host}:{port_part}/v2/"
+
+    import aiohttp
+    import asyncio
+
+    logger.info(f"Validating registry connectivity to {registry_url}...")
+
+    try:
+        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=10)) as session:
+            async with session.get(test_url) as response:
+                if response.status == 200:
+                    logger.info(f"Registry at {registry_url} is accessible (tested via {test_host})")
+                    return
+                else:
+                    raise RuntimeError(f"Registry returned status {response.status}")
+    except asyncio.TimeoutError:
+        raise RuntimeError(f"Registry at {registry_url} is not responding (timeout)")
+    except aiohttp.ClientError as e:
+        raise RuntimeError(f"Registry at {registry_url} is not accessible: {e}")
+    except Exception as e:
+        raise RuntimeError(f"Failed to validate registry connectivity: {e}")
+
+
+async def validate_docker_network(network_name: str):
+    """
+    Validate that the specified Docker network exists.
+
+    Args:
+        network_name: Name of the Docker network to validate
+
+    Raises:
+        RuntimeError: If network doesn't exist
+    """
+    import os
+
+    # Skip network validation if running in container without Docker socket
+    if os.path.exists("/.dockerenv") and not os.path.exists("/var/run/docker.sock"):
+        logger.info("Running in container without Docker socket - skipping network validation")
+        return
+
+    try:
+        import docker
+        client = docker.from_env()
+
+        # List all networks
+        networks = client.networks.list(names=[network_name])
+
+        if not networks:
+            # Try to find networks with similar names
+            all_networks = client.networks.list()
+            similar_networks = [n.name for n in all_networks if "fuzzforge" in n.name.lower()]
+
+            error_msg = f"Docker network '{network_name}' not found."
+            if similar_networks:
+                error_msg += f" Available networks: {similar_networks}"
+            else:
+                error_msg += " Please ensure Docker Compose is running."
+
+            raise RuntimeError(error_msg)
+
+        logger.info(f"Docker network '{network_name}' validated")
+
+    except Exception as e:
+        if isinstance(e, RuntimeError):
+            raise
+        logger.error(f"Network validation failed: {e}")
+        raise RuntimeError(f"Failed to validate Docker network: {e}")
+
+
+async def validate_infrastructure():
+    """
+    Validate all required infrastructure components.
+
+    This should be called during startup to ensure everything is ready.
+    """
+    logger.info("Validating infrastructure...")
+
+    # Validate Docker connection
+    await validate_docker_connection()
+
+    # Validate registry connectivity for custom image building
+    await validate_registry_connectivity()
+
+    # Validate network (check for default network pattern)
+    import os
+    compose_project = os.getenv('COMPOSE_PROJECT_NAME', 'fuzzforge_alpha')
+    docker_network = f"{compose_project}_default"
+
+    try:
+        await validate_docker_network(docker_network)
+    except RuntimeError as e:
+        logger.warning(f"Network validation failed: {e}")
+        logger.warning("Workflows may not be able to connect to Prefect services")
+
+    logger.info("Infrastructure validation completed")

backend/src/core/workflow_discovery.py

@@ -0,0 +1,459 @@
+"""
+Workflow Discovery - Registry-based discovery and loading of workflows
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import logging
+import yaml
+from pathlib import Path
+from typing import Dict, Optional, Any, Callable
+from pydantic import BaseModel, Field, ConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowInfo(BaseModel):
+    """Information about a discovered workflow"""
+    name: str = Field(..., description="Workflow name")
+    path: Path = Field(..., description="Path to workflow directory")
+    workflow_file: Path = Field(..., description="Path to workflow.py file")
+    dockerfile: Path = Field(..., description="Path to Dockerfile")
+    has_docker: bool = Field(..., description="Whether workflow has custom Dockerfile")
+    metadata: Dict[str, Any] = Field(..., description="Workflow metadata from YAML")
+    flow_function_name: str = Field(default="main_flow", description="Name of the flow function")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class WorkflowDiscovery:
+    """
+    Discovers workflows from the filesystem and validates them against the registry.
+
+    This system:
+    1. Scans for workflows with metadata.yaml files
+    2. Cross-references them with the manual registry
+    3. Provides registry-based flow functions for deployment
+
+    Workflows must have:
+    - workflow.py: Contains the Prefect flow
+    - metadata.yaml: Mandatory metadata file
+    - Entry in toolbox/workflows/registry.py: Manual registration
+    - Dockerfile (optional): Custom container definition
+    - requirements.txt (optional): Python dependencies
+    """
+
+    def __init__(self, workflows_dir: Path):
+        """
+        Initialize workflow discovery.
+
+        Args:
+            workflows_dir: Path to the workflows directory
+        """
+        self.workflows_dir = workflows_dir
+        if not self.workflows_dir.exists():
+            self.workflows_dir.mkdir(parents=True, exist_ok=True)
+            logger.info(f"Created workflows directory: {self.workflows_dir}")
+
+        # Import registry - this validates it on import
+        try:
+            from toolbox.workflows.registry import WORKFLOW_REGISTRY, list_registered_workflows
+            self.registry = WORKFLOW_REGISTRY
+            logger.info(f"Loaded workflow registry with {len(self.registry)} registered workflows")
+        except ImportError as e:
+            logger.error(f"Failed to import workflow registry: {e}")
+            self.registry = {}
+        except Exception as e:
+            logger.error(f"Registry validation failed: {e}")
+            self.registry = {}
+
+        # Cache for discovered workflows
+        self._workflow_cache: Optional[Dict[str, WorkflowInfo]] = None
+        self._cache_timestamp: Optional[float] = None
+        self._cache_ttl = 60.0  # Cache TTL in seconds
+
+    async def discover_workflows(self) -> Dict[str, WorkflowInfo]:
+        """
+        Discover workflows by cross-referencing filesystem with registry.
+        Uses caching to avoid frequent filesystem scans.
+
+        Returns:
+            Dictionary mapping workflow names to their information
+        """
+        # Check cache validity
+        import time
+        current_time = time.time()
+
+        if (self._workflow_cache is not None and
+            self._cache_timestamp is not None and
+            (current_time - self._cache_timestamp) < self._cache_ttl):
+            # Return cached results
+            logger.debug(f"Returning cached workflow discovery ({len(self._workflow_cache)} workflows)")
+            return self._workflow_cache
+        workflows = {}
+        discovered_dirs = set()
+        registry_names = set(self.registry.keys())
+
+        if not self.workflows_dir.exists():
+            logger.warning(f"Workflows directory does not exist: {self.workflows_dir}")
+            return workflows
+
+        # Recursively scan all directories and subdirectories
+        await self._scan_directory_recursive(self.workflows_dir, workflows, discovered_dirs)
+
+        # Check for registry entries without corresponding directories
+        missing_dirs = registry_names - discovered_dirs
+        if missing_dirs:
+            logger.warning(
+                f"Registry contains workflows without filesystem directories: {missing_dirs}. "
+                f"These workflows cannot be deployed."
+            )
+
+        logger.info(
+            f"Discovery complete: {len(workflows)} workflows ready for deployment, "
+            f"{len(missing_dirs)} registry entries missing directories, "
+            f"{len(discovered_dirs - registry_names)} filesystem workflows not registered"
+        )
+
+        # Update cache
+        self._workflow_cache = workflows
+        self._cache_timestamp = current_time
+
+        return workflows
+
+    async def _scan_directory_recursive(self, directory: Path, workflows: Dict[str, WorkflowInfo], discovered_dirs: set):
+        """
+        Recursively scan directory for workflows.
+
+        Args:
+            directory: Directory to scan
+            workflows: Dictionary to populate with discovered workflows
+            discovered_dirs: Set to track discovered workflow names
+        """
+        for item in directory.iterdir():
+            if not item.is_dir():
+                continue
+
+            if item.name.startswith('_') or item.name.startswith('.'):
+                continue  # Skip hidden or private directories
+
+            # Check if this directory contains workflow files (workflow.py and metadata.yaml)
+            workflow_file = item / "workflow.py"
+            metadata_file = item / "metadata.yaml"
+
+            if workflow_file.exists() and metadata_file.exists():
+                # This is a workflow directory
+                workflow_name = item.name
+                discovered_dirs.add(workflow_name)
+
+                # Only process workflows that are in the registry
+                if workflow_name not in self.registry:
+                    logger.warning(
+                        f"Workflow '{workflow_name}' found in filesystem but not in registry. "
+                        f"Add it to toolbox/workflows/registry.py to enable deployment."
+                    )
+                    continue
+
+                try:
+                    workflow_info = await self._load_workflow(item)
+                    if workflow_info:
+                        workflows[workflow_info.name] = workflow_info
+                        logger.info(f"Discovered and registered workflow: {workflow_info.name}")
+                except Exception as e:
+                    logger.error(f"Failed to load workflow from {item}: {e}")
+            else:
+                # This is a category directory, recurse into it
+                await self._scan_directory_recursive(item, workflows, discovered_dirs)
+
+    async def _load_workflow(self, workflow_dir: Path) -> Optional[WorkflowInfo]:
+        """
+        Load and validate a single workflow.
+
+        Args:
+            workflow_dir: Path to the workflow directory
+
+        Returns:
+            WorkflowInfo if valid, None otherwise
+        """
+        workflow_name = workflow_dir.name
+
+        # Check for mandatory files
+        workflow_file = workflow_dir / "workflow.py"
+        metadata_file = workflow_dir / "metadata.yaml"
+
+        if not workflow_file.exists():
+            logger.warning(f"Workflow {workflow_name} missing workflow.py")
+            return None
+
+        if not metadata_file.exists():
+            logger.error(f"Workflow {workflow_name} missing mandatory metadata.yaml")
+            return None
+
+        # Load and validate metadata
+        try:
+            metadata = self._load_metadata(metadata_file)
+            if not self._validate_metadata(metadata, workflow_name):
+                return None
+        except Exception as e:
+            logger.error(f"Failed to load metadata for {workflow_name}: {e}")
+            return None
+
+        # Check for mandatory Dockerfile
+        dockerfile = workflow_dir / "Dockerfile"
+        if not dockerfile.exists():
+            logger.error(f"Workflow {workflow_name} missing mandatory Dockerfile")
+            return None
+
+        has_docker = True  # Always True since Dockerfile is mandatory
+
+        # Get flow function name from metadata or use default
+        flow_function_name = metadata.get("flow_function", "main_flow")
+
+        return WorkflowInfo(
+            name=workflow_name,
+            path=workflow_dir,
+            workflow_file=workflow_file,
+            dockerfile=dockerfile,
+            has_docker=has_docker,
+            metadata=metadata,
+            flow_function_name=flow_function_name
+        )
+
+    def _load_metadata(self, metadata_file: Path) -> Dict[str, Any]:
+        """
+        Load metadata from YAML file.
+
+        Args:
+            metadata_file: Path to metadata.yaml
+
+        Returns:
+            Dictionary containing metadata
+        """
+        with open(metadata_file, 'r') as f:
+            metadata = yaml.safe_load(f)
+
+        if metadata is None:
+            raise ValueError("Empty metadata file")
+
+        return metadata
+
+    def _validate_metadata(self, metadata: Dict[str, Any], workflow_name: str) -> bool:
+        """
+        Validate that metadata contains all required fields.
+
+        Args:
+            metadata: Metadata dictionary
+            workflow_name: Name of the workflow for logging
+
+        Returns:
+            True if valid, False otherwise
+        """
+        required_fields = ["name", "version", "description", "author", "category", "parameters", "requirements"]
+
+        missing_fields = []
+        for field in required_fields:
+            if field not in metadata:
+                missing_fields.append(field)
+
+        if missing_fields:
+            logger.error(
+                f"Workflow {workflow_name} metadata missing required fields: {missing_fields}"
+            )
+            return False
+
+        # Validate version format (semantic versioning)
+        version = metadata.get("version", "")
+        if not self._is_valid_version(version):
+            logger.error(f"Workflow {workflow_name} has invalid version format: {version}")
+            return False
+
+        # Validate parameters structure
+        parameters = metadata.get("parameters", {})
+        if not isinstance(parameters, dict):
+            logger.error(f"Workflow {workflow_name} parameters must be a dictionary")
+            return False
+
+        return True
+
+    def _is_valid_version(self, version: str) -> bool:
+        """
+        Check if version follows semantic versioning (x.y.z).
+
+        Args:
+            version: Version string
+
+        Returns:
+            True if valid semantic version
+        """
+        try:
+            parts = version.split('.')
+            if len(parts) != 3:
+                return False
+            for part in parts:
+                int(part)  # Check if each part is a number
+            return True
+        except (ValueError, AttributeError):
+            return False
+
+    def invalidate_cache(self) -> None:
+        """
+        Invalidate the workflow discovery cache.
+        Useful when workflows are added or modified.
+        """
+        self._workflow_cache = None
+        self._cache_timestamp = None
+        logger.debug("Workflow discovery cache invalidated")
+
+    def get_flow_function(self, workflow_name: str) -> Optional[Callable]:
+        """
+        Get the flow function from the registry.
+
+        Args:
+            workflow_name: Name of the workflow
+
+        Returns:
+            The flow function if found in registry, None otherwise
+        """
+        if workflow_name not in self.registry:
+            logger.error(
+                f"Workflow '{workflow_name}' not found in registry. "
+                f"Available workflows: {list(self.registry.keys())}"
+            )
+            return None
+
+        try:
+            from toolbox.workflows.registry import get_workflow_flow
+            flow_func = get_workflow_flow(workflow_name)
+            logger.debug(f"Retrieved flow function for '{workflow_name}' from registry")
+            return flow_func
+        except Exception as e:
+            logger.error(f"Failed to get flow function for '{workflow_name}': {e}")
+            return None
+
+    def get_registry_info(self, workflow_name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get registry information for a workflow.
+
+        Args:
+            workflow_name: Name of the workflow
+
+        Returns:
+            Registry information if found, None otherwise
+        """
+        if workflow_name not in self.registry:
+            return None
+
+        try:
+            from toolbox.workflows.registry import get_workflow_info
+            return get_workflow_info(workflow_name)
+        except Exception as e:
+            logger.error(f"Failed to get registry info for '{workflow_name}': {e}")
+            return None
+
+    @staticmethod
+    def get_metadata_schema() -> Dict[str, Any]:
+        """
+        Get the JSON schema for workflow metadata.
+
+        Returns:
+            JSON schema dictionary
+        """
+        return {
+            "type": "object",
+            "required": ["name", "version", "description", "author", "category", "parameters", "requirements"],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Workflow name"
+                },
+                "version": {
+                    "type": "string",
+                    "pattern": "^\\d+\\.\\d+\\.\\d+$",
+                    "description": "Semantic version (x.y.z)"
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Workflow description"
+                },
+                "author": {
+                    "type": "string",
+                    "description": "Workflow author"
+                },
+                "category": {
+                    "type": "string",
+                    "enum": ["comprehensive", "specialized", "fuzzing", "focused"],
+                    "description": "Workflow category"
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Workflow tags for categorization"
+                },
+                "requirements": {
+                    "type": "object",
+                    "required": ["tools", "resources"],
+                    "properties": {
+                        "tools": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Required security tools"
+                        },
+                        "resources": {
+                            "type": "object",
+                            "required": ["memory", "cpu", "timeout"],
+                            "properties": {
+                                "memory": {
+                                    "type": "string",
+                                    "pattern": "^\\d+[GMK]i$",
+                                    "description": "Memory limit (e.g., 1Gi, 512Mi)"
+                                },
+                                "cpu": {
+                                    "type": "string",
+                                    "pattern": "^\\d+m?$",
+                                    "description": "CPU limit (e.g., 1000m, 2)"
+                                },
+                                "timeout": {
+                                    "type": "integer",
+                                    "minimum": 60,
+                                    "maximum": 7200,
+                                    "description": "Workflow timeout in seconds"
+                                }
+                            }
+                        }
+                    }
+                },
+                "parameters": {
+                    "type": "object",
+                    "description": "Workflow parameters schema"
+                },
+                "default_parameters": {
+                    "type": "object",
+                    "description": "Default parameter values"
+                },
+                "required_modules": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Required module names"
+                },
+                "supported_volume_modes": {
+                    "type": "array",
+                    "items": {"enum": ["ro", "rw"]},
+                    "default": ["ro", "rw"],
+                    "description": "Supported volume mount modes"
+                },
+                "flow_function": {
+                    "type": "string",
+                    "default": "main_flow",
+                    "description": "Name of the flow function in workflow.py"
+                }
+            }
+        }

backend/src/main.py

@@ -0,0 +1,864 @@
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+import asyncio
+import logging
+import os
+from uuid import UUID
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
+from typing import Any, Dict, Optional, List
+
+import uvicorn
+from fastapi import FastAPI
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from fastmcp.server.http import create_sse_app
+
+from src.core.prefect_manager import PrefectManager
+from src.core.setup import setup_docker_pool, setup_result_storage, validate_infrastructure
+from src.core.workflow_discovery import WorkflowDiscovery
+from src.api import workflows, runs, fuzzing
+from src.services.prefect_stats_monitor import prefect_stats_monitor
+
+from fastmcp import FastMCP
+from prefect.client.orchestration import get_client
+from prefect.client.schemas.filters import (
+    FlowRunFilter,
+    FlowRunFilterDeploymentId,
+    FlowRunFilterState,
+    FlowRunFilterStateType,
+)
+from prefect.client.schemas.sorting import FlowRunSort
+from prefect.states import StateType
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+prefect_mgr = PrefectManager()
+
+
+class PrefectBootstrapState:
+    """Tracks Prefect initialization progress for API and MCP consumers."""
+
+    def __init__(self) -> None:
+        self.ready: bool = False
+        self.status: str = "not_started"
+        self.last_error: Optional[str] = None
+        self.task_running: bool = False
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "ready": self.ready,
+            "status": self.status,
+            "last_error": self.last_error,
+            "task_running": self.task_running,
+        }
+
+
+prefect_bootstrap_state = PrefectBootstrapState()
+
+# Configure retry strategy for bootstrapping Prefect + infrastructure
+STARTUP_RETRY_SECONDS = max(1, int(os.getenv("FUZZFORGE_STARTUP_RETRY_SECONDS", "5")))
+STARTUP_RETRY_MAX_SECONDS = max(
+    STARTUP_RETRY_SECONDS,
+    int(os.getenv("FUZZFORGE_STARTUP_RETRY_MAX_SECONDS", "60")),
+)
+
+prefect_bootstrap_task: Optional[asyncio.Task] = None
+
+# ---------------------------------------------------------------------------
+# FastAPI application (REST API remains unchanged)
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="FuzzForge API",
+    description="Security testing workflow orchestration API with fuzzing support",
+    version="0.6.0",
+)
+
+app.include_router(workflows.router)
+app.include_router(runs.router)
+app.include_router(fuzzing.router)
+
+
+def get_prefect_status() -> Dict[str, Any]:
+    """Return a snapshot of Prefect bootstrap state for diagnostics."""
+    status = prefect_bootstrap_state.as_dict()
+    status["workflows_loaded"] = len(prefect_mgr.workflows)
+    status["deployments_tracked"] = len(prefect_mgr.deployments)
+    status["bootstrap_task_running"] = (
+        prefect_bootstrap_task is not None and not prefect_bootstrap_task.done()
+    )
+    return status
+
+
+def _prefect_not_ready_status() -> Optional[Dict[str, Any]]:
+    """Return status details if Prefect is not ready yet."""
+    status = get_prefect_status()
+    if status.get("ready"):
+        return None
+    return status
+
+
+@app.get("/")
+async def root() -> Dict[str, Any]:
+    status = get_prefect_status()
+    return {
+        "name": "FuzzForge API",
+        "version": "0.6.0",
+        "status": "ready" if status.get("ready") else "initializing",
+        "workflows_loaded": status.get("workflows_loaded", 0),
+        "prefect": status,
+    }
+
+
+@app.get("/health")
+async def health() -> Dict[str, str]:
+    status = get_prefect_status()
+    health_status = "healthy" if status.get("ready") else "initializing"
+    return {"status": health_status}
+
+
+# Map FastAPI OpenAPI operationIds to readable MCP tool names
+FASTAPI_MCP_NAME_OVERRIDES: Dict[str, str] = {
+    "list_workflows_workflows__get": "api_list_workflows",
+    "get_metadata_schema_workflows_metadata_schema_get": "api_get_metadata_schema",
+    "get_workflow_metadata_workflows__workflow_name__metadata_get": "api_get_workflow_metadata",
+    "submit_workflow_workflows__workflow_name__submit_post": "api_submit_workflow",
+    "get_workflow_parameters_workflows__workflow_name__parameters_get": "api_get_workflow_parameters",
+    "get_run_status_runs__run_id__status_get": "api_get_run_status",
+    "get_run_findings_runs__run_id__findings_get": "api_get_run_findings",
+    "get_workflow_findings_runs__workflow_name__findings__run_id__get": "api_get_workflow_findings",
+    "get_fuzzing_stats_fuzzing__run_id__stats_get": "api_get_fuzzing_stats",
+    "update_fuzzing_stats_fuzzing__run_id__stats_post": "api_update_fuzzing_stats",
+    "get_crash_reports_fuzzing__run_id__crashes_get": "api_get_crash_reports",
+    "report_crash_fuzzing__run_id__crash_post": "api_report_crash",
+    "stream_fuzzing_updates_fuzzing__run_id__stream_get": "api_stream_fuzzing_updates",
+    "cleanup_fuzzing_run_fuzzing__run_id__delete": "api_cleanup_fuzzing_run",
+    "root__get": "api_root",
+    "health_health_get": "api_health",
+}
+
+
+# Create an MCP adapter exposing all FastAPI endpoints via OpenAPI parsing
+FASTAPI_MCP_ADAPTER = FastMCP.from_fastapi(
+    app,
+    name="FuzzForge FastAPI",
+    mcp_names=FASTAPI_MCP_NAME_OVERRIDES,
+)
+_fastapi_mcp_imported = False
+
+
+# ---------------------------------------------------------------------------
+# FastMCP server (runs on dedicated port outside FastAPI)
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(name="FuzzForge MCP")
+
+
+async def _bootstrap_prefect_with_retries() -> None:
+    """Initialize Prefect infrastructure with exponential backoff retries."""
+
+    attempt = 0
+
+    while True:
+        attempt += 1
+        prefect_bootstrap_state.task_running = True
+        prefect_bootstrap_state.status = "starting"
+        prefect_bootstrap_state.ready = False
+        prefect_bootstrap_state.last_error = None
+
+        try:
+            logger.info("Bootstrapping Prefect infrastructure...")
+            await validate_infrastructure()
+            await setup_docker_pool()
+            await setup_result_storage()
+            await prefect_mgr.initialize()
+            await prefect_stats_monitor.start_monitoring()
+
+            prefect_bootstrap_state.ready = True
+            prefect_bootstrap_state.status = "ready"
+            prefect_bootstrap_state.task_running = False
+            logger.info("Prefect infrastructure ready")
+            return
+
+        except asyncio.CancelledError:
+            prefect_bootstrap_state.status = "cancelled"
+            prefect_bootstrap_state.task_running = False
+            logger.info("Prefect bootstrap task cancelled")
+            raise
+
+        except Exception as exc:  # pragma: no cover - defensive logging on infra startup
+            logger.exception("Prefect bootstrap failed")
+            prefect_bootstrap_state.ready = False
+            prefect_bootstrap_state.status = "error"
+            prefect_bootstrap_state.last_error = str(exc)
+
+            # Ensure partial initialization does not leave stale state behind
+            prefect_mgr.workflows.clear()
+            prefect_mgr.deployments.clear()
+            await prefect_stats_monitor.stop_monitoring()
+
+            wait_time = min(
+                STARTUP_RETRY_SECONDS * (2 ** (attempt - 1)),
+                STARTUP_RETRY_MAX_SECONDS,
+            )
+            logger.info("Retrying Prefect bootstrap in %s second(s)", wait_time)
+
+            try:
+                await asyncio.sleep(wait_time)
+            except asyncio.CancelledError:
+                prefect_bootstrap_state.status = "cancelled"
+                prefect_bootstrap_state.task_running = False
+                raise
+
+
+def _lookup_workflow(workflow_name: str):
+    info = prefect_mgr.workflows.get(workflow_name)
+    if not info:
+        return None
+    metadata = info.metadata
+    defaults = metadata.get("default_parameters", {})
+    default_target_path = metadata.get("default_target_path") or defaults.get("target_path")
+    supported_modes = metadata.get("supported_volume_modes") or ["ro", "rw"]
+    if not isinstance(supported_modes, list) or not supported_modes:
+        supported_modes = ["ro", "rw"]
+    default_volume_mode = (
+        metadata.get("default_volume_mode")
+        or defaults.get("volume_mode")
+        or supported_modes[0]
+    )
+    return {
+        "name": workflow_name,
+        "version": metadata.get("version", "0.6.0"),
+        "description": metadata.get("description", ""),
+        "author": metadata.get("author"),
+        "tags": metadata.get("tags", []),
+        "parameters": metadata.get("parameters", {}),
+        "default_parameters": metadata.get("default_parameters", {}),
+        "required_modules": metadata.get("required_modules", []),
+        "supported_volume_modes": supported_modes,
+        "default_target_path": default_target_path,
+        "default_volume_mode": default_volume_mode,
+        "has_custom_docker": bool(info.has_docker),
+    }
+
+
+@mcp.tool
+async def list_workflows_mcp() -> Dict[str, Any]:
+    """List all discovered workflows and their metadata summary."""
+    not_ready = _prefect_not_ready_status()
+    if not_ready:
+        return {
+            "workflows": [],
+            "prefect": not_ready,
+            "message": "Prefect infrastructure is still initializing",
+        }
+
+    workflows_summary = []
+    for name, info in prefect_mgr.workflows.items():
+        metadata = info.metadata
+        defaults = metadata.get("default_parameters", {})
+        workflows_summary.append({
+            "name": name,
+            "version": metadata.get("version", "0.6.0"),
+            "description": metadata.get("description", ""),
+            "author": metadata.get("author"),
+            "tags": metadata.get("tags", []),
+            "supported_volume_modes": metadata.get("supported_volume_modes", ["ro", "rw"]),
+            "default_volume_mode": metadata.get("default_volume_mode")
+            or defaults.get("volume_mode")
+            or "ro",
+            "default_target_path": metadata.get("default_target_path")
+            or defaults.get("target_path"),
+            "has_custom_docker": bool(info.has_docker),
+        })
+    return {"workflows": workflows_summary, "prefect": get_prefect_status()}
+
+
+@mcp.tool
+async def get_workflow_metadata_mcp(workflow_name: str) -> Dict[str, Any]:
+    """Fetch detailed metadata for a workflow."""
+    not_ready = _prefect_not_ready_status()
+    if not_ready:
+        return {
+            "error": "Prefect infrastructure not ready",
+            "prefect": not_ready,
+        }
+
+    data = _lookup_workflow(workflow_name)
+    if not data:
+        return {"error": f"Workflow not found: {workflow_name}"}
+    return data
+
+
+@mcp.tool
+async def get_workflow_parameters_mcp(workflow_name: str) -> Dict[str, Any]:
+    """Return the parameter schema and defaults for a workflow."""
+    not_ready = _prefect_not_ready_status()
+    if not_ready:
+        return {
+            "error": "Prefect infrastructure not ready",
+            "prefect": not_ready,
+        }
+
+    data = _lookup_workflow(workflow_name)
+    if not data:
+        return {"error": f"Workflow not found: {workflow_name}"}
+    return {
+        "parameters": data.get("parameters", {}),
+        "defaults": data.get("default_parameters", {}),
+    }
+
+
+@mcp.tool
+async def get_workflow_metadata_schema_mcp() -> Dict[str, Any]:
+    """Return the JSON schema describing workflow metadata files."""
+    return WorkflowDiscovery.get_metadata_schema()
+
+
+@mcp.tool
+async def submit_security_scan_mcp(
+    workflow_name: str,
+    target_path: str | None = None,
+    volume_mode: str | None = None,
+    parameters: Dict[str, Any] | None = None,
+) -> Dict[str, Any] | Dict[str, str]:
+    """Submit a Prefect workflow via MCP."""
+    try:
+        not_ready = _prefect_not_ready_status()
+        if not_ready:
+            return {
+                "error": "Prefect infrastructure not ready",
+                "prefect": not_ready,
+            }
+
+        workflow_info = prefect_mgr.workflows.get(workflow_name)
+        if not workflow_info:
+            return {"error": f"Workflow '{workflow_name}' not found"}
+
+        metadata = workflow_info.metadata or {}
+        defaults = metadata.get("default_parameters", {})
+
+        resolved_target_path = target_path or metadata.get("default_target_path") or defaults.get("target_path")
+        if not resolved_target_path:
+            return {
+                "error": (
+                    "target_path is required and no default_target_path is defined in metadata"
+                ),
+                "metadata": {
+                    "workflow": workflow_name,
+                    "default_target_path": metadata.get("default_target_path"),
+                },
+            }
+
+        requested_volume_mode = volume_mode or metadata.get("default_volume_mode") or defaults.get("volume_mode")
+        if not requested_volume_mode:
+            requested_volume_mode = "ro"
+
+        normalised_volume_mode = (
+            str(requested_volume_mode).strip().lower().replace("-", "_")
+        )
+        if normalised_volume_mode in {"read_only", "readonly", "ro"}:
+            normalised_volume_mode = "ro"
+        elif normalised_volume_mode in {"read_write", "readwrite", "rw"}:
+            normalised_volume_mode = "rw"
+        else:
+            supported_modes = metadata.get("supported_volume_modes", ["ro", "rw"])
+            if isinstance(supported_modes, list) and normalised_volume_mode in supported_modes:
+                pass
+            else:
+                normalised_volume_mode = "ro"
+
+        parameters = parameters or {}
+
+        cleaned_parameters: Dict[str, Any] = {**defaults, **parameters}
+
+        # Ensure *_config structures default to dicts so Prefect validation passes.
+        for key, value in list(cleaned_parameters.items()):
+            if isinstance(key, str) and key.endswith("_config") and value is None:
+                cleaned_parameters[key] = {}
+
+        # Some workflows expect configuration dictionaries even when omitted.
+        parameter_definitions = (
+            metadata.get("parameters", {}).get("properties", {})
+            if isinstance(metadata.get("parameters"), dict)
+            else {}
+        )
+        for key, definition in parameter_definitions.items():
+            if not isinstance(key, str) or not key.endswith("_config"):
+                continue
+            if key not in cleaned_parameters:
+                default_value = definition.get("default") if isinstance(definition, dict) else None
+                cleaned_parameters[key] = default_value if default_value is not None else {}
+            elif cleaned_parameters[key] is None:
+                cleaned_parameters[key] = {}
+
+        flow_run = await prefect_mgr.submit_workflow(
+            workflow_name=workflow_name,
+            target_path=resolved_target_path,
+            volume_mode=normalised_volume_mode,
+            parameters=cleaned_parameters,
+        )
+
+        return {
+            "run_id": str(flow_run.id),
+            "status": flow_run.state.name if flow_run.state else "PENDING",
+            "workflow": workflow_name,
+            "message": f"Workflow '{workflow_name}' submitted successfully",
+            "target_path": resolved_target_path,
+            "volume_mode": normalised_volume_mode,
+            "parameters": cleaned_parameters,
+            "mcp_enabled": True,
+        }
+    except Exception as exc:  # pragma: no cover - defensive logging
+        logger.exception("MCP submit failed")
+        return {"error": f"Failed to submit workflow: {exc}"}
+
+
+@mcp.tool
+async def get_comprehensive_scan_summary(run_id: str) -> Dict[str, Any] | Dict[str, str]:
+    """Return a summary for the given flow run via MCP."""
+    try:
+        not_ready = _prefect_not_ready_status()
+        if not_ready:
+            return {
+                "error": "Prefect infrastructure not ready",
+                "prefect": not_ready,
+            }
+
+        status = await prefect_mgr.get_flow_run_status(run_id)
+        findings = await prefect_mgr.get_flow_run_findings(run_id)
+
+        workflow_name = "unknown"
+        deployment_id = status.get("workflow", "")
+        for name, deployment in prefect_mgr.deployments.items():
+            if str(deployment) == str(deployment_id):
+                workflow_name = name
+                break
+
+        total_findings = 0
+        severity_summary = {"critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0}
+
+        if findings and "sarif" in findings:
+            sarif = findings["sarif"]
+            if isinstance(sarif, dict):
+                total_findings = sarif.get("total_findings", 0)
+
+        return {
+            "run_id": run_id,
+            "workflow": workflow_name,
+            "status": status.get("status", "unknown"),
+            "is_completed": status.get("is_completed", False),
+            "total_findings": total_findings,
+            "severity_summary": severity_summary,
+            "scan_duration": status.get("updated_at", "")
+            if status.get("is_completed")
+            else "In progress",
+            "recommendations": (
+                [
+                    "Review high and critical severity findings first",
+                    "Implement security fixes based on finding recommendations",
+                    "Re-run scan after applying fixes to verify remediation",
+                ]
+                if total_findings > 0
+                else ["No security issues found"]
+            ),
+            "mcp_analysis": True,
+        }
+    except Exception as exc:  # pragma: no cover
+        logger.exception("MCP summary failed")
+        return {"error": f"Failed to summarize run: {exc}"}
+
+
+@mcp.tool
+async def get_run_status_mcp(run_id: str) -> Dict[str, Any]:
+    """Return current status information for a Prefect run."""
+    try:
+        not_ready = _prefect_not_ready_status()
+        if not_ready:
+            return {
+                "error": "Prefect infrastructure not ready",
+                "prefect": not_ready,
+            }
+
+        status = await prefect_mgr.get_flow_run_status(run_id)
+        workflow_name = "unknown"
+        deployment_id = status.get("workflow", "")
+        for name, deployment in prefect_mgr.deployments.items():
+            if str(deployment) == str(deployment_id):
+                workflow_name = name
+                break
+
+        return {
+            "run_id": status["run_id"],
+            "workflow": workflow_name,
+            "status": status["status"],
+            "is_completed": status["is_completed"],
+            "is_failed": status["is_failed"],
+            "is_running": status["is_running"],
+            "created_at": status["created_at"],
+            "updated_at": status["updated_at"],
+        }
+    except Exception as exc:
+        logger.exception("MCP run status failed")
+        return {"error": f"Failed to get run status: {exc}"}
+
+
+@mcp.tool
+async def get_run_findings_mcp(run_id: str) -> Dict[str, Any]:
+    """Return SARIF findings for a completed run."""
+    try:
+        not_ready = _prefect_not_ready_status()
+        if not_ready:
+            return {
+                "error": "Prefect infrastructure not ready",
+                "prefect": not_ready,
+            }
+
+        status = await prefect_mgr.get_flow_run_status(run_id)
+        if not status.get("is_completed"):
+            return {"error": f"Run {run_id} not completed. Status: {status.get('status')}"}
+
+        findings = await prefect_mgr.get_flow_run_findings(run_id)
+
+        workflow_name = "unknown"
+        deployment_id = status.get("workflow", "")
+        for name, deployment in prefect_mgr.deployments.items():
+            if str(deployment) == str(deployment_id):
+                workflow_name = name
+                break
+
+        metadata = {
+            "completion_time": status.get("updated_at"),
+            "workflow_version": "unknown",
+        }
+        info = prefect_mgr.workflows.get(workflow_name)
+        if info:
+            metadata["workflow_version"] = info.metadata.get("version", "unknown")
+
+        return {
+            "workflow": workflow_name,
+            "run_id": run_id,
+            "sarif": findings,
+            "metadata": metadata,
+        }
+    except Exception as exc:
+        logger.exception("MCP findings failed")
+        return {"error": f"Failed to retrieve findings: {exc}"}
+
+
+@mcp.tool
+async def list_recent_runs_mcp(
+    limit: int = 10,
+    workflow_name: str | None = None,
+    states: List[str] | None = None,
+) -> Dict[str, Any]:
+    """List recent Prefect runs with optional workflow/state filters."""
+
+    not_ready = _prefect_not_ready_status()
+    if not_ready:
+        return {
+            "runs": [],
+            "prefect": not_ready,
+            "message": "Prefect infrastructure is still initializing",
+        }
+
+    try:
+        limit_value = int(limit)
+    except (TypeError, ValueError):
+        limit_value = 10
+    limit_value = max(1, min(limit_value, 100))
+
+    deployment_map = {
+        str(deployment_id): workflow
+        for workflow, deployment_id in prefect_mgr.deployments.items()
+    }
+
+    deployment_filter_value = None
+    if workflow_name:
+        deployment_id = prefect_mgr.deployments.get(workflow_name)
+        if not deployment_id:
+            return {
+                "runs": [],
+                "prefect": get_prefect_status(),
+                "error": f"Workflow '{workflow_name}' has no registered deployment",
+            }
+        try:
+            deployment_filter_value = UUID(str(deployment_id))
+        except ValueError:
+            return {
+                "runs": [],
+                "prefect": get_prefect_status(),
+                "error": (
+                    f"Deployment id '{deployment_id}' for workflow '{workflow_name}' is invalid"
+                ),
+            }
+
+    desired_state_types: List[StateType] = []
+    if states:
+        for raw_state in states:
+            if not raw_state:
+                continue
+            normalised = raw_state.strip().upper()
+            if normalised == "ALL":
+                desired_state_types = []
+                break
+            try:
+                desired_state_types.append(StateType[normalised])
+            except KeyError:
+                continue
+    if not desired_state_types:
+        desired_state_types = [
+            StateType.RUNNING,
+            StateType.COMPLETED,
+            StateType.FAILED,
+            StateType.CANCELLED,
+        ]
+
+    flow_filter = FlowRunFilter()
+    if desired_state_types:
+        flow_filter.state = FlowRunFilterState(
+            type=FlowRunFilterStateType(any_=desired_state_types)
+        )
+    if deployment_filter_value:
+        flow_filter.deployment_id = FlowRunFilterDeploymentId(
+            any_=[deployment_filter_value]
+        )
+
+    async with get_client() as client:
+        flow_runs = await client.read_flow_runs(
+            limit=limit_value,
+            flow_run_filter=flow_filter,
+            sort=FlowRunSort.START_TIME_DESC,
+        )
+
+    results: List[Dict[str, Any]] = []
+    for flow_run in flow_runs:
+        deployment_id = getattr(flow_run, "deployment_id", None)
+        workflow = deployment_map.get(str(deployment_id), "unknown")
+        state = getattr(flow_run, "state", None)
+        state_name = getattr(state, "name", None) if state else None
+        state_type = getattr(state, "type", None) if state else None
+
+        results.append(
+            {
+                "run_id": str(flow_run.id),
+                "workflow": workflow,
+                "deployment_id": str(deployment_id) if deployment_id else None,
+                "state": state_name or (state_type.name if state_type else None),
+                "state_type": state_type.name if state_type else None,
+                "is_completed": bool(getattr(state, "is_completed", lambda: False)()),
+                "is_running": bool(getattr(state, "is_running", lambda: False)()),
+                "is_failed": bool(getattr(state, "is_failed", lambda: False)()),
+                "created_at": getattr(flow_run, "created", None),
+                "updated_at": getattr(flow_run, "updated", None),
+                "expected_start_time": getattr(flow_run, "expected_start_time", None),
+                "start_time": getattr(flow_run, "start_time", None),
+            }
+        )
+
+    # Normalise datetimes to ISO 8601 strings for serialization
+    for entry in results:
+        for key in ("created_at", "updated_at", "expected_start_time", "start_time"):
+            value = entry.get(key)
+            if value is None:
+                continue
+            try:
+                entry[key] = value.isoformat()
+            except AttributeError:
+                entry[key] = str(value)
+
+    return {"runs": results, "prefect": get_prefect_status()}
+
+
+@mcp.tool
+async def get_fuzzing_stats_mcp(run_id: str) -> Dict[str, Any]:
+    """Return fuzzing statistics for a run if available."""
+    not_ready = _prefect_not_ready_status()
+    if not_ready:
+        return {
+            "error": "Prefect infrastructure not ready",
+            "prefect": not_ready,
+        }
+
+    stats = fuzzing.fuzzing_stats.get(run_id)
+    if not stats:
+        return {"error": f"Fuzzing run not found: {run_id}"}
+    # Be resilient if a plain dict slipped into the cache
+    if isinstance(stats, dict):
+        return stats
+    if hasattr(stats, "model_dump"):
+        return stats.model_dump()
+    if hasattr(stats, "dict"):
+        return stats.dict()
+    # Last resort
+    return getattr(stats, "__dict__", {"run_id": run_id})
+
+
+@mcp.tool
+async def get_fuzzing_crash_reports_mcp(run_id: str) -> Dict[str, Any]:
+    """Return crash reports collected for a fuzzing run."""
+    not_ready = _prefect_not_ready_status()
+    if not_ready:
+        return {
+            "error": "Prefect infrastructure not ready",
+            "prefect": not_ready,
+        }
+
+    reports = fuzzing.crash_reports.get(run_id)
+    if reports is None:
+        return {"error": f"Fuzzing run not found: {run_id}"}
+    return {"run_id": run_id, "crashes": [report.model_dump() for report in reports]}
+
+
+@mcp.tool
+async def get_backend_status_mcp() -> Dict[str, Any]:
+    """Expose backend readiness, workflows, and registered MCP tools."""
+
+    status = get_prefect_status()
+    response: Dict[str, Any] = {"prefect": status}
+
+    if status.get("ready"):
+        response["workflows"] = list(prefect_mgr.workflows.keys())
+
+    try:
+        tools = await mcp._tool_manager.list_tools()
+        response["mcp_tools"] = sorted(tool.name for tool in tools)
+    except Exception as exc:  # pragma: no cover - defensive logging
+        logger.debug("Failed to enumerate MCP tools: %s", exc)
+
+    return response
+
+
+def create_mcp_transport_app() -> Starlette:
+    """Build a Starlette app serving HTTP + SSE transports on one port."""
+
+    http_app = mcp.http_app(path="/", transport="streamable-http")
+    sse_app = create_sse_app(
+        server=mcp,
+        message_path="/messages",
+        sse_path="/",
+        auth=mcp.auth,
+    )
+
+    routes = [
+        Mount("/mcp", app=http_app),
+        Mount("/mcp/sse", app=sse_app),
+    ]
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette):  # pragma: no cover - integration wiring
+        async with AsyncExitStack() as stack:
+            await stack.enter_async_context(
+                http_app.router.lifespan_context(http_app)
+            )
+            await stack.enter_async_context(
+                sse_app.router.lifespan_context(sse_app)
+            )
+            yield
+
+    combined_app = Starlette(routes=routes, lifespan=lifespan)
+    combined_app.state.fastmcp_server = mcp
+    combined_app.state.http_app = http_app
+    combined_app.state.sse_app = sse_app
+    return combined_app
+
+
+# ---------------------------------------------------------------------------
+# Combined lifespan: Prefect init + dedicated MCP transports
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def combined_lifespan(app: FastAPI):
+    global prefect_bootstrap_task, _fastapi_mcp_imported
+
+    logger.info("Starting FuzzForge backend...")
+
+    # Ensure FastAPI endpoints are exposed via MCP once
+    if not _fastapi_mcp_imported:
+        try:
+            await mcp.import_server(FASTAPI_MCP_ADAPTER)
+            _fastapi_mcp_imported = True
+            logger.info("Mounted FastAPI endpoints as MCP tools")
+        except Exception as exc:
+            logger.exception("Failed to import FastAPI endpoints into MCP", exc_info=exc)
+
+    # Kick off Prefect bootstrap in the background if needed
+    if prefect_bootstrap_task is None or prefect_bootstrap_task.done():
+        prefect_bootstrap_task = asyncio.create_task(_bootstrap_prefect_with_retries())
+        logger.info("Prefect bootstrap task started")
+    else:
+        logger.info("Prefect bootstrap task already running")
+
+    # Start MCP transports on shared port (HTTP + SSE)
+    mcp_app = create_mcp_transport_app()
+    mcp_config = uvicorn.Config(
+        app=mcp_app,
+        host="0.0.0.0",
+        port=8010,
+        log_level="info",
+        lifespan="on",
+    )
+    mcp_server = uvicorn.Server(mcp_config)
+    mcp_server.install_signal_handlers = lambda: None  # type: ignore[assignment]
+    mcp_task = asyncio.create_task(mcp_server.serve())
+
+    async def _wait_for_uvicorn_startup() -> None:
+        started_attr = getattr(mcp_server, "started", None)
+        if hasattr(started_attr, "wait"):
+            await asyncio.wait_for(started_attr.wait(), timeout=10)
+            return
+
+        # Fallback for uvicorn versions where "started" is a bool
+        poll_interval = 0.1
+        checks = int(10 / poll_interval)
+        for _ in range(checks):
+            if getattr(mcp_server, "started", False):
+                return
+            await asyncio.sleep(poll_interval)
+        raise asyncio.TimeoutError
+
+    try:
+        await _wait_for_uvicorn_startup()
+    except asyncio.TimeoutError:  # pragma: no cover - defensive logging
+        if mcp_task.done():
+            raise RuntimeError("MCP server failed to start") from mcp_task.exception()
+        logger.warning("Timed out waiting for MCP server startup; continuing anyway")
+
+    logger.info("MCP HTTP available at http://0.0.0.0:8010/mcp")
+    logger.info("MCP SSE available at http://0.0.0.0:8010/mcp/sse")
+
+    try:
+        yield
+    finally:
+        logger.info("Shutting down MCP transports...")
+        mcp_server.should_exit = True
+        mcp_server.force_exit = True
+        await asyncio.gather(mcp_task, return_exceptions=True)
+
+        if prefect_bootstrap_task and not prefect_bootstrap_task.done():
+            prefect_bootstrap_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await prefect_bootstrap_task
+        prefect_bootstrap_state.task_running = False
+        if not prefect_bootstrap_state.ready:
+            prefect_bootstrap_state.status = "stopped"
+            prefect_bootstrap_state.next_retry_seconds = None
+        prefect_bootstrap_task = None
+
+        logger.info("Shutting down Prefect statistics monitor...")
+        await prefect_stats_monitor.stop_monitoring()
+        logger.info("Shutting down FuzzForge backend...")
+
+
+app.router.lifespan_context = combined_lifespan

backend/src/models/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+

backend/src/models/findings.py

@@ -0,0 +1,182 @@
+"""
+Models for workflow findings and submissions
+"""
+
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+from pydantic import BaseModel, Field, field_validator
+from typing import Dict, Any, Optional, Literal, List
+from datetime import datetime
+from pathlib import Path
+
+
+class WorkflowFindings(BaseModel):
+    """Findings from a workflow execution in SARIF format"""
+    workflow: str = Field(..., description="Workflow name")
+    run_id: str = Field(..., description="Unique run identifier")
+    sarif: Dict[str, Any] = Field(..., description="SARIF formatted findings")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class ResourceLimits(BaseModel):
+    """Resource limits for workflow execution"""
+    cpu_limit: Optional[str] = Field(None, description="CPU limit (e.g., '2' for 2 cores, '500m' for 0.5 cores)")
+    memory_limit: Optional[str] = Field(None, description="Memory limit (e.g., '1Gi', '512Mi')")
+    cpu_request: Optional[str] = Field(None, description="CPU request (guaranteed)")
+    memory_request: Optional[str] = Field(None, description="Memory request (guaranteed)")
+
+
+class VolumeMount(BaseModel):
+    """Volume mount specification"""
+    host_path: str = Field(..., description="Host path to mount")
+    container_path: str = Field(..., description="Container path for mount")
+    mode: Literal["ro", "rw"] = Field(default="ro", description="Mount mode")
+
+    @field_validator("host_path")
+    @classmethod
+    def validate_host_path(cls, v):
+        """Validate that the host path is absolute (existence checked at runtime)"""
+        path = Path(v)
+        if not path.is_absolute():
+            raise ValueError(f"Host path must be absolute: {v}")
+        # Note: Path existence is validated at workflow runtime
+        # We can't validate existence here as this runs inside Docker container
+        return str(path)
+
+    @field_validator("container_path")
+    @classmethod
+    def validate_container_path(cls, v):
+        """Validate that the container path is absolute"""
+        if not v.startswith('/'):
+            raise ValueError(f"Container path must be absolute: {v}")
+        return v
+
+
+class WorkflowSubmission(BaseModel):
+    """Submit a workflow with configurable settings"""
+    target_path: str = Field(..., description="Absolute path to analyze")
+    volume_mode: Literal["ro", "rw"] = Field(
+        default="ro",
+        description="Volume mount mode: read-only (ro) or read-write (rw)"
+    )
+    parameters: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Workflow-specific parameters"
+    )
+    timeout: Optional[int] = Field(
+        default=None,  # Allow workflow-specific defaults
+        description="Timeout in seconds (None for workflow default)",
+        ge=1,
+        le=604800  # Max 7 days to support fuzzing campaigns
+    )
+    resource_limits: Optional[ResourceLimits] = Field(
+        None,
+        description="Resource limits for workflow container"
+    )
+    additional_volumes: List[VolumeMount] = Field(
+        default_factory=list,
+        description="Additional volume mounts (e.g., for corpus, output directories)"
+    )
+
+    @field_validator("target_path")
+    @classmethod
+    def validate_path(cls, v):
+        """Validate that the target path is absolute (existence checked at runtime)"""
+        path = Path(v)
+        if not path.is_absolute():
+            raise ValueError(f"Path must be absolute: {v}")
+        # Note: Path existence is validated at workflow runtime when volumes are mounted
+        # We can't validate existence here as this runs inside Docker container
+        return str(path)
+
+
+class WorkflowStatus(BaseModel):
+    """Status of a workflow run"""
+    run_id: str = Field(..., description="Unique run identifier")
+    workflow: str = Field(..., description="Workflow name")
+    status: str = Field(..., description="Current status")
+    is_completed: bool = Field(..., description="Whether the run is completed")
+    is_failed: bool = Field(..., description="Whether the run failed")
+    is_running: bool = Field(..., description="Whether the run is currently running")
+    created_at: datetime = Field(..., description="Run creation time")
+    updated_at: datetime = Field(..., description="Last update time")
+
+
+class WorkflowMetadata(BaseModel):
+    """Complete metadata for a workflow"""
+    name: str = Field(..., description="Workflow name")
+    version: str = Field(..., description="Semantic version")
+    description: str = Field(..., description="Workflow description")
+    author: Optional[str] = Field(None, description="Workflow author")
+    tags: List[str] = Field(default_factory=list, description="Workflow tags")
+    parameters: Dict[str, Any] = Field(..., description="Parameters schema")
+    default_parameters: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Default parameter values"
+    )
+    required_modules: List[str] = Field(
+        default_factory=list,
+        description="Required module names"
+    )
+    supported_volume_modes: List[Literal["ro", "rw"]] = Field(
+        default=["ro", "rw"],
+        description="Supported volume mount modes"
+    )
+    has_custom_docker: bool = Field(
+        default=False,
+        description="Whether workflow has custom Dockerfile"
+    )
+
+
+class WorkflowListItem(BaseModel):
+    """Summary information for a workflow in list views"""
+    name: str = Field(..., description="Workflow name")
+    version: str = Field(..., description="Semantic version")
+    description: str = Field(..., description="Workflow description")
+    author: Optional[str] = Field(None, description="Workflow author")
+    tags: List[str] = Field(default_factory=list, description="Workflow tags")
+
+
+class RunSubmissionResponse(BaseModel):
+    """Response after submitting a workflow"""
+    run_id: str = Field(..., description="Unique run identifier")
+    status: str = Field(..., description="Initial status")
+    workflow: str = Field(..., description="Workflow name")
+    message: str = Field(default="Workflow submitted successfully")
+
+
+class FuzzingStats(BaseModel):
+    """Real-time fuzzing statistics"""
+    run_id: str = Field(..., description="Unique run identifier")
+    workflow: str = Field(..., description="Workflow name")
+    executions: int = Field(default=0, description="Total executions")
+    executions_per_sec: float = Field(default=0.0, description="Current execution rate")
+    crashes: int = Field(default=0, description="Total crashes found")
+    unique_crashes: int = Field(default=0, description="Unique crashes")
+    coverage: Optional[float] = Field(None, description="Code coverage percentage")
+    corpus_size: int = Field(default=0, description="Current corpus size")
+    elapsed_time: int = Field(default=0, description="Elapsed time in seconds")
+    last_crash_time: Optional[datetime] = Field(None, description="Time of last crash")
+
+
+class CrashReport(BaseModel):
+    """Individual crash report from fuzzing"""
+    run_id: str = Field(..., description="Run identifier")
+    crash_id: str = Field(..., description="Unique crash identifier")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    signal: Optional[str] = Field(None, description="Crash signal (SIGSEGV, etc.)")
+    crash_type: Optional[str] = Field(None, description="Type of crash")
+    stack_trace: Optional[str] = Field(None, description="Stack trace")
+    input_file: Optional[str] = Field(None, description="Path to crashing input")
+    reproducer: Optional[str] = Field(None, description="Minimized reproducer")
+    severity: str = Field(default="medium", description="Crash severity")
+    exploitability: Optional[str] = Field(None, description="Exploitability assessment")

backend/src/services/prefect_stats_monitor.py

@@ -0,0 +1,394 @@
+"""
+Generic Prefect Statistics Monitor Service
+
+This service monitors ALL workflows for structured live data logging and
+updates the appropriate statistics APIs. Works with any workflow that follows
+the standard LIVE_STATS logging pattern.
+"""
+# Copyright (c) 2025 FuzzingLabs
+#
+# Licensed under the Business Source License 1.1 (BSL). See the LICENSE file
+# at the root of this repository for details.
+#
+# After the Change Date (four years from publication), this version of the
+# Licensed Work will be made available under the Apache License, Version 2.0.
+# See the LICENSE-APACHE file or http://www.apache.org/licenses/LICENSE-2.0
+#
+# Additional attribution and requirements are provided in the NOTICE file.
+
+
+import asyncio
+import json
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Dict, Any, Optional
+from prefect.client.orchestration import get_client
+from prefect.client.schemas.objects import FlowRun, TaskRun
+from src.models.findings import FuzzingStats
+from src.api.fuzzing import fuzzing_stats, initialize_fuzzing_tracking, active_connections
+
+logger = logging.getLogger(__name__)
+
+
+class PrefectStatsMonitor:
+    """Monitors Prefect flows and tasks for live statistics from any workflow"""
+
+    def __init__(self):
+        self.monitoring = False
+        self.monitor_task = None
+        self.monitored_runs = set()
+        self.last_log_ts: Dict[str, datetime] = {}
+        self._client = None
+        self._client_refresh_time = None
+        self._client_refresh_interval = 300  # Refresh connection every 5 minutes
+
+    async def start_monitoring(self):
+        """Start the Prefect statistics monitoring service"""
+        if self.monitoring:
+            logger.warning("Prefect stats monitor already running")
+            return
+
+        self.monitoring = True
+        self.monitor_task = asyncio.create_task(self._monitor_flows())
+        logger.info("Started Prefect statistics monitor")
+
+    async def stop_monitoring(self):
+        """Stop the monitoring service"""
+        self.monitoring = False
+        if self.monitor_task:
+            self.monitor_task.cancel()
+            try:
+                await self.monitor_task
+            except asyncio.CancelledError:
+                pass
+        logger.info("Stopped Prefect statistics monitor")
+
+    async def _get_or_refresh_client(self):
+        """Get or refresh Prefect client with connection pooling."""
+        now = datetime.now(timezone.utc)
+
+        if (self._client is None or
+            self._client_refresh_time is None or
+            (now - self._client_refresh_time).total_seconds() > self._client_refresh_interval):
+
+            if self._client:
+                try:
+                    await self._client.aclose()
+                except Exception:
+                    pass
+
+            self._client = get_client()
+            self._client_refresh_time = now
+            await self._client.__aenter__()
+
+        return self._client
+
+    async def _monitor_flows(self):
+        """Main monitoring loop that watches Prefect flows"""
+        try:
+            while self.monitoring:
+                try:
+                    # Use connection pooling for better performance
+                    client = await self._get_or_refresh_client()
+
+                    # Get recent flow runs (limit to reduce load)
+                    flow_runs = await client.read_flow_runs(
+                        limit=50,
+                        sort="START_TIME_DESC",
+                    )
+
+                    # Only consider runs from the last 15 minutes
+                    recent_cutoff = datetime.now(timezone.utc) - timedelta(minutes=15)
+                    for flow_run in flow_runs:
+                        created = getattr(flow_run, "created", None)
+                        if created is None:
+                            continue
+                        try:
+                            # Ensure timezone-aware comparison
+                            if created.tzinfo is None:
+                                created = created.replace(tzinfo=timezone.utc)
+                            if created >= recent_cutoff:
+                                await self._monitor_flow_run(client, flow_run)
+                        except Exception:
+                            # If comparison fails, attempt monitoring anyway
+                            await self._monitor_flow_run(client, flow_run)
+
+                    await asyncio.sleep(5)  # Check every 5 seconds
+
+                except Exception as e:
+                    logger.error(f"Error in Prefect monitoring: {e}")
+                    await asyncio.sleep(10)
+
+        except asyncio.CancelledError:
+            logger.info("Prefect monitoring cancelled")
+        except Exception as e:
+            logger.error(f"Fatal error in Prefect monitoring: {e}")
+        finally:
+            # Clean up client on exit
+            if self._client:
+                try:
+                    await self._client.__aexit__(None, None, None)
+                except Exception:
+                    pass
+                self._client = None
+
+    async def _monitor_flow_run(self, client, flow_run: FlowRun):
+        """Monitor a specific flow run for statistics"""
+        run_id = str(flow_run.id)
+        workflow_name = flow_run.name or "unknown"
+
+        try:
+            # Initialize tracking if not exists - only for workflows that might have live stats
+            if run_id not in fuzzing_stats:
+                initialize_fuzzing_tracking(run_id, workflow_name)
+                self.monitored_runs.add(run_id)
+
+            # Skip corrupted entries (should not happen after startup cleanup, but defensive)
+            elif not isinstance(fuzzing_stats[run_id], FuzzingStats):
+                logger.warning(f"Skipping corrupted stats entry for {run_id}, reinitializing")
+                initialize_fuzzing_tracking(run_id, workflow_name)
+                self.monitored_runs.add(run_id)
+
+            # Get task runs for this flow
+            task_runs = await client.read_task_runs(
+                flow_run_filter={"id": {"any_": [flow_run.id]}},
+                limit=25,
+            )
+
+            # Check all tasks for live statistics logging
+            for task_run in task_runs:
+                await self._extract_stats_from_task(client, run_id, task_run, workflow_name)
+
+            # Also scan flow-level logs as a fallback
+            await self._extract_stats_from_flow_logs(client, run_id, flow_run, workflow_name)
+
+        except Exception as e:
+            logger.warning(f"Error monitoring flow run {run_id}: {e}")
+
+    async def _extract_stats_from_task(self, client, run_id: str, task_run: TaskRun, workflow_name: str):
+        """Extract statistics from any task that logs live stats"""
+        try:
+            # Get task run logs
+            logs = await client.read_logs(
+                log_filter={
+                    "task_run_id": {"any_": [task_run.id]}
+                },
+                limit=100,
+                sort="TIMESTAMP_ASC"
+            )
+
+            # Parse logs for LIVE_STATS entries (generic pattern for any workflow)
+            latest_stats = None
+            for log in logs:
+                # Prefer structured extra field if present
+                extra_data = getattr(log, "extra", None) or getattr(log, "extra_fields", None) or None
+                if isinstance(extra_data, dict):
+                    stat_type = extra_data.get("stats_type")
+                    if stat_type in ["fuzzing_live_update", "scan_progress", "analysis_update", "live_stats"]:
+                        latest_stats = extra_data
+                        continue
+
+                # Fallback to parsing from message text
+                if ("FUZZ_STATS" in log.message or "LIVE_STATS" in log.message):
+                    stats = self._parse_stats_from_log(log.message)
+                    if stats:
+                        latest_stats = stats
+
+            # Update statistics if we found any
+            if latest_stats:
+                # Calculate elapsed time from task start
+                elapsed_time = 0
+                if task_run.start_time:
+                    # Ensure timezone-aware arithmetic
+                    now = datetime.now(timezone.utc)
+                    try:
+                        elapsed_time = int((now - task_run.start_time).total_seconds())
+                    except Exception:
+                        # Fallback to naive UTC if types mismatch
+                        elapsed_time = int((datetime.utcnow() - task_run.start_time.replace(tzinfo=None)).total_seconds())
+
+                updated_stats = FuzzingStats(
+                    run_id=run_id,
+                    workflow=workflow_name,
+                    executions=latest_stats.get("executions", 0),
+                    executions_per_sec=latest_stats.get("executions_per_sec", 0.0),
+                    crashes=latest_stats.get("crashes", 0),
+                    unique_crashes=latest_stats.get("unique_crashes", 0),
+                    corpus_size=latest_stats.get("corpus_size", 0),
+                    elapsed_time=elapsed_time
+                )
+
+                # Update the global stats
+                previous = fuzzing_stats.get(run_id)
+                fuzzing_stats[run_id] = updated_stats
+
+                # Broadcast to any active WebSocket clients for this run
+                if active_connections.get(run_id):
+                    # Handle both Pydantic objects and plain dicts
+                    if isinstance(updated_stats, dict):
+                        stats_data = updated_stats
+                    elif hasattr(updated_stats, 'model_dump'):
+                        stats_data = updated_stats.model_dump()
+                    elif hasattr(updated_stats, 'dict'):
+                        stats_data = updated_stats.dict()
+                    else:
+                        stats_data = updated_stats.__dict__
+
+                    message = {
+                        "type": "stats_update",
+                        "data": stats_data,
+                    }
+                    disconnected = []
+                    for ws in active_connections[run_id]:
+                        try:
+                            await ws.send_text(json.dumps(message))
+                        except Exception:
+                            disconnected.append(ws)
+                    # Clean up disconnected sockets
+                    for ws in disconnected:
+                        try:
+                            active_connections[run_id].remove(ws)
+                        except ValueError:
+                            pass
+
+                logger.debug(f"Updated Prefect stats for {run_id}: {updated_stats.executions} execs")
+
+        except Exception as e:
+            logger.warning(f"Error extracting stats from task {task_run.id}: {e}")
+
+    async def _extract_stats_from_flow_logs(self, client, run_id: str, flow_run: FlowRun, workflow_name: str):
+        """Extract statistics by scanning flow-level logs for LIVE/FUZZ stats"""
+        try:
+            logs = await client.read_logs(
+                log_filter={
+                    "flow_run_id": {"any_": [flow_run.id]}
+                },
+                limit=200,
+                sort="TIMESTAMP_ASC"
+            )
+
+            latest_stats = None
+            last_seen = self.last_log_ts.get(run_id)
+            max_ts = last_seen
+
+            for log in logs:
+                # Skip logs we've already processed
+                ts = getattr(log, "timestamp", None)
+                if last_seen and ts and ts <= last_seen:
+                    continue
+                if ts and (max_ts is None or ts > max_ts):
+                    max_ts = ts
+
+                # Prefer structured extra field if available
+                extra_data = getattr(log, "extra", None) or getattr(log, "extra_fields", None) or None
+                if isinstance(extra_data, dict):
+                    stat_type = extra_data.get("stats_type")
+                    if stat_type in ["fuzzing_live_update", "scan_progress", "analysis_update", "live_stats"]:
+                        latest_stats = extra_data
+                        continue
+
+                # Fallback to message parse
+                if ("FUZZ_STATS" in log.message or "LIVE_STATS" in log.message):
+                    stats = self._parse_stats_from_log(log.message)
+                    if stats:
+                        latest_stats = stats
+
+            if max_ts:
+                self.last_log_ts[run_id] = max_ts
+
+            if latest_stats:
+                # Use flow_run timestamps for elapsed time if available
+                elapsed_time = 0
+                start_time = getattr(flow_run, "start_time", None) or getattr(flow_run, "start_time", None)
+                if start_time:
+                    now = datetime.now(timezone.utc)
+                    try:
+                        if start_time.tzinfo is None:
+                            start_time = start_time.replace(tzinfo=timezone.utc)
+                        elapsed_time = int((now - start_time).total_seconds())
+                    except Exception:
+                        elapsed_time = int((datetime.utcnow() - start_time.replace(tzinfo=None)).total_seconds())
+
+                updated_stats = FuzzingStats(
+                    run_id=run_id,
+                    workflow=workflow_name,
+                    executions=latest_stats.get("executions", 0),
+                    executions_per_sec=latest_stats.get("executions_per_sec", 0.0),
+                    crashes=latest_stats.get("crashes", 0),
+                    unique_crashes=latest_stats.get("unique_crashes", 0),
+                    corpus_size=latest_stats.get("corpus_size", 0),
+                    elapsed_time=elapsed_time
+                )
+
+                fuzzing_stats[run_id] = updated_stats
+
+                # Broadcast if listeners exist
+                if active_connections.get(run_id):
+                    # Handle both Pydantic objects and plain dicts
+                    if isinstance(updated_stats, dict):
+                        stats_data = updated_stats
+                    elif hasattr(updated_stats, 'model_dump'):
+                        stats_data = updated_stats.model_dump()
+                    elif hasattr(updated_stats, 'dict'):
+                        stats_data = updated_stats.dict()
+                    else:
+                        stats_data = updated_stats.__dict__
+
+                    message = {
+                        "type": "stats_update",
+                        "data": stats_data,
+                    }
+                    disconnected = []
+                    for ws in active_connections[run_id]:
+                        try:
+                            await ws.send_text(json.dumps(message))
+                        except Exception:
+                            disconnected.append(ws)
+                    for ws in disconnected:
+                        try:
+                            active_connections[run_id].remove(ws)
+                        except ValueError:
+                            pass
+
+        except Exception as e:
+            logger.warning(f"Error extracting stats from flow logs {run_id}: {e}")
+
+    def _parse_stats_from_log(self, log_message: str) -> Optional[Dict[str, Any]]:
+        """Parse statistics from a log message"""
+        try:
+            import re
+
+            # Prefer explicit JSON after marker tokens
+            m = re.search(r'(?:FUZZ_STATS|LIVE_STATS)\s+(\{.*\})', log_message)
+            if m:
+                try:
+                    return json.loads(m.group(1))
+                except Exception:
+                    pass
+
+            # Fallback: Extract the extra= dict and coerce to JSON
+            stats_match = re.search(r'extra=({.*?})', log_message)
+            if not stats_match:
+                return None
+
+            extra_str = stats_match.group(1)
+            extra_str = extra_str.replace("'", '"')
+            extra_str = extra_str.replace('None', 'null')
+            extra_str = extra_str.replace('True', 'true')
+            extra_str = extra_str.replace('False', 'false')
+
+            stats_data = json.loads(extra_str)
+
+            # Support multiple stat types for different workflows
+            stat_type = stats_data.get("stats_type")
+            if stat_type in ["fuzzing_live_update", "scan_progress", "analysis_update", "live_stats"]:
+                return stats_data
+
+        except Exception as e:
+            logger.debug(f"Error parsing log stats: {e}")
+
+        return None
+
+
+# Global instance
+prefect_stats_monitor = PrefectStatsMonitor()