Best Practices

Practical guidance for deploying TealTiger governance in production.

1. Separate Governance from Development

The governance team defines policy. The development team consumes it. These are separate roles.

Do	Don’t
Governance team authors and signs policy bundles	Developers write governance rules inline
Developers call `evaluate()` and handle decisions	Developers configure enforcement behavior
FREEZE rules set by governance team	Application code sets safety controls
Cost ceilings owned by governance	Application code sets its own limits

Why: Separation of duties is a compliance requirement (SOC 2, ISO 42001). It also prevents accidental weakening of controls during development. Related: Governance at Scale

2. Start with OWASP Policy Pack, Then Customize

Don’t author policies from scratch. Start with the pre-built OWASP Agentic Top 10 pack, observe behavior in MONITOR mode, then customize.

// Week 1: Deploy OWASP pack in MONITOR mode
const engine = new TealEngine({
  policy: OWASPPolicyPack.default(),
  modules: OWASPPolicyPack.modules(),
  mode: 'MONITOR',
});

// Week 3: Review audit logs, customize thresholds
// Week 5: Switch to ENFORCE for high-confidence controls
// Week 8: Full ENFORCE with custom additions

Why: The OWASP pack covers all 10 ASI risks with production-tested defaults. Customizing from a working baseline is faster and safer than building from zero.

3. Use FREEZE Rules for Non-Negotiable Safety

FREEZE rules are your last line of defense. Use them for actions that should never happen regardless of policy changes.

freeze: [
  { id: 'FREEZE-001', condition: { action: 'database.drop' }, reason: 'FREEZE_DATABASE_DROP' },
  { id: 'FREEZE-002', condition: { action: 'system.shutdown', environment: 'production' }, reason: 'FREEZE_PROD_SHUTDOWN' },
  { id: 'FREEZE-003', condition: { action: 'governance.*.modify' }, reason: 'FREEZE_GOVERNANCE_MODIFICATION' },
]

Why: FREEZE rules cannot be bypassed by hot-swap, application code, or configuration changes. They persist across restarts. They’re the circuit breaker for governance itself.

4. Evaluate Before Every Action

Call engine.evaluate() before the agent executes any action — not after. Governance is pre-execution enforcement.

// ✅ Correct: evaluate THEN execute
const decision = await engine.evaluate(request, ctx);
if (decision.action === 'ALLOW') {
  await executeAction(request);
}

// ❌ Wrong: execute then check
await executeAction(request);  // Too late — damage already done
const decision = await engine.evaluate(request, ctx);

Why: Post-execution governance is audit, not enforcement. You can’t un-delete a database.

5. Handle All Decision Types

Your code must handle ALLOW, DENY, PENDING, and MODIFY. Don’t just check for ALLOW.

switch (decision.action) {
  case 'ALLOW': return await execute(request);
  case 'DENY': throw new GovernanceDeniedError(decision.reason_codes);
  case 'PENDING': return await waitForApproval(decision.approval.token);
  case 'MODIFY': return await execute(decision.metadata.sanitized_request);
}

Why: Ignoring PENDING means approval workflows never fire. Ignoring MODIFY means sanitized content is never used.

6. Use Signed Bundles in Production

Never load unsigned policy bundles in production. Always verify bundle integrity.

const engine = new TealEngine({
  bundle: await loadBundle('./governance/bundle.signed.json'),
  bundle_verification: {
    public_key: process.env.GOVERNANCE_PUBLIC_KEY,
    require_signature: true,
  },
});

Why: Unsigned bundles can be tampered with. Signed bundles prove the governance team authored the policy. This is the foundation of separation of duties.

7. Register Agent Identities (NHI)

Every agent should have a registered Non-Human Identity with explicit scopes and environment constraints.

nhi_inventory: {
  agents: new Map([
    ['support-bot-001', {
      owner: '[email protected]',
      scopes: ['read:tickets', 'write:responses'],
      environment: ['production'],
      status: 'active',
    }]
  ])
}

Why: Without NHI, agents operate as ambient credentials with no accountability. With NHI, every decision is attributed to a verified principal.

8. Set Governance-Owned Cost Ceilings

Cost limits should be set by the governance team, not application code. Application code can be MORE restrictive but never LESS.

cost_governance: {
  governance_limits: {
    per_request_max: 2.00,      // Governance ceiling
    daily_per_agent_max: 50.00, // Cannot be raised by app code
    reasoning_token_budget: 10000,
  }
}

Why: If developers control cost limits, a bug or misconfiguration can cause unbounded spend. Governance-owned ceilings are the safety net.

9. Forward Evidence to SIEM

Governance decisions are security events. Forward them to your SIEM for correlation with other security signals.

response_hooks: [{
  id: 'siem-export',
  trigger: 'always',
  endpoint: process.env.SIEM_WEBHOOK_URL,
  dedup_window_ms: 60000,
  rate_limit: { max_per_minute: 100 },
}]

Why: Governance events in isolation are useful. Governance events correlated with network logs, auth events, and application traces are powerful.

10. Test Policies in CI/CD

Run the policy test harness in your CI pipeline. Governance regressions should fail the build.

# In CI pipeline
npx tealtiger test --policy ./governance/bundle.json --corpus ./tests/golden-corpus.yaml

Why: Policy changes can have unintended consequences. Golden corpus tests catch regressions before they reach production.

Anti-Patterns to Avoid

Anti-Pattern	Why It’s Bad	Do This Instead
Hardcoding policies in application code	No separation of duties	Use signed bundles
Setting `mode: 'MONITOR'` permanently	Governance is never enforced	Graduate to ENFORCE after validation
Ignoring PENDING decisions	Approval workflows never fire	Implement approval handling
Disabling audit in production	No evidence for compliance	Always keep audit enabled
Using `fail_open` for security workloads	Ungoverned requests pass through on error	Use `fail_closed` (default)
Skipping NHI registration	No agent accountability	Register every agent identity

Governance at Scale

Enterprise operating model

OWASP Policy Pack

Zero-config governance

Configuration Reference

All configuration options

Anti-Patterns

Common mistakes in detail

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

1. Separate Governance from Development

2. Start with OWASP Policy Pack, Then Customize

3. Use FREEZE Rules for Non-Negotiable Safety

4. Evaluate Before Every Action

5. Handle All Decision Types

6. Use Signed Bundles in Production

7. Register Agent Identities (NHI)

8. Set Governance-Owned Cost Ceilings

9. Forward Evidence to SIEM

10. Test Policies in CI/CD

Anti-Patterns to Avoid

Governance at Scale

OWASP Policy Pack

Configuration Reference

Anti-Patterns

​1. Separate Governance from Development

​2. Start with OWASP Policy Pack, Then Customize

​3. Use FREEZE Rules for Non-Negotiable Safety

​4. Evaluate Before Every Action

​5. Handle All Decision Types

​6. Use Signed Bundles in Production

​7. Register Agent Identities (NHI)

​8. Set Governance-Owned Cost Ceilings

​9. Forward Evidence to SIEM

​10. Test Policies in CI/CD

​Anti-Patterns to Avoid

​Related Documentation

Governance at Scale

OWASP Policy Pack

Configuration Reference

Anti-Patterns

1. Separate Governance from Development

2. Start with OWASP Policy Pack, Then Customize

3. Use FREEZE Rules for Non-Negotiable Safety

4. Evaluate Before Every Action

5. Handle All Decision Types

6. Use Signed Bundles in Production

7. Register Agent Identities (NHI)

8. Set Governance-Owned Cost Ceilings

9. Forward Evidence to SIEM

10. Test Policies in CI/CD

Anti-Patterns to Avoid

Related Documentation