Rules API | SentinelNerd

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"
  }
}