How to Monitor Pentest Progress Using Shannon's Temporal Web UI Query Mechanism

Shannon exposes real-time pentest progress through a Temporal query handler that snapshots the workflow's mutable PipelineState, accessible via both the Temporal Web UI and CLI.

Shannon orchestrates penetration-testing runs as Temporal workflows, maintaining an internal state that tracks every phase from reconnaissance to vulnerability exploitation. By registering a dedicated query handler within the workflow, Shannon enables external monitoring tools—including the Temporal Web UI—to fetch live progress snapshots without interrupting the active pentest.

Understanding Shannon's Progress Tracking Architecture

Shannon's monitoring capability rests on a mutable state object that lives inside the Temporal workflow execution. This state evolves as agents complete their tasks, and a registered query handler exposes it to external consumers.

The Mutable PipelineState Interface

In src/temporal/shared.ts, Shannon defines the PipelineState interface that serves as the source of truth for progress tracking:

export interface PipelineState {
  status: 'running' | 'completed' | 'failed';
  currentPhase: string | null;
  currentAgent: string | null;
  completedAgents: string[];
  startTime: number;
  // ... additional per-agent metrics
}

The workflow mutates this state after each activity execution, recording which agents have finished, which is currently active, and how long the pipeline has been running.

Query Handler Registration

Within src/temporal/workflows.ts, Shannon registers the getProgress query handler using Temporal's setHandler API:

setHandler(getProgress, (): PipelineProgress => ({
  ...state,
  workflowId,
  elapsedMs: Date.now() - state.startTime,
}));

This handler returns a computed PipelineProgress object that includes the raw state plus derived fields like elapsedMs. Because queries execute against the workflow's event history, they return consistent snapshots even while activities are actively running.

Querying Progress via the Temporal Web UI

The Temporal Web UI provides a graphical interface for monitoring Shannon workflows without writing code.

Accessing the Web UI URL

When you start a pentest using Shannon's client (src/temporal/client.ts), the CLI prints a direct link to the Temporal Web UI:

console.log(
  chalk.white('  Web UI:  ') +
  chalk.blue(`http://localhost:8233/namespaces/default/workflows/${workflowId}`)
);

Opening this URL in your browser loads the workflow detail page for the specific pentest run.

Running the getProgress Query

Once inside the Temporal Web UI:

1. Navigate to the Queries tab on the workflow detail page.
2. Select getProgress from the available query handlers.
3. Click Run Query.

The UI displays the JSON response containing status, currentPhase, currentAgent, completedAgents, and elapsedMs. Because the query reads from the workflow's in-memory state, you can refresh repeatedly to watch the pentest advance through phases in real time.

Monitoring from the Command Line

For automation and scripting, Shannon provides both a dedicated CLI tool and programmatic access to the query mechanism.

Using the Built-in Query CLI

Shannon includes a query utility in src/temporal/query.ts that connects to the Temporal server and invokes the progress query:

# Query a specific workflow by ID

./shannon query ID=shannon-1704672000000

This command outputs a formatted progress report:

Workflow Progress
────────────────────────────────────────
Workflow ID: shannon-1704672000000
Status: running
Current Phase: vulnerability-exploitation
Current Agent: pipelines
Elapsed: 3m 12s
Completed: 5/13 agents

Completed agents:
  - pre-recon (1m 5s, $0.0123) [claude-2]
  - recon (45s, $0.0087) [claude-2]

Programmatic Query with Node.js

You can also fetch progress from your own Node.js applications using the Temporal client SDK:

import { Connection, Client } from '@temporalio/client';
import { getProgress } from './src/temporal/shared';

async function fetchProgress(workflowId: string) {
  const connection = await Connection.connect({ address: 'localhost:7233' });
  const client = new Client({ connection });
  const handle = client.workflow.getHandle(workflowId);
  
  const progress = await handle.query(getProgress);
  console.log('Current phase:', progress.currentPhase);
  console.log('Elapsed time:', progress.elapsedMs, 'ms');
  
  await connection.close();
}

fetchProgress('shannon-1704672000000');

This approach is useful for building custom dashboards or integrating Shannon progress data into existing security platforms.

Summary

• Shannon tracks pentest progress through a mutable PipelineState object maintained inside each Temporal workflow.
• The getProgress query handler in src/temporal/workflows.ts exposes this state as a read-only snapshot, including derived metrics like elapsedMs.
• Monitor via Temporal Web UI by visiting the URL printed at startup (http://localhost:8233/...) and running the getProgress query from the Queries tab.
• Monitor via CLI using ./shannon query ID=<workflowId> or programmatically using the Temporal client SDK to call handle.query(getProgress).

Frequently Asked Questions

How does Shannon ensure query results reflect the latest pentest state?

Shannon's workflow mutates the PipelineState object after each agent completes its task. Because Temporal queries execute against the workflow's in-memory state and event history, the getProgress handler returns a consistent snapshot that includes all mutations committed up to the moment of the query.

Can I query progress while the pentest is actively running?

Yes. Temporal queries are read-only operations that do not block workflow execution. You can invoke getProgress repeatedly via the Web UI or CLI while agents are executing, and the workflow will continue processing activities without interruption.

What information does the progress query return?

The query returns a PipelineProgress object containing: status (running/completed/failed), currentPhase (e.g., "vulnerability-exploitation"), currentAgent (active agent name), completedAgents (array of finished agents with duration and cost), elapsedMs (total runtime), and the workflowId.

Where is the Temporal Web UI URL displayed when starting a pentest?

When you execute ./shannon start, the client code in src/temporal/client.ts prints the Web UI URL to the console. The URL follows the pattern http://localhost:8233/namespaces/default/workflows/${workflowId}, allowing you to click directly into the workflow's monitoring page.

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