Dépannage

Guide de dépannage pour EnforceCore — erreurs courantes, étapes de débogage et FAQ.

Erreurs Courantes

EnforcementViolation / ToolDeniedError

enforcecore.exceptions.ToolDeniedError: Tool 'execute_shell' is denied by policy 'strict'

Cause : L'outil est dans denied_tools ou n'est pas dans allowed_tools.

Résolution :

1. Vérifiez votre fichier de politique (section rules.allowed_tools / rules.denied_tools)
2. Exécutez enforcecore dry-run --policy policy.yaml --tool execute_shell pour tester
3. Vérifiez la priorité deny-sur-allow — un outil dans les deux listes est toujours bloqué

PolicyLoadError

enforcecore.exceptions.PolicyLoadError: Policy file not found: policies/agent.yaml

Résolution : Vérifiez le chemin du fichier. EnforceCore résout les chemins relatifs depuis le répertoire de travail courant. Utilisez des chemins absolus ou ENFORCECORE_DEFAULT_POLICY pour éviter les ambiguïtés.

CostLimitError

enforcecore.exceptions.CostLimitError: Budget exceeded: $5.12 / $5.00

Résolution : Augmentez ENFORCECORE_COST_BUDGET_USD ou le champ resource_limits.max_cost_usd dans votre politique.

ContentViolationError

enforcecore.exceptions.ContentViolationError: Content rule violated: shell_injection

Cause : Les arguments de l'outil contiennent un pattern détecté comme dangereux (injection shell, traversée de chemin, injection SQL ou exécution de code).

Résolution : Vérifiez les entrées de votre outil. Si c'est un faux positif, examinez les patterns avec enforcecore inspect policy.yaml.

RateLimitError

enforcecore.exceptions.RateLimitError: Rate limit exceeded for tool 'search_web': 11/10 in 60s window

Résolution : Ajustez rate_limits.global_rpm ou les limites par outil dans votre politique.

AuditError — Échec de Vérification

enforcecore.exceptions.AuditError: Chain verification failed at entry 42

Cause : La piste d'audit a été altérée (entrée modifiée, supprimée ou réordonnée).

Résolution :

1. Exécutez enforcecore verify audit.jsonl pour identifier les entrées corrompues
2. Si vous utilisez witness, exécutez verify_with_witness() pour identifier les divergences
3. Les fichiers d'audit avec immutable=True sont protégés au niveau OS

ImmutableError

enforcecore.exceptions.ImmutableError: Failed to set append-only flag: permission denied

Cause : immutable=True est activé mais le processus n'a pas les permissions requises.

Résolution :

• Linux : Ajoutez CAP_LINUX_IMMUTABLE au processus ou au conteneur Docker (--cap-add LINUX_IMMUTABLE)
• macOS : La commande chflags uappend fonctionne au niveau utilisateur — vérifiez les permissions du fichier
• Windows : Non supporté — immutable=True émet un avertissement et continue

Étapes de Débogage

1. Valider votre politique

enforcecore validate policies/strict.yaml

Vérifie la syntaxe YAML, la conformité au schéma Pydantic et la cohérence des règles.

2. Dry-run d'un outil

enforcecore dry-run --policy policy.yaml --tool search_web

Simule l'enforcement sans exécuter l'appel. Affiche la décision et les raisons.

3. Inspecter les règles chargées

enforcecore inspect policies/strict.yaml

Affiche les outils autorisés/refusés, les catégories PII actives, les règles de contenu et les limites.

4. Vérifier la piste d'audit

enforcecore verify audit.jsonl

Vérifie l'intégrité de la chaîne Merkle SHA-256.

5. Activer les logs de débogage

ENFORCECORE_LOG_LEVEL=DEBUG python your_agent.py

Active les logs structurés détaillés pour chaque étape du pipeline d'enforcement.

6. Vérifier les threads orphelins

guard = enforcer.guard
print(guard.leaked_thread_count)  # 0 = sain, > 0 = fuites détectées

FAQ

EnforceCore remplace-t-il le sandboxing conteneur ?

Non. EnforceCore opère à la couche sémantique applicative (L3) — il comprend les appels d'outils, les données personnelles et les budgets de coût. Le sandboxing conteneur (Docker, gVisor), la sécurité OS (seccomp, AppArmor, SELinux) et le sandboxing réseau opèrent à L1–L2. Utilisez les deux ensemble pour une défense en profondeur. Voir le tableau de défense en profondeur.

Comment fonctionne la priorité deny-sur-allow ?

Si un outil apparaît dans denied_tools ET allowed_tools, il est toujours bloqué. C'est l'invariant formel P4. Voir les Invariants Formels.

L'audit est-il vraiment inviolable ?

La chaîne Merkle SHA-256 détecte toute modification. Pour une protection supplémentaire :

• immutable=True active la protection append-only au niveau OS
• Les backends witness publient les hashes vers un emplacement séparé pour la détection de reconstruction de chaîne
• Voir la section Auditeur Merkle pour les détails.

Quel est le surcoût de performance ?

~0,056 ms (P50) par appel, négligeable par rapport à la latence des outils (100 ms–10 s). Voir la Suite d'Évaluation pour les benchmarks par composant.

EnforceCore fonctionne-t-il avec mon framework ?

Oui — il fonctionne avec tout code Python. Des adaptateurs natifs existent pour LangGraph, CrewAI et AutoGen. Voir les Intégrations.

Comment configurer la rédaction PII ?

Voir la section Rédacteur PII pour les catégories, stratégies et la protection unicode.

Comment configurer les variables d'environnement ?

Les 18 variables sont documentées dans la Référence API.

Références Rapides