Monitoring

Shannon provides multiple ways to monitor penetration test execution in real-time: workflow logs, Temporal Web UI, and direct queries.

Quick Monitoring Commands

# Tail workflow log (most common)
./shannon logs ID=example-com_shannon-1771007534808

# Tail with auto-discovery (for named workspaces)
./shannon logs ID=q1-audit

Workflow Logs

The primary way to monitor Shannon execution is through workflow logs.

Viewing Logs

Get Workspace ID

When you start Shannon, it outputs the workspace ID:

./shannon start URL=https://example.com REPO=repo-name

Output:

Workflow ID: example-com_shannon-1771007534808
Logs:        ./shannon logs ID=example-com_shannon-1771007534808

Tail Logs

./shannon logs ID=example-com_shannon-1771007534808

Logs stream in real-time as Shannon executes.

Log Format

Workflow logs are human-readable and show:

Timestamps - When each event occurred
Phase transitions - Moving between Pre-Recon, Recon, Analysis, etc.
Agent status - Starting, running, completed, failed
Tool usage - Browser actions, API calls, file operations
Errors - Failures, retries, timeouts

[2026-03-03 10:15:23] Starting workflow: example-com_shannon-1771007534808
[2026-03-03 10:15:23] Target URL: https://example.com
[2026-03-03 10:15:23] Repository: /repos/my-app
[2026-03-03 10:15:23] ========================================
[2026-03-03 10:15:23] Phase 1: Pre-Reconnaissance
[2026-03-03 10:15:23] ========================================
[2026-03-03 10:15:24] Agent: pre-recon (running)
[2026-03-03 10:15:24] 🔍 Scanning target with nmap...
[2026-03-03 10:15:45] ✅ Found 3 open ports: 80, 443, 22
[2026-03-03 10:16:12] 🌐 Browser: Navigating to https://example.com
[2026-03-03 10:16:18] 📜 Analyzing source code structure...
[2026-03-03 10:22:34] Agent: pre-recon (completed)
[2026-03-03 10:22:34] ========================================
[2026-03-03 10:22:34] Phase 2: Reconnaissance
[2026-03-03 10:22:34] ========================================
[2026-03-03 10:22:35] Agent: recon (running)

Log File Location

Workflow logs are saved to:

audit-logs/<workspace-id>/workflow.log

For custom output directories (using OUTPUT=), logs are saved to:

<output-path>/<workspace-id>/workflow.log

Auto-Discovery

The ./shannon logs command automatically finds log files:

Checks default location: ./audit-logs/<id>/workflow.log
Handles resume workflow IDs: workspace_resume_123
Searches custom output directories
Falls back to find for non-standard locations

Named Workspace
Auto-Named Workspace
Custom Output

# Start with named workspace
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit

# Tail logs (auto-discovers)
./shannon logs ID=q1-audit

# Start without name
./shannon start URL=https://example.com REPO=repo-name
# Workspace: example-com_shannon-1771007534808

# Tail logs with full ID
./shannon logs ID=example-com_shannon-1771007534808

# Start with custom output
./shannon start URL=https://example.com REPO=repo-name OUTPUT=./my-reports

# Logs still auto-discovered
./shannon logs ID=example-com_shannon-1771007534808

Temporal Web UI

Shannon uses Temporal for workflow orchestration. The Temporal Web UI provides detailed execution visibility.

Accessing the UI

Open in your browser:

http://localhost:8233

For WSL2 UsersIf running Shannon in WSL2, find your WSL IP address:

ip addr

Then navigate to http://<wsl-ip>:8233 from your Windows browser.

UI Features

Workflow List

View all running and completed workflows

Execution History

Timeline of all events and activities

Activity Details

Input/output for each agent execution

Error Inspection

Stack traces and failure details

Finding Your Workflow

Open Temporal UI

Navigate to http://localhost:8233

Select Namespace

Use the default namespace (auto-selected)

Search by Workflow ID

Enter your workspace ID in the search bar:

example-com_shannon-1771007534808

View Execution

Click the workflow to see:

Current status (Running, Completed, Failed)
Execution history timeline
Input parameters
Stack trace for errors

Key Views

History
Pending Activities
Stack Trace
Query

Timeline of all events:

Workflow started
Activity scheduled
Activity started
Activity completed
Activity failed
Workflow completed

Click any event to see input/output payloads.

Shows currently executing activities:

Activity name (e.g., executePipelineStep)
Start time
Duration so far
Heartbeat status

Run workflow queries:

getProgress - Current phase and agent status
Custom queries (if defined)

Workflow Queries

Shannon supports querying workflow state programmatically, but this is only available through the Temporal Web UI or custom code.

No CLI Query CommandShannon does not currently provide a ./shannon query command. To check workflow progress:

Use the Temporal Web UI at http://localhost:8233
Use ./shannon logs ID=<workflow-id> to view detailed logs
Use ./shannon workspaces to list all workspaces and their status

For developers who want to implement custom queries, Shannon exposes a PROGRESS_QUERY that returns:

{
  currentPhase: string;
  completedAgents: string[];
  currentAgent: string;
  status: string;
  startTime: string;
  duration: string;
}

See src/temporal/shared.ts for the query definition and src/temporal/workflows.ts for query handlers.

Workspace Listing

View all workspaces with status, duration, and cost:

./shannon workspaces

Output:

