SOC Log Triage

A defensive command-line security tool for normalizing heterogeneous logs, applying portable detection rules, and producing analyst-friendly findings.

This project explores a practical security-engineering problem: how to turn inconsistent raw event data into repeatable, explainable triage decisions without hiding the logic behind an opaque workflow.

Why this project exists

Security analysts routinely work across logs with different schemas, field names, and levels of context. SOC Log Triage provides a small, inspectable pipeline that separates ingestion, normalization, detection logic, and reporting so that each stage can be tested and reasoned about independently.

The project is intentionally defensive. It contains no exploitation or destructive capability.

Capabilities

• Ingest JSONL and CSV event data
• Normalize source-specific records into a consistent internal schema
• Apply human-readable YAML detection rules
• Generate findings in the console and structured JSON reports
• Keep detection logic separate from parsing and reporting
• Support reproducible blue-team exercises and portfolio demonstrations

Security-engineering themes

This repository is intentionally simple enough to inspect end to end while still demonstrating several principles I use in larger systems:

• Explainability: findings should be traceable to explicit rules and observable evidence.
• Separation of concerns: ingestion, normalization, detection, and reporting are distinct stages.
• Repeatability: the same source events and rules should produce consistent results.
• Defensive utility: automation should reduce analyst friction without pretending to replace analyst judgment.

Quick start

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

soc-log-triage triage sample_data/sample_auth.jsonl \
  --rules rules/example_rules.yml \
  --out findings.json

soc-log-triage triage sample_data/sample_proxy.csv \
  --rules rules/example_rules.yml

Portfolio context

SOC Log Triage is one of several projects I use to explore trustworthy automation and security decision support. My larger work extends the same ideas into authenticated APIs, cyber-physical systems, telemetry validation, auditability, and independent verification.

See also:

• BattleReef Marine Controller
• Secure Notes API
• Security Program Starter
• About / Portfolio