Querying the Audit Trail

Quick Search

Go to Governance → Audit Trail and use quick filters:

• Time Range: Last hour, day, week, month, or custom
• User: Select specific user or all users
• Model: Filter by AI model (gpt-4, claude-3, etc.)
• Status: Show blocked, allowed, or warned requests
• Violation Type: PII, injection, toxicity, etc.

Example: Find all blocked PII attempts in the last 24 hours:

1. Time Range: “Last 24 hours”
2. Status: “Blocked”
3. Violation Type: “PII detected”
4. Click Search

Advanced Query Syntax

Use the advanced search box for complex queries:

user:john@company.com
  AND model:gpt-4
  AND violation:pii_detected
  AND decision:blocked
  AND timestamp:[2025-03-01 TO 2025-03-15]

Field Operators

Operator	Example	Meaning
:	user:john@company.com	Exact match
~	prompt~"SQL injection"	Contains (text search)
>	tokens>5000	Greater than
<	latency_ms<100	Less than
[..TO..]	timestamp:[2025-01-01 TO 2025-03-15]	Date range
AND	user:john AND violation:pii	Both must match
OR	violation:pii OR violation:injection	Either can match
NOT	NOT decision:blocked	Exclude

Searchable Fields

User/Request Info

• user: User ID or email
• user_id: Numeric user ID
• user_email: Email address
• department: Department name
• model: AI model name
• timestamp: Date/time
• tokens: Token count

Decision/Status

• decision: allowed, blocked, warned
• violation: Type of violation
• stage: Firewall stage (pii-scanner, injection-detector, etc.)
• confidence: Detection confidence (0.0-1.0)

Performance

• latency_ms: Request latency
• scan_latency_ms: Governance latency only
• tokens: Token count

Query Examples

Find All PII Violations by User

user:jane@company.com AND violation:pii_detected

Returns: Every time Jane’s request contained PII

Find High-Confidence Injections This Month

violation:injection_detected
AND confidence>[0.9]
AND timestamp:[2025-03-01 TO 2025-03-31]

Returns: High-confidence injection attempts from March

Find All Requests Over 10 Seconds

latency_ms>10000

Returns: Slow requests for performance analysis

Find Requests by Department

department:marketing AND decision:blocked

Returns: All blocked requests from marketing department

Find Policy Violations by Stage

stage:content-safety AND decision:blocked

Returns: All content safety violations that were blocked

Find Warnings (Not Blocks)

decision:warned AND violation:toxicity_detected

Returns: Requests that triggered toxicity warnings but weren’t blocked

Saved Searches

Create search templates you use regularly:

1. Go to Governance → Audit Trail → Saved Searches
2. Click + New Saved Search
3. Name: “PII Incidents”
4. Query: violation:pii_detected AND decision:blocked
5. Click Save

Now you can run this search anytime from the dropdown.

Common Saved Searches:

• “Security Incidents”: decision:blocked AND violation:(pii_detected OR injection_detected)
• “High Latency”: scan_latency_ms>200
• “User Compliance”: user:$USER AND timestamp:[LAST_7_DAYS]
• “Policy Testing”: policy:test-policy AND timestamp:[LAST_24_HOURS]

Aggregations & Analytics

Click Analytics to see trends:

By Violation Type

Pie chart: % of violations by type
PII: 45%
Toxicity: 25%
Injection: 20%
Other: 10%

By Decision

Bar chart: Blocked vs. allowed by day
Mar 13: 15 blocked, 2500 allowed
Mar 14: 8 blocked, 2400 allowed
Mar 15: 12 blocked, 2600 allowed

By User

Table: Top users with violations
user123: 15 violations
user456: 12 violations
user789: 8 violations

By Stage

Bar chart: Violations detected per stage
PII Scanner: 125
Content Safety: 78
Injection Detector: 45
Truth Scanner: 32

Latency Distribution

Histogram: Request latency
<50ms: 40%
50-100ms: 35%
100-200ms: 20%
>200ms: 5%

Exporting Results

Quick Export

1. Run query
2. Click Export
3. Choose format:
   • CSV: For spreadsheets
   • JSON: For programmatic use
   • PDF: For printing/sharing
4. Download

Scheduled Exports

Export audit logs automatically on a schedule:

1. Go to Governance → Audit Trail → Scheduled Exports
2. Click + New Scheduled Export
3. Query: Your search query
4. Schedule: Daily, weekly, monthly
5. Format: CSV, JSON, or PDF
6. Recipients: Email addresses
7. Click Create

Now you’ll receive audit reports automatically!

API Access

Query audit logs programmatically:

REST API

curl -X GET "http://localhost:5000/api/v1/governance/audit/logs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "violation:pii_detected AND decision:blocked",
    "limit": 100,
    "offset": 0,
    "sort": "timestamp:desc"
  }'

Response:

{
  "total": 45,
  "returned": 20,
  "entries": [
    {
      "id": "log_abc123",
      "timestamp": "2025-03-15T10:23:45Z",
      "user_id": "user_123",
      "model": "gpt-4",
      "decision": "blocked",
      "violation": "pii_detected",
      "confidence": 0.98
    }
  ]
}

Python SDK

from truthvouch import TruthVouchClient

client = TruthVouchClient(api_key="tvk_...")

# Query audit logs
results = client.governance.audit.query(
    query="violation:pii_detected AND decision:blocked",
    start_date="2025-03-01",
    end_date="2025-03-31",
    limit=100
)

for entry in results:
    print(f"{entry.timestamp} - {entry.user_id}: {entry.violation}")

# Get summary statistics
stats = client.governance.audit.stats(
    query="violation:*",
    group_by="violation"
)

print(stats)
# Output:
# {
#   "pii_detected": 45,
#   "injection_detected": 20,
#   "toxicity_detected": 15
# }

Performance Tips

For Large Datasets:

1. Use Date Ranges: Instead of querying all time, specify a date range

   timestamp:[2025-03-01 TO 2025-03-15]  # Not timestamp:[*]

2. Limit Results: Don’t retrieve 1 million entries at once

   Get first 100, then paginate if needed

3. Index Common Filters: Queries on indexed fields are fast

   • user — indexed
   • timestamp — indexed
   • decision — indexed
   • violation — indexed

4. Avoid Text Search: Full-text search in request content is slow

   # Slow:
   prompt~"specific text"
   
   # Fast:
   violation:pii_detected AND decision:blocked

Real-World Scenarios

Scenario 1: Investigate User Behavior

Goal: Review john@company.com’s recent activity

user:john@company.com AND timestamp:[LAST_7_DAYS]

What you see:

• 847 total requests
• 3 blocked (PII detected)
• 5 warnings (content safety)
• Avg latency: 95ms

Action: Email john about PII blocking rules

Scenario 2: Audit Compliance

Goal: Prove to auditors that PII masking is working

violation:pii_detected AND decision:blocked
AND timestamp:[2025-01-01 TO 2025-03-31]

What you see:

• 247 PII detection events blocked
• 100% effectiveness (0 PII leaked)
• Distributed across 45 users
• Confidence avg: 0.94

Export as: PDF for auditor

Scenario 3: Detect Attack Patterns

Goal: Find potential prompt injection attempts

violation:injection_detected AND confidence>[0.7]
AND timestamp:[LAST_24_HOURS]

What you see:

• 8 high-confidence injection attempts
• From 3 different IP addresses
• All blocked successfully
• Patterns: “ignore system”, “forget instructions”

Action: Alert security team about suspicious IPs

Related Topics

• Audit Trail Overview
• Audit Export & Compliance
• Governance Reports