← Back to projects
Security engineering case study · v0.10.0
TraceHawk — evidence-first security log investigation
I built a local-first investigation workspace that turns raw logs into deterministic findings, explainable incidents, line-level evidence, MITRE ATT&CK context, and exportable analyst reports.
The project is deliberately transparent: the public demo is constrained and stateless, the source is downloadable, the verification gates are reproducible, the detection limitations are published, and extensive AI assistance is disclosed instead of hidden.
Live Azure Container Apps
Open source MIT License
Scope Local-first portfolio system
01 · Project overview
From raw telemetry to auditable investigation
Security demos often stop at a list of alerts. I designed TraceHawk around the investigation chain: where an alert came from, which raw lines support it, why findings were correlated, what confidence can be justified, and what can be exported for review.
Problem
Raw Linux, cloud, container, Windows, Zeek, Suricata, and Docker logs are difficult to review consistently when parsing, detection, correlation, and evidence handling are spread across separate tools.
Design response
I combined bounded intake, confidence-ranked parsing, transparent YAML rules, explainable correlation, evidence integrity checks, case workspaces, reports, and operational proof into one reviewable system.
My role
I owned product direction, architecture decisions, security boundaries, acceptance criteria, test strategy, debugging, release decisions, Azure delivery, public export review, and documentation quality.
Who it is for
The current shape fits homelabs, security learning, small-team evaluation, and portfolio review. It is not positioned as a replacement for a production SIEM or a multi-tenant SOC platform.
02 · Investigation workflow
A case remains connected to its evidence
The interface is structured around a repeatable sequence: load bounded evidence, inspect deterministic findings, review correlation rationale, pivot through entities and raw lines, and produce a report.
Media note: these interface captures were recorded on the v0.9.0 UI. The current case study, source links, architecture claims, and verification baseline refer to v0.10.0.
Bounded input→
Parsed events→
Findings→
Incidents→
Evidence→
Report
03 · Architecture
Deterministic authority with an optional AI boundary
Findings are produced only by deterministic detection code. Optional local Ollama explanations receive a bounded projection of already selected evidence and cannot create, alter, or score findings.
InputUploads, samples, live sources
BoundaryRequest and resource limits
AnalysisParsers + 66 YAML rules
InvestigationCorrelation + entities
OutputEvidence + reports
Frontend
React, TypeScript, and Vite provide intake, investigation, evidence, entity, incident, report, tutorial, and operational views.
Backend
FastAPI, Pydantic, and SQLAlchemy enforce API contracts, authorization modes, resource limits, analysis orchestration, and persistence.
Detection content
Versioned YAML rules and correlation patterns keep detection logic inspectable, testable, and independent from titles or hard-coded rule identifiers.
Operations
Docker, Azure Container Apps, structured logs, metrics, health checks, backup and restore procedures, CI gates, and exact-commit verification support delivery.
04 · Security boundaries
The public demo is a separate constrained deployment
I do not expose the protected analyst workspace as the public portfolio demo. The anonymous deployment has a stricter capability contract and is intended only for sanitized evaluation.
| Boundary | Public demo behavior | Reason |
|---|---|---|
| Persistence | Database and server-side session storage disabled | Visitor evidence must not become retained analyst state. |
| AI | External AI disabled | Uploaded content must not be forwarded to a model provider. |
| Private APIs | Private routes return 404 | The public surface exposes only the bounded demo contract. |
| Input | Request, file, line, case, and analysis budgets | Anonymous work remains resource bounded. |
| Content | Fixed sanitized samples and session-only visitor analysis | Production logs and confidential evidence are out of scope. |
Safe use: do not upload credentials, client data, private topology, production logs, internal hostnames, or real incident evidence to the public demo.
05 · Verification evidence
Claims are tied to executable gates
The figures below reflect the current v0.10.0 verification baseline. They are evidence of tested behavior, not a claim of production-scale SOC readiness.
Backend tests
89.11% measured coverage across API, parsing, detection, correlation, evidence, reports, authorization, and operations paths.
Frontend tests
74.4% statement coverage and 62.19% branch coverage across critical investigation interactions.
Browser workflows
Five private-workspace and two public-demo end-to-end Chromium paths.
Security scan findings
No known pip/npm dependency vulnerabilities, no Gitleaks secrets, and no Semgrep findings in the verified gate.
- All 66 rules have positive contracts; committed scenarios reported no unexpected or missing findings.
- The live Azure verifier confirmed database-disabled public mode, external AI disabled, private API denial, and eight tutorial chapters.
- CI also covers container build, dependency audits, secret scanning, static analysis, browser workflows, and public exact-commit verification.
- The complete gate is reproducible from the source repository with
make verify-all.
06 · Detection quality
External data exposes weaknesses that fixtures cannot
I evaluated selected rule families against role-separated IoT-23 captures. The results are intentionally published with false positives and false negatives because a security project is not credible if only successful fixtures are shown.
| Rule family | Windows | TP / FP / FN / TN | Precision | Recall |
|---|---|---|---|---|
| Network scan | 880 | 1 / 1 / 1 / 877 | 50.0% | 50.0% |
| Command-and-control indicator | 270 | 2 / 21 / 1 / 246 | 8.7% | 66.7% |
Interpretation: the C2 indicator is too noisy for production authority in its current form. The evaluation proves the measurement process and identifies tuning work; it does not prove mature detection accuracy.
07 · AI use and accountability
I disclose how the implementation was produced
I estimate that approximately 99% of the implementation code was initially generated or drafted with generative AI assistance. I do not present that code volume as proof of personal authorship by manual typing.
What AI accelerated
- Initial implementation drafts and repetitive code paths.
- Test scaffolding, documentation drafts, and review prompts.
- Alternative implementation ideas and rapid iteration.
What remains my responsibility
- Problem selection, product direction, scope, and architecture decisions.
- Security boundaries, test expectations, debugging, and acceptance.
- Understanding tradeoffs, rejecting unsafe output, releases, and public claims.
The evidence standard: a certificate can support the claim that I understand principles, while a project demonstrates application. Tests, architecture explanations, limitations, and an explicit AI-use record make it possible to evaluate what I actually learned and can defend.
08 · Certification context
Certification and project evidence reinforce each other
I completed Microsoft Certified: Azure Fundamentals (AZ-900). TraceHawk adds practical evidence around Azure delivery, deployment boundaries, containerized services, security controls, CI validation, and operational ownership.
This Microsoft Learn link includes my Microsoft Student Ambassadors Contributor ID. The portfolio, demo, and GitHub links do not use Microsoft tracking parameters because they are not Microsoft Learn destinations.
09 · Limits and next steps
Current boundaries are explicit
Not yet claimed
- Multi-tenant isolation or horizontally scaled operation.
- A distributed log store or collector fleet.
- A centralized rate limiter or immutable external audit sink.
- Automated response, production SIEM replacement, or certified detection coverage.
Engineering direction
- Tune noisy rule families against external datasets.
- Expand negative controls and cross-source evaluation.
- Keep public/private deployment contracts independently verifiable.
- Improve operational evidence without overstating scale readiness.
Review the working system