Skip to content
/
Add a custom detection

Add a custom detection

Request

Creates a custom detection from the name, detection logic and rules you send. The detection event type is derived from the name, returned in the response, and cannot be changed afterwards. Rules are evaluated in the order you send them, and the first rule that matches wins.

Security
x-api-key
Bodyapplication/jsonrequired

The new custom detection's complete state.

detectionEventNamestring, <= 75 charactersrequired

The custom detection's name. May only contain letters, numbers, spaces and underscores. The detection event type identifying the detection is derived from it (uppercased, spaces become underscores, prefixed with CUSTOM_) and returned in the response.

Example:"Torrent website visit"
detectionLogicstringrequired

The detection logic: one or more detection rules, each a YAML document describing what the browser extension matches on, separated by the standard YAML document separator. It is stored exactly as sent. See the custom detection specification for the format of the YAML.

Example:"input: web_request\nmetadata:\n indicator: TORRENT_MAGNET_LINK_DETECTED\nconditions:\n request_url:\n scheme: magnet\n"
rulesArray of objects, [ 1 .. 50 ] items(New Custom Detection Control Rule)required

The control rules the custom detection starts with, in priority order. At least one is required.

POST
/v1/controls/customDetections
curl -i -X POST \
  https://api.pushsecurity.com/v1/controls/customDetections \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "detectionEventName": "Torrent website visit",
    "detectionLogic": "input: web_request\nmetadata:\n  indicator: TORRENT_MAGNET_LINK_DETECTED\nconditions:\n  request_url:\n    scheme: magnet\n",
    "rules": [
      {
        "name": "Warn Finance about torrent sites",
        "enabled": true,
        "mode": "WARN"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
detectionEventTypestringrequired

The custom detection's unique identifier. Always an uppercase identifier beginning with CUSTOM_.

Example:"CUSTOM_TORRENT_WEBSITE_VISIT"
detectionEventNamestringrequired

The custom detection's name, set when the detection was created. It cannot be updated.

Example:"Torrent website visit"
detectionLogicstringrequired

The detection logic: one or more detection rules, each a YAML document describing what the browser extension matches on, separated by the standard YAML document separator. It is returned exactly as stored. See the custom detection specification for the format of the YAML.

Example:"input: web_request\nmetadata:\n indicator: TORRENT_MAGNET_LINK_DETECTED\nconditions:\n request_url:\n scheme: magnet\n"
rulesArray of objects(Custom Detection Control Rule)required

The custom detection's control rules, in priority order. The first rule that matches wins.

Response
{
  "detectionEventType": "CUSTOM_TORRENT_WEBSITE_VISIT",
  "detectionEventName": "Torrent website visit",
  "detectionLogic": "input: web_request\nmetadata:\n  indicator: TORRENT_MAGNET_LINK_DETECTED\nconditions:\n  request_url:\n    scheme: magnet\n",
  "rules": [
    {
      "id": "c478966c-f927-411c-b919-179832d3d50c",
      "name": "Warn Finance about torrent sites",
      "enabled": true,
      "mode": "WARN",
      "severity": "MEDIUM",
      "title": "Torrent sites are not allowed",
      "subtext": "Downloading torrents on company devices is not permitted.",
      "buttonText": "I understand",
      "detectOnInternalHosts": false,
      "criteria": {
        "employeeIds": {
          "matches": [ … ]
        },
        "employeeGroups": {
          "matches": [ … ]
        }
      }
    }
  ]
}