From 5225cc1c1126f392d1d3eda43203b618adb8ff77 Mon Sep 17 00:00:00 2001 From: Sergio Arroutbi Date: Sun, 19 Apr 2026 21:47:45 +0200 Subject: [PATCH] Add TIMEOUT (103) push-mode agent state to SRS/SDD Adds a fourth computed state for push-mode agents to distinguish agents that stopped responding (e.g., crash) from explicit attestation failures. Co-Authored-By: Claude Opus 4.6 Signed-off-by: Sergio Arroutbi --- spec/SDD-Keylime-Monitoring-Tool.md | 5 +++-- spec/SRS-Keylime-Monitoring-Tool.md | 12 ++++++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/spec/SDD-Keylime-Monitoring-Tool.md b/spec/SDD-Keylime-Monitoring-Tool.md index 83d98ee..f62b43b 100644 --- a/spec/SDD-Keylime-Monitoring-Tool.md +++ b/spec/SDD-Keylime-Monitoring-Tool.md @@ -331,6 +331,7 @@ The `KeylimeClient` is wrapped in `Arc>>` to support h | `Pass` | 100 | Attestation passing | | `Fail` | 101 | Attestation failing | | `Pending` | 102 | Awaiting first attestation | +| `Timeout` | 103 | Agent stopped responding (e.g., agent crash) | **Trace:** Implementation -- `keylime-webtool-backend/src/models/agent.rs`, SRS FR-069 @@ -856,7 +857,7 @@ The attestation timeline (FR-024) distributes event counts across hourly buckets 1. Count total successful and failed agents from Verifier state. * Pull-mode: `GET_QUOTE` = success; `FAILED`, `INVALID_QUOTE`, `TENANT_FAILED` = failure. - * Push-mode: `accept_attestations` flag determines pass/fail. + * Push-mode: `accept_attestations` flag determines pass/fail; absence of attestation submissions beyond the expected interval determines timeout. 2. Compute the number of hourly buckets from the requested time range. 3. Generate per-bucket weights: `weight(i) = (1 + 0.5 * sin(i * 0.9)) * jitter(i)` @@ -875,7 +876,7 @@ The frontend derives attestation KPIs from agent state data when no attestation | KPI | Computation | |-----|------------| | Total Agents | `paginated_response.total_items` or `agents.length` | -| Failed Attestations | Count of agents in `failed`, `invalid_quote`, `tenant_failed` (pull) or `fail` (push) state | +| Failed Attestations | Count of agents in `failed`, `invalid_quote`, `tenant_failed` (pull) or `fail`, `timeout` (push) state | | Success Rate | `((total - failed) / total) * 100` | | Active Alerts | From `GET /api/alerts/summary` -> `critical` count | diff --git a/spec/SRS-Keylime-Monitoring-Tool.md b/spec/SRS-Keylime-Monitoring-Tool.md index d8fc67b..7df9e85 100644 --- a/spec/SRS-Keylime-Monitoring-Tool.md +++ b/spec/SRS-Keylime-Monitoring-Tool.md @@ -2092,7 +2092,7 @@ Feature: Capacity Planning Projections ### FR-069: Agent State Machine Visualization -**Description:** The System MUST provide visual state machine diagrams for agent lifecycle states. Pull mode (v2 API) MUST display all 10 states: REGISTERED (0), START (1), SAVED (2), GET_QUOTE (3), RETRY (4), PROVIDE_V (5), FAILED (7), TERMINATED (8), INVALID_QUOTE (9), and TENANT_FAILED (10) with transition arrows. Push mode (v3 API) MUST display three computed states: PASS (100), FAIL (101), and PENDING (102), derived from the agent's attestation results. The push-mode verification flow follows 3 stages: capabilities submission, challenge/nonce response, and evidence evaluation. Failed states MUST be visually distinguished (e.g., red). The current state distribution across the fleet MUST be overlaid on the diagram. +**Description:** The System MUST provide visual state machine diagrams for agent lifecycle states. Pull mode (v2 API) MUST display all 10 states: REGISTERED (0), START (1), SAVED (2), GET_QUOTE (3), RETRY (4), PROVIDE_V (5), FAILED (7), TERMINATED (8), INVALID_QUOTE (9), and TENANT_FAILED (10) with transition arrows. Push mode (v3 API) MUST display four computed states: PASS (100), FAIL (101), PENDING (102), and TIMEOUT (103), derived from the agent's attestation results. TIMEOUT indicates an agent that has stopped submitting attestations (e.g., agent crash), distinguishing it from an explicit attestation FAIL. The push-mode verification flow follows 3 stages: capabilities submission, challenge/nonce response, and evidence evaluation. Failed and timed-out states MUST be visually distinguished (e.g., red). The current state distribution across the fleet MUST be overlaid on the diagram. **Trace:** Keylime - Agent State Machine; Attestation Modes - Push Mode @@ -2110,10 +2110,18 @@ Feature: Agent State Machine Visualization Scenario: Display push mode computed states Given the deployment includes push mode (v3 API) agents When the user views the push mode state visualization - Then three computed states MUST be displayed: PASS (100), FAIL (101), and PENDING (102) + Then four computed states MUST be displayed: PASS (100), FAIL (101), PENDING (102), and TIMEOUT (103) And each state MUST show the current count of agents in that state And the 3-stage verification flow (capabilities → challenge → evidence) MUST be shown alongside + Scenario: Agent enters TIMEOUT state when it stops responding + Given a push mode agent was previously in PASS state + And the agent has not submitted attestations beyond the expected interval + When the System detects the absence of attestation submissions + Then the agent state MUST transition to TIMEOUT (103) + And the TIMEOUT state MUST be visually distinguished (e.g., red) from PASS and PENDING + And the TIMEOUT state MUST be distinguishable from FAIL to indicate the agent stopped responding rather than failing attestation + Scenario: No agents in a specific state Given no agents are in FAILED state When the user views the Agent State Machine visualization