Repository navigation
API Reference
The FastAPI backend serves everything on 127.0.0.1:8000 (configurable via SNITCH_BIND/SNITCH_PORT). Every endpoint requires the launch token — send X-Snitch-Token: <TOKEN> or ?token=<TOKEN>. The WebSocket accepts ?token=<TOKEN> and validates the Origin header against loopback.
L'API FastAPI écoute sur 127.0.0.1:8000. Chaque endpoint exige le jeton — X-Snitch-Token ou ?token=. Le WebSocket valide aussi l'Origin.
Agent endpoints authenticate differently: X-Snitch-Agent: sagt_… (dedicated, hashed at rest, revocable) or the master token — see Fleet & Agent.
Les endpoints agent s'authentifient autrement : X-Snitch-Agent: sagt_… (dédié, hashé, révocable) ou le jeton maître — voir Flotte & agent.
| Method | Path | Description |
|---|---|---|
GET |
/graph |
Current graph snapshot — nodes (hosts/processes) and edges with volumes / instantané — nœuds et liens avec volumes |
GET |
/devices |
Passively discovered LAN devices / appareils LAN découverts passivement |
GET |
/timeline |
Sliding-window aggregates / agrégats de la fenêtre glissante |
GET |
/alerts |
Recent anomaly alerts / alertes récentes |
GET |
/media |
Mic/camera usage state / état micro/caméra |
GET |
/watchlist · POST
|
Watched hosts/processes / cibles surveillées |
| Method | Path | Description |
|---|---|---|
GET |
/history/host/{ip} |
Per-minute aggregates for a host / agrégats par minute |
GET |
/history/process/{name} |
Same per process / idem par processus |
GET |
/history/top_processes |
Top processes by volume / top processus par volume |
| Method | Path | Description |
|---|---|---|
GET |
/capture/status |
Capture state, interface, counters / état, interface, compteurs |
GET |
/capture/interfaces |
List capturable interfaces / interfaces capturables |
POST |
/capture/start · /capture/stop
|
Start/stop / démarrer/arrêter |
POST |
/capture/interface |
Switch interface / changer d'interface |
POST |
/capture/ports · /capture/processes · /capture/whitelist
|
Filters / filtres |
| Method | Path | Description |
|---|---|---|
GET/POST/DELETE
|
/alerts/ignore |
Suppression rules / règles de suppression |
GET/POST
|
/alerts/rules · DELETE /alerts/rules/{id} · POST …/{id}/toggle
|
Custom detection rules / règles de détection |
POST |
/alerts/rules/sigma |
Import a Sigma rule (documented subset, skipped reasons) / importer une règle Sigma |
GET |
/alerts/rules/yaral |
Export rules as YARA-L (Chronicle) / exporter en YARA-L |
| Method | Path | Description |
|---|---|---|
GET |
/firewall/status · /firewall/rules
|
State + rules / état + règles |
POST |
/firewall/rules · DELETE /firewall/rules/{id} · POST …/{id}/toggle
|
Manage rules (IP/CIDR/domain/process/port/asn/country, block/throttle) / gérer les règles |
POST |
/firewall/lockdown |
Panic switch — block all outbound / couper tout le sortant |
GET/POST
|
/firewall/profiles · /firewall/profile
|
Named rule sets / jeux de règles nommés |
POST |
/firewall/blocklist |
Import a feed — {url|path, kind:"domain"|"ip", action} / importer un flux |
| Method | Path | Description |
|---|---|---|
POST |
/ingest/enroll |
Enroll an agent — {name} → one-shot sagt_… token (master token auth) / enrôler — jeton unique sagt_…
|
POST |
/ingest/events |
Agent event batch — snitch-agent/1 contract, bounded / lot d'événements, contrat snitch-agent/1
|
GET |
/ingest/agents · POST /ingest/revoke
|
List / revoke agent tokens / lister / révoquer |
| Method | Path | Description |
|---|---|---|
GET/POST
|
/remote/pairing |
Pair a headless peer / appairer un pair |
GET |
/remote/fleet |
Merged hardening audit of every peer / audit fusionné des pairs |
GET/POST
|
/remote/ioc_sync |
IOC gossip between configured peers / gossip d'IOC entre pairs |
| Method | Path | Description |
|---|---|---|
GET |
/security/audit |
Host hardening report / rapport de durcissement |
GET/POST
|
/security/explain |
Structured alert explanation (SLM-backed, loopback only) / explication d'alerte |
GET/POST
|
/security/ask · /security/ask/verdict
|
Ask-on-first-connect verdicts (NFQUEUE) / verdicts ask-mode |
GET/POST
|
/security/ebpf · /security/ebpf_enforce · /security/ebpf/block · /security/ebpf/isolate
|
eBPF probe + cgroup enforcement / sonde eBPF + enforcement cgroup |
GET/POST
|
/security/integrity · /security/integrity/check
|
Merkle module integrity / intégrité Merkle des modules |
POST |
/security/deep_inspect · /security/hollow · /security/perf · /security/sandbox
|
Frida inspect, hollowing, PMU counters, zero-egress sandbox / inspection Frida, hollowing, compteurs PMU, sandbox zéro-égress |
GET/POST
|
/security/iocpack · /security/iocpack/import
|
Deniable IOC export (Bloom/Merkle) / export d'IOC déniable |
GET |
/security/sinkhole |
Sinkhole responder status / état du répondeur sinkhole |
GET |
/security/ti · POST /security/threat_check
|
Threat-intel status + manual check / état TI + vérification |
GET |
/security/slm |
Local SLM backend status / état du backend SLM |
POST |
/processes/kill · /processes/suspend
|
Process actions / actions processus |
| Method | Path | Description |
|---|---|---|
GET |
/forensics/export |
Timeline + process tree + SHA-256 — format=ecs emits NDJSON Elastic Common Schema / export — format=ecs en NDJSON ECS |
GET |
/forensics/pcap |
Bounded raw-frame ring as .pcap (Wireshark-ready) / anneau de trames en .pcap
|
| Method | Path | Description |
|---|---|---|
GET/POST
|
/settings |
Read/update settings — snitch.toml/$SNITCH_CONFIG overrides them declaratively / réglages — surcharge déclarative par snitch.toml
|
GET |
/diagnostics |
Runtime snapshot, no secrets / instantané sans secrets |
GET |
/geo/status · POST /geo/download
|
GeoIP state / download (only opt-in outbound call) / état GeoIP / téléchargement (seul appel sortant opt-in) |
POST |
/shutdown |
Graceful shutdown / arrêt propre |
The UI consumes one WS stream. Messages are JSON with a type field:
type |
Payload | Cadence |
|---|---|---|
init |
Full snapshot (graph, settings, capture state) | On connect / à la connexion |
batch |
New/updated nodes+edges, counters, alerts | ~every 250 ms / toutes les ~250 ms |
node_update |
Single node update / mise à jour d'un nœud | As needed / à la demande |
nodes_removed |
Pruned node ids / nœuds purgés | |
alert |
New anomaly alert / nouvelle alerte | |
device_update |
LAN device seen/changed / appareil LAN | |
media |
Mic/camera state / micro/caméra | |
capture_status |
Capture started/stopped / capture |
TOKEN=$(cat data/api_token.txt)
# Graph snapshot / instantané du graphe
curl -H "X-Snitch-Token: $TOKEN" http://127.0.0.1:8000/graph
# ECS export for a SIEM / export ECS pour un SIEM
curl -H "X-Snitch-Token: $TOKEN" \
"http://127.0.0.1:8000/forensics/export?format=ecs" > events.ndjson
# Enroll an agent / enrôler un agent
curl -X POST -H "X-Snitch-Token: $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"web-01"}' http://127.0.0.1:8000/ingest/enroll
# → {"token":"sagt_…"} (one-shot display / affichage unique)Snitch Wiki
Getting started / Démarrage
Docs (EN + FR)
- Architecture
- Security & Privacy / Sécurité & confidentialité
- API Reference / Référence
- Fleet & Agent / Flotte & agent
Help / Aide (EN + FR)
Project / Projet