=== Shannon Workspaces ===

  WORKSPACE                      URL                            STATUS         DURATION   COST      
  ────────────────────────────────────────────────────────────────────────────────────────────────
  q1-audit                       https://example.com            in-progress    45m        $32.50    (resumable)
  example-com_shannon-17710...   https://example.com            failed         12m        $8.20     (resumable)
  prod-scan-2026                 https://prod.example.com       completed      1h 15m     $48.90    

3 workspaces found (2 resumable)

Resume with: ./shannon start URL=<url> REPO=<repo> WORKSPACE=<name>

Status Indicators

in-progress

Running

Workflow is currently executing

completed

Success

All agents finished successfully

failed

Error

Workflow encountered an error or was interrupted

Workspace Metadata

Each workspace directory contains session.json with execution metadata:

{
  "session": {
    "id": "example-com_shannon-1771007534808",
    "webUrl": "https://example.com",
    "status": "in-progress",
    "createdAt": "2026-03-03T10:15:23.000Z",
    "completedAt": null
  },
  "metrics": {
    "total_cost_usd": 32.50,
    "total_duration_ms": 2718000,
    "completed_agents": ["pre-recon", "recon"],
    "failed_agents": []
  }
}

Agent Logs

Individual agent execution logs are saved to:

audit-logs/<workspace-id>/agents/<agent-name>.log

These logs contain:

Detailed tool usage
LLM prompts and responses (excerpts)
Error details
Retry attempts

Viewing Agent Logs

tail -f audit-logs/q1-audit/agents/vuln-injection.log

Monitoring Best Practices

Keep Logs Running

Open ./shannon logs in a separate terminal window to monitor progress in real-time:

# Terminal 1: Start Shannon
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit

# Terminal 2: Watch logs
./shannon logs ID=my-audit

Check Temporal UI Periodically

Use the Temporal Web UI to:

Verify heartbeats are active (no stuck activities)
Check for retry patterns (may indicate issues)
Inspect failed activities for detailed errors

Save Logs for Analysis

Copy logs before running ./shannon stop CLEAN=true:

cp -r audit-logs/my-audit ./archived-audits/

Monitor Resource Usage

Shannon runs in Docker. Monitor container resources:

docker stats

Troubleshooting

Logs not found for workflow ID

Error:

ERROR: Workflow log not found for ID: my-audit

Causes:

Workflow hasn’t started yet (check Temporal UI)
Incorrect workspace ID (use ./shannon workspaces to list)
Custom output directory not searched (specify full path)

Solution: Verify workspace name with ./shannon workspaces or check Temporal UI.

Temporal UI not accessible

Issue: Can’t access http://localhost:8233Causes:

Containers not running
Port conflict on 8233
WSL2 networking (use WSL IP instead of localhost)

Solution:

# Check if containers are running
docker compose ps

# Ensure Temporal is up
./shannon start URL=https://example.com REPO=repo-name

# For WSL2, get IP
ip addr

Agent stuck (no log updates)

Issue: Logs stop updating, agent appears frozenCheck in Temporal UI:

Pending activities with long duration (>30min)
Heartbeat status (should be periodic)
Failed heartbeats (indicates stuck activity)

Solution:

Wait for timeout/retry (automatic)
Manual stop and resume if timeout is too long

./shannon stop
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit

High API costs

Issue: Costs increasing rapidlyCheck:

session.json for total_cost_usd
Agent logs for excessive retries
Temporal UI for failed activities

Solution:

Reduce max_concurrent_pipelines in config
Use smaller models (if overridden)
Stop and review before continuing

Monitoring Checklist

Before starting a production audit:

Verify Containers Running

docker compose ps
# Should show: temporal, worker (running)

Open Temporal UI

Ensure http://localhost:8233 is accessible

Start Log Tail

./shannon logs ID=<workspace-id>

Keep this terminal open throughout the run.

Bookmark Workspace

Save workspace ID for later reference:

echo "my-audit" > .current-workspace

Resume Workflow

Resume interrupted runs from checkpoints

Configuration

Adjust retry and concurrency settings

Get Started

Core Concepts

Guides

CLI Reference

Quick Monitoring Commands

Workflow Logs

Viewing Logs

Log Format

Log File Location

Auto-Discovery

Temporal Web UI

Accessing the UI

UI Features

Workflow List

Execution History

Activity Details

Error Inspection

Finding Your Workflow

Key Views

Workflow Queries

Workspace Listing

Status Indicators

Workspace Metadata

Agent Logs

Viewing Agent Logs

Monitoring Best Practices

Troubleshooting

Monitoring Checklist

Resume Workflow

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

​Quick Monitoring Commands

​Workflow Logs

​Viewing Logs

​Log Format

​Log File Location

​Auto-Discovery

​Temporal Web UI

​Accessing the UI

​UI Features

Workflow List

Execution History

Activity Details

Error Inspection

​Finding Your Workflow

​Key Views

​Workflow Queries

​Workspace Listing

​Status Indicators

​Workspace Metadata

​Agent Logs

​Viewing Agent Logs

​Monitoring Best Practices

​Troubleshooting

​Monitoring Checklist

​Related Resources

Resume Workflow

Configuration

Build docs developers (and LLMs) love

Quick Monitoring Commands

Workflow Logs

Viewing Logs

Log Format

Log File Location

Auto-Discovery

Temporal Web UI

Accessing the UI

UI Features

Finding Your Workflow

Key Views

Workflow Queries

Workspace Listing

Status Indicators

Workspace Metadata

Agent Logs

Viewing Agent Logs

Monitoring Best Practices

Troubleshooting

Monitoring Checklist

Related Resources