The policy section of attesta.yaml controls how Attesta responds to different risk levels. It defines the challenge type for each risk tier, minimum review durations, multi-party approval requirements, and what happens when things go wrong.
The minimum_review_seconds setting enforces a mandatory waiting period before an operator can approve an action. This is Attesta’s primary defense against rubber-stamping — approving actions without actually reading them.
policy: minimum_review_seconds: low: 0 # Auto-approved, no delay needed medium: 3 # Must wait 3 seconds before pressing "y" high: 10 # Must wait 10 seconds before answering quiz critical: 30 # Must wait 30 seconds per approver
The timer starts when the challenge is first presented. If the operator attempts to approve before the timer expires, the approval is rejected and they must wait.
Custom domain profiles can set even longer review times via the min_review_overrides field. For example, a compliance-focused profile might override CRITICAL to 60 seconds and HIGH to 20 seconds.
The Policy dataclass exposes minimum review times through the min_review_time() method:
from attesta.config.loader import Policyfrom attesta.core.types import RiskLevelpolicy = Policy()# Get minimum review time for a risk levelreview_time = policy.min_review_time(RiskLevel.HIGH) # Returns 10# Or use the dict directlypolicy.minimum_review_seconds # {"low": 0, "medium": 3, "high": 10, "critical": 30}
The require_multi_party setting specifies how many independent approvers are needed for each risk level. Only risk levels listed in this mapping trigger multi-party review.
policy: require_multi_party: critical: 2 # Two independent approvers high: 2 # Optionally require 2 approvers for HIGH too
When multi-party approval is required, each approver completes a different sub-challenge in a rotating pattern: teach-back, then quiz, then confirm. This ensures that at least one approver demonstrates genuine comprehension.
The critical_always_verify flag on the Policy dataclass is hardcoded to True and cannot be disabled via configuration. CRITICAL actions always require full verification regardless of trust score. This is a safety invariant.
The fail_mode setting controls what happens when a challenge times out or the system cannot reach a human operator.
deny (default)
allow
escalate
policy: fail_mode: deny
The action is blocked with verdict TIMED_OUT. The gate decorator raises AttestaDenied. This is the safest option and the recommended setting for production.
policy: fail_mode: allow
The action is permitted with verdict APPROVED (timeout metadata is still recorded). Use only in local development.
policy: fail_mode: escalate
The action is blocked with verdict ESCALATED, and an escalated lifecycle event is emitted. Use this when you have a fallback escalation workflow listening to that event.
Never deploy with fail_mode: allow in production. If a timeout or network issue prevents human review, the action will execute without any approval — this defeats the entire purpose of Attesta.
The timeout_seconds setting defines the maximum time (in seconds) to wait for the operator to complete a challenge. After this duration, the fail_mode policy takes effect.
