Configuration Reference - TealTiger Docs

Quick Start

Zero-Config (OWASP Pack)

TypeScript
Python

import { TealEngine } from 'tealtiger';

const engine = new TealEngine({
  policy_packs: ['owasp-agentic-top10']
});

from tealtiger import TealEngine

engine = TealEngine({"policy_packs": ["owasp-agentic-top10"]})

Loads all 10 OWASP Agentic controls with sensible defaults, MONITOR mode, and fail-closed behavior.

Custom Configuration

TypeScript
Python

import { TealEngine } from 'tealtiger';

const engine = new TealEngine({
  policy_packs: ['owasp-agentic-top10'],
  mode: 'ENFORCE',
  freeze_rules: [{ id: 'no-prod-deploy', match: { action_class: 'PRODUCTION_DEPLOY' }, reason: 'Change freeze' }],
  nhi_inventory: { agents: myAgentRegistry },
  automation_levels: [{ match: { risk_above: 0.8 }, automation_level: 'approval_required' }],
  cost_governance: { governance_limits: { per_request_max: 0.50, per_daily_max: 100 } },
  response_hooks: [{ id: 'slack-alert', trigger: 'policy_violation', endpoint: 'https://hooks.slack.com/...' }]
});

from tealtiger import TealEngine

engine = TealEngine({
    "policy_packs": ["owasp-agentic-top10"],
    "mode": "ENFORCE",
    "freeze_rules": [{"id": "no-prod-deploy", "match": {"action_class": "PRODUCTION_DEPLOY"}, "reason": "Change freeze"}],
    "automation_levels": [{"match": {"risk_above": 0.8}, "automation_level": "approval_required"}],
    "cost_governance": {"governance_limits": {"per_request_max": 0.50, "per_daily_max": 100}}
})

TealEngineOptions

The full v1.3 options interface. All fields are optional — absence preserves v1.2 behavior.

interface TealEngineOptions {
  // Policy sources
  policy_packs?: string[];
  policies?: PolicyRule[];
  bundle?: PolicyBundle;
  // Enforcement
  mode?: 'ENFORCE' | 'MONITOR' | 'REPORT_ONLY';
  plan_only_mode?: boolean;
  // Safety rails
  freeze_rules?: FreezeRule[];
  automation_levels?: AutomationLevelRule[];
  // Identity
  nhi_inventory?: NHIInventory;
  zsp_config?: ZSPConfig;
  attestation_config?: AttestationConfig;
  // Cost governance (governance-owned, overrides app config)
  cost_governance?: CostGovernanceConfig;
  // Modules
  classifier?: ClassifierConfig;
  drift?: DriftConfig;
  temporal?: TemporalConfig;
  state?: StateConfig;
  flow?: FlowConfig;
  proof?: ProofConfig;
  // Observability
  response_hooks?: ResponseHookConfig[];
  otel_config?: OTelConfig;
  audit?: AuditConfig;
  logging?: LoggingConfig;
  // Behavior
  fail_behavior?: 'fail_closed' | 'fail_open';
}

Policy Configuration

Policy Rules

Each rule maps a condition to an action with an automation level:

policies: [{
  id: 'block-pii-in-output',
  control_id: 'GUARD.PII.OUTPUT.001',
  match: { event_type: 'output', content_contains: 'pii' },
  action: 'DENY',
  automation_level: 'auto_deny',
  reason_code: 'PII_IN_OUTPUT'
}]

Automation Levels

Level	Behavior
`auto_allow`	Return ALLOW immediately
`auto_deny`	Return DENY immediately
`auto_sanitize`	Return MODIFY with sanitized content
`approval_required`	Return PENDING until external approval

automation_levels: [
  { match: { action_class: 'READ_ONLY' }, automation_level: 'auto_allow' },
  { match: { action_class: 'CODE_CHANGE' }, automation_level: 'approval_required' },
  { match: { risk_above: 0.9 }, automation_level: 'auto_deny' }
]

Policy Matchers

