SentinelForge

SentinelForge is a defensive cybersecurity portfolio project: a small SOC analytics engine that normalizes mixed security logs, applies explainable detection rules, scores risk, and generates analyst-friendly findings and HTML reports.

It is designed to be safe to demo in interviews because it works only with logs and sample data. There is no exploitation, payload delivery, credential harvesting, or live target scanning.

Why This Project Looks Good on GitHub

• Real detection engineering structure: normalized events, rule classes, risk scoring, and evidence objects.
• Multiple telemetry sources: authentication, web access, cloud activity, and network flow style events.
• Explainable findings: every alert includes severity, confidence, MITRE ATT&CK mapping, evidence, and recommended response.
• Portfolio-ready documentation: architecture notes, demo commands, and extension points.
• Test coverage for key detections.

Demo

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e . pytest
sentinelforge scan data\samples --report reports\demo.html
pytest

Expected result: the CLI prints a ranked set of findings and writes an HTML report to reports/demo.html. Use --fail-on-high in CI if you want high or critical detections to produce exit code 1.

Example Findings

SentinelForge can currently detect:

• Brute force login bursts followed by a successful login.
• Impossible travel patterns across countries in a short time window.
• Suspicious privilege escalation and admin role assignment.
• Web exploit probes and automated recon user agents.
• IOC matches against suspicious IPs, domains, or user agents.
• Potential data exfiltration based on unusual outbound volume.

Project Layout

src/sentinelforge/
  cli.py          Command-line interface.
  config.py       TOML config and IOC loading.
  engine.py       Detection orchestration and risk ranking.
  models.py       Event and Finding dataclasses.
  parsers.py      JSONL/CSV log ingestion and normalization.
  report.py       Static HTML report generation.
  rules.py        Built-in detection rules.
data/samples/     Safe synthetic logs for demos.
examples/         Example tuning and IOC config.
tests/            Pytest suite.

Input Format

SentinelForge accepts JSON Lines (.jsonl) and CSV (.csv). Fields are normalized when common names are present:

Normalized Field	Common Aliases
timestamp	time, @timestamp, event_time
source	log_type, dataset, service
event_type	action, event, event_name
user	username, actor, principal
src_ip	client_ip, source_ip, ip
country	geo_country, src_country
url	path, request_uri
user_agent	ua, http_user_agent
bytes_out	sent_bytes, egress_bytes

Tuning

Create a TOML config like examples/sentinelforge.toml:

[thresholds]
brute_force_failures = 5
brute_force_window_minutes = 10
exfiltration_bytes = 50000000

[iocs]
ips = ["203.0.113.66"]
domains = ["malicious.example"]
user_agents = ["evilbot"]

Then run:

sentinelforge scan data\samples --config examples\sentinelforge.toml --report reports\tuned.html

Interview Talking Points

• Explainable detections are easier to audit than black-box alerts.
• The engine separates parsing, detection rules, and reporting so new telemetry can be added cleanly.
• Findings include confidence and severity independently, which mirrors real SOC triage.
• Sample logs are synthetic and safe, but the parser accepts common real-world field aliases.

Roadmap

• Sigma rule import for simple logsource and condition matching.
• Baseline learning for user and host behavior.
• SQLite-backed case history and alert deduplication.
• Optional FastAPI dashboard.