docs: add compliance event reporting to filter scripts and documentation

[lonelycode]

Summary

• Updated all 6 pre-provided filter scripts in examples/filter-scripts/ to emit compliance_events (PII redaction, content blocking, harmful content detection, refund promises, LLM policy checks)
• Updated all 3 embedded UI templates in ScriptTemplateSelector.js with compliance event examples
• Added full "Compliance Event Reporting" documentation section to docs/site/docs/filters.md with schema reference, validation rules, and examples for both request and response filters
• Updated examples/filter-scripts/README.md with compliance event field reference and usage examples
• Updated features/Filters.md feature spec with compliance event implementation details

Test plan

• go test -tags enterprise ./scripting/... passes
• JS syntax validated with acorn parser
• Load each embedded template in admin UI filter editor and confirm rendering
• Create a filter using the PII Redaction template and verify compliance events appear in analytics

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Martin Buhr seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[probelabs]

This PR introduces a new compliance event reporting feature for filter scripts. It allows scripts to emit non-blocking audit events, such as PII redactions or policy violations, which are captured by the analytics pipeline for reporting and auditing.

The changes primarily focus on documenting this new feature and providing practical examples. All existing example filter scripts and UI templates have been updated to demonstrate how to generate these compliance events.

Files Changed Analysis

The changes are distributed across documentation, example scripts, and UI components:

• Documentation (docs/site/docs/filters.md, examples/filter-scripts/README.md, features/Filters.md): The bulk of the changes reside here, with over 240 lines of new documentation. A new "Compliance Event Reporting" section has been added, detailing the feature, the event schema, validation rules, and providing copy-paste examples for both request and response filters. The feature specification has also been updated to reflect the implementation details.
• Example Scripts (examples/filter-scripts/*.tengo): All 6 example scripts have been updated to include logic for emitting compliance_events. This provides users with working examples for common use cases like content blocking, PII redaction, and detecting harmful content.
• Admin UI (ui/admin-frontend/src/admin/components/filters/ScriptTemplateSelector.js): The 3 built-in filter templates in the admin UI have been updated to include examples of the new compliance_events field, ensuring users can easily adopt this feature when creating new filters.

Architecture & Impact Assessment

• What this PR accomplishes: It formally introduces and documents the ability for filter scripts to generate structured, non-blocking compliance events. This enhances the platform's governance and auditing capabilities by creating a formal record of actions taken by filters, without altering the request/response flow.

• Key technical changes introduced:

  • A new optional field, compliance_events, is added to the output object of filter scripts.
  • This field accepts an array of Compliance Event objects, each with a defined schema (event_type, severity, description, metadata).
  • The documentation exposes a new API endpoint, GET /api/v1/compliance/events, for querying these stored events.

• Affected system components:

  • Filter Scripts: Authors of filter scripts now have a new mechanism for reporting.
  • Analytics Pipeline: This system is responsible for ingesting, storing, and indexing the compliance events generated by the scripts.
  • Admin API: A new endpoint is documented for retrieving compliance data.
  • Admin UI: The filter editor templates are updated to promote the use of this new feature.

Data Flow

sequenceDiagram
    participant Client
    participant AI Gateway
    participant Filter Script
    participant Analytics Pipeline
    participant Admin

    Client->>AI Gateway: Makes API Request
    AI Gateway->>Filter Script: Executes Filter
    Filter Script->>AI Gateway: Returns output with `compliance_events`
    AI Gateway-->>Analytics Pipeline: Forwards compliance events for storage
    AI Gateway->>Client: Proxies request/response

    Admin->>AI Gateway: GET /api/v1/compliance/events
    AI Gateway->>Analytics Pipeline: Queries stored events
    Analytics Pipeline-->>AI Gateway: Returns events
    AI Gateway-->>Admin: Responds with event data

Loading

Scope Discovery & Context Expansion

While this PR focuses on documentation and examples, it reveals a significant backend feature. The changes in features/Filters.md point to an underlying implementation in files like models/compliance_event.go and scripting/compliance_recorder.go, which handle the processing and storage of these events. The mention of a Prometheus metric (aistudio_compliance_events_total) also indicates that this feature is integrated into the platform's monitoring system.

The broader impact extends to:

• Compliance Teams: They now have a new, structured data source for auditing LLM interactions and governance policy enforcement.
• Platform Administrators: They can use the new API endpoint to build reports or integrate with external monitoring tools.
• Developers: They are now encouraged to build more observable and auditable filter scripts by default, as shown in the updated examples and UI templates.

Metadata

• Review Effort: 2 / 5
• Primary Label: feature

---

Powered by Visor from Probelabs

Last updated: 2026-04-14T09:35:47.565Z | Triggered by: pr_updated | Commit: f9bac0f

💡 TIP: You can chat with Visor using /visor ask <your question>

[probelabs]

Security Issues (2)

Severity	Location	Issue
🟡 Warning	docs/site/docs/filters.md:175	The documentation for the `compliance_events` feature does not specify any limits on the number or size of events that can be emitted from a single script execution. A malicious or buggy script could generate a very large array of compliance events, leading to high memory consumption and load on the analytics pipeline, which could be a vector for a denial-of-service (DoS) attack. 💡 Suggestion The backend should enforce a reasonable limit on the number and total size of compliance events per request. This limit should be clearly documented where the `compliance_events` field is introduced to guide script authors.
🟡 Warning	docs/site/docs/filters.md:785-786	The documentation for the `description` and `metadata` fields in compliance events does not warn about the security and privacy risks of including raw user or LLM-generated content. Including raw input in these fields can lead to: 1. Stored XSS vulnerabilities if the content is rendered without proper escaping in an analytics UI. 2. Sensitive data leaks (e.g., PII, credentials, private conversations) being stored in the compliance event log, which may violate data protection policies and regulations. 💡 Suggestion Update the documentation to explicitly warn developers not to include raw, un-sanitized user or LLM content in compliance events. A security note should be added to the description of both the `description` and `metadata` fields. For example: 'Human-readable description of what happened. **Security Note:** Avoid including raw user or LLM content to prevent Stored XSS vulnerabilities and sensitive data leaks. Log matched rule identifiers or sanitized data instead.'

✅ Performance Check Passed

No performance issues found – changes LGTM.

---

Powered by Visor from Probelabs

Last updated: 2026-04-14T09:35:33.592Z | Triggered by: pr_updated | Commit: f9bac0f

💡 TIP: You can chat with Visor using /visor ask <your question>