OpsSentinel — Real-time Anomaly + Incident Console (Explainable SecOps)

Educational Purpose & Skills Showcase: This repository is a portfolio-grade demonstration intended for learning, interviews, and technical evaluation. It is not a drop-in replacement for a regulated production system. Security controls are implemented as Security-by-Design exemplars and must be reviewed and adapted for any real deployment.

What it does

OpsSentinel streams synthetic application and security log events into a Django backend, detects anomalies using deterministic rule baselines, and opens incidents with explainability artifacts.

• Why this alert? Rule trace, evidence summary, and sequence replay
• Real-time feed: WebSockets via Django Channels
• Detection jobs: Celery for periodic evaluation
• Operational resilience hooks: Designed for future chaos injection patterns

Why this project matters

OpsSentinel is designed to demonstrate security-aware, operations-aware, and governance-aware full-stack engineering. It combines real-time incident visibility, explainable anomaly detection, typed frontend integration, and reproducible local execution into a portfolio-ready SecOps reference implementation.

It is especially useful as a showcase of:

• Django backend API design for operational systems
• real-time event streaming with Channels and Redis
• scheduled evaluation workflows with Celery
• explainability-oriented incident response design
• Angular strict-mode frontend delivery with typed service integration
• secure-by-default repository conventions and development tooling
• Docker-based reproducibility for end-to-end verification

Key engineering signals

This repository demonstrates the following technical themes:

• Explainable detection design: anomalies are paired with traces, evidence summaries, and replay-oriented reasoning artifacts
• Real-time system behavior: WebSocket delivery supports live dashboard updates
• Typed frontend-backend integration: Angular client behavior is aligned with explicit API contracts
• Security-by-Design defaults: correlation IDs, dependency checks, secret hygiene, and audit-oriented structure
• Operational reproducibility: Docker Compose provides the preferred integrated verification path
• Governance-aware implementation: AI usage is constrained by explicit ethics, evaluation, and review controls

Screenshots

Frontend Dashboard

Angular dashboard running through the containerized frontend, which is the preferred integrated verification path.

API Documentation

OpenAPI documentation served through Swagger UI.

Health Endpoint

Operational health endpoint validating backend dependency status.

Note: The preferred final verification path is Docker at http://localhost:8080/. Local Angular development through http://localhost:4200/ is supported for convenience via proxy, but the Docker-backed stack is the portfolio reference path.

Architecture overview

• Backend: Django, Django REST Framework, drf-spectacular, Channels, Celery
• Data stores: PostgreSQL, Redis
• Frontend: Angular strict mode, typed API service contracts, correlation ID propagation
• DevSecOps: pre-commit, pip-audit, safety, ESLint strict, gitleaks

Runtime model

Backend responsibilities

The backend is responsible for:

• ingesting synthetic operational and security events
• applying deterministic anomaly evaluation rules
• opening and updating incidents
• exposing health, schema, and documentation endpoints
• delivering real-time updates through Channels
• supporting asynchronous or scheduled evaluation through Celery
• returning traceable responses with correlation identifiers

Frontend responsibilities

The Angular client is responsible for:

• presenting incident and anomaly state in a dashboard workflow
• consuming typed API responses
• preserving correlation-aware request handling
• surfacing explainability artifacts to the operator
• providing an integrated interface for portfolio-grade verification

Infrastructure responsibilities

The supporting services are responsible for:

• PostgreSQL: relational persistence for incidents and event state
• Redis: channel layer and asynchronous support
• Docker Compose: integrated local orchestration across services
• Nginx container path: preferred frontend verification route in Docker

Security-by-Design principles implemented

• Traceability: X-Correlation-ID is propagated on every request and echoed in responses
• Least exposure: .env.example only is committed; real .env is ignored
• Hardening defaults: Secure headers, HTTPOnly cookies, and explicit dependency checks
• Audit-friendly detection: Deterministic baseline rules with structured traces

AI Ethics & Disclosure

OpsSentinel is designed to support AI-assisted investigation in a controlled, auditable way. If or when a model is used, the following must be enforced.

PII scrubbing

• No direct PII is permitted as model input
• Redact emails, phone numbers, account identifiers, card-like patterns, tokens, JWTs, and API keys
• Never persist raw sensitive content in explainability fields

Human-in-the-loop patterns

• Mandatory approvals for CRITICAL severity escalations, automated remediation, or customer-impacting actions
• Model outputs are advisory; the operator confirms actions and documents rationale

Hallucination mitigation

• Evidence-only generation
• Explicit limitations and uncertainty handling
• Retrieval over guessing
• Refusal when evidence is insufficient

