Enterprise SIEM & SOC Platform (NetSentinel)

NetSentinel is a portfolio-ready Security Information and Event Management (SIEM) and Security Operations Center (SOC) backend. It ingests security logs, turns high-priority events into alerts, and gives analysts a focused workflow for search, investigations, IOCs, timelines, and evidence.

Key features

• Log ingestion pipeline with validated, timestamped source-IP records
• High-performance log search with filters, pagination, sorting, and PostgreSQL full-text search
• JWT authentication with role-based access control for admin, analyst, and viewer
• SOC case management with IOC tracking and investigation timelines
• Filesystem evidence storage with streamed SHA-256 hashing and PostgreSQL metadata
• Lightweight alerting when HIGH or CRITICAL logs are ingested

Architecture

The FastAPI application is organized into dedicated authentication, logging, search, alerting, and case-management modules. PostgreSQL holds normalized operational data and search indexes; evidence content is stored separately on the local filesystem so the database retains only chain-of-custody metadata.

                    +------------------+
                    |      Client      |
                    +--------+---------+
                             |
                             v
                    +------------------+
                    |   FastAPI API    |
                    | auth | logs      |
                    | search | cases  |
                    +---+----------+---+
                        |          |
                        v          v
              +---------------+  +------------------+
              |  PostgreSQL   |  | Evidence Storage |
              | logs, alerts, |  | files + SHA-256  |
              | RBAC, cases   |  +------------------+
              +---------------+

API endpoints

Area	Endpoint	Purpose
Authentication	POST /auth/login	Exchange email/password form data for a bearer token
Logs	POST /logs/ingest	Validate and ingest one raw log; high-priority logs create alerts
Search	GET /search	Filter, sort, paginate, and full-text search logs
Alerts	GET /alerts	List generated HIGH and CRITICAL alerts
Cases	POST, GET /cases	Create and list SOC investigations
Case detail	GET /cases/{case_id}	Retrieve one case
IOCs	POST, GET /cases/{case_id}/iocs	Track case-linked indicators
Timeline	POST, GET /cases/{case_id}/timeline-events	Build an investigation timeline
Evidence	POST, GET /cases/{case_id}/evidence	Upload/list SHA-256-hashed evidence

Operational endpoints require Authorization: Bearer <token>. Analysts and admins can ingest logs and write cases; viewers have read-only access.

Quick start

1. Clone and create a virtual environment

git clone https://github.com/<your-username>/netsentinel-siem-soc.git
cd netsentinel-siem-soc
python -m venv .venv

Activate the environment (.venv\Scripts\activate on Windows or source .venv/bin/activate on macOS/Linux), then install dependencies:

pip install -r requirements.txt

2. Configure environment variables

cp .env.example .env

Set DATABASE_URL, a high-entropy JWT_SECRET_KEY, and a strong ADMIN_PASSWORD. EVIDENCE_STORAGE_PATH defaults to data/evidence.

3. Start PostgreSQL

Create a local PostgreSQL database matching DATABASE_URL. For example:

CREATE DATABASE netsentinel;

4. Run migrations and seed RBAC data

alembic upgrade head
python -m app.seed

The seed command creates the admin, analyst, and viewer roles, practical SOC permissions, and the initial administrator account.

5. Start the API

uvicorn app.main:app --reload

Open Swagger UI at http://127.0.0.1:8000/docs.

Example requests

Authenticate first, then supply the returned bearer token to protected routes. Complete cURL examples are in examples/curl-requests.sh.

Ingest a high-priority log

POST /logs/ingest
{
  "timestamp": "2026-08-10T14:30:00+05:30",
  "severity": "HIGH",
  "message": "Multiple failed sign-ins detected for privileged account",
  "src_ip": "203.0.113.42"
}

Search investigation data

GET /search?start_time=2026-08-10T00:00:00Z&severity=HIGH&keyword=sign-ins&limit=25&sort_direction=desc

Demo data

After migrations and seed data are applied, create a small walkthrough dataset:

python scripts/demo_data.py

It creates INFO, WARNING, HIGH, and CRITICAL logs; two alerts; one investigation case; a malicious-IP IOC; a timeline event; and a SHA-256-hashed evidence file.

Screenshots

Add these screenshots before publishing the repository. Keeping the names below makes the project page easy to scan without committing real incident data.

Screenshot	Suggested path	What to show
Swagger UI	docs/screenshots/swagger-ui.png	Authenticated API endpoint groups
Search results	docs/screenshots/search-results.png	Filtered high-severity search response
Alerts output	docs/screenshots/alerts-output.png	Generated alerts with source log IDs

Recommended commit history

chore: initialize FastAPI and PostgreSQL backend
feat(auth): add JWT authentication and RBAC system
feat(logs): implement validated log ingestion pipeline
feat(search): add indexed log search with pagination
feat(soc): add case, IOC, timeline, and evidence modules
feat(alerts): generate alerts for high-priority logs
docs: finalize NetSentinel portfolio documentation and demo data