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

> Monitor pentest progress effectively using Shannon's Temporal Web UI query mechanism. Access real-time workflow state via the Temporal Web UI and CLI for better insights.

- Repository: [KeygraphHQ/shannon](https://github.com/keygraphhq/shannon)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/shared.ts), Shannon defines the `PipelineState` interface that serves as the source of truth for progress tracking:

```typescript
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`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/workflows.ts), Shannon registers the `getProgress` query handler using Temporal's `setHandler` API:

```typescript
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`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/client.ts)), the CLI prints a direct link to the Temporal Web UI:

```typescript
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`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/query.ts) that connects to the Temporal server and invokes the progress query:

```bash

# 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:

```typescript
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`](https://github.com/KeygraphHQ/shannon/blob/main/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`](https://github.com/KeygraphHQ/shannon/blob/main/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.