AI Security Gateway

Appearance

Alert Recording System Documentation ​

Alert System Overview ​

The AI Security Gateway features a sophisticated alert recording system that captures, processes, and stores security alerts from both MCP and LLM proxy instances. This system ensures that all security events are properly logged to the database for analysis, reporting, and Web UI display with real-time WebSocket notifications.

Alert Dashboard

Alert Investigation Workflow

How the Alert System Works ​

Alert System Flow ​

The alert system captures and processes security events through the following workflow:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Proxy Layer   │    │ Alert Recording │    │   Database      │
│                 │    │    & Storage    │    │   & Web UI      │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ MCP Proxy       │───▶│ Alert System    │───▶│ Alert Storage   │
│ LLM Proxy       │    │                 │    │ Real-time UI    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Alert Processing Pipeline ​

  1. Detection: Security policies detect threats in proxy traffic
  2. Recording: Alerts are automatically saved to the database
  3. Notification: WebSocket broadcasts alert to connected clients in real-time
  4. Display: Alerts appear instantly in the Web UI dashboard
  5. Management: Users can filter, acknowledge, investigate, and resolve alerts
  6. Export: Alerts can be exported as JSON or CSV for external analysis

Understanding Alert Sources ​

Alerts are generated by several independent detection systems within the gateway. The Policy Name field on each alert tells you which system produced it:

Policy NameSourceWhat It Means
traffic-analysisBuilt-in traffic analysis engineHeuristic pattern detection — flags suspicious behaviours for investigation. Monitor-only, may produce false positives. See Traffic Analysis Detections.
guardrail-{provider}Guardrail providers (e.g., guardrail-dynamoai)External AI safety evaluation detected a policy violation. The Raw Data field contains detailed per-policy evaluation results (scores, classifications, rationale). See Guardrail Providers Guide.
mcp-tool-filteringTool permission systemA tool call was blocked or rate-limited. The alert description explains which permission tier resolved the decision (user-override, group-permission, tool-config, or not-discovered).
(from policy files)Security policy engineRule-based detection from security policies assigned to the proxy.

Tip: Use the Policy Name filter in the Alerts dashboard to view alerts from a specific source. For example, filter by traffic-analysis to see only heuristic detections, or by guardrail-dynamoai to see only DynamoAI guardrail violations.

Alert Data and Metadata ​

Each alert captured by the system includes comprehensive information for security analysis:

Core Alert Information:

  • Severity: Critical, High, Medium, or Low priority classification
  • Title: Brief description of the security event
  • Description: Detailed explanation of what was detected
  • Status: Current investigation state (new, acknowledged, in_progress, resolved, false_positive)
  • Timestamps: When the alert was created and last updated

Enhanced Metadata:

  • Proxy Type: Whether alert came from MCP or LLM proxy
  • Source: IP address or identifier of the request origin
  • Target: Full URL or endpoint that was accessed
  • Rule ID: Specific security rule that detected the threat
  • Policy Name: Which detection system generated the alert (see table above)
  • Raw Data: Complete request/response data for forensic analysis — for guardrail alerts, this contains the full evaluation results with per-policy scores and rationale

Alert Status Workflow ​

The alert system implements a status workflow to track investigation and resolution:

┌──────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────┐
│ New  │───▶│ Acknowledged │───▶│ In Progress │───▶│ Resolved │
└──────┘    └──────────────┘    └─────────────┘    └──────────┘
   │                                                       ▲
   │         ┌───────────────┐                           │
   └────────▶│False Positive │──────────────────────────┘
             └───────────────┘

Status Definitions:

  • New: Alert just created, awaiting review
  • Acknowledged: Alert reviewed, investigation pending
  • In Progress: Active investigation underway
  • Resolved: Issue addressed, alert closed
  • False Positive: Determined to be non-threatening, marked for policy tuning

Using the Alert System ​

Accessing Alerts in the Web UI ​

Navigate to the Alert Dashboard:

  1. Open the AI Security Gateway web interface at http://localhost:8080
  2. Login with your credentials
  3. Click Alerts in the main navigation
  4. View real-time alerts with color-coded severity indicators

Alert Dashboard Features:

  • Real-time Updates: New alerts appear instantly via WebSocket
  • Severity Filtering: Filter by Critical, High, Medium, or Low
  • Status Filtering: View by new, acknowledged, in_progress, resolved, or false_positive
  • Date Range: Filter alerts by time period
  • Policy Filtering: See alerts from specific security policies
  • Proxy Filtering: View alerts from specific proxy instances
  • Bulk Actions: Acknowledge or resolve multiple alerts at once
  • Export: Download alerts as JSON or CSV

