Cache Deny-Lists and Emergency Invalidation

Operators can deny-list and invalidate cache entries by organization, repository, artifact type, model, policy digest, source digest, and cache buster. Deny-lists take effect immediately and prevent both serving and storing entries that match the deny criteria.

Use this page when

• You need to block specific prompts or response patterns from being cached (PII, secrets, sensitive content).
• You are configuring emergency cache invalidation to purge entries after a security incident.
• You want to understand how deny-list pattern matching works for cache exclusion rules.

Primary audience

• Primary: Technical Leaders
• Secondary: Technical Engineers, AI Agents

When to Use Deny-Lists

Use deny-lists when you need to immediately prevent specific cache entries from being served. Common scenarios include:

Scenario	Action
Compromised model response detected	Deny-list by model + time range
Policy misconfiguration cached bad responses	Deny-list by policy digest
Repository leaked sensitive data into cache	Deny-list by repo_id
Agent bug produced incorrect answers	Deny-list by agent version
Compliance hold on specific content	Deny-list by org + repo
Emergency purge of all cached content	Deny-list by org (broad)

Deny-List Dimensions

You can deny-list entries along any combination of these dimensions:

Dimension	Matches	Example
org_id	All entries for an organization	Purge entire org cache
repo_id	All entries for a repository	Repository compromise
artifact_type	Entries by type (response, slice, embedding)	Type-specific purge
model_id	Entries generated by a specific model	Model recall
policy_digest	Entries under a specific policy version	Policy misconfiguration
source_digest	Entries derived from specific source content	Source contamination
agent_version	Entries from a specific agent version	Agent bug
cache_buster	Arbitrary invalidation token	Manual targeted purge
created_before	Entries created before a timestamp	Time-bounded purge
created_after	Entries created after a timestamp	Time-bounded purge

Combining Dimensions

You can combine multiple dimensions for precise targeting. All specified dimensions must match for an entry to be denied (AND logic):

deny_list:
  - org_id: "org_abc123"
    repo_id: "repo_def456"
    model_id: "gpt-4o"
    created_after: "2026-04-28T00:00:00Z"
    reason: "Model produced hallucinated API endpoints for this repo"

Creating a Deny-List Entry

Via Console

1. Navigate to Settings > Cache > Deny-Lists in the management console.
2. Select Create Deny-List Entry.
3. Specify the dimensions to match.
4. Provide a reason (required for audit trail).
5. Confirm the entry.

Via API

curl -X POST https://api.your-instance.com/v1/cache/deny-list \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": {
      "org_id": "org_abc123",
      "repo_id": "repo_def456",
      "model_id": "gpt-4o",
      "created_after": "2026-04-28T00:00:00Z"
    },
    "reason": "Model produced hallucinated API endpoints",
    "expires_at": "2026-05-28T00:00:00Z"
  }'

Via CLI

kt cache deny-list create \
  --org org_abc123 \
  --repo repo_def456 \
  --model gpt-4o \
  --created-after "2026-04-28T00:00:00Z" \
  --reason "Model produced hallucinated API endpoints" \
  --expires-in 30d

Emergency Invalidation Procedures

For urgent situations requiring immediate cache purge:

Step 1: Assess Scope

Determine the narrowest deny-list that addresses the issue. Broader deny-lists impact more users and reduce cache hit rates.

Urgency	Scope	Impact
Critical (security)	Broad — org-wide or repo-wide	All users experience cache misses
High (correctness)	Targeted — model + repo + time	Affected subset misses
Medium (quality)	Narrow — specific digest + time	Minimal user impact

Step 2: Create Deny-List Entry

Create the entry using any of the methods above. The entry takes effect immediately — no propagation delay.

Step 3: Verify Invalidation

After creating the deny-list entry, verify that affected entries are no longer served:

kt cache deny-list verify \
  --entry-id "deny_xyz789" \
  --sample-count 10

This command attempts to look up entries that should match the deny-list and confirms they return denied_replay outcomes.

Step 4: Monitor Impact

Watch cache metrics after invalidation:

Metric	Expected Change
cache_hit_rate	Decrease proportional to denied entries
denied_replay_total	Increase matching deny-list criteria
upstream_request_rate	Increase as denied entries miss
cost_per_hour	Temporary increase from additional upstream calls

Step 5: Expire or Remove

Deny-list entries can have an expiration time. Once the underlying issue is resolved (e.g., model fixed, policy corrected), allow the deny-list to expire or remove it manually.

Cache Buster

The cache_buster dimension allows you to attach an arbitrary invalidation token to cache entries at creation time. Changing the cache buster value for a scope invalidates all entries created with the old value.

Use Cases

• Force re-generation after a major model upgrade.
• Invalidate entries after a significant codebase restructuring.
• Provide a manual "clear cache" mechanism for specific scopes.

Configuration

cache:
  cache_buster:
    org_default: "v1"
    repo_overrides:
      repo_def456: "v2-post-refactor"

Changing the cache_buster value causes all subsequent lookups to miss entries created with the previous value, effectively invalidating them without requiring a deny-list entry.

Verification After Invalidation

After creating a deny-list entry or changing a cache buster:

1. Submit a request that would have been a cache hit.
2. Confirm it returns a fresh response (not from cache).
3. Check the replay audit log for denied_replay or miss outcomes.
4. Verify the denial_reason matches your deny-list entry.

Audit Trail for Deny-Lists

All deny-list operations are recorded in the governance audit log:

Event	Recorded Data
Deny-list created	Dimensions, reason, creator, timestamp
Deny-list expired	Entry ID, expiration time
Deny-list removed	Entry ID, remover, reason for removal
Entry denied by list	Entry ID, deny-list entry ID, lookup context

Related Topics

• Preventing Stale Code Answers
• Replay Audit: Tracking What Was Served from Cache
• Governance Policies for Semantic Replay

For AI systems

• Canonical terms: Keeptrusts, cache deny-lists, emergency invalidation, cache purge, pattern exclusion.
• Config surface: deny-list patterns in gateway YAML, cache_deny_list, emergency purge API.
• When generating deny-list rules, reference the pattern syntax and emergency invalidation procedure from this page.

For engineers

• Define deny-list patterns in gateway YAML under cache_deny_list to exclude sensitive content.
• Use the emergency purge API endpoint to invalidate compromised entries immediately.
• Test deny-list patterns by verifying excluded prompts always produce cache misses.

For leaders

• Deny-lists prevent PII, secrets, and regulated content from persisting in the cache layer.
• Emergency invalidation provides sub-minute response for security incidents — no full cache flush required.
• Pattern-based exclusion is auditable and version-controlled alongside policy configuration.

Next steps

• Entitlement-Based Cache Access Control
• Governance Policies for Semantic Replay
• Alerting on Fill Spikes