Add wiki page: API-Reference
@@ -0,0 +1,336 @@
|
|||||||
|
# API Reference
|
||||||
|
|
||||||
|
All endpoints are prefixed with `/api/v1/`. Authentication via cookie `aegis_token` or
|
||||||
|
`Authorization: Bearer <token>`. Role abbreviations: A=admin, RL=red_lead, BL=blue_lead,
|
||||||
|
RT=red_tech, BT=blue_tech, V=viewer, Any=all authenticated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Auth — /api/v1/auth
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| POST | /auth/login | Public | Login with username+password (form-encoded). Sets `aegis_token` cookie. |
|
||||||
|
| POST | /auth/logout | Any | Revokes token (adds jti to Redis blacklist). Clears cookie. |
|
||||||
|
| GET | /auth/me | Any | Returns current user profile + role. |
|
||||||
|
| POST | /auth/change-password | Any | Change own password. Required if `must_change_password=true`. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Users — /api/v1/users
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /users | A | List all users (paginated). |
|
||||||
|
| POST | /users | A | Create a new user. Sets `must_change_password=true`. |
|
||||||
|
| GET | /users/{id} | A | Get user by ID. |
|
||||||
|
| PATCH | /users/{id} | A | Update user (role, is_active, display_name, etc.). |
|
||||||
|
| DELETE | /users/{id} | A | Deactivate (soft-delete) a user. |
|
||||||
|
| GET | /users/me | Any | Get own profile. |
|
||||||
|
| PATCH | /users/me/preferences | Any | Update own UI preferences (theme, notifications, etc.). |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Techniques — /api/v1/techniques
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /techniques | Any | List techniques. Query: tactic_id, platform, coverage_status, search. |
|
||||||
|
| GET | /techniques/{mitre_id} | Any | Get technique by MITRE ID (e.g. T1059.001). |
|
||||||
|
| POST | /techniques | A | Create a custom technique (non-MITRE). |
|
||||||
|
| PATCH | /techniques/{mitre_id} | A | Update technique metadata. |
|
||||||
|
| PATCH | /techniques/{mitre_id}/review | RL,BL,A | Mark technique as needing review. |
|
||||||
|
| GET | /techniques/{mitre_id}/d3fend | Any | D3FEND countermeasure mappings for this technique. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tests — /api/v1/tests
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /tests | Any | List tests. Filters: state, technique_id, campaign_id, assigned_to. |
|
||||||
|
| POST | /tests | RL,BL,A | Create a new test in draft state. |
|
||||||
|
| POST | /tests/from-template | RL,BL,A | Create test(s) from a saved template. |
|
||||||
|
| GET | /tests/{id} | Any | Get full test detail including all fields. |
|
||||||
|
| PATCH | /tests/{id} | RL,BL,A | Update general fields (title, objective, technique, etc.). Draft/rejected only. |
|
||||||
|
| PATCH | /tests/{id}/classification | A | Set data_classification (confidential, restricted, etc.). |
|
||||||
|
| PATCH | /tests/{id}/red | RL,RT,A | Update red-side fields. State: red_executing. |
|
||||||
|
| PATCH | /tests/{id}/blue | BL,BT,A | Update blue-side fields. State: blue_evaluating. |
|
||||||
|
| POST | /tests/{id}/start-execution | RL,RT,A | Transition draft → red_executing. |
|
||||||
|
| POST | /tests/{id}/submit-red | RL,RT,A | Transition red_executing → blue_evaluating. |
|
||||||
|
| POST | /tests/{id}/submit-blue | BL,BT,A | Transition blue_evaluating → in_review. |
|
||||||
|
| POST | /tests/{id}/validate-red | RL,A | Approve/reject red side. State: in_review. |
|
||||||
|
| POST | /tests/{id}/validate-blue | BL,A | Approve/reject blue side. State: in_review. |
|
||||||
|
| POST | /tests/{id}/reopen | RL,BL,A | Transition rejected → draft. |
|
||||||
|
| POST | /tests/{id}/pause-timer | All except V | Pause elapsed time counter. |
|
||||||
|
| POST | /tests/{id}/resume-timer | All except V | Resume elapsed time counter. |
|
||||||
|
| PATCH | /tests/{id}/remediation | RL,BL,A | Update remediation status/notes (any state post-review). |
|
||||||
|
| GET | /tests/{id}/timeline | Any | Full audit trail of state changes and actions. |
|
||||||
|
| GET | /tests/{id}/retest-chain | Any | All tests in this retest lineage. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Evidence — /api/v1/tests/{id}/evidence & /api/v1/evidence
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| POST | /tests/{id}/evidence | Role-dependent* | Upload evidence file. team=red or team=blue. |
|
||||||
|
| GET | /tests/{id}/evidence | Any | List all evidence files for a test. |
|
||||||
|
| GET | /evidence/{id} | Any | Get evidence metadata. |
|
||||||
|
| GET | /evidence/{id}/download | Any | Download evidence file from MinIO (signed URL or stream). |
|
||||||
|
| DELETE | /evidence/{id} | Own or RL,BL,A | Delete evidence file. |
|
||||||
|
|
||||||
|
*red evidence: RL, RT, A | blue evidence: BL, BT, A. State restrictions apply (see [Test-Lifecycle](Test-Lifecycle)).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Campaigns — /api/v1/campaigns
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /campaigns | Any | List campaigns. Filters: status, type, date range. |
|
||||||
|
| POST | /campaigns | RL,BL,A | Create a new campaign. |
|
||||||
|
| GET | /campaigns/{id} | Any | Get campaign detail. |
|
||||||
|
| PATCH | /campaigns/{id} | RL,BL,A | Update campaign metadata. |
|
||||||
|
| POST | /campaigns/{id}/tests | RL,BL,A | Add a test to a campaign. |
|
||||||
|
| DELETE | /campaigns/{id}/tests/{ctid} | RL,BL,A | Remove a test from a campaign. |
|
||||||
|
| POST | /campaigns/{id}/activate | RL,BL,A | Transition draft → active. |
|
||||||
|
| POST | /campaigns/{id}/complete | RL,A | Transition active → completed. |
|
||||||
|
| GET | /campaigns/{id}/progress | Any | Count validated/total tests in campaign. |
|
||||||
|
| POST | /campaigns/from-threat-actor/{actor_id} | RL,BL,A | Auto-create campaign + tests from threat actor profile. |
|
||||||
|
| PATCH | /campaigns/{id}/schedule | RL,BL,A | Set start_date / end_date. |
|
||||||
|
| GET | /campaigns/{id}/history | Any | Campaign state change history. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Attack Paths — /api/v1/attack-paths
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /attack-paths | Any | List attack paths. |
|
||||||
|
| POST | /attack-paths | All except V | Create an attack path (sequence of techniques). |
|
||||||
|
| GET | /attack-paths/{id} | Any | Get attack path detail. |
|
||||||
|
| PATCH | /attack-paths/{id} | All except V | Update attack path metadata. |
|
||||||
|
| DELETE | /attack-paths/{id} | RL,BL,A | Delete attack path. |
|
||||||
|
| POST | /attack-paths/{id}/steps | All except V | Add a step (technique) to attack path. |
|
||||||
|
| DELETE | /attack-paths/{id}/steps/{sid} | All except V | Remove a step. |
|
||||||
|
| POST | /attack-paths/{id}/executions | All except V | Start an execution of the attack path. |
|
||||||
|
| POST | /executions/{id}/start | All except V | Begin execution. |
|
||||||
|
| POST | /executions/{id}/steps/{sid} | All except V | Record step outcome. |
|
||||||
|
| POST | /executions/{id}/complete | All except V | Mark execution complete. |
|
||||||
|
| POST | /executions/{id}/abort | RL,BL,A | Abort execution. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Knowledge — /api/v1/knowledge
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /knowledge/playbooks | Any | List playbooks. Filter by technique, type. |
|
||||||
|
| POST | /knowledge/playbooks | RL,BL,A | Create a playbook. |
|
||||||
|
| GET | /knowledge/playbooks/{id} | Any | Get playbook + versions list. |
|
||||||
|
| PATCH | /knowledge/playbooks/{id} | RL,BL,A | Update playbook (creates version snapshot). |
|
||||||
|
| DELETE | /knowledge/playbooks/{id} | RL,BL,A | Delete playbook. |
|
||||||
|
| GET | /knowledge/playbooks/{id}/versions | Any | List all versions of a playbook. |
|
||||||
|
| POST | /knowledge/playbooks/{id}/restore/{version} | RL,BL,A | Restore a previous version. |
|
||||||
|
| GET | /knowledge/lessons | Any | List lessons learned. Filter by severity, technique. |
|
||||||
|
| POST | /knowledge/lessons | RL,BL,A | Create a lesson learned. |
|
||||||
|
| GET | /knowledge/lessons/{id} | Any | Get lesson detail. |
|
||||||
|
| PATCH | /knowledge/lessons/{id} | RL,BL,A | Update lesson. |
|
||||||
|
| DELETE | /knowledge/lessons/{id} | RL,BL,A | Delete lesson. |
|
||||||
|
| GET | /knowledge/stats | Any | Summary: playbooks by type, lessons by severity. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ownership — /api/v1/ownership
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /ownership/assignments | Any | Technique-to-owner assignments. |
|
||||||
|
| POST | /ownership/assignments | RL,BL,A | Assign technique ownership. |
|
||||||
|
| PATCH | /ownership/assignments/{id} | RL,BL,A | Update assignment. |
|
||||||
|
| DELETE | /ownership/assignments/{id} | RL,BL,A | Remove assignment. |
|
||||||
|
| GET | /ownership/assets | Any | Asset ownership list. |
|
||||||
|
| POST | /ownership/assets | BL,A | Create asset ownership record. |
|
||||||
|
| GET | /ownership/revalidation-queue | BL,A | Techniques requiring revalidation. |
|
||||||
|
| POST | /ownership/revalidation-queue/generate | BL,A | Generate revalidation queue from infrastructure changes. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Risk — /api/v1/risk
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| POST | /risk/compute | RL,BL,A | Trigger risk recomputation. |
|
||||||
|
| GET | /risk/profiles | Any | Risk profile per technique. |
|
||||||
|
| GET | /risk/matrix | Any | Risk matrix (impact × coverage). |
|
||||||
|
| GET | /risk/summary | Any | Aggregate risk numbers. |
|
||||||
|
| GET | /risk/recommendations | Any | Prioritized list of techniques to test next. |
|
||||||
|
| GET | /risk/top | Any | Top N highest-risk uncovered techniques. ?limit=N |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Alerts — /api/v1/alerts
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| POST | /alerts/evaluate | RL,BL,A | Manually trigger evaluation of all enabled rules. |
|
||||||
|
| GET | /alerts/summary | Any | Alert counts by status, severity, rule type. |
|
||||||
|
| GET | /alerts | Any | List alert instances. Filters: status, severity, rule_type. |
|
||||||
|
| GET | /alerts/{id} | Any | Get alert instance detail. |
|
||||||
|
| POST | /alerts/{id}/acknowledge | RL,BL,A | Acknowledge an alert. |
|
||||||
|
| POST | /alerts/{id}/resolve | RL,BL,A | Resolve an alert. |
|
||||||
|
| POST | /alerts/{id}/dismiss | RL,BL,A | Dismiss an alert. |
|
||||||
|
| GET | /alerts/rules | Any | List alert rules. |
|
||||||
|
| POST | /alerts/rules | RL,BL,A | Create an alert rule. |
|
||||||
|
| GET | /alerts/rules/{id} | Any | Get rule detail. |
|
||||||
|
| PATCH | /alerts/rules/{id} | RL,BL,A | Update rule. |
|
||||||
|
| DELETE | /alerts/rules/{id} | A | Delete rule. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dashboard — /api/v1/dashboard
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /dashboard/kpis | Any | Key metrics: total techniques, covered %, tests, campaigns. |
|
||||||
|
| GET | /dashboard/executive | Any | Narrative executive summary. |
|
||||||
|
| GET | /dashboard/coverage-by-tactic | Any | Coverage breakdown per tactic. |
|
||||||
|
| GET | /dashboard/posture-history | Any | Historical coverage trend data. |
|
||||||
|
| GET | /dashboard/activity | Any | Recent activity feed (tests, campaigns, validations). |
|
||||||
|
| POST | /dashboard/posture-snapshot | RL,BL,A | Create an immediate posture snapshot. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Snapshots — /api/v1/snapshots
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /snapshots | Any | List snapshots (paginated). |
|
||||||
|
| POST | /snapshots | RL,BL,A | Create a manual snapshot. |
|
||||||
|
| GET | /snapshots/{id} | Any | Get snapshot detail. |
|
||||||
|
| DELETE | /snapshots/{id} | A | Delete a snapshot. |
|
||||||
|
| GET | /snapshots/evolution | Any | Trend data: coverage over time. |
|
||||||
|
| GET | /snapshots/compare | Any | Diff two snapshots. Query: ?a=<id>&b=<id> |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reports — /api/v1/reports
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /reports/coverage-summary | Any | Coverage data as JSON. |
|
||||||
|
| GET | /reports/coverage-csv | Any | Coverage data as CSV download. |
|
||||||
|
| GET | /reports/test-results | Any | Test results data as JSON. |
|
||||||
|
| GET | /reports/remediation-status | Any | Remediation tracking data. |
|
||||||
|
| GET | /reports/generate/purple-campaign/{id} | RL,BL,A,V | Full campaign report. ?format=pdf|docx|html |
|
||||||
|
| GET | /reports/generate/coverage-summary | RL,BL,A,V | Coverage status report. |
|
||||||
|
| GET | /reports/generate/executive-summary | RL,BL,A,V | Executive briefing document. |
|
||||||
|
| GET | /reports/generate/quarterly-summary | RL,BL,A,V | Quarterly review report. |
|
||||||
|
| GET | /reports/generate/technique/{id} | RL,BL,A,V | Per-technique detail report. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Detection Lifecycle — /api/v1/detection-lifecycle
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /detection-lifecycle/assets | Any | List detection assets. |
|
||||||
|
| POST | /detection-lifecycle/assets | BL,A | Create a detection asset. |
|
||||||
|
| GET | /detection-lifecycle/assets/{id} | Any | Get asset detail. |
|
||||||
|
| PATCH | /detection-lifecycle/assets/{id} | BL,A | Update asset. |
|
||||||
|
| DELETE | /detection-lifecycle/assets/{id} | BL,A | Delete asset. |
|
||||||
|
| POST | /detection-lifecycle/assets/{id}/techniques/{tid} | BL,A | Link asset to technique. |
|
||||||
|
| DELETE | /detection-lifecycle/assets/{id}/techniques/{tid} | BL,A | Unlink asset from technique. |
|
||||||
|
| GET | /detection-lifecycle/validations | Any | List detection validations. |
|
||||||
|
| POST | /detection-lifecycle/validations | BL,A | Create a validation record. |
|
||||||
|
| POST | /detection-lifecycle/validations/{id}/invalidate | BL,A | Invalidate (revoke) a validation. |
|
||||||
|
| GET | /detection-lifecycle/infrastructure-changes | Any | List infrastructure change records. |
|
||||||
|
| POST | /detection-lifecycle/infrastructure-changes | BL,A | Record an infrastructure change. |
|
||||||
|
| GET | /detection-lifecycle/dashboard | Any | Detection confidence per technique. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Detection Rules — /api/v1/detection-rules
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /detection-rules | Any | List detection rules. |
|
||||||
|
| POST | /detection-rules | BL,A | Create detection rule. |
|
||||||
|
| GET | /detection-rules/{id} | Any | Get rule detail. |
|
||||||
|
| PATCH | /detection-rules/{id} | BL,A | Update rule. |
|
||||||
|
| DELETE | /detection-rules/{id} | BL,A | Delete rule. |
|
||||||
|
| POST | /detection-rules/evaluate | BL,BT,A | Record rule triggered/not-triggered for a test. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Test Templates — /api/v1/test-templates
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /test-templates | Any | List templates. |
|
||||||
|
| POST | /test-templates | RL,BL,A | Create template from existing test or from scratch. |
|
||||||
|
| GET | /test-templates/{id} | Any | Get template detail. |
|
||||||
|
| PATCH | /test-templates/{id} | RL,BL,A | Update template. |
|
||||||
|
| DELETE | /test-templates/{id} | RL,BL,A | Delete template. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Webhooks — /api/v1/webhooks (admin only)
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /webhooks | A | List configured webhooks. |
|
||||||
|
| POST | /webhooks | A | Create a webhook (URL, events, secret). |
|
||||||
|
| GET | /webhooks/{id} | A | Get webhook detail. |
|
||||||
|
| PATCH | /webhooks/{id} | A | Update webhook. |
|
||||||
|
| DELETE | /webhooks/{id} | A | Delete webhook. |
|
||||||
|
| POST | /webhooks/{id}/test | A | Send a test event to the webhook URL. |
|
||||||
|
|
||||||
|
Webhook events: `test.validated`, `test.state_changed`, `campaign.completed`,
|
||||||
|
`alert.fired`, `coverage.changed`.
|
||||||
|
|
||||||
|
SSRF protection: webhook URLs are validated against private IP ranges before saving.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Keys — /api/v1/api-keys
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /api-keys | Any | List own API keys. |
|
||||||
|
| POST | /api-keys | Any | Create a new API key. Scope: read/write/admin. |
|
||||||
|
| DELETE | /api-keys/{id} | Own or A | Revoke an API key. |
|
||||||
|
|
||||||
|
Keys are prefixed `aegis_` and passed as `Authorization: Bearer aegis_<hex>`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## SSO — /api/v1/sso
|
||||||
|
|
||||||
|
| Method | Path | Auth | Description |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| GET | /sso/status | Any | Whether SSO is configured and enabled. |
|
||||||
|
| PUT | /sso/config | A | Configure SAML 2.0 SSO settings. |
|
||||||
|
| GET | /sso/login | Public | Initiate SAML login redirect. |
|
||||||
|
| POST | /sso/callback | Public | SAML assertion callback. |
|
||||||
|
| GET | /sso/metadata | Public | Service provider metadata XML. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Other Modules
|
||||||
|
|
||||||
|
| Module | Path prefix | Auth | Notes |
|
||||||
|
|--------|-------------|------|-------|
|
||||||
|
| Notifications | /notifications | Any (own) | GET list, PATCH mark-read |
|
||||||
|
| Audit Logs | /audit-logs | A | GET with filters |
|
||||||
|
| Jira | /jira | RL,BL,A | sync, issues |
|
||||||
|
| Threat Actors | /threat-actors | Any GET, RL,BL,A manage | |
|
||||||
|
| Compliance | /compliance | Any | frameworks, controls, gaps |
|
||||||
|
| Analytics | /analytics | Any | trend analytics |
|
||||||
|
| Heatmap | /heatmap | Any | Coverage matrix |
|
||||||
|
| Scores | /scores | Any GET; A for config PATCH | |
|
||||||
|
| Worklogs | /worklogs | Any create; own or A to read | |
|
||||||
|
| OSINT | /osint | RL,BL,A | |
|
||||||
|
| Data Sources | /data-sources | Any GET; A manage | |
|
||||||
|
| System | /system | A (scheduler, sync); Public (health) | |
|
||||||
|
|||||||
Reference in New Issue
Block a user