Skip to content

API Reference

MoneyLisa edited this page Oct 22, 2026 · 2 revisions

API Reference / Référence API

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.

REST endpoints

Traffic & topology / Trafic & topologie

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

History / Historique

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

Capture control / Contrôle de la capture

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

Alerts & rules / Alertes & règles

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

Firewall / Pare-feu

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

Agent ingest / Ingestion d'agents

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

Remote & fleet / À distance & flotte

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

Security research / Recherche sécurité

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

Forensics / Forensique

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

Settings & system / Réglages & système

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

WebSocket — /ws?token=<TOKEN>

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

Examples / Exemples

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

  • Installation — EN · FR
  • Usage / Utilisation — EN · FR

Docs (EN + FR)

Help / Aide (EN + FR)

Project / Projet

Clone this wiki locally