Temporal graph detection. Clear evidence. Connected investigation.
Quick start · Investigation guide · Architecture · Contribute · Security
TGDetect is a local investigation workspace for security telemetry. It combines a trained temporal graph model with searchable events, connected entity graphs, alert evidence, and directed chronological chain exploration. The included checkpoint and recorded evaluation use DARPA Transparent Computing CADETS E3.
The application opens with a pitch-black and orange landing page featuring the approved Blender Trace Engine and a reversible scroll assembly. Its workspace buttons open the dashboard at /dashboard on the same host. The dashboard opens in black mode with restrained wine-colored motion, an original TGD monogram, and self-hosted Instrument Sans. Solarized Light is available from the theme control. Data panels keep an opaque background, and decorative motion respects reduced-motion preferences.
Preview Solarized Light
| Workspace | Capabilities |
|---|---|
| Overview | Inspect corpus counts, checkpoint metadata, calibration, and recorded test metrics. |
| Detection graph | Find IPs, hosts, processes and files; follow directed observations; focus entities; change hops; filter starting predictions; zoom, fit, and export. |
| Investigate alerts | Review scored entities and contributing events; reconstruct candidate paths; replay, backtrace, and step through chronological chains. |
| Event explorer | Search paginated train, validation, and test events with endpoint attributes and relation filters. |
| Model & validation | Inspect artifact-backed configuration and verify CPU checkpoint replay against saved GPU scores. |
| Uploaded datasets | Import supported JSON, NDJSON, or CSV endpoint events; run the original checkpoint and calibration; explore a separate persistent graph. |
Model status: this is a research-backed investigation application. The supplied checkpoint has a substantial false-alert burden; its predictions require analyst review. Connected paths are investigation hypotheses, and anomaly evidence is not a probability of compromise. See evaluation and limitations.
- Python 3.11+; verified locally with 3.13.5.
- Node.js 20.9+ and npm; verified locally with 20.19.2.
- Approximately 2 GB for the extracted corpus/model plus space for dependencies and the 262 MiB download. A GPU and Modal account are unnecessary for the local application.
git clone https://github.com/Pratham2511/TGDetect-V3.git
cd TGDetect-V3
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
# Use the CPU wheel for the local dashboard.
python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cpu
python -m pip install -r backend/requirements.txt
python scripts/download_local_data.py
python scripts/verify_package.py
python scripts/run_backend.pyThe downloader retrieves the model/data release, verifies the archive and every extracted file, and installs them into backend/dashboard/data/cadets_v3/. This directory is excluded from Git. Re-running the command verifies an existing installation.
In a second terminal, from the repository root:
cd frontend
npm ci
npm run build
npm run startOpen http://localhost:3000 for the landing page and press Open workspace to enter the dashboard. The dashboard is also available directly at http://localhost:3000/dashboard. Both use one frontend process; the landing assets are generated automatically by the frontend build. The API is at http://127.0.0.1:8000; interactive API documentation is at http://127.0.0.1:8000/docs.
For development, use python scripts/run_backend.py --reload and npm run dev in frontend/. To change the API origin, copy frontend/.env.example to frontend/.env.local, set TGDETECT_API_ORIGIN, and restart/rebuild Next.js. This value belongs to the server-side proxy.
See setup and troubleshooting for offline installation, other ports, and common errors.
TGDetect-V3/
├── frontend/ # One Next.js server for landing, dashboard, and API proxy
│ ├── landing/ # Editable HTML, animation source, and approved Blender export
│ ├── public/landing/ # Generated landing output; ignored by Git
│ └── src/app/dashboard/ # Existing investigation workspace at /dashboard
├── backend/
│ ├── dashboard/ # FastAPI APIs, graph uploads, checkpoint runtime
│ │ └── data/ # Local release data and uploads; ignored by Git
│ ├── research/ # V3 implementation and required compatibility code
│ ├── results/ # Original recorded research/comparison measurements
│ ├── artifacts/ # Compatibility copies required by research scripts
│ ├── requirements.txt # Pinned Python dependencies
│ └── environment-record.json
├── docs/ # Setup, architecture, API, evaluation, assets, provenance
├── scripts/ # Download, run, verify, and refresh the inventory
├── .github/ # CI, issue forms, and pull request template
├── DATA_BUNDLE.json # Release archive URL, size, and SHA-256
├── DATA_MANIFEST.json # Individual corpus/model file checksums
└── PACKAGE_MANIFEST.json # Source file checksums
Backend package names and the frozen research implementation are preserved. The frontend receives model configuration and metrics from the API. Reorganizing and redesigning the workspace does not change weights, scoring, or recorded results.
The optional /legacy route retains the prior Sysmon interface. Its separate DEDALE artifacts are not included in this V3 package; its model workflows are unavailable without them. The CADETS workspace at /dashboard is supplied in full. See landing implementation for animation and build details.
The V3 pipeline combines typed endpoint encoding, causal endpoint history, graph attention, temporal convolution, selective memory compression, and endpoint memory. Relation reconstruction and endpoint-pair anomaly losses produce event evidence. Validation calibration aggregates the strongest incident evidence within time windows to score entities. Read the architecture.
Recorded held-out node metrics for the supplied checkpoint:
| Precision | Recall | F1 | Average precision | ROC AUC |
|---|---|---|---|---|
| 0.4194% | 35.2941% | 0.8289% | 0.7797% | 89.1762% |
These values come from the original result artifact. They are not measurements of the UI or uploaded datasets. Evaluation details explain the test scope and limitations; recorded comparison results retain the original V3/ORTHRUS provenance.
source .venv/bin/activate
python scripts/verify_package.py
python -m pytest backend/research/test_sliding_v3.py \
backend/research/test_orthrus_universal.py \
backend/research/test_cadets_dashboard.py \
backend/research/test_graph_uploads.py -q
cd frontend
npm run lint
npm run buildReal-data integration tests include checkpoint replay, chronological chains, graph isolation, and upload scoring against saved losses. CI runs source verification, model unit tests, frontend lint, and a production build. See the validation record for checks performed on this layout.
Issues and pull requests are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and use the repository's bug and feature forms. Report vulnerabilities through GitHub private vulnerability reporting, following SECURITY.md. Do not include private telemetry or credentials in reports.
This project builds on MaheshMarathe005/TGDetect. The model, research code, dataset preparation, and original measurements retain their provenance. The included ORTHRUS reference snapshot is credited to UBC Provenance / ORTHRUS.
Licensing is documented per component in LICENSE.md and NOTICE.md: the frontend retains its original MIT notice, Instrument Sans uses SIL OFL 1.1, and upstream research/data rights are preserved. See provenance for the pinned source and unchanged artifact hashes.