Alert System API Endpoints ​

For programmatic access to alerts, the following REST API endpoints are available:

Core Alert Endpoints ​

  • GET /api/v1/system/alerts: Retrieve all system alerts
    • Supports filtering by severity, status, policy name, date range
    • Pagination with limit and offset parameters
  • PUT /api/v1/system/alerts/{id}/status: Update alert status
    • Change status to: acknowledged, in_progress, resolved, false_positive
  • POST /api/v1/system/alerts/bulk-acknowledge: Acknowledge multiple alerts
  • POST /api/v1/system/alerts/bulk-resolve: Resolve multiple alerts
  • DELETE /api/v1/system/alerts/{id}: Delete alert (admin only)
  • GET /api/v1/proxies/{id}/alerts: Get alerts for specific proxy

Real-time Notifications ​

  • WebSocket /ws: Real-time alert notifications
    • Connect to receive instant alerts as they occur
    • Notification type: new_alert with full alert details

Authentication Required: All endpoints require OAuth 2.1 authentication with JWT tokens.

See Also: API Examples for detailed usage examples

Alert System Configuration ​

Configuring Alert Settings ​

All alert system configuration is managed through the web UI:

  1. Navigate to Settings → System Configuration
  2. Configure alert processing options:
    • Maximum Alerts per Proxy: Limit stored alerts per proxy instance
    • Retention Period: How long to keep alerts (default: 90 days)
    • Auto Cleanup: Automatically remove old alerts
    • WebSocket Notifications: Enable/disable real-time alert notifications
  3. Click Save to apply changes

Alert Retention Policy ​

Manage alert data retention:

  1. Navigate to Settings → Database → Advanced Retention Settings
  2. Set Alert Retention Days (recommended: 90-180 days for compliance)
  3. Old alerts are automatically deleted based on this policy
  4. Deleted alerts are soft-deleted (audit trail preserved)

Alert System Usage Examples ​

Working with Alerts in the Web UI ​

Viewing and Filtering Alerts:

  1. Navigate to Alerts dashboard
  2. Use filters to find specific alerts:
    • Filter by severity (Critical, High, Medium, Low)
    • Filter by status (new, acknowledged, in_progress, resolved, false_positive)
    • Filter by date range
    • Filter by policy name
    • Filter by proxy instance
  3. Click on an alert to view full details including raw request/response data

Managing Alert Status:

  1. Select one or more alerts using checkboxes
  2. Use bulk actions:
    • Acknowledge: Mark alerts as reviewed
    • In Progress: Mark alerts as under investigation
    • Resolve: Mark alerts as resolved
    • False Positive: Mark alerts as non-threatening
  3. Or update individual alerts by clicking the alert and changing status

Exporting Alerts:

  1. Apply desired filters to select alerts
  2. Click Export button
  3. Choose format:
    • JSON: For programmatic processing or SIEM integration
    • CSV: For spreadsheet analysis or reporting
  4. File downloads automatically

Retrieving Alerts via API ​

For programmatic access (scripts, automation, SIEM integration):

bash
# Set authentication token (see Authentication Guide for obtaining tokens)
export JWT_TOKEN="your-jwt-token"

# Get all high severity alerts
curl -s "http://localhost:8080/api/v1/system/alerts?severity=High" \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

# Get alerts from the last 24 hours
curl -s "http://localhost:8080/api/v1/system/alerts?time_range=24h" \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

# Get alerts with pagination (first 10 results)
curl -s "http://localhost:8080/api/v1/system/alerts?limit=10&offset=0" \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

# Update alert status to acknowledged
curl -X PUT "http://localhost:8080/api/v1/system/alerts/1/status" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "acknowledged"}'

# Bulk acknowledge multiple alerts
curl -X POST "http://localhost:8080/api/v1/system/alerts/bulk-acknowledge" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alert_ids": [1, 2, 3, 4, 5]}'

See Also: Authentication Guide for obtaining API tokens

Web UI Alert Features ​

The alert system is fully integrated into the web interface:

Real-time Alert Dashboard ​

Key Features:

  • Live Updates: Alerts appear instantly as they occur (no page refresh needed)
  • Color-Coded Severity: Visual indicators for Critical (red), High (orange), Medium (yellow), Low (blue)
  • Status Badges: Clear indicators for new, acknowledged, in_progress, resolved, false_positive
  • Search: Quickly find alerts by keywords
  • Sorting: Sort by severity, date, status, or policy name

Alert Investigation Workflow ​

  1. Review Alert Details: Click any alert to see full information
  2. View Raw Data: Examine complete request/response data
  3. Check Policy Context: See which security policy and rule triggered
  4. Update Status: Move alert through investigation workflow
  5. Add Notes: Document investigation findings (future feature)
  6. Export Evidence: Download alert data for reporting