Governance artifacts

See:

• ai_governance/prompt_catalog.json
• ai_governance/evals/sample_eval.json

Local development

Backend

Run from D:\Projects\OpsSentinel\api:

cd .\api
.\.venv\Scripts\Activate.ps1
python manage.py migrate
python manage.py runserver 0.0.0.0:8000

Backend endpoints:

• Health: http://localhost:8000/api/core/health/
• OpenAPI schema: http://localhost:8000/api/schema/
• Swagger UI: http://localhost:8000/api/docs/

Frontend

Run from D:\Projects\OpsSentinel\client:

cd .\client
npm install
npx ng serve --proxy-config .\proxy.conf.json

Frontend local URL:

• http://localhost:4200/

Docker Compose

Run from D:\Projects\OpsSentinel:

cd .\
if (-not (Test-Path ".\.env")) { Copy-Item ".\.env.example" ".\.env" }
docker compose up --build

Containerized endpoints:

• Frontend: http://localhost:8080/
• API health: http://localhost:8000/api/core/health/
• API docs: http://localhost:8000/api/docs/

To stop the stack:

docker compose down

If a terminal command hangs or needs to be interrupted, press:

CTRL + C

Demo incident seed

Run this after the Docker stack is up to create a visible incident for the dashboard.

$event = Invoke-RestMethod -Method Post -Uri "http://localhost:8000/api/incidents/events/" -ContentType "application/json" -Body '{
  "ts": "2026-03-11T10:00:00Z",
  "source": "api-gateway",
  "event_type": "LOGIN",
  "actor": "demo-user",
  "ip": "203.0.113.10",
  "message": "login from unusual location",
  "risk_score": 0.92
}'

Invoke-RestMethod -Method Post -Uri "http://localhost:8000/api/incidents/events/$($event.id)/evaluate/"

Verification path

The preferred verification order is:

1. Start the Docker stack
2. Open http://localhost:8080/
3. Confirm the dashboard loads
4. Confirm http://localhost:8000/api/core/health/ returns healthy dependency state
5. Confirm http://localhost:8000/api/docs/ loads Swagger UI
6. Seed a demo incident
7. Confirm incident visibility and explainability artifacts in the dashboard

Quality gates

Run from D:\Projects\OpsSentinel:

.\scripts\quality-gates.ps1

This executes:

• pip-audit
• safety check or safety scan
• flake8
• python manage.py test
• npx ng lint

Repository structure

OpsSentinel/
  .dockerignore
  .editorconfig
  .env.example
  .flake8
  .gitattributes
  .gitignore
  .gitleaks.toml
  .pre-commit-config.yaml
  README.md
  LICENSE
  docker-compose.yml
  screenshots/
    api-docs-browser.png
    api-health-browser.png
    frontend-dashboard.png
  infra/
    docker/
      api.Dockerfile
      client.Dockerfile
      nginx.conf
  docs/
    adr/
      0001-architecture-baseline.md
  scripts/
    verify-tree.ps1
    quality-gates.ps1
  ai_governance/
    prompt_catalog.json
    evals/
      sample_eval.json
  api/
    manage.py
    requirements.txt
    requirements-dev.txt
    opssentinel_api/
    core/
    incidents/
    tests/
  client/
    angular.json
    package.json
    package-lock.json
    proxy.conf.json
    tsconfig.json
    tsconfig.app.json
    tsconfig.spec.json
    eslint.config.js
    public/
    src/

Operational notes

Preferred portfolio verification route

The Docker-backed path is the reference demonstration route because it verifies:

• multi-service orchestration
• frontend-backend integration
• containerized frontend delivery
• API documentation exposure
• health endpoint behavior
• incident lifecycle visibility

Scope boundary

OpsSentinel is a skills showcase and engineering reference. It is not a finished SOC platform, SIEM replacement, or regulated incident response system.

Secrets handling

Do not commit:

• real .env files
• API keys
• credentials
• production tokens
• sensitive customer or log data

Commit only safe templates such as .env.example.

Suggested repository metadata

For a stronger GitHub presentation, configure the repository with:

• Repository name: OpsSentinel
• Description: Real-time anomaly and incident console with Django, DRF, Channels, Celery, Angular, PostgreSQL, Redis, and Docker Compose
• Topics: django, djangorestframework, django-channels, celery, angular, typescript, redis, postgresql, docker-compose, openapi, security, secops, incident-response, observability

License

This project is licensed under the MIT License.

Copyright (c) 2026 Cherry Augusta

This repository is provided as an educational and portfolio-grade software engineering project. See the LICENSE file for full license text.