Référence API

EnforceCore expose 30 symboles publics Tier 1 depuis le package enforcecore — le contrat stable et gelé. 80 symboles Tier 2 supplémentaires restent importables pour la compatibilité ascendante mais ne sont pas couverts par la garantie de stabilité.

Stabilité API : Les 30 symboles Tier 1 sont gelés depuis v1.0.0b1. Aucun ajout ni retrait jusqu'à v2.0.0. Les imports Tier 2 émettent des avertissements de dépréciation.

Symboles Tier 1 (Stables — 30)

API Principale

Décorateur @enforce()

from enforcecore import enforce

@enforce(policy="policies/agent.yaml")
async def search_web(query: str) -> str:
    return await api.search(query)

# Politique inline
@enforce(
    allowed_tools=["search_web", "calculator"],
    pii_redaction=True,
    max_cost_usd=5.0,
)
async def my_tool(args: dict) -> str: ...

Classe Enforcer

from enforcecore import Enforcer, Policy

enforcer = Enforcer.from_file("policy.yaml")
result = enforcer.enforce_sync(search_fn, "query", tool_name="search_web")
result = await enforcer.enforce_async(search_fn, "query", tool_name="search_web")

Note : guard_sync() et guard_async() ont été supprimés en v1.0.16a1. Utilisez enforce_sync() / enforce_async() à la place.

API Politique

from enforcecore import Policy, load_policy

policy = load_policy("policies/strict.yaml")

policy = Policy(
    name="ma-politique",
    rules={
        "allowed_tools": ["search", "calculator"],
        "pii_redaction": {"enabled": True, "categories": ["email", "phone"]},
    },
    on_violation="block",
)

API Rédacteur

Catégories PII

Stratégies de Rédaction

from enforcecore.redactor import Redactor

redactor = Redactor(categories=["email", "phone"])
result = redactor.redact("Appeler 555-123-4567 ou john@example.com")
print(result.text)   # "Appeler <PHONE> ou <EMAIL>"

API Auditeur

from enforcecore import Auditor, verify_trail, load_trail

auditor = Auditor(output_path="audit.jsonl")
e1 = auditor.record(tool_name="search_web", policy_name="default", decision="allowed")

result = verify_trail("audit.jsonl")
print(result.is_valid)

Backends d'Audit Pluggables

from enforcecore import JsonlBackend, NullBackend, CallbackBackend, MultiBackend

callback = CallbackBackend(on_event=lambda entry: send_to_datadog(entry))
multi = MultiBackend([JsonlBackend("audit.jsonl"), callback])

API Witness

Backends witness à hash uniquement pour la détection de falsification au-delà de la vérification Merkle.

from enforcecore.auditor.witness import CallbackWitness, FileWitness, LogWitness

witness = FileWitness(path="/var/log/enforcecore/witness.jsonl")

auditor = Auditor(
    output_path="audit.jsonl",
    witness=witness,
)

Vérification Witness

from enforcecore.auditor.witness import verify_with_witness

result = verify_with_witness(
    trail_path="audit.jsonl",
    witness_path="/secure/witness.jsonl",
)
print(result.is_valid)
print(result.mismatches)

Witness piloté par Settings (v1.0.0b5)

ENFORCECORE_AUDIT_WITNESS_FILE=/var/log/enforcecore/witness.jsonl

API Immutable

Protection append-only au niveau OS pour les fichiers d'audit.

auditor = Auditor(output_path="audit.jsonl", immutable=True)

ENFORCECORE_AUDIT_IMMUTABLE=true

API Guard

from enforcecore.guard import ResourceGuard, CostTracker, KillSwitch

tracker = CostTracker(budget_usd=10.0)
tracker.record(0.05)
tracker.check_budget()

guard = ResourceGuard(cost_tracker=tracker)
print(guard.leaked_thread_count)  # 0 = sain

API Scanner de Secrets

from enforcecore import SecretScanner, PatternRegistry

scanner = SecretScanner()
secrets = scanner.scan("aws_key = AKIAIOSFODNN7EXAMPLE")

# 11 catégories intégrées : aws_key, github_token, generic_api_key,
# bearer_jwt, private_key, password_url, gcp_service_account,
# azure_connection_string, database_uri, ssh_private_key, slack_token

API Règles de Contenu

from enforcecore import RuleEngine, get_builtin_rules

engine = RuleEngine(rules=get_builtin_rules())
violations = engine.check("os.system('rm -rf /')")
# 4 catégories : shell_injection, path_traversal, sql_injection, code_execution

API Rate Limiter

from enforcecore import RateLimiter, RateLimit

limiter = RateLimiter(
    per_tool=RateLimit(max_calls=10, window_seconds=60),
    global_limit=RateLimit(max_calls=50, window_seconds=60),
)
limiter.check("search_web")  # Lève RateLimitError si dépassé

API Vérificateur de Domaines

from enforcecore import DomainChecker

checker = DomainChecker(
    allowed=["api.example.com", "*.trusted.io"],
    denied=["*.evil.com"],
)
checker.check("api.example.com")  # OK
checker.check("hack.evil.com")    # Lève DomainDeniedError

API Hooks

from enforcecore import on_pre_call, on_post_call, on_violation, on_redaction

@on_violation
def alerter(ctx):
    send_alert(f"⚠️ {ctx.tool_name} bloqué : {ctx.violation_type}")

@on_redaction
def suivre_pii(ctx):
    metrics.increment("pii_redacted", ctx.redaction_count)

API Observabilité

from enforcecore import EnforceCoreMetrics, EnforceCoreInstrumentor

metrics = EnforceCoreMetrics()
instrumentor = EnforceCoreInstrumentor()
instrumentor.instrument()

API Hardening

from enforcecore import validate_tool_name, check_input_size, deep_redact
from enforcecore import get_enforcement_depth, get_enforcement_chain
from enforcecore import prepare_for_detection  # Pipeline unicode complet

Hiérarchie des Exceptions

EnforceCoreError              # Exception de base
├── PolicyError
│   ├── PolicyLoadError       # Fichier introuvable / illisible
│   ├── PolicyValidationError # Violation de schéma
│   └── PolicyEvaluationError # Erreur durant évaluation
├── EnforcementViolation
│   ├── ToolDeniedError       # Outil non autorisé
│   ├── DomainDeniedError     # Domaine réseau bloqué
│   ├── CostLimitError        # Budget dépassé
│   ├── RateLimitError        # Limite de débit dépassée
│   ├── ContentViolationError # Règle de contenu violée
│   └── ResourceLimitError    # Limite de ressource dépassée
├── RedactionError            # Erreur PII (fail-closed)
├── AuditError                # Erreur audit (fail-closed)
├── HardeningError
│   ├── InvalidToolNameError  # Nom d'outil invalide
│   ├── InputTooLargeError    # Payload trop volumineux
│   └── EnforcementDepthError # Profondeur récursive dépassée
└── GuardError                # Échec resource guard

CLI

enforcecore info                          # Version et plateforme
enforcecore validate policies/strict.yaml # Valider une politique
enforcecore verify audit.jsonl            # Vérifier une piste d'audit
enforcecore eval --scenarios all          # Suite d'évaluation
enforcecore dry-run --policy policy.yaml --tool search_web  # Dry-run
enforcecore inspect policies/strict.yaml  # Inspecter les règles

Variables d'Environnement

Toutes les configurations via variables d'environnement (via pydantic-settings). Référence canonique — les 18 variables :