Skip to content

Add TIMEOUT (103) push-mode agent state to SRS/SDD #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sarroutbi merged 1 commit into from
Apr 19, 2026
Merged

Add TIMEOUT (103) push-mode agent state to SRS/SDD #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions spec/SDD-Keylime-Monitoring-Tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,7 @@ The `KeylimeClient` is wrapped in `Arc<RwLock<Arc<KeylimeClient>>>` 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

Expand Down Expand Up @@ -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)`
Expand All @@ -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 |

Expand Down
12 changes: 10 additions & 2 deletions spec/SRS-Keylime-Monitoring-Tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
Loading