From f39ac93068036526ab6a6847865d59785b9da39f Mon Sep 17 00:00:00 2001 From: kitos Date: Fri, 22 May 2026 12:32:59 +0000 Subject: [PATCH] Add wiki page: Test-Lifecycle --- Test-Lifecycle.-.md | 251 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) diff --git a/Test-Lifecycle.-.md b/Test-Lifecycle.-.md index e69de29..af0eea1 100644 --- a/Test-Lifecycle.-.md +++ b/Test-Lifecycle.-.md @@ -0,0 +1,251 @@ +# Test Lifecycle + +Every test in Aegis follows a structured state machine from creation to final validation. +This page documents every state, transition, actor, and field update rule. + +--- + +## State Diagram + +``` + ┌─────────┐ + │ draft │◄──────────────────────────┐ + └────┬────┘ │ + │ POST /start-execution │ + │ (red_tech, red_lead, admin) │ POST /reopen + ▼ │ (leads, admin) + ┌─────────────────┐ │ + │ red_executing │ │ + └────────┬────────┘ │ + │ POST /submit-red │ + │ (red_tech, red_lead, admin) │ + ▼ │ + ┌─────────────────────┐ │ + │ blue_evaluating │ │ + └────────┬────────────┘ │ + │ POST /submit-blue │ + │ (blue_tech, blue_lead, admin) │ + ▼ │ + ┌───────────┐ │ + │ in_review │ │ + └─────┬─────┘ │ + │ Both validate (approved) │ + │ │ + ┌──────────┴──────────┐ │ + │ Either rejects │ │ + ▼ ▼ │ + ┌──────────┐ ┌───────────┐ │ + │ rejected │─────────┤ validated │ │ + └──────────┘ └───────────┘ │ + │ │ + └───────────────────────────────────────────┘ +``` + +--- + +## States Reference + +### draft + +- **Description**: Initial state. Test has been defined but not yet executed. +- **Who creates**: red_lead, blue_lead, admin (POST /api/v1/tests) +- **Who can edit general fields**: red_lead, blue_lead, admin (PATCH /api/v1/tests/{id}) +- **Available actions**: + - Edit test metadata (title, description, technique_id, objective, target_environment, etc.) + - Add to campaigns + - Attach red evidence (even before execution, for pre-work files) +- **Cannot do**: upload blue evidence, start timer + +**Create payload example:** +```json +{ + "title": "T1059.001 PowerShell cradle download", + "technique_id": "T1059.001", + "objective": "Verify AMSI bypass detection", + "target_environment": "Windows 10 workstation", + "severity": "high", + "campaign_id": "optional-uuid" +} +``` + +--- + +### red_executing + +- **Description**: Red team is actively executing the attack. +- **Trigger**: POST /api/v1/tests/{id}/start-execution +- **Who can trigger**: red_tech, red_lead, admin +- **Timer starts** automatically when entering this state. +- **Who updates red fields**: red_tech, red_lead, admin (PATCH /api/v1/tests/{id}/red) + +**Red fields (PATCH /tests/{id}/red):** +```json +{ + "tool_used": "Cobalt Strike 4.8", + "command_executed": "powershell -nop -w hidden -enc ...", + "output_observed": "Beacon established on 10.0.0.5", + "red_notes": "Used staged payload to bypass AV", + "attacker_ip": "10.10.10.100", + "target_ip": "10.0.0.5", + "start_time": "2024-03-15T10:00:00Z", + "end_time": "2024-03-15T10:15:00Z" +} +``` + +**Evidence upload (team=red):** +```http +POST /api/v1/tests/{id}/evidence +Content-Type: multipart/form-data + +file= +team=red +description=PowerShell execution screenshot +``` + +--- + +### blue_evaluating + +- **Description**: Blue team is evaluating what they detected (or didn't). +- **Trigger**: POST /api/v1/tests/{id}/submit-red +- **Who can trigger**: red_tech, red_lead, admin +- **Who updates blue fields**: blue_tech, blue_lead, admin (PATCH /api/v1/tests/{id}/blue) + +**Blue fields (PATCH /tests/{id}/blue):** +```json +{ + "detection_result": "detected", + "detection_notes": "Windows Defender ATP alert fired: Suspicious PowerShell", + "alert_fired": true, + "alert_name": "ASR rule: Block Office apps from creating child processes", + "response_action": "Endpoint isolated automatically", + "time_to_detect_seconds": 47, + "blue_notes": "AMSI telemetry captured full script content" +} +``` + +`detection_result` values: +- `detected` — blue team observed the attack in time +- `not_detected` — attack was not detected +- `partial` — partial detection (some indicators observed but not full alert) + +**Evidence upload (team=blue):** +```http +POST /api/v1/tests/{id}/evidence +Content-Type: multipart/form-data + +file= +team=blue +description=SIEM alert screenshot +``` + +--- + +### in_review + +- **Description**: Both leads must independently validate their side. +- **Trigger**: POST /api/v1/tests/{id}/submit-blue +- **Who can trigger**: blue_tech, blue_lead, admin +- **No field updates allowed** while in review. +- **Evidence is locked** — no new evidence uploads. + +**Red validation (red_lead, admin):** +```http +POST /api/v1/tests/{id}/validate-red +{"red_validation_status": "approved", "red_validation_notes": "Execution was clean"} +``` + +**Blue validation (blue_lead, admin):** +```http +POST /api/v1/tests/{id}/validate-blue +{"blue_validation_status": "approved", "blue_validation_notes": "Detection confirmed"} +``` + +Both validations can be `approved` or `rejected`. + +--- + +### validated + +- **Description**: Both leads approved. Test is complete and results are official. +- **Trigger**: Both red_validation_status and blue_validation_status = `approved` +- **Effects**: + - Technique coverage status is recalculated + - Webhook events fired (if configured): `test.validated` + - Score may be updated + - Snapshot data refreshed +- **After validation**: Leads and admin can still edit the `remediation` fields: + ```http + PATCH /api/v1/tests/{id}/remediation + { + "remediation_status": "in_progress", + "remediation_notes": "SIEM rule deployed to block this technique", + "remediation_owner": "blue-lead-user-uuid" + } + ``` + +--- + +### rejected + +- **Description**: At least one lead rejected their side. +- **Trigger**: Either validate-red or validate-blue returns `rejected` +- **Recovery**: POST /api/v1/tests/{id}/reopen (leads, admin) sends back to `draft` + +--- + +## Evidence Rules Summary + +| State | Red evidence | Blue evidence | +|-------|-------------|---------------| +| draft | Upload allowed | Not allowed | +| red_executing | Upload allowed | Not allowed | +| blue_evaluating | Not allowed | Upload allowed | +| in_review | **Locked** | **Locked** | +| validated | **Locked** | **Locked** | +| rejected | **Locked** | **Locked** | + +--- + +## Timer + +The test timer measures elapsed execution time. + +| Action | Endpoint | Allowed roles | +|--------|----------|---------------| +| Pause timer | POST /tests/{id}/pause-timer | All except viewer | +| Resume timer | POST /tests/{id}/resume-timer | All except viewer | + +The timer automatically starts when entering `red_executing`. + +--- + +## Timeline and Audit Trail + +Every state change is recorded in the timeline: +```http +GET /api/v1/tests/{id}/timeline +``` + +Response includes entries for: +- State transitions (from_state, to_state, actor, timestamp) +- Validation actions (approved/rejected, actor, timestamp) +- Evidence uploads (team, filename, actor, timestamp) +- Timer pauses/resumes +- Worklog entries + +--- + +## Retest Chain + +When a test is a retest of a previous (failed) test, it is linked via `retest_of`: +```json +{"retest_of": "previous-test-uuid"} +``` + +Navigate the full chain: +```http +GET /api/v1/tests/{id}/retest-chain +``` + +Returns an ordered list of all tests in the chain, oldest first.