Audit Trail

Overview

Every evaluation Aguardic runs produces a permanent record. When a policy rule is triggered, a violation is created with full details -- what was checked, what matched, why it fired, and what enforcement action was taken. These violations form your audit trail: a timestamped, tamper-evident log of every governance decision your organization has made.

This guide covers how violations work, how to investigate them, and how to use them for compliance reporting.

Violation Lifecycle

Violations move through a defined lifecycle that tracks your team's response:

NEW  ──>  ACKNOWLEDGED  ──>  RESOLVED
                         └──>  DISMISSED

NEW

The violation was just detected during an evaluation. No one has reviewed it yet. New violations appear in the dashboard with a badge count and can trigger notifications.

ACKNOWLEDGED

A team member has reviewed the violation and confirmed it needs attention. Acknowledging a violation signals to the rest of the team that someone is investigating. This prevents duplicate work on the same issue.

RESOLVED

The root cause has been addressed. When resolving a violation, you provide:

• Resolution type -- How the issue was fixed (e.g., policy updated, code changed, content removed).
• Resolution note -- A description of what was done and why.

Resolved violations remain in the audit trail permanently for compliance purposes.

DISMISSED

The violation was determined to be a false positive or not applicable. When dismissing, you provide:

• Dismiss reason -- Why this is not a real issue (e.g., test data, false positive, acceptable risk).

Dismissed violations are tracked separately so you can review your false positive rate and tune policies accordingly.

What Violations Capture

Each violation records comprehensive details for investigation and audit:

| Field | Description | |-------|-------------| | ruleId | The ID of the policy rule that was violated. | | ruleName | Human-readable name of the rule. | | severity | Violation severity: LOW, MEDIUM, HIGH, or CRITICAL. | | explanation | Why the rule was triggered -- for deterministic rules this describes the condition match; for semantic rules this is the LLM's reasoning. | | field | The input field that triggered the violation (e.g., content, user.email). | | snippet | The relevant portion of content that caused the violation. | | resolvedAction | The enforcement action applied: ALLOW, WARN, BLOCK, or APPROVAL_REQUIRED. | | metadata | Additional context captured during evaluation. | | evaluationRunId | UUID linking to the full evaluation run for tracing. | | locationPath | For code violations: the file path where the violation occurred. | | lineStart / lineEnd | For code violations: the specific line range. |

The evaluationRunId is your link to the full evaluation context -- which policies were checked, what input was provided, and what the overall outcome was. Use it to trace any violation back to the exact evaluation that produced it.

Dashboard Features

The Violations page in the Aguardic dashboard provides tools for managing and investigating violations at scale.

Filtering and Search

Filter violations by any combination of:

• Severity -- Focus on CRITICAL and HIGH violations first.
• Status -- View only NEW violations that need attention, or review DISMISSED ones to audit false positive rates.
• Policy -- See all violations from a specific policy to assess its effectiveness.
• Integration -- Filter by source (GitHub, Slack, OpenAI, etc.) to understand where violations are coming from.
• Time range -- Narrow down to specific periods for incident investigation or compliance audits.

Assignment

Assign violations to specific team members for investigation. Assignments show up in the assignee's violation queue, making it clear who is responsible for each issue.

Timeline and Notes

Each violation has a timeline that records every status change and note. Add notes to document your investigation process:

• What you found during investigation
• Who you consulted
• What remediation steps you took
• Links to external tickets or documentation

The timeline creates a complete narrative of how your team responded to each violation -- valuable during compliance reviews.

External Ticket Linking

Link violations to tickets in external systems like Jira or GitHub Issues. This connects your governance audit trail to your engineering workflow, making it easy to track remediation from detection through resolution.

Statistics and Trends

The dashboard displays violation statistics including:

• Violation counts by severity and status
• Trends over time (are violations increasing or decreasing?)
• Most frequently triggered rules
• Average time to resolution

Use these metrics to identify patterns, tune policies, and demonstrate governance effectiveness to stakeholders.

Investigation Workflow

When a new violation appears, follow this workflow to investigate and resolve it.

1. Review the violation details

Open the violation to see the full context: which rule fired, the severity, the explanation, and the content snippet that triggered it. The explanation tells you why the rule matched -- this is especially useful for semantic rules where the LLM provides its reasoning.

2. Check the evaluation run

Click through to the evaluation run using the evaluationRunId. The evaluation run shows:

• The complete input that was evaluated
• All policies that were checked (not just the one that fired)
• The overall outcome and enforcement action
• The integration and target key

This gives you the full picture of what happened during that evaluation.

3. Check the session (if applicable)

If the evaluation was part of a session, review the session's action chain. This shows you what happened before and after the violation:

• What tools were called leading up to the violation
• Whether similar violations occurred earlier in the session
• The overall data tags and tools used across the session

Session context is critical for investigating agent-related violations where the issue is not a single action but a pattern of behavior.

4. Acknowledge the violation

Once you have reviewed the details and confirmed the violation is legitimate, acknowledge it. This signals to your team that someone is actively investigating.

5. Investigate the root cause

Depending on the violation type, investigation may involve:

• Code violations -- Check the locationPath and line numbers, review the code change in your VCS.
• AI response violations -- Review the model prompt and response, check whether the model's guardrails are configured correctly.
• Data violations -- Determine how sensitive data reached the flagged context, trace the data flow.
• Policy tuning -- If the violation is a false positive, consider adjusting the rule conditions, prompt, or severity.

6. Resolve or dismiss

Resolve the violation when the root cause has been addressed. Provide a resolution type and note so the audit trail reflects what was done. Example: "Updated prompt template to include explicit instruction not to provide medical advice."

Dismiss the violation if it is a false positive or not applicable. Provide a reason so you can audit your false positive rate later. Example: "Test data used during QA -- not a real SSN."

Compliance Reporting

The audit trail is designed to support compliance reporting and regulatory reviews. Every record is immutable and timestamped, providing:

• Complete evaluation history -- Every piece of content that was checked, what the outcome was, and which policies applied.
• Violation response tracking -- When each violation was detected, who acknowledged it, when it was resolved, and what remediation was performed.
• Policy change history -- Policies are versioned, so you can show exactly which rules were in effect at any point in time.
• Session context -- For agent workflows, the full action chain shows exactly what the AI did and how governance decisions were applied at each step.

This data supports audit requirements across multiple compliance frameworks. When a regulator asks "what controls do you have over your AI systems?", the audit trail provides concrete evidence of policy enforcement, violation detection, and incident response.

Next Steps

• Your First Policy -- Create your first governance policy
• Evaluation Sessions -- Understand sessions for multi-step investigation
• AI Systems -- Register and classify your AI applications
• Core Concepts -- Review the violation lifecycle and severity levels