interface PolicyMatcher {
  action_class?: string;        // 'CODE_CHANGE', 'TOOL_INVOKE', etc.
  event_type?: string;          // 'input' | 'output' | 'tool_call'
  tool_name?: string;
  risk_above?: number;          // 0.0 - 1.0
  environment?: string;
  agent_id?: string;
}

FREEZE Rules Configuration

FREEZE rules are immutable safety controls evaluated before all other policies. They cannot be removed by hot-swap, agent output, or runtime config changes.

freeze_rules: [
  {
    id: 'change-freeze-q4',
    match: { action_class: 'PRODUCTION_DEPLOY' },
    reason: 'Q4 change freeze — no production deploys',
    created_by: '[email protected]',
    immutable: true
  }
]

Semantics:

Evaluated FIRST in pre-evaluation (before NHI, before modules)
Persist across process restarts and bundle hot-swaps
Modification attempts logged as FREEZE_TAMPER_ATTEMPT
Matched actions denied with FREEZE_BLOCK

PLAN_ONLY Mode

Blocks all side-effecting actions while allowing read-only and reasoning actions:

const engine = new TealEngine({ plan_only_mode: true });
// Side-effecting → DENY with PLAN_ONLY_BLOCK

NHI Configuration

Non-Human Identity governance treats AI agents as principals with identity, scope, and revocation.

nhi_inventory: {
  agents: new Map([
    ['agent-codegen-01', {
      agent_id: 'agent-codegen-01',
      owner: 'platform-team',
      capability_scope: ['read:repo', 'invoke:tool:search'],
      environment_constraints: ['staging', 'development'],
      status: 'active'
    }]
  ])
}

Pre-evaluation checks:

Condition	Reason Code
Status `revoked`	`NHI_REVOKED`
Status `suspended`	`NHI_SUSPENDED`
Action outside scope	`NHI_SCOPE_VIOLATION`
Wrong environment	`NHI_ENVIRONMENT_VIOLATION`

Zero Standing Privilege (ZSP)

Every tool/resource access requires a valid JIT grant:

zsp_config: { enabled: true, max_grant_ttl_ms: 300_000 }

Cost Governance Configuration

Cost limits in governance bundles override application-level config. This enforces the separation of duties model — governance teams set limits, developers consume them.

cost_governance: {
  governance_limits: {
    per_request_max: 0.50,
    per_session_max: 5.00,
    per_daily_max: 100.00,
    per_agent_max: 50.00,
    reasoning_token_budget: 32_000
  },
  anomaly: { baseline_window: 100, spike_multiplier: 10, growth_rate_threshold: 0.5 },
  attribution: { emit_format: 'json', include_agent_id: true, include_workflow_id: true }
}

Reason codes: COST_ANOMALY_DETECTED, COST_SPIKE_DETECTED, REASONING_TOKEN_BUDGET_EXCEEDED

Module Configuration

Classifier

Optional ML detection using local ONNX inference. Defaults to regex_only (v1.2 behavior).

classifier: {
  model_path: './models/prompt-injection-v1.onnx',
  ensemble_mode: 'ensemble_union',
  confidence_threshold: 0.5,
  max_tokens: 512
}

Mode	Behavior
`regex_only`	v1.2 compatible, no ML
`ml_only`	Only classifier output
`ensemble_union`	Block if either detects
`ensemble_intersection`	Block only if both detect

Drift Detection

drift: { baseline_window: 500, threshold_sigma: 3, min_samples: 50 }

Temporal Governance

temporal: {
  session_ttl_ms: 3_600_000,
  cooldown_rules: [{ action_class: 'PRODUCTION_DEPLOY', min_interval_ms: 600_000 }],
  time_restrictions: [{ action_class: 'DATABASE_WRITE', allowed_hours: { start: 9, end: 17 }, timezone: 'UTC', allowed_days: [1,2,3,4,5] }]
}

State Governance

state: { max_context_size: 128_000, on_exceed: 'truncate', track_provenance: true, mutation_governance: true }

Flow (Declarative Workflows)

flow: { workflows_dir: './governance/workflows', org_workflows_dir: './governance/org-workflows' }

Post-Evaluation Hooks

Response hooks fire within 100ms of a governance decision. Supports deduplication and rate limiting.

