Add wiki page: Roles-and-Permissions
@@ -0,0 +1,222 @@
|
|||||||
|
# Roles and Permissions
|
||||||
|
|
||||||
|
Aegis uses Role-Based Access Control (RBAC) with six roles organized in a hierarchy.
|
||||||
|
Every authenticated request carries the user's role, which is checked against the
|
||||||
|
required role for each endpoint.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Role Hierarchy
|
||||||
|
|
||||||
|
```
|
||||||
|
admin
|
||||||
|
└─ red_lead / blue_lead
|
||||||
|
└─ red_tech / blue_tech
|
||||||
|
└─ viewer
|
||||||
|
```
|
||||||
|
|
||||||
|
Higher roles generally include the capabilities of lower roles, with some
|
||||||
|
team-specific restrictions (e.g. a `red_lead` cannot perform `blue_lead` actions).
|
||||||
|
|
||||||
|
> **Admin bypass**: `admin` ALWAYS passes any role check, regardless of which role
|
||||||
|
> is required. There is no endpoint an admin cannot call.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Role Descriptions
|
||||||
|
|
||||||
|
### admin
|
||||||
|
|
||||||
|
**Primary use case**: Platform administrator. Full system access.
|
||||||
|
|
||||||
|
**Can do:**
|
||||||
|
- Everything any other role can do
|
||||||
|
- Create, update, deactivate, and delete users
|
||||||
|
- View audit logs (`GET /api/v1/audit-logs`)
|
||||||
|
- Delete snapshots (`DELETE /api/v1/snapshots/{id}`)
|
||||||
|
- Delete alert rules
|
||||||
|
- Trigger MITRE ATT&CK sync (`POST /api/v1/system/sync-mitre`)
|
||||||
|
- Manage webhooks (`GET/POST/PATCH/DELETE /api/v1/webhooks`) — **admin only**
|
||||||
|
- Set data classification on tests (`PATCH /api/v1/tests/{id}/classification`)
|
||||||
|
- View scheduler status (`GET /api/v1/system/scheduler-status`)
|
||||||
|
- Configure SSO (`PUT /api/v1/sso/config`)
|
||||||
|
- Manage data sources (`POST/PATCH/DELETE /api/v1/data-sources`)
|
||||||
|
- Complete campaigns (along with red_lead)
|
||||||
|
|
||||||
|
**Cannot do:**
|
||||||
|
- Be locked out — bypasses all role checks by design
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### red_lead
|
||||||
|
|
||||||
|
**Primary use case**: Red Team Lead. Manages the offensive side of operations.
|
||||||
|
|
||||||
|
**Can do:**
|
||||||
|
- Create, update, and delete tests (in `draft` or `rejected` state)
|
||||||
|
- Create campaigns and complete them (`POST /campaigns/{id}/complete`)
|
||||||
|
- Create test templates
|
||||||
|
- Create and manage playbooks and lessons
|
||||||
|
- Validate the red side of a test (`POST /tests/{id}/validate-red`)
|
||||||
|
- Manage attack paths (including delete)
|
||||||
|
- Create alert rules
|
||||||
|
- Generate professional reports (PDF, DOCX, HTML)
|
||||||
|
- Start test execution
|
||||||
|
- Upload red evidence
|
||||||
|
- Submit red assessment
|
||||||
|
- All viewer capabilities
|
||||||
|
|
||||||
|
**Cannot do:**
|
||||||
|
- Access audit logs
|
||||||
|
- Perform blue-side actions (validate-blue, submit-blue, update blue fields)
|
||||||
|
- Delete snapshots
|
||||||
|
- Sync MITRE data
|
||||||
|
- Access or manage webhooks
|
||||||
|
- Set data classification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### blue_lead
|
||||||
|
|
||||||
|
**Primary use case**: Blue Team Lead. Manages the defensive side of operations.
|
||||||
|
|
||||||
|
**Can do:**
|
||||||
|
- Evaluate and validate the blue side of a test (`POST /tests/{id}/validate-blue`)
|
||||||
|
- Validate blue side (`POST /tests/{id}/validate-blue`)
|
||||||
|
- Manage detection assets and detection rules
|
||||||
|
- Create playbooks and lessons
|
||||||
|
- Generate a revalidation queue
|
||||||
|
- Manage ownership of assets
|
||||||
|
- Create alert rules
|
||||||
|
- Generate professional reports (PDF, DOCX, HTML)
|
||||||
|
- Upload blue evidence (in `blue_evaluating` state)
|
||||||
|
- Submit blue assessment
|
||||||
|
- All viewer capabilities
|
||||||
|
|
||||||
|
**Cannot do:**
|
||||||
|
- Complete campaigns (red_lead + admin only)
|
||||||
|
- Start test execution (`POST /tests/{id}/start-execution`)
|
||||||
|
- Validate the red side
|
||||||
|
- Access audit logs
|
||||||
|
- Delete snapshots
|
||||||
|
- Sync MITRE data
|
||||||
|
- Access or manage webhooks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### red_tech
|
||||||
|
|
||||||
|
**Primary use case**: Red Team Technician. Executes attacks.
|
||||||
|
|
||||||
|
**Can do:**
|
||||||
|
- Start test execution (`POST /tests/{id}/start-execution`) — moves `draft` → `red_executing`
|
||||||
|
- Update red-side fields (`PATCH /tests/{id}/red`): `tool_used`, `command_executed`, `output_observed`, `red_notes`, etc.
|
||||||
|
- Upload red evidence files
|
||||||
|
- Submit red assessment (`POST /tests/{id}/submit-red`) — moves `red_executing` → `blue_evaluating`
|
||||||
|
- Pause and resume test timers
|
||||||
|
- Create worklogs for tests
|
||||||
|
- View all read-only data (same as viewer)
|
||||||
|
|
||||||
|
**Cannot do:**
|
||||||
|
- Create new tests
|
||||||
|
- Create campaigns
|
||||||
|
- Manage playbooks or lessons
|
||||||
|
- Access webhooks, audit logs, or admin endpoints
|
||||||
|
- Perform blue-side actions
|
||||||
|
- Validate either side
|
||||||
|
- Generate professional reports
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### blue_tech
|
||||||
|
|
||||||
|
**Primary use case**: Blue Team Technician. Evaluates detection.
|
||||||
|
|
||||||
|
**Can do:**
|
||||||
|
- Update blue-side fields (`PATCH /tests/{id}/blue`): `detection_result` (detected/not_detected/partial), `detection_notes`, `alert_fired`, `response_action`, etc.
|
||||||
|
- Upload blue evidence files (only while test is in `blue_evaluating` state)
|
||||||
|
- Submit blue assessment (`POST /tests/{id}/submit-blue`) — moves `blue_evaluating` → `in_review`
|
||||||
|
- Evaluate detection rules (`POST /api/v1/detection-rules/evaluate`)
|
||||||
|
- Create detection validations
|
||||||
|
- Pause and resume test timers
|
||||||
|
- Create worklogs for tests
|
||||||
|
- View all read-only data (same as viewer)
|
||||||
|
|
||||||
|
**Cannot do:**
|
||||||
|
- Start test execution
|
||||||
|
- Submit red assessment
|
||||||
|
- Validate either side
|
||||||
|
- Create tests, campaigns, playbooks, or lessons
|
||||||
|
- Access webhooks, audit logs, or admin endpoints
|
||||||
|
- Generate professional reports
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### viewer
|
||||||
|
|
||||||
|
**Primary use case**: Stakeholder, auditor, or report consumer. Read-only access plus report generation.
|
||||||
|
|
||||||
|
**Can do:**
|
||||||
|
- Read all entities: tests, techniques, campaigns, playbooks, lessons, coverage, snapshots, alerts, dashboards, detection lifecycle, scores, heatmap, threat actors, compliance, analytics
|
||||||
|
- Generate professional reports: PDF, DOCX, HTML (all report types)
|
||||||
|
- Mark own notifications as read
|
||||||
|
|
||||||
|
**Cannot do:**
|
||||||
|
- Create or modify any entity (no POST/PATCH/DELETE on data entities)
|
||||||
|
- Upload evidence
|
||||||
|
- Change test state
|
||||||
|
- Manage users, webhooks, alert rules, playbooks, campaigns, or any configuration
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Access Matrix
|
||||||
|
|
||||||
|
The table below shows key endpoints and which roles can call them.
|
||||||
|
✅ = allowed, ❌ = forbidden, * = with restrictions (see notes)
|
||||||
|
|
||||||
|
| Endpoint | admin | red_lead | blue_lead | red_tech | blue_tech | viewer |
|
||||||
|
|----------|-------|----------|-----------|----------|-----------|--------|
|
||||||
|
| POST /tests | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| PATCH /tests/{id} (general) | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /tests/{id}/start-execution | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||||
|
| PATCH /tests/{id}/red | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||||
|
| POST /tests/{id}/submit-red | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||||
|
| PATCH /tests/{id}/blue | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
|
||||||
|
| POST /tests/{id}/submit-blue | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
|
||||||
|
| POST /tests/{id}/validate-red | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /tests/{id}/validate-blue | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /tests/{id}/reopen | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /tests/{id}/pause-timer | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||||
|
| PATCH /tests/{id}/classification | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /campaigns | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /campaigns/{id}/complete | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /campaigns/from-threat-actor/{id} | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /knowledge/playbooks | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| GET /reports/generate/* | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
|
||||||
|
| GET /audit-logs | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| ALL /webhooks | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| DELETE /snapshots/{id} | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /system/sync-mitre | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| PUT /sso/config | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| PATCH /data-sources | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| GET /users (list) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /users | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
| PATCH /alerts/rules | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| POST /alerts/evaluate | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
| GET /scores/organization | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||||
|
| PATCH /scores/config | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes on Role Enforcement
|
||||||
|
|
||||||
|
1. **JWT carries the role**: The user's role is embedded in the JWT payload and
|
||||||
|
re-verified against the database on every request.
|
||||||
|
2. **Admin bypass is unconditional**: The `require_role()` dependency immediately
|
||||||
|
returns if `current_user.role == "admin"`.
|
||||||
|
3. **Resource ownership**: Some endpoints additionally check that the requesting
|
||||||
|
user owns the resource (e.g. API keys, worklogs, notifications). Admins bypass
|
||||||
|
ownership checks too.
|
||||||
|
4. **must_change_password**: If this flag is set on the user record, all endpoints
|
||||||
|
return `403 PASSWORD_CHANGE_REQUIRED` until the password is changed via
|
||||||
|
`POST /api/v1/auth/change-password`.
|
||||||
|
|||||||
Reference in New Issue
Block a user