Rules API

The Rules API lets you manage detection rules programmatically. Deploy rules from version control, sync across instances, or build custom rule management UIs.

Note

Rules API endpoints require rules:read for GET requests and rules:write for create/update/delete operations.

List Rules

GET /v1/rules

Retrieve all detection rules for the current instance.

Parameter Type Required Description
enabled boolean Optional Filter by enabled status
source string Optional Filter by event source
severity string Optional Filter by severity
tag string Optional Filter by tag
search string Optional Search rule names and descriptions
page integer Optional Page number (default: 1)
per_page integer Optional Results per page (default: 50)
Example Request 

curl -H "Authorization: Bearer snk_live_xxxx" \
      "https://api.sentinelnerd.com/v1/rules?enabled=true&source=unifi_network"
Example Response 
{
  "data": [
    {
      "id": "rule_abc123",
      "name": "net.ssh_brute_force",
      "description": "Multiple SSH login failures from a single source",
      "severity": "high",
      "enabled": true,
      "source": "unifi_network",
      "tags": ["network", "brute_force", "ssh"],
      "conditions": [...],
      "window": "5m",
      "threshold": { "count": 10, "group_by": "event.src_ip" },
      "actions": [...],
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-14T16:30:00Z",
      "stats": {
        "matches_24h": 7,
        "matches_7d": 42,
        "last_match": "2025-01-15T13:45:00Z"
      }
    }
  ],
  "pagination": {
    "total": 54,
    "page": 1,
    "per_page": 50,
    "total_pages": 2
  }
}

Get Single Rule

GET /v1/rules/:id

Retrieve a single detection rule by ID with full configuration and match statistics.

Create Rule

POST /v1/rules

Create a new detection rule.

Parameter Type Required Description
name string Required Unique rule name in namespace.name format
description string Required Human-readable description
severity string Required critical, high, medium, low, or info
enabled boolean Optional Whether the rule is active (default: true)
source string Optional Event source filter (default: any)
tags string[] Optional Tags for organizing rules
conditions object[] Required Array of condition objects
window string Optional Time window for aggregate rules (e.g., 5m, 1h)
threshold object Optional Threshold configuration for windowed rules
actions object[] Required Array of action objects to execute on match
Create Rule 
curl -X POST https://api.sentinelnerd.com/v1/rules \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom.failed_admin_login",
    "description": "Failed login attempt on admin accounts",
    "severity": "high",
    "source": "unifi_network",
    "tags": ["authentication", "admin"],
    "conditions": [
      { "field": "event.type", "equals": "login_failure" },
      { "field": "event.username", "regex": "^(admin|root|ubnt)$" }
    ],
    "actions": [
      { "alert": { "channels": ["slack", "email"] } }
    ]
  }'

Update Rule

PUT /v1/rules/:id

Update an existing detection rule. Sends the full rule configuration (not a partial update).

Parameter Type Required Description
name string Required Rule name (cannot be changed)
description string Required Updated description
severity string Required Updated severity
enabled boolean Required Updated enabled status
conditions object[] Required Updated conditions
actions object[] Required Updated actions

Toggle Rule

PATCH /v1/rules/:id

Partially update a rule. Useful for enabling/disabling without sending the full configuration.

Parameter Type Required Description
enabled boolean Optional Enable or disable the rule
severity string Optional Update severity only
Disable a Rule 
curl -X PATCH https://api.sentinelnerd.com/v1/rules/rule_abc123 \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Delete Rule

DELETE /v1/rules/:id

Permanently delete a detection rule. This cannot be undone.

Warning

Deleting a rule is permanent. Consider disabling it instead if you might need it again. Built-in rules cannot be deleted, only disabled.

Simulate Rule

POST /v1/rules/simulate

Test a rule against historical events without creating it.

Parameter Type Required Description
rule object Required Full rule configuration to test
time_range object Required Time range to test against (max 7 days)
Simulate Response 
{
  "data": {
    "matches": 23,
    "sample_events": [...],
    "estimated_alerts_per_day": 3.2,
    "false_positive_estimate": "low"
  }
}