Skip to main content

Policy Violations

When traces trigger enabled policies, LangGuard records violations with full context for investigation and remediation.

Understanding Violations​

Violation Structure​

Each violation includes:

FieldDescription
PolicyWhich policy was triggered
SeverityCritical, High, Medium, Low
TraceThe trace that triggered it
MessageHuman-readable explanation
EvidenceWhat specifically triggered it
TimestampWhen it was detected
StatusNew, Acknowledged, Resolved

Example Violation​

┌──────────────────────────────────────────────────────────────┐
│  Policy Violation                                            │
├──────────────────────────────────────────────────────────────┤
│  Policy: PII Data Detection                                  │
│  Severity: 🔴 Critical                                       │
│  Status: New                                                 │
│                                                              │
│  Message:                                                    │
│  Email address detected in output                            │
│                                                              │
│  Evidence:                                                   │
│  Pattern: user@example.com                                   │
│  Location: output.response.text                              │
│                                                              │
│  Trace: customer_query (tr_abc123)                           │
│  Agent: CustomerService                                      │
│  Time: March 15, 2024 10:30:00 AM                            │
│                                                              │
│  [View Trace] [Acknowledge] [Mark Resolved]                  │
└──────────────────────────────────────────────────────────────┘

Viewing Violations​

Violations Dashboard​

Navigate to Policies > Violations:

┌───────────────────────────────────────────────────────────────┐
│  Policy Violations                              [Filter ▼]    │
├───────────────────────────────────────────────────────────────┤
│  Time       │ Policy          │ Severity │ Agent    │ Status  │
├─────────────┼─────────────────┼──────────┼──────────┼─────────┤
│  10:30 AM   │ PII Detection   │ Critical │ ChatBot  │ New     │
│  10:28 AM   │ Token Limits    │ Medium   │ DataBot  │ New     │
│  10:15 AM   │ SQL Injection   │ High     │ QueryBot │ Ack     │
│  10:00 AM   │ Rate Limiting   │ Medium   │ ChatBot  │ Resolved│
└─────────────┴─────────────────┴──────────┴──────────┴─────────┘

Filtering​

Filter violations by:

  • Severity: Critical, High, Medium, Low
  • Status: New, Acknowledged, Resolved
  • Policy: Specific policy name
  • Agent: Agent that triggered violation
  • Time Range: Last hour, 24h, 7d, custom

Searching​

Search across violations:

Search: email agent:CustomerService severity:critical

Violation Details​

From Trace Explorer​

  1. Open any trace in Trace Explorer
  2. Click the Violations tab
  3. View all violations for that trace

From Violation List​

  1. Click any violation row
  2. View full details in drawer:
    • Policy information
    • Evidence
    • Trace context
    • Related violations

Managing Violations​

Violation Statuses​

StatusMeaningNext Actions
NewJust detectedReview, Acknowledge
AcknowledgedBeing investigatedResolve, Add notes
ResolvedIssue addressedArchive

Acknowledging Violations​

Mark that you've seen and are investigating:

  1. Select violation(s)
  2. Click Acknowledge
  3. Optionally add notes

Resolving Violations​

Mark as addressed:

  1. Select violation(s)
  2. Click Mark Resolved
  3. Add resolution notes (recommended)

Bulk Actions​

Manage multiple violations:

  1. Check multiple violations
  2. Use bulk action menu:
    • Acknowledge All
    • Mark All Resolved
    • Export Selected

Violation Analysis​

By Severity​

View breakdown by severity:

Violation Distribution (Last 7 Days)
────────────────────────────────────
Critical: ████ 4
High:     ██████████ 12
Medium:   ████████████████████ 25
Low:      █████████ 9

By Policy​

See which policies trigger most:

Top Policies (Last 7 Days)
────────────────────────────────────
1. PII Detection        18 violations
2. Token Limits         15 violations
3. Rate Limiting        12 violations
4. SQL Injection         5 violations

By Agent​

Identify problematic agents:

Violations by Agent (Last 7 Days)
────────────────────────────────────
CustomerService    22 violations
DataProcessor      15 violations
EmailBot           8 violations

Track violations over time:

Daily Violations (Last 30 Days)
30 |                    ╭─╮
   |                 ╭──╯ ╰╮
20 |    ╭───╮    ╭──╯      ╰──╮
   | ╭──╯   ╰────╯            ╰───
10 |─╯
   └────────────────────────────────
    1  5  10  15  20  25  30

Trace Details with Violations​

Overview Card​

In trace details, violations appear prominently:

┌──────────────────────────────────────────┐
│  Policy Violations (2)                   │
├──────────────────────────────────────────┤
│  🔴 Critical: PII Data Detection         │
│     Email address in output              │
├──────────────────────────────────────────┤
│  🟡 Medium: Token Limits                 │
│     2,150 tokens (limit: 2,000)          │
└──────────────────────────────────────────┘

Evidence Display​

Click to expand violation evidence:

Evidence:
├── Pattern Matched: email
├── Value: "user@example.com"
├── Location: output.response.text
├── Position: characters 145-165
└── Context: "...contact us at user@example.com for..."

API Access​

List Violations​

GET /api/policies/violations?severity=critical&status=new&limit=50

Response:

{
  "violations": [
    {
      "id": "viol_123",
      "policyId": "pol_456",
      "policyName": "PII Detection",
      "severity": "critical",
      "traceId": "tr_abc",
      "message": "Email address detected",
      "evidence": {"pattern": "email", "value": "user@example.com"},
      "status": "new",
      "createdAt": "2024-03-15T10:30:00Z"
    }
  ],
  "total": 47
}

Get Violations by Trace​

GET /api/policies/violations/by-trace/:traceId

Update Violation Status​

PATCH /api/policies/violations/:id
Content-Type: application/json

{
  "status": "acknowledged",
  "notes": "Investigating with security team"
}

Workflows​

Incident Response​

When critical violations occur:

  1. Triage - Review violation details
  2. Investigate - Check trace and evidence
  3. Acknowledge - Mark as being worked
  4. Remediate - Fix the underlying issue
  5. Resolve - Mark complete with notes
  6. Review - Analyze to prevent recurrence

Regular Review​

Weekly violation review process:

  1. Filter to last 7 days
  2. Sort by severity (Critical first)
  3. Review each violation:
    • Is the policy working correctly?
    • Is this a true positive?
    • What action is needed?
  4. Acknowledge reviewed items
  5. Create tickets for follow-up

False Positives​

When violations are false positives:

  1. Review the policy logic
  2. Adjust thresholds or patterns
  3. Mark violation as resolved
  4. Add note: "False positive - policy adjusted"
  5. Monitor for recurrence

Notifications (Coming Soon)​

Configure alerts for violations:

  • Email notifications for Critical
  • Slack integration for High+
  • Webhook for custom integrations
  • Daily digest reports

Best Practices​

1. Don't Ignore Violations​

Every violation represents a potential issue. Establish a process for review.

2. Tune Policies​

High false positive rates indicate policies need adjustment:

  • Narrow regex patterns
  • Adjust thresholds
  • Add exceptions

3. Document Resolutions​

Always add notes when resolving:

Resolved: False positive. User email was in allowed list.
Policy updated to exclude @company.com addresses.

Rising violation counts may indicate:

  • New agent behavior
  • Changed data patterns
  • Policy needs adjustment

5. Automate Where Possible​

For known-acceptable violations:

  • Create exceptions in policies
  • Use allowlists for approved patterns
  • Adjust severity levels appropriately

Next Steps​