Bulk Operations ​

Efficiently manage multiple alerts:

  • Select multiple alerts using checkboxes
  • Apply bulk actions (acknowledge, resolve, false positive)
  • Filter then bulk-action matching alerts
  • Perfect for handling alert storms or batch processing

Alert System Best Practices ​

Managing Alert Volume ​

If you receive too many alerts:

  1. Review security policies - they may be too strict
  2. Use False Positive status to mark non-threatening patterns
  3. Adjust policy thresholds in Settings → Policies
  4. Consider creating custom policies for your environment

For high-traffic environments:

  • Set reasonable retention periods (90 days recommended)
  • Use bulk operations to process similar alerts
  • Export and archive old alerts before cleanup
  • Monitor database size in Settings → Database

Alert Investigation Tips ​

  1. Start with Critical and High severity alerts first
  2. Review raw data to understand the full context
  3. Check for patterns - multiple similar alerts may indicate:
    • Ongoing attack
    • Misconfiguration
    • Policy tuning needed
  4. Update status as you investigate to track progress
  5. Export evidence before resolving for documentation

Troubleshooting Alerts ​

Alerts Not Appearing ​

Check these common issues:

  1. Proxy Running? Verify proxy is started in Proxies dashboard
  2. Policies Assigned? Check proxy has security policies assigned
  3. WebSocket Connected? Refresh browser to reconnect
  4. Filters Too Restrictive? Clear all filters to see all alerts

To verify system health:

  1. Navigate to Settings → System Health
  2. Check database connectivity status
  3. Verify proxy instances are running
  4. Review system logs for errors

Missing Alert Details ​

If alert data seems incomplete:

  1. Check Settings → Alert Processing configuration
  2. Verify Raw Data Capture is enabled
  3. Ensure proxy has sufficient permissions
  4. Review proxy logs for recording errors

Export Not Working ​

If alert export fails:

  1. Check browser allows downloads
  2. Verify you have alerts matching current filters
  3. Try smaller date range if dataset is large
  4. Check browser console for JavaScript errors

Alert Security and Compliance ​

Access Control ​

Role-Based Permissions:

  • Viewer: Can view alerts (read-only)
  • User: Can view and update alert status
  • Admin: Full access including deletion

Authentication Required: All alert access requires OAuth 2.1 authentication with valid JWT tokens.

Data Protection ​

Sensitive Data Handling:

  • Personal information in alerts is masked per compliance requirements
  • Raw data access restricted to authorized users
  • All API access logged in audit system
  • Alerts use soft deletion to preserve audit trail

Compliance Features ​

Audit Trail:

  • All alert status changes are logged with user, timestamp, and action
  • Alert access is tracked in system audit logs
  • Retention policies ensure compliance with data regulations
  • Export capabilities support compliance reporting

Supported Compliance Standards:

  • SOC 2 Type II (access logging, change tracking)
  • HIPAA (security event logging, data access trails)
  • GDPR (data protection, retention management)
  • PCI DSS (security monitoring, audit trails)

Current Features (v2.1) ​

The alert recording system includes these fully implemented features:

  1. Real-time WebSocket Notifications: Live alert streaming to connected clients
  2. Advanced Status Workflow: New → Acknowledged → In Progress → Resolved → False Positive
  3. Bulk Operations: Acknowledge or resolve multiple alerts simultaneously
  4. Rich Filtering: Filter by severity, status, policy, date range, proxy ID
  5. OAuth 2.1 Authentication: Role-based access control for all endpoints
  6. Comprehensive Audit Logging: All alert operations logged with 35+ event types
  7. Export Capabilities: JSON and CSV export for external analysis
  8. Vue.js Integration: Full frontend with real-time updates and management UI

Alert System Future Enhancements ​

Planned Features ​

  1. Alert Correlation: Machine learning-based alert pattern detection and grouping
  2. Custom Dashboards: User-configurable alert dashboards with widgets
  3. Advanced Analytics: Trend analysis, prediction, anomaly detection
  4. Enhanced SIEM Integration: Bidirectional sync with enterprise SIEM platforms
  5. Alert Comments: Collaborative investigation with threaded comments
  6. Alert Templates: Customizable alert formats for different notification channels

Extension Points ​

The alert system is designed for extensibility:

  • Custom Alert Recorders: Implement AlertRecorder interface for custom storage
  • Alert Processors: Add custom alert processing logic
  • Notification Channels: Integrate with additional notification systems
  • Dashboard Widgets: Create custom Web UI components for alert display