response_hooks: [
  {
    id: 'pagerduty-critical',
    trigger: 'high_risk',
    endpoint: 'https://events.pagerduty.com/v2/enqueue',
    retry_policy: { max_retries: 3, backoff_ms: 1000 },
    dedup_window_ms: 60_000,
    rate_limit: { max_per_minute: 10 }
  }
]

Triggers: policy_violation, high_risk, freeze_tamper

OTel Configuration

otel_config: { enabled: true, endpoint: 'http://localhost:4318', service_name: 'tealtiger-governance' }

Span attributes: tealtiger.decision.action, tealtiger.decision.risk_score, tealtiger.policy.version, tealtiger.agent.id, tealtiger.correlation_id.

Bundle Configuration

Policy bundles implement the separation of duties model: the governance team authors and signs bundles, developers load them at runtime.

Loading a Signed Bundle

TypeScript
Python

import { TealEngine, loadBundle } from 'tealtiger';

const bundle = await loadBundle('./governance/bundle-v2.signed.json');
const engine = new TealEngine({ bundle });

from tealtiger import TealEngine, load_bundle

bundle = load_bundle("./governance/bundle-v2.signed.json")
engine = TealEngine({"bundle": bundle})

Bundle Schema

interface PolicyBundle {
  bundle_version: string;
  requires_sdk: string;            // '^1.3.0'
  hash: string;                    // SHA-256
  signature?: string;              // Ed25519
  policies: PolicyRule[];
  cost_limits?: GovernanceCostLimits;
  freeze_rules?: FreezeRule[];
  fail_behavior: 'fail_closed' | 'fail_open';
}

Integrity Verification

const engine = new TealEngine({
  bundle,
  bundle_verification: { public_key: process.env.GOVERNANCE_PUBLIC_KEY, require_signature: true }
});
// Verification failure → POLICY_BUNDLE_INTEGRITY_FAILED

Hot-Swapping

await engine.loadPolicy(newBundle);
// Validation failure → previous bundle retained, POLICY_BUNDLE_SWAP_FAILED emitted

Environment Variables

Variable	Purpose	Default
`TEALTIGER_MODE`	Enforcement mode	`MONITOR`
`TEALTIGER_LOG_LEVEL`	Log verbosity	`INFO`
`TEALTIGER_BUNDLE_PATH`	Signed policy bundle path	—
`TEALTIGER_OTEL_ENDPOINT`	OTel collector endpoint	—
`TEALTIGER_CLASSIFIER_MODEL`	ONNX model path	—
`GOVERNANCE_PUBLIC_KEY`	Ed25519 key for bundle verification	—
`TEALTIGER_FAIL_BEHAVIOR`	`fail_closed` or `fail_open`	`fail_closed`
`TEALTIGER_PLAN_ONLY`	Enable PLAN_ONLY mode	`false`

Configuration Precedence

Resolved highest priority first:

FREEZE rules — immutable, cannot be overridden
Signed bundle — governance-team-owned limits and policies
Environment variables — deployment-specific overrides
Constructor options — developer-provided config
Defaults — secure defaults (fail-closed, MONITOR mode, regex_only)

This enforces the separation of duties model: governance teams sign bundles with cost limits, freeze rules, and policy baselines. Developers configure modules and hooks. Operations override mode and endpoints via environment variables. Bundle-level settings always take precedence over constructor options.

​Quick Start

​Zero-Config (OWASP Pack)

​Custom Configuration

​TealEngineOptions

​Policy Configuration

​Policy Rules

​Automation Levels

​Policy Matchers

​FREEZE Rules Configuration

​PLAN_ONLY Mode

​NHI Configuration

​Zero Standing Privilege (ZSP)

​Cost Governance Configuration

​Module Configuration

​Classifier

​Drift Detection

​Temporal Governance

​State Governance

​Flow (Declarative Workflows)

​Post-Evaluation Hooks

​OTel Configuration

​Bundle Configuration

​Loading a Signed Bundle

​Bundle Schema

​Integrity Verification

​Hot-Swapping

​Environment Variables

​Configuration Precedence