Replace a custom detection

Request

Replaces the custom detection's logic and rules with what you send. Any rule you don't include is deleted. The detection event name cannot be changed, and is ignored if you send one.

A rule with an id updates the existing rule with that id. A rule without an id is created. Rules are evaluated in the order you send them, and the first rule that matches wins.

To change part of a detection, retrieve it first, apply your changes, and send the complete detection back. Sending a detection that matches what's stored, rule ids included, changes nothing, so a job that re-syncs your detections is safe to run repeatedly.

Security

x-api-key

Path

detectionEventTypestring^CUSTOM_[A-Z0-9_]+$required

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

Example:CUSTOM_TORRENT_WEBSITE_VISIT

Bodyapplication/jsonrequired

The custom detection's complete desired state.

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, <= 50 items(Custom Detection Control Rule)required

The complete list of control rules the custom detection should have, in priority order. May be empty.

detectionEventTypestring

Optional. The custom detection's unique identifier cannot be updated, so when present this must equal the detection event type in the URL.

Example:"CUSTOM_TORRENT_WEBSITE_VISIT"

detectionEventNamestring

Optional. The custom detection's name cannot be updated, so this field is ignored: the stored name is kept and returned in the response. It is accepted so that a GET response body can be sent back unchanged.

Example:"Torrent website visit"

PUT

/v1/controls/customDetections/{detectionEventType}

curl -i -X PUT \
  https://api.pushsecurity.com/v1/controls/customDetections/CUSTOM_TORRENT_WEBSITE_VISIT \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "detectionLogic": "input: web_request\nmetadata:\n  indicator: TORRENT_MAGNET_LINK_DETECTED\nconditions:\n  request_url:\n    scheme: magnet\n",
    "rules": [
      {
        "name": "Monitor everyone",
        "enabled": true,
        "mode": "MONITOR",
        "severity": "LOW"
      }
    ]
  }'

Responses

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": [ … ]
        }
      }
    }
  ]
}