🚨 Create Incident Management API
Issue: #120
Type: Feature
Priority: High
Estimated Effort: 2–3 days
🧠 Concept
Implement a comprehensive Incident Management API that enables security teams to create, manage, investigate, assign, prioritize, and resolve security incidents throughout their lifecycle.
This module should serve as the central backend for Sentinel's incident response workflow, exposing RESTful APIs that integrate with the alerting, detection, notification, and threat hunting modules.
⚠️ Problem
Security alerts alone are insufficient without a structured incident response process.
Analysts need a centralized system to:
- Track incidents from creation to resolution
- Assign ownership to responders
- Manage investigation progress
- Prioritize response efforts
- Maintain a complete audit history
- Link incidents to alerts and detections
Without an Incident Management API:
- Incident ownership becomes unclear.
- Investigations are difficult to coordinate.
- Security teams lack visibility into active investigations.
- Historical incidents cannot be audited or reported.
- Response metrics such as MTTR become difficult to measure.
📁 Implementation Scope
Suggested module structure:
src/modules/incidents/
├── controllers/
│ └── incidents.controller.ts
├── services/
│ ├── incidents.service.ts
│ ├── incident-status.service.ts
│ └── incident-assignment.service.ts
├── repositories/
│ └── incidents.repository.ts
├── dto/
│ ├── create-incident.dto.ts
│ ├── update-incident.dto.ts
│ ├── update-status.dto.ts
│ ├── assign-owner.dto.ts
│ └── query-incidents.dto.ts
├── entities/
├── interfaces/
├── enums/
├── guards/
├── decorators/
├── utils/
└── tests/
🏗️ Dependencies
This module should integrate with existing or upcoming modules where applicable:
- Alerts Module
- Detection Engine
- Notification Service
- Authentication & Authorization
- Prisma ORM
- Observability/Logging
- Audit Logging
✅ Requirements
Incident CRUD
Implement RESTful CRUD operations.
Supported operations:
- Create incident
- Retrieve incident
- List incidents
- Update incident
- Archive/Delete incident (soft delete preferred)
Incident model should include fields such as:
- ID
- Title
- Description
- Status
- Severity
- Priority
- Category
- Organization ID
- Assigned User
- Source Alert(s)
- Detection Source
- Tags
- Created At
- Updated At
- Resolved At
- Closed At
Incident Listing
Support:
- Pagination
- Sorting
- Filtering
- Full-text search
Filters should include:
- Status
- Severity
- Priority
- Assigned owner
- Category
- Organization
- Source
- Date range
Sorting should support:
- Created date
- Updated date
- Severity
- Priority
- Status
Incident Details
Provide an endpoint that returns:
- Complete incident information
- Current status
- Assigned analyst
- Related alerts
- Related detections
- Linked wallets/contracts
- Investigation timeline
- Resolution metadata
- Audit history
Incident Lifecycle
Support configurable lifecycle states such as:
- New
- Open
- Acknowledged
- Investigating
- Contained
- Resolved
- Closed
- Reopened
The API should validate status transitions and reject invalid state changes.
Each transition should:
- Update timestamps
- Record audit events
- Trigger notifications (when configured)
Ownership Management
Support:
- Assign incident owner
- Reassign owner
- Remove assignment
- Retrieve current assignee
Ownership updates should be audit logged.
Severity & Priority
Support independent updates for:
Severity
Priority
These values should be filterable from the listing endpoint.
Search
Support searching by:
- Incident ID
- Alert ID
- Wallet address
- Transaction hash
- Contract address
- Incident title
- Description
- Assigned user
Search should work alongside filters and pagination.
Audit Trail
Maintain a complete audit history.
Record events including:
- Incident creation
- Status changes
- Ownership changes
- Severity updates
- Priority updates
- Incident edits
- Resolution
- Closure
- Reopening
Audit entries should capture:
- Timestamp
- User
- Previous value
- New value
- Action performed
Validation & Error Handling
Implement:
- DTO validation
- Meaningful HTTP status codes
- Consistent API error responses
- Validation for invalid IDs
- Validation for invalid lifecycle transitions
API Documentation
Document every endpoint using Swagger/OpenAPI.
Documentation should include:
- Request schemas
- Response schemas
- Query parameters
- Path parameters
- Validation rules
- Example payloads
🔒 Non-Functional Requirements
- RESTful API design
- Modular NestJS architecture
- Type-safe DTOs
- Repository pattern
- Structured logging
- Input validation
- Pagination support
- Clean separation of concerns
- Ready for RBAC integration
- Unit-testable services
📡 Suggested Endpoints
| Method |
Endpoint |
Description |
POST |
/incidents |
Create a new incident |
GET |
/incidents |
List incidents |
GET |
/incidents/:id |
Retrieve incident details |
PATCH |
/incidents/:id |
Update incident |
PATCH |
/incidents/:id/status |
Update incident status |
PATCH |
/incidents/:id/assign |
Assign or reassign owner |
PATCH |
/incidents/:id/severity |
Update severity |
PATCH |
/incidents/:id/priority |
Update priority |
DELETE |
/incidents/:id |
Archive/Delete incident |
🧪 Testing Requirements
- Unit tests for services
- Controller tests
- Repository tests
- DTO validation tests
- API integration tests
- Status transition validation tests
- Assignment workflow tests
📚 Related Modules
- Alerts
- Detection
- Notifications
- Threat Hunting
- Security Posture
- Authentication
- Audit Logging
🚫 Out of Scope
- Frontend incident management pages
- Real-time collaboration features
- AI-assisted incident triage
- Third-party ticketing integrations (e.g., Jira, ServiceNow)
- Automated incident remediation
🎯 Acceptance Criteria
🚨 Create Incident Management API
Issue: #120
Type: Feature
Priority: High
Estimated Effort: 2–3 days
🧠 Concept
Implement a comprehensive Incident Management API that enables security teams to create, manage, investigate, assign, prioritize, and resolve security incidents throughout their lifecycle.
This module should serve as the central backend for Sentinel's incident response workflow, exposing RESTful APIs that integrate with the alerting, detection, notification, and threat hunting modules.
Security alerts alone are insufficient without a structured incident response process.
Analysts need a centralized system to:
Without an Incident Management API:
📁 Implementation Scope
Suggested module structure:
🏗️ Dependencies
This module should integrate with existing or upcoming modules where applicable:
✅ Requirements
Incident CRUD
Implement RESTful CRUD operations.
Supported operations:
Incident model should include fields such as:
Incident Listing
Support:
Filters should include:
Sorting should support:
Incident Details
Provide an endpoint that returns:
Incident Lifecycle
Support configurable lifecycle states such as:
The API should validate status transitions and reject invalid state changes.
Each transition should:
Ownership Management
Support:
Ownership updates should be audit logged.
Severity & Priority
Support independent updates for:
Severity
Priority
These values should be filterable from the listing endpoint.
Search
Support searching by:
Search should work alongside filters and pagination.
Audit Trail
Maintain a complete audit history.
Record events including:
Audit entries should capture:
Validation & Error Handling
Implement:
API Documentation
Document every endpoint using Swagger/OpenAPI.
Documentation should include:
🔒 Non-Functional Requirements
📡 Suggested Endpoints
POST/incidentsGET/incidentsGET/incidents/:idPATCH/incidents/:idPATCH/incidents/:id/statusPATCH/incidents/:id/assignPATCH/incidents/:id/severityPATCH/incidents/:id/priorityDELETE/incidents/:id🧪 Testing Requirements
📚 Related Modules
🚫 Out of Scope
🎯 Acceptance Criteria