SentriOps (v1.0.0) — Incident Response Automation MVP

SentriOps is a lightweight SOAR-style Incident Response Automation tool built to demonstrate real-world SOC workflows: alert ingestion, risk scoring, severity classification, playbook-driven response, approval-gated automation, and a tamper-evident audit trail.

Core Problem

Security teams often lose time and consistency during incident response due to manual triage, ad-hoc escalation, and inconsistent execution. SentriOps standardizes response logic using playbooks and enforces governance through approvals and auditing.

Key Features

• Alert Ingestion → Incident Creation

  • Ingests alerts via API and creates incidents with immutable alert storage.

• Risk Scoring & Severity

  • Produces a deterministic risk_score and maps it to S1–S5 severity.

• Incident Lifecycle (State Machine)

  • Enforces valid state transitions (no skipping).

• Playbook Framework (YAML)

  • Maps incident types to response playbooks with action steps and conditional gates.

• Approval Workflow

  • Automatically requests approval for high-risk or privileged-context scenarios before execution.

• Audit Trail

  • Records key actions as append-only audit events for traceability and governance.

• Dynamic Web UI

  • Dashboard, incident detail view, approvals queue, and live-updating audit trail.

Tech Stack

• Backend: FastAPI (Python)
• DB: SQLite (local)
• ORM: SQLAlchemy
• Playbooks: YAML
• UI: Jinja2 + Tailwind (CDN) + HTMX-style partial refresh pattern

Architecture Overview

Flow (MVP):

1. POST /alerts/ingest accepts an alert payload

2. System computes risk_score + severity and creates an incident in Classified

3. Analyst triggers playbook run from UI or API

4. If approval conditions match:

   • incident → AwaitingApproval
   • approval record created
   • audit event: APPROVAL_REQUESTED

5. After approval:

   • incident → InProgress → Contained (simulated action execution)
   • audit events: APPROVAL_DECIDED, PLAYBOOK_STARTED, PLAYBOOK_COMPLETED

Repository Structure

• app/ — FastAPI application

  • core/ — constants, scoring model
  • db/ — SQLite engine/session + init
  • models/ — SQLAlchemy tables + Pydantic schemas
  • services/ — business logic (ingest, runner, approvals, audit, queries)
  • web/templates/ — UI pages and partials

• playbooks/ — YAML playbooks (PB-* files)

• data/ — local runtime data (SQLite DB ignored by git)

Quick Start (Windows)

1) Create and activate venv

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2) Install dependencies

pip install fastapi uvicorn sqlalchemy pydantic pyyaml

3) Run the server

python -m uvicorn app.main:app --reload

4) Open the app

• Web UI: http://127.0.0.1:8000/
• API docs: http://127.0.0.1:8000/docs

API Endpoints (MVP)

• GET /health — service health
• POST /alerts/ingest — ingest alert → create incident
• GET /incidents — list incidents
• GET /incidents/{id} — incident detail
• POST /incidents/{id}/run — run playbook (may request approval)
• GET /approvals — list approvals (filter by status)
• POST /approvals/{id}/decide — approve/reject
• GET /audit-logs — list audit logs (filter by incident_id)

Demo Walkthrough (2–3 minutes)

Scenario A — Approval-gated brute force response

1. Ingest a privileged brute-force alert:

{
  "incident_type": "brute_force",
  "impact": 4,
  "likelihood": 4,
  "confidence": 3,
  "context": {
    "ip": "91.23.11.9",
    "target_account": "admin",
    "privileged_account": true,
    "window_minutes": 5,
    "failed_attempts": 20
  }
}

2. Open the incident in UI and click Run Playbook

3. Observe incident transitions to AwaitingApproval

4. Open Approvals page and click Approve

5. Observe incident becomes Contained

6. Show audit trail:

   • APPROVAL_REQUESTED
   • APPROVAL_DECIDED
   • PLAYBOOK_STARTED
   • PLAYBOOK_COMPLETED

Scenario B — Phishing response (no approval)

1. Ingest phishing alert (moderate severity)
2. Run playbook
3. Observe direct execution and completion

Playbooks

Playbooks live in playbooks/ and are YAML-based.

Example fields:

• id, name, incident_type
• actions: ordered list of steps
• requires_approval_if: rules such as severity_at_least and privileged_account

Roadmap (Phase 3)

• Authentication + roles (Analyst vs Approver)
• Action plugins (block IP, disable user, isolate host)
• Integrations (Slack/Teams, email, SIEM/EDR)
• Background jobs (Celery/RQ) for async execution
• Postgres + Alembic migrations
• Docker + deployment (Render/Railway/Azure)

License

MIT (or update if you prefer a different license)

Author

Gufran Ahmed

• LinkedIn: https://www.linkedin.com/in/cyb-gufran/
• GitHub: https://github.com/cyb-gufran
• Email: agufran006@gmail.com