Docs
GitHub · ★ 174Référence
La surface complète de la version ouverte : features Cargo, la CLI en un coup d’œil, chaque variable d’environnement, l’API HTTP et les portées des clés d’API. Reflète le dépôt ; GitHub reste la copie de référence.
Features Cargo (iaga-sentinel-core)
| Feature | Par défaut | Ajoute |
|---|---|---|
sqlite | on | Backend SQLite pour l’audit + les reçus. |
postgres | off | Backend Postgres. |
receipts | on | Reçus signés en Ed25519 et chaînés par hachage. |
dictum | on | Parseur + évaluateur de politiques Dictum + iaga policy … |
reasoning | on | Échafaudage du plan de raisonnement + iaga reasoning info. |
ml | off | Backend ML tract-onnx ; sur activation, +~5 Mo de binaire, +~2 min de compilation à froid. |
kernel | on | Noyau d’application + iaga run + iaga kernel status. |
linux-bpf | off | Échafaudage eBPF/LSM Linux + API ringbuf. Le véritable chargeur Aya-rs relève d’IAGA Sentinel Enterprise. |
cost-control | on | Mesure locale des dépenses LLM, /v1/cost/*, iaga cost, budgets de session, cache de réponses MCP. Activé par défaut depuis la 1.8.1 ; les reçus restent identiques à l’octet près quand aucun usage n’est signalé. |
plugin-attestation | off | Vérification hors ligne du bundle Sigstore + du SBOM CycloneDX + iaga plugins verify. |
dictum-wasm | off | MVP de génération de code Dictum vers WASM + iaga policy compile. Le vérificateur de types Hindley-Milner lui-même n’est pas conditionné par ce feature ; la sous-commande iaga policy requiert le feature dictum, activé par défaut. |
otel-receipts | off | Émet chaque reçu signé comme span OpenTelemetry sur /v1/telemetry/spans et /v1/telemetry/export, avec iaga.receipt.id, iaga.chain.head, iaga.policy.verdict et iaga.is_authoritative. Aucune dépendance nouvelle. |
plugin-manifest-signing | off | Manifestes de plugins signés en Ed25519, vérifiés au chargement contre des clés de confiance, plus iaga plugins sign-manifest et verify-manifest. Orthogonal à plugin-attestation. |
default = ["demo", "sqlite", "receipts", "dictum", "reasoning", "kernel", "cost-control"] depuis la 1.8.1. cargo build --no-default-features reproduit le contrat d’échange antérieur, sans cost-control.
Le vérificateur autonome iaga-verify (crate iaga-sentinel-verify) est un binaire séparé, léger en dépendances, et l’artefact que vous pouvez mettre devant un auditeur. Compilez-le de façon reproductible :
cargo build --release -p iaga-sentinel-verify --no-default-features --features verify-onlyLa CLI en un coup d’œil
| Commande | Ce qu’elle fait |
|---|---|
iaga serve [--seed-demo] [--port N] [--policy file.dictum] | Lance le sidecar : API, tableau de bord, signataire, magasin d’audit. Depuis la 1.9.2, --policy valide chaque chemin de contexte référencé par une politique et sort en code 2 sur un chemin inconnu, en nommant le chemin et les racines valides. |
iaga inspect <payload.json> | Verdict du pipeline en un seul appel, depuis la CLI. |
iaga run --agent-id <id> -- <cmd> [args…] | Lance un processus enfant sous gouvernance, avec effacement des secrets de l’environnement. |
iaga replay [--list] [<run_id>] [--verify-only] [--re-execute] [--export f.json] | Vérifie ou rejoue les chaînes de reçus signés. |
iaga policy check/lint/test/compile <file.dictum> | Vérifie les types, valide, exécute à blanc ou compile du Dictum. |
iaga gen-key --label <name> [--scope agent] | Génère une clé d’API (admin par défaut). |
iaga audit [--limit N] [--format json] | Affiche la piste d’audit. |
iaga cost [summary|by-model|by-agent|by-tool|budget] | Vues des dépenses (cost-control, activé par défaut). |
iaga proxy --agent-id <id> --command <cmd> [args…] | Proxy de gouvernance MCP transparent. |
iaga mcp-server | Expose les outils de gouvernance via MCP stdio. |
iaga mcp-doctor <endpoint> | Contrôle de santé de n’importe quel point d’entrée MCP : handshake, schéma des outils, would-block. |
iaga plugins list/validate/verify/sign-manifest/verify-manifest | Cycle de vie des plugins WASM. |
iaga kernel status / iaga reasoning info | Rapports de posture honnêtes. |
iaga import/export/migrate/validate | Gestion de la configuration des politiques et de la base de données. |
iaga-verify <chain.json> [--key <hex>] | Vérification hors ligne autonome des reçus. |
Variables d’environnement
| Variable | Effet |
|---|---|
IAGA_SENTINEL_OPEN_MODE | true désactive l’authentification (réservé aux parcours guidés). |
PORT | Port d’écoute (4010 par défaut) ; --port prévaut. |
DATABASE_URL | postgres://… bascule le backend (avec --features postgres). |
IAGA_SENTINEL_SIGNER_KEY_PATH | BYOK : chemin d’un fichier de clé de signature Ed25519 de 32 octets. |
IAGA_SENTINEL_RECEIPT_CAPTURE | 1 capture les entrées du pipeline pour replay --re-execute. |
IAGA_SENTINEL_RECEIPT_FAIL_CLOSED | 1 fait échouer l’appel quand un reçu ne peut pas être signé, au lieu de renvoyer un verdict sans preuve (depuis la 1.9.0, désactivé par défaut, si bien que le contrat d’échange antérieur à la 1.9.0 est inchangé). La ligne d’audit est toujours écrite avant le reçu, si bien qu’un plantage entre les deux peut encore les faire diverger. |
IAGA_SENTINEL_ENV_DENYLIST | Fichier TOML étendant la liste d’exclusion de l’effacement des secrets pour iaga run. |
IAGA_SENTINEL_ENV_DENYLIST_STRICT | 1 fait échouer les lancements en fail-closed quand le TOML de la liste d’exclusion est illisible ou malformé (par défaut : avertir et utiliser les valeurs intégrées). |
IAGA_SENTINEL_PLUGIN_DIR | Répertoire des plugins WASM (./plugins par défaut). |
IAGA_SENTINEL_REASONING_MODELS | Chemins des modèles ONNX pour le feature ml. |
IAGA_SENTINEL_SESSION_BUDGET_USD | Plafond de dépenses par session (avec cost-control). |
IAGA_SENTINEL_PRICING_FILE | Remplace la table de tarification intégrée. |
IAGA_SENTINEL_LOG_LEVEL / _LOG_FORMAT | Filtre de traçage et sortie text/json. |
IAGA_SENTINEL_DEFAULT_MODE | Mode de gouvernance par défaut pour les espaces de travail sans correspondance. |
IAGA_SENTINEL_NHI_MASTER_SEED | Graine déterministe pour les clés d’identité NHI. |
IAGA_SENTINEL_HOST | Interface sur laquelle le serveur écoute (0.0.0.0 par défaut). |
IAGA_SENTINEL_CORS_ORIGINS | Liste d’autorisation CORS séparée par des virgules (non définie = Any permissif, le comportement antérieur à la 1.5.2). |
IAGA_SENTINEL_AUTH_CACHE_TTL_MS | TTL du cache des clés d’API vérifiées (60000 par défaut ; 0 le désactive et vérifie chaque requête). |
IAGA_SENTINEL_MAX_SESSIONS / _SESSION_TTL_MS | Plafond du magasin de graphes de session (10000 par défaut) et TTL (30 min par défaut). |
IAGA_SENTINEL_BLOCK_COOLDOWN_MS / _MAX_BLOCK_COUNT | Délai de refroidissement des sessions bloquées (60 s par défaut) et nombre d’avertissements avant blocage permanent (3 par défaut). |
IAGA_SENTINEL_CLEANUP_INTERVAL_SECS / _CLEANUP_TTL_SECS | Cadence du nettoyage TTL en arrière-plan (300 par défaut) et seuil d’ancienneté (3600 par défaut). |
IAGA_SENTINEL_COST_CACHE_TTL_MS / _COST_CACHE_MAX_ENTRIES | TTL du cache de réponses (5 min par défaut) et plafond de taille (4096 par défaut), avec cost-control. |
Surface HTTP
Les corps de requête et la plupart des réponses suivent le contrat d’échange en camelCase. Sur /v1/inspect, les champs de premier niveau sont agentId, framework et action ; l’outil et le type vivent à l’intérieur, sous action.toolName et action.type. Hors mode ouvert, les requêtes exigent Authorization: Bearer <key>. Quelques réponses sont en snake_case à dessein : le flux d’événements SSE, le résumé d’exécution de /v1/receipts (run_id, receipt_count, last_timestamp, terminal_verdict) et /v1/rate-limit/status.
| Point d’entrée | Ce qu’il fait |
|---|---|
POST /v1/inspect | Verdict de gouvernance pour une action ; le point d’entrée unique sur lequel tout s’intègre. |
GET|POST /v1/auth/keys · DELETE /v1/auth/keys/{id} | Gestion des clés d’API (portée admin). |
GET /v1/reviews · POST /v1/reviews/{id} | File de revue : lister les éléments, approuver ou rejeter. |
GET /v1/sandbox/pending | Exécutions à blanc en bac à sable avec analyse d’impact, en attente d’un opérateur. |
GET /v1/receipts · GET /v1/receipts/{run_id} | Liste les exécutions ; lit la chaîne de reçus signés d’une exécution. |
GET /v1/cost/summary · /by-model · /by-agent · /by-tool · /over-time?bucket= | Agrégation des dépenses (cost-control). |
POST /v1/webhooks · GET /v1/webhooks/dlq | Enregistre des points d’entrée de webhooks ; inspecte et relance la file des lettres mortes. |
GET /v1/events/stream | Flux en direct (server-sent events) de chaque verdict, création de revue et résolution. |
GET /v1/policy/overlay | Hachage du bundle Dictum chargé et nombre de politiques. |
POST /v1/plugins/reload | Recharge le registre des plugins WASM (portée admin). |
GET /v1/telemetry/spans · /v1/telemetry/export | Les reçus signés comme spans OpenTelemetry (otel-receipts). |
POST /v1/risk/feedback · POST /v1/risk/weights/reset | Pondérations de risque adaptatives : le retour d’information les déplace ; reset restaure les valeurs par défaut (admin). |
GET /health | Vivacité ; renvoie 200 dans les 10 secondes environ suivant le premier démarrage. |
Portées des clés d’API
Les clés d’API portent une portée depuis la 1.5.2 : admin (par défaut — accès complet, identique aux clés antérieures à la 1.5.2) ou agent (iaga gen-key --scope agent), qui peut piloter la surface de gouvernance mais pas gérer les clés, les webhooks, la configuration de limitation de débit, le renseignement sur les menaces ni les rechargements de plugins.
Notez que les pondérations de risque adaptatives sont globales au processus, tous agents confondus : un retour envoyé à /v1/risk/feedback les déplace pour chaque agent de l’instance, et POST /v1/risk/weights/reset (admin) restaure les valeurs par défaut.
Pour aller plus loin
- Tutoriel : chaque surface ci-dessus, parcourue de bout en bout.
- Architecture : les crates derrière ces features.
- Registres de décision d’architecture : docs/adr sur GitHub — 22 ADR (0001 à 0023, sans 0009), listés sur la page Architecture.
- Documents du projet sur GitHub : SECURITY.md (signalement de vulnérabilités), DATA_HANDLING.md (traitement des données et confidentialité), CONTRIBUTING.md, et CHANGELOG.md (notes de version).