Skip to content

Alerts Reference

Detailed reference information for the Alerts API.

Field Validation

Name

Field Constraints
Length 1-64 characters
Format Any printable characters

Description

Field Constraints
Length 0-128 characters
Format Any printable characters

Condition Types

Type Description Example Values
apps Application matched ["app-uuid-1"]
rules Rule matched ["rule-uuid-1"]
datatypes_detected Data type detected ["ssn-uuid"]
datatypes_obfuscated Data type obfuscated ["credit-card-uuid"]
detected Sensitive data found ["true"] or ["false"]
obfuscated Data was masked ["true"] or ["false"]
blocked Request was blocked ["true"] or ["false"]
bypassed Request bypassed scanning ["true"] or ["false"]
hostname Hostname matched ["api.example.com"]
username Username matched ["john.doe"]
usergroup User group matched ["Finance"]
content_type Content type ["application/json"]
client_device Device type ["Mobile"]
client_ip Client IP ["192.168.1.100"]
icap_mode ICAP mode ["REQMOD"], ["RESPMOD"], ["API"]

Threshold Time Formats

Format Description Use Case
"1m" 1 minute Immediate alerts
"5m" 5 minutes Short-term bursts
"15m" 15 minutes Medium-term patterns
"1h" 1 hour Hourly monitoring
"24h" 24 hours Daily thresholds
"1d" 1 day Same as 24h
"7d" 7 days Weekly patterns

Threshold Types

Rolling Window

Threshold evaluated over a sliding time window:

{
      "thresholdTime": "5",
      "thresholdType": "minutes"
}

Behavior: - Window slides continuously - More responsive to sudden bursts - Better for real-time monitoring - Recommended for most use cases

Fixed Window

Threshold evaluated over fixed time intervals:

{
  "thresholdTime": "1",
  "thresholdType": "hours"
}

Behavior: - Window resets at fixed intervals - Useful for periodic reporting - May miss events at boundary - Better for daily/weekly summaries

Threshold Configuration

Time Units

Specify how often to evaluate the alert conditions:

Unit Description Example
"minutes" Check every N minutes "thresholdTime": "5", "thresholdType": "minutes"
"hours" Check every N hours "thresholdTime": "1", "thresholdType": "hours"
"days" Check every N days "thresholdTime": "1", "thresholdType": "days"
"CRON" Custom cron schedule "thresholdTime": "0 */2 * * *", "thresholdType": "CRON"

Examples

Every 15 minutes: 

{
  "thresholdTime": "15",
  "thresholdType": "minutes"
}

Every 2 hours using CRON: 

{
  "thresholdTime": "0 */2 * * *",
  "thresholdType": "CRON"
}

Daily at midnight: 

{
  "thresholdTime": "0 0 * * *",
  "thresholdType": "CRON"
}

Notification Channels

Email

{
  "notificationTypes": ["email"],
  "emailRecipients": [
    "security@company.com",
    "soc@company.com"
  ]
}

Requirements: - SMTP must be configured in Shield - Recipients must be valid email addresses - No limit on number of recipients

Slack

{
  "notificationTypes": ["slack"],
  "slackChannels": [
    "channel-uuid-1",
    "channel-uuid-2"
  ]
}

Requirements: - Slack integration must be configured - Channel UUIDs obtained from Shield configuration

Microsoft Teams

{
  "notificationTypes": ["teams"],
  "teamsChannels": [
    "channel-uuid-1"
  ]
}

Requirements: - Teams integration must be configured - Channel UUIDs obtained from Shield configuration

Webhooks

{
  "notificationTypes": ["webhook"],
  "webhookUrls": [
    "https://api.company.com/shield-alerts"
  ]
}

Requirements: - Webhook endpoints must be accessible from Shield - Endpoint must accept POST requests - Returns 200-299 status code

Alert Patterns

Compliance Monitoring

Monitor for unmasked PII leaving the organization:

{
  "name": "HIPAA Data Leakage",
            "thresholdTime": "1",
            "thresholdType": "minutes",
  "conditions": [
    {"type": "datatypes_detected", "values": ["phi-uuid"]},
    {"type": "obfuscated", "values": ["false"]}
  ]
}

Security Monitoring

Detect potential data exfiltration attempts:

{
  "name": "Potential Data Exfiltration",
      "thresholdTime": "5",
      "thresholdType": "minutes",
  "conditions": [
    {"type": "detected", "values": ["true"]},
    {"type": "icap_mode", "values": ["REQMOD"]}
  ]
}

Operational Monitoring

Monitor for bypass activity or system issues:

{
  "name": "Bypass Activity",
  "thresholdTime": "1",
  "thresholdType": "hours",
  "conditions": [
    {"type": "bypassed", "values": ["true"]}
  ]
}

Best Practices

  • Set appropriate thresholds - Too sensitive = alert fatigue, too high = missed incidents
  • Use rolling windows - More effective than fixed windows for detecting bursts
  • Combine conditions - Multiple conditions create more specific alerts
  • Test alerts - Verify notifications reach recipients before enabling in production
  • Monitor alert logs - Review triggered alerts regularly to tune thresholds
  • Name descriptively - Clear names help identify alert purpose in notifications
  • Document purpose - Use description field to explain why the alert exists
  • Group related alerts - Use consistent naming for alerts monitoring similar events
  • Review periodically - Disabled or outdated alerts should be removed

Negating Conditions

Use the isNot field to negate conditions:

{
  "conditions": [
    {
      "type": "obfuscated",
      "values": ["true"],
      "isNot": true  // Alert when NOT obfuscated
    }
  ]
}

This is useful for: - Monitoring for missing obfuscation - Detecting bypass conditions - Alerting on absence of expected behavior