How to Debug Worker Logs and Query Workflow Execution Status in Shannon

Use ./shannon logs ID=<workflow-id> to tail real-time worker output and ./shannon query ID=<workflow-id> to inspect execution status via the Temporal getProgress query.

Shannon, an open-source AI-driven penetration testing framework from KeygraphHQ/shannon, orchestrates every pentest as a Temporal workflow. Understanding how to debug worker logs and query workflow execution status is essential for monitoring long-running security assessments, diagnosing agent failures, and verifying pipeline progress without interrupting active operations.

Understanding Shannon's Logging Architecture

Shannon's observability layer splits output between persistent audit files and ephemeral worker console streams, both managed by the Node.js services defined in src/temporal/worker.ts.

The Unified Workflow Log

Every workflow writes a canonical log file to audit-logs/<workflow-id>/workflow.log. The WorkflowLogger class in src/audit/workflow-logger.ts initializes this file during the first activity execution, writing structured headers via generateWorkflowLogPath and initialize methods. Throughout the pentest, phase transitions (logPhase) and agent completions (logAgent) append human-readable entries:

[2026-02-16 12:34:56] [PHASE] Starting: recon
[2026-02-16 12:35:02] [AGENT] vuln-xss: Completed (1m 20s $0.03)

Worker Console Output

The worker process itself—bootstrapped in src/temporal/worker.ts via NativeConnection.connect—emits diagnostic messages to stdout/stderr. These streams capture Temporal connection events, workflow bundling status, and runtime errors before they reach the unified log. The CLI wrapper (shannon) forwards these streams to the Docker Compose environment, making them accessible via container inspection.

How to Debug Worker Logs in Shannon

Shannon provides three primary methods for debugging worker logs, ranging from real-time monitoring to low-level container inspection.

Real-Time Log Monitoring

The recommended approach for debugging active workflows uses the CLI wrapper to tail the unified log:

./shannon logs ID=<workflow-id>

This command auto-detects the log path by searching ./audit-logs and any custom OUTPUT directory, then executes tail -f on workflow.log. The implementation resides in the shannon script (lines 33–71), providing live updates as agents complete phases or encounter errors.

Inspecting Worker Console Output

For connection-level debugging or worker boot failures, inspect the worker container directly:

docker compose logs -f worker

This captures output from src/temporal/worker.ts before it reaches the unified audit log, revealing Temporal server connectivity issues or workflow bundling errors.

Accessing Logs via Docker

When the CLI wrapper is unavailable, access logs directly through the worker container:

docker compose exec -T worker \
  tail -f ./audit-logs/<workflow-id>/workflow.log

This bypasses the host filesystem mounting and reads directly from the container's working directory, useful in containerized CI/CD environments.

Querying Workflow Execution Status

Shannon exposes workflow state through Temporal's query system, implemented in src/temporal/query.ts, allowing programmatic inspection of pipeline progress without interrupting execution.

Using the getProgress Query

The getProgress query, registered in src/temporal/workflows.ts, returns a PipelineProgress object containing real-time execution metadata. The query handler in src/temporal/query.ts constructs this object by aggregating state from the running workflow, enabling external tools to poll for status.

CLI Command Reference

Execute the query through the CLI wrapper:

./shannon query ID=<workflow-id>

This command runs the query via Docker exec:

docker compose exec -T worker \
  node dist/temporal/query.js <workflow-id>

The wrapper handles workflow ID validation and formats the output for terminal readability.

Interpreting PipelineProgress Results

The query returns a structured status object with the following fields:

• status: running, completed, or failed
• currentPhase: The active pentest phase (e.g., recon, exploit)
• currentAgent: The AI agent currently executing
• completedAgents: Array of finished agents with timing data
• failedAgent / error: Detailed failure information if the workflow encountered errors
• agentMetrics: Token usage, execution duration, and estimated cost per agent

This data enables precise debugging of stalled workflows or cost analysis of completed pentests.

Summary

• Shannon runs pentests as Temporal workflows with logs centralized in audit-logs/<workflow-id>/workflow.log via src/audit/workflow-logger.ts.
• Use ./shannon logs ID=<workflow-id> to tail real-time worker output and phase transitions.
• Query execution status programmatically via ./shannon query ID=<workflow-id>, which invokes the getProgress Temporal query defined in src/temporal/query.ts.
• For low-level debugging, inspect the worker container directly with docker compose logs or access logs via docker compose exec.
• The Temporal Web UI at http://localhost:8233 provides a graphical interface for workflow history and task queue inspection.

Frequently Asked Questions

Where are Shannon workflow logs stored?

Shannon stores workflow logs in audit-logs/<workflow-id>/workflow.log relative to the project root. The WorkflowLogger class in src/audit/workflow-logger.ts generates this path via generateWorkflowLogPath and initializes the file during the first workflow activity. You can access these logs via the ./shannon logs CLI command or directly through Docker.

How do I check if a Shannon workflow is still running?

Use the ./shannon query ID=<workflow-id> command to check execution status. This invokes the getProgress query implemented in src/temporal/query.ts, which returns a PipelineProgress object with a status field indicating running, completed, or failed. Alternatively, visit the Temporal Web UI at http://localhost:8233 to view active workflow executions graphically.

What information does the getProgress query return?

The getProgress query returns a comprehensive PipelineProgress object containing: status (workflow state), currentPhase (active pentest phase), currentAgent (running AI agent), completedAgents (finished agents with timing), failedAgent and error (failure details), and agentMetrics (token usage, duration, cost). This data enables precise monitoring of AI-driven pentest progress without interrupting execution.

Can I debug Shannon worker issues without the CLI wrapper?

Yes, you can debug workers directly using Docker commands. Run docker compose logs -f worker to view the worker console output from src/temporal/worker.ts, which captures Temporal connection events and bundling status. For log inspection, execute docker compose exec -T worker tail -f ./audit-logs/<workflow-id>/workflow.log. You can also attach to the worker container with docker compose exec -T worker bash for interactive debugging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}