Custom detections: Specification

Custom detections let admins write their own detection rules. Use them to identify browser-based threats specific to your organisation.

Rules are written in YAML. A configuration file may contain one or more rules, separated by --- (standard YAML multi-document syntax). Push validates the configuration against this specification when you save a custom detection.

Each rule is a YAML document with the following top-level keys:

One of:

• dom_content — Match against the page DOM (CSS selectors, HTML comments, page URL, document title, JavaScript-set cookies).
• web_request — Match against outgoing HTTP requests.
• web_response — Match against incoming HTTP responses.

Conditions define when the rule fires. The structure determines how they are combined:

• A map (key-value pairs at the same level) combines conditions with logical AND — all must match.
• A list combines conditions with logical OR — any must match.

These can be nested to express more complex logic. The following example requires method AND request_url, with request_url being evaluated as (path endswith /submit.php):

conditions:
  method: POST
  request_url:
    path|endswith: /submit.php

A selector entry can be a plain string (used directly with querySelector()), or a map with the following keys:

# Match any <a> inside a <p> that contains "Create one!"
css_selectors:
  selector: p > a
  text_content|includes: Create one!

# All <script> elements must contain "atob("
css_selectors:
  selector_all: script
  text_content|includes: atob(
  condition: all

Match against HTML comment content. A plain string checks for exact equality. Use a named key with a modifier for other tests:

# Match either comment (OR)
html_comments:
  - ex1|includes: example text
  - ex2|startswith: another example

# Both comments must match (AND)
html_comments:
  ex1|includes: example text
  ex2|startswith: another example

Note: A rule that tests request_headers cannot also test body. These come from different browser extension events.

input: web_request
metadata:
  indicator: SUSPICIOUS_FORM_SUBMISSION
conditions:
  method: POST
  request_url:
    path|endswith: /collect
  form_data:
    - name: email
      value|exists: true

input: web_response
metadata:
  indicator: TRACKING_COOKIE_SET
conditions:
  cookies:
    - name: tracking_id
      value|exists: true

A URL condition can be:

1. A plain string — tested against the full URL (exact equality after trimming, or with a modifier).
2. A map targeting specific URL components.

# Path ends with /login
request_url:
  path|endswith: /login

# Any part of the hostname equals "ipfs"
request_url:
  hostname_parts: ipfs

# Query parameter "token" exists
request_url:
  search_params:
    - name: token
      value|exists: true

Conditions for search_params, form_data, request_headers, response_headers, cookies, and document_cookies are key-value tests. Use name and value sub-keys to match against entries:

# Any query parameter starting "user_" with a numeric value
request_url:
  search_params:
    - name|startswith: user_
      value|re: ^[\d-]+$

# Match a form submission containing an email at a specific domain
form_data:
  - name: email
    value|endswith: @example.com
  - name: password
    value|exists: true

Append modifiers to a condition key with |:

Modifiers can be stacked. Unknown modifiers are ignored, which allows applying multiple tests of the same type to a single key — all must match:

# Normalize then check equality
text_content|normalize: example text

# All three includes tests must match
css_selectors:
  selector_all: script
  text_content|includes|a: fetch(
  text_content|includes|b: atob(
  text_content|includes|c: document.write(

Note: Wildcard tests (includes and re) are performed on values truncated to 500,000 characters.

Use extension_version_constraints to restrict a rule to specific extension versions — for example, to require a minimum version for a feature the rule depends on, or to avoid a version with a known bug.

Specify a list of version ranges. Items in the list are combined with OR. Multiple constraints within a single item are combined with AND.

extension_version_constraints:
  - ">=2.5.0"
  - ">=1.9.0 <2.0.0"

Supported operators: <, <=, >, >=, !=.

---
description: Detect requests using the magnet protocol
input: web_request
metadata:
  indicator: TORRENT_MAGNET_LINK_DETECTED
conditions:
  request_url:
    scheme: magnet
---
description: Detect form submissions to a known data collection endpoint
input: web_request
metadata:
  indicator: SUSPICIOUS_FORM_SUBMISSION
conditions:
  method: POST
  request_url:
    path|endswith: /collect
  form_data:
    - name: email
      value|exists: true