From scattered events to defensible investigations.
Built for the Meta Global AI Developer Hackathon 2026.
An interactive terminal workspace for investigating authentication, application and file activity. Import CSV/JSONL, detect transparent signals, open a case, let Meta choose evidence searches through a real local MCP subprocess, inspect original records, export a report, and resume later.
No website, external database, Docker, cloud account for storage, or GPU is required. Live AI requires access to Meta Model API. Manual investigation works without an API key.
uv run sentinel demo --recorded-caseThis explicit option opens the real Meta investigation recorded for the film, labeled
RECORDED META RUN in its title/provider, case brief and activity status. It makes no model
request. All 27 evidence records, original source references and quantitative query receipts are
revalidated against the imported fictional logs before the case is installed. You can inspect
its four findings, pivot through entities, export it and reopen it. Existing analyst notes are
preserved on repeated launches. The normal demo command still starts without a recorded case.
The packaged example includes canonical evidence and receipts. Historical individual tool-file paths are labeled as recorded references; those runtime files are not bundled. A new validation artifact records what was checked. The original captured export and its SHA-256 are retained in package data. Live follow-up questions require your Meta configuration and start only when you submit them; they use the real MCP/model workflow.
A short walkthrough: Enter inspects a source record, Escape returns, F6 explains the case, F4 returns to its timeline and F5 exports both report formats. Open the Case review tab to compare observed facts, hypotheses and open questions. See the real recorded case brief and recorded operation status captures.
Administrators and small security teams often start an investigation with scattered logs: failed authentications in one file, application access in another, and an export elsewhere. SENTINEL brings those records into one terminal workspace so an analyst can reconstruct the sequence, follow accounts, hosts, IP addresses and sessions, and inspect the original evidence.
Deterministic rules surface signals. Meta chooses focused searches through actual MCP tools, reviews gaps and alternatives, and returns structured findings. Code checks retrieved event references and supplies computed quantities. Cases retain evidence, notes and activity so another analyst can reopen the work and assess what is observed, what is a hypothesis, and what remains unknown. An alert is not a verdict of compromise, and a download alone does not prove exfiltration.
Watch or download the approved film — 2:24, 1080p, English, real terminal recordings and a verified live Meta investigation. The film explains ingestion, the local/API architecture, actual MCP searches, source inspection, review, export and reopening. The editable Hyperframes project, storyboard, verification and publication credits are included. Data and architecture graphics are explanatory illustrations, separate from actual UI.
Use macOS, Linux, or Windows with uv installed.
From a clean checkout of main:
git clone https://github.com/lelouchzr/sentinel.git
cd sentinel
uv sync --locked --python 3.12
uv run sentinel doctor
uv run sentinel demodemo is the single demonstration command. It generates 3,542 deterministic fictional records in
.sentinel-sources, imports them into .sentinel, runs three rules, and opens the Textual workspace.
A repeated launch preserves cases and does not duplicate unchanged events. Reopening a case after an abrupt process exit
recovers a stale running status as interrupted, retaining completed evidence and notes. Native
process locks protect investigations that are still active. Allow a few seconds for
first ingestion. The default dataset produces 15 alerts; every displayed value comes from storage.
Earlier projects and their untouched original history are retained in a separate private archive.
Their original local checkouts remain intact. The public repository has only main, with
anonymized author contact and local-path metadata.
See repository preservation before changing or updating that checkout.
See the publication review for the scope and limits of the audit.
The hackathon submission kit includes English form answers, the YouTube thumbnail, and the video publication checklist.
Set a key in the terminal that launches Sentinel. To avoid entering it into shell history:
read -rs META_API_KEY
export META_API_KEY
export META_BASE_URL=https://api.meta.ai/v1
export META_MODEL=muse-spark-1.3
uv run sentinel demoType the key after the first command, then press Enter. In shells where read -s is unavailable,
use your preferred environment/secret manager. Sentinel does not automatically load .env files.
META_API_KEY takes precedence over the documented alias MODEL_API_KEY. .env.example contains
configuration names only. Never put keys in source, reports or recorded terminal input.
Selected log excerpts and case context are sent to the configured Meta API during live runs. Event storage, deterministic rules and manual browsing run locally; AI processing is remote. The application never silently switches providers or selects an offline fixture.
In the TUI, select the first AUTH-002 alert with Enter, press F2 and ask:
Investigate the successful login after failures and the linked session activity. What is recorded, what remains uncertain, and which evidence would establish authorization?
The investigator selects MCP tools from actual results. The evidence reviewer checks support, gaps and alternatives. The reporter produces structured findings. Code rejects invalid references, renders observed facts from canonical records, and uses computed receipts for quantitative facts. Model hypotheses and model-authored notes remain explicitly unverified interpretations.
Provider states distinguish missing configuration, unverified configuration, successful connection
and failure. doctor checks local readiness only; it does not spend API credit.
Provider errors distinguish authentication, model access, missing endpoints, request schema,
quota/rate limits, network failures and timeouts. Messages never include provider response bodies
or credentials. Failed requests are not automatically retried; completed evidence is retained.
Default bounds: 10 model requests, 18 tool calls, 160 distinct retrieved event records, 45 seconds per request, 180 seconds overall.
Override with SENTINEL_MAX_MODEL_CALLS, SENTINEL_MAX_TOOL_CALLS,
SENTINEL_REQUEST_TIMEOUT and SENTINEL_DEADLINE. Paid request retries are disabled.
Private model reasoning is neither requested for display nor persisted.
The core CLI, DuckDB storage, MCP subprocess client/server and Textual UI use portable APIs. Native file locks use filelock (Unix flock or Windows LockFileEx); tzdata supplies IANA zones on systems without a timezone database. Generated CSV/JSONL bytes remain identical across platforms. See platform validation for executed results and remaining terminal limits.
In PowerShell, installation and startup use the same uv commands:
uv sync --locked --python 3.12
$env:META_API_KEY = [System.Net.NetworkCredential]::new("", (Read-Host "Meta API key" -AsSecureString)).Password
uv run sentinel demoThe key prompt is optional for manual browsing. META_BASE_URL and META_MODEL use the documented
defaults; PowerShell overrides use $env:META_BASE_URL and $env:META_MODEL.
GNU Make is optional. On Windows, run its checks directly:
uv run ruff format --check .
uv run ruff check .
uv run pytest -q
uv build
uv run python scripts/platform_smoke.pyCI validates macOS on main and can also be started through workflow dispatch. It tests actual MCP children,
Textual Pilot, clean wheel installation, provenance, reset and persistence without model credentials.
Further Linux/Windows work is on hold; historical native results are documented separately.
The optional bundled asciicast recorder remains POSIX-only; use an external recorder on Windows.
The workspace uses a dark teal theme with explicit text labels: green for successful outcomes, red for failures/high-priority signals, amber for attention and purple for reporting activity. The compact guide shows the current case stage. Filters and the question input show their keyboard shortcuts; activity colors distinguish actual investigation responsibilities.
Human CLI output uses readable panels and signal tables. Use --json for machine-readable
output; it remains free of ANSI formatting. Colors follow terminal capabilities and NO_COLOR.
Color is supplementary: statuses, roles and severity remain readable in monochrome.
See the actual wide workspace and
compact workspace captures.
Recommended: 140 columns × 42 rows. The workspace is also tested at 100 × 30.
| Key/action | Result |
|---|---|
| Tab / Shift+Tab, arrows | Move focus and navigate |
| Enter on an alert | Create a case, or reopen the existing case for that alert |
| Enter on a case | Reopen its original dataset and case timeline |
| Enter on an event | Inspect canonical fields, original record, position and file hash |
| F1 | Help and filter examples |
| F2 | Focus the investigation question |
| F3 | Focus exact search filters |
| F4 | Show attached case evidence chronologically |
| F5 | Export selected case as Markdown and JSON |
| F6 | Explain the case, evidence scope and next checks |
| Ctrl+G | Cancel the investigation; keep completed work |
| Ctrl+Q | Shut down cleanly |
Evidence supports exact account, ip, host, action, outcome, resource, session, start,
end and min_bytes filters combined with AND. Example:
account=morgan ip=203.0.113.74 start=2026-10-20T09:00:00Z end=2026-10-20T09:10:00Z
Submit an empty filter to return to the dataset. Pages contain at most 100 records; counts cover all
matches. Tables scroll vertically and horizontally; open an event for all fields on narrow terminals.
The Case review tab accepts analyst notes. Activity shows actual operations, arguments, result counts
and artifact paths. Function keys keep normal text-entry editing shortcuts available.
On macOS keyboards you may need Fn for function keys. NO_COLOR is respected.
Markdown exports include a contents list, individual finding links, and clickable event/query references that jump to the original evidence or computed receipt. Evidence sections link back to the findings. JSON exports retain their structured format and source records.
The Activity tab shows the current role, model requests/replies, tool attempts/completions, attached evidence and elapsed time from recorded operations. New runs persist their actual configured limits. Follow-ups have separate counters; old cases do not acquire invented budgets. An abruptly stopped process has no claimed execution duration when its stop time is unknown. No private model reasoning is displayed. Tool attempts include rejected/failed requests; completed operations are counted separately. The recorded provider remains explicit.
uv run sentinel cases progress CASE_ID
uv run sentinel cases progress CASE_ID --jsonSearch results from an obsolete view cannot replace the current filters or case. Failed exports and database reads show safe diagnostics while keeping case/source files available for recovery.
Press F6 for a computed case brief: the actual detection explanation, UTC range, attached record count, recorded bytes, involved accounts/IPs/hosts/sessions, source files and suggested next checks. These quantities describe attached evidence, not the entire dataset. The brief works without Meta. "Use suggested question" fills an editable draft and does not call the API. An existing draft is kept. Press Enter yourself to start a configured live investigation.
The evidence dialog separates canonical fields, provenance and the original untrusted record. Its Account, Source IP, Host and Session buttons run exact filters; no filter syntax is needed. F4 returns to attached evidence and clears the displayed search filters.
uv run sentinel cases brief CASE_ID
uv run sentinel cases brief CASE_ID --jsonGlobal --workspace must appear before the command. State defaults to SENTINEL_WORKSPACE or
.sentinel. --json emits machine-readable output without ANSI where shown in command help.
uv run sentinel ingest ./examples/company-logs --json
uv run sentinel investigate ./examples/company-logs
uv run sentinel tui
uv run sentinel alerts --json
uv run sentinel cases create --alert ALERT_ID --json
uv run sentinel cases list
uv run sentinel cases open CASE_ID
uv run sentinel cases open CASE_ID --json
uv run sentinel cases note CASE_ID "Check the identity-provider MFA audit trail."
uv run sentinel run CASE_ID --question "Which session links authentication and resource access?" --json
uv run sentinel search --account svc-backup --limit 10 --json
uv run sentinel event EVENT_ID --json
uv run sentinel export CASE_ID --format markdown
uv run sentinel export CASE_ID --format json
uv run sentinel cases status CASE_ID closed
uv run sentinel --workspace .sentinel mcp --case CASE_IDingest and investigate run detection. Rerun explicit thresholds with:
uv run sentinel detect-rules --failures 8 --window 300 --transfer-bytes 100000000 --jsonExit codes: 0 success; 2 invalid input/configuration or an incomplete investigation; 3 local I/O/state
failure; 130 interrupted CLI investigation. Typer also uses 2 for invalid command syntax.
A TUI requires a terminal; use demo --no-tui, investigate --no-tui, or JSON commands in scripts.
The generator uses seed 20261104; it writes into a new or empty directory and never overwrites it.
examples/company-logs is the committed reproducible dataset. Source files are opened read-only.
The demo's generated sources remain separate from its mutable workspace.
uv run sentinel generate-data /tmp/sentinel-variant --seed 17
uv run sentinel --workspace .sentinel-variant ingest /tmp/sentinel-variant --json
uv run sentinel demo --resetdemo --reset archives a recognized generated demo workspace beside its previous path. It never
recursively deletes a directory, never touches source datasets, and refuses a manually imported
workspace. It preserves old cases in the archive. Close other sessions before resetting.
See schema and provenance and evaluation material.
The evaluation key is outside the model-visible source directory and is never sent to the agent.
The completed 144-second Hyperframes film is the current hackathon
presentation. It uses real macOS terminal captures, English motion graphics and licensed
instrumental music, with animated explanatory diagrams and the verified live Meta recording,
labeled at its actual playback speed. The expanded 2:24 cut explains the architecture through
continuous motion, animated type and a real-event data plane.
The editable source, source recordings, publication credits and verification are in video/.
make check
make integration
uv buildmake check runs Ruff formatting/lint and pytest. make integration runs actual disposable local
MCP subprocesses; it opens no network listener and never targets production. Offline model fixtures
are clearly labeled and exist only in tests. Neither command calls Meta or reads a live API key.
An explicit paid validation is available with:
uv run python scripts/validate_live.py --prompt-keyLive Meta investigation was exercised against the included data; see verification. The demo guide, 180-second narration and recording checklist include exact launch, keys and honest API fallback. The recording target is macOS; Linux and Windows follow-up work is on hold. See macOS demo readiness for the remaining rehearsal and capture steps. Actual Textual captures are in screenshots.
- Architecture and trust boundaries
- Canonical input schema and provenance
- MCP tools and client connection
- Known limitations
- Official references
This is an investigative aid with three focused rules. It does not claim complete Sigma support, production SIEM coverage, legal chain of custody or forensic certification. An alert is a signal, and a recorded download does not establish malicious exfiltration.