{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Custom detections: Specification","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"custom-detections-specification","__idx":0},"children":["Custom detections: Specification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Custom detections let admins write their own detection rules. Use them to identify browser-based threats specific to your organisation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rules are written in YAML. A configuration file may contain one or more rules, separated by ",{"$$mdtype":"Tag","name":"code","attributes":{"style":{"whiteSpace":"nowrap"}},"children":["---"]}," (standard YAML multi-document syntax). Push validates the configuration against this specification when you save a custom detection."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rule-structure","__idx":1},"children":["Rule structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each rule is a YAML document with the following top-level keys:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Key"},"children":["Key "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"10%","data-label":"Required"},"children":["Required "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["input"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The data source the rule operates on."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicator configuration for the rule."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conditions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logic that determines when the rule fires."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A note for your own reference. Not used at runtime."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["min_spec"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Minimum specification version required to evaluate this rule."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["extension_version_constraints"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Restrict the rule to specific extension versions."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"input","__idx":2},"children":["input"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dom_content"]}," — Match against the page DOM (CSS selectors, HTML comments, page URL, document title, JavaScript-set cookies)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["web_request"]}," — Match against outgoing HTTP requests."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["web_response"]}," — Match against incoming HTTP responses."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"metadata","__idx":3},"children":["metadata"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Key"},"children":["Key "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"10%","data-label":"Required"},"children":["Required "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["indicator"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENUM_STYLE"]}," string labelling the specific indicator matched by this rule. Must match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["^[A-Z0-9_]+$"]},". You may use any value, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TORRENT_MAGNET_LINK"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conditions","__idx":4},"children":["conditions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Conditions define when the rule fires. The structure determines how they are combined:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["map"]}," (key-value pairs at the same level) combines conditions with logical ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AND"]}," — all must match."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["list"]}," combines conditions with logical ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OR"]}," — any must match."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"conditions:\n  method: POST\n  request_url:\n    path|endswith: /submit.php\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"dom-content-rules-input-dom_content","__idx":5},"children":["DOM content rules (input: dom_content)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Key"},"children":["Key "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"60%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["css_selectors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match elements in the page DOM."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["html_comments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match HTML comments in the document."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match the page URL (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window.location.href"]},"). See URL conditions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document.title"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_cookies"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match cookies accessible via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document.cookie"]}," (key-value test)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"css-selectors","__idx":6},"children":["CSS selectors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A selector entry can be a plain string (used directly with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["querySelector()"]},"), or a map with the following keys:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Key"},"children":["Key "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"60%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selector"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSS selector using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["querySelector()"]}," — matches the first element."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selector_all"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSS selector using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["querySelectorAll()"]}," — matches all elements."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text_content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test the element's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["textContent"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text_nodes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test the concatenated value of child text nodes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inner_html"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test the element's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["innerHTML"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outer_html"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test the element's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outerHTML"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["condition"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selector_all"]}," only. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["all"]}," to require every matched element to pass the test. Default is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["any"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Match any <a> inside a <p> that contains \"Create one!\"\ncss_selectors:\n  selector: p > a\n  text_content|includes: Create one!\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# All <script> elements must contain \"atob(\"\ncss_selectors:\n  selector_all: script\n  text_content|includes: atob(\n  condition: all\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"html-comments","__idx":7},"children":["HTML comments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Match against HTML comment content. A plain string checks for exact equality. Use a named key with a modifier for other tests:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Match either comment (OR)\nhtml_comments:\n  - ex1|includes: example text\n  - ex2|startswith: another example\n\n# Both comments must match (AND)\nhtml_comments:\n  ex1|includes: example text\n  ex2|startswith: another example\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-request-rules-input-web_request","__idx":8},"children":["HTTP request rules (input: web_request)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Key"},"children":["Key "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"60%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["method"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP method, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match the request URL. See URL conditions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tab_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match the URL of the browser tab at the time of the request. See URL conditions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource type, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["script"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["xmlhttprequest"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["main_frame"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Raw request body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form_data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parsed form data for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]}," requests (key-value test)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_headers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP request headers (key-value test)."]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," A rule that tests ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_headers"]}," cannot also test ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]},". These come from different browser extension events."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"input: web_request\nmetadata:\n  indicator: SUSPICIOUS_FORM_SUBMISSION\nconditions:\n  method: POST\n  request_url:\n    path|endswith: /collect\n  form_data:\n    - name: email\n      value|exists: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-response-rules-input-web_response","__idx":9},"children":["HTTP response rules (input: web_response)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Key"},"children":["Key "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"60%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["method"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match the request URL. See URL conditions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tab_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Match the URL of the browser tab. See URL conditions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP response status code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_headers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP response headers (key-value test)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cookies"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cookies from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["set-cookie"]}," response headers (key-value test)."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"input: web_response\nmetadata:\n  indicator: TRACKING_COOKIE_SET\nconditions:\n  cookies:\n    - name: tracking_id\n      value|exists: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"url-conditions","__idx":10},"children":["URL conditions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A URL condition can be:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A plain string — tested against the full URL (exact equality after trimming, or with a modifier)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A map targeting specific URL components."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"30%","data-label":"Component"},"children":["Component "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"30%","data-label":"Description"},"children":["Description "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Example value"},"children":["Example value "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["href"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://a.b.example.co.uk:8080/login?x=y#h"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheme"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Protocol, without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Scheme + host + port"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://a.b.example.co.uk:8080"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["host"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hostname + port"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a.b.example.co.uk:8080"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hostname"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full hostname"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a.b.example.co.uk"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subdomain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subdomain parts only"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a.b"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sld"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Second-level domain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tld"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top-level domain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["co.uk"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["root"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hostname without subdomain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example.co.uk"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL path"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/login"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["params"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full query string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?x=y"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hash"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fragment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#h"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["port"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Port number (blank if the default for the protocol)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["8080"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search_params"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parsed query parameters (key-value test)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hostname_parts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of hostname parts split on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["."]}," — matches if any part matches"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Path ends with /login\nrequest_url:\n  path|endswith: /login\n\n# Any part of the hostname equals \"ipfs\"\nrequest_url:\n  hostname_parts: ipfs\n\n# Query parameter \"token\" exists\nrequest_url:\n  search_params:\n    - name: token\n      value|exists: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-value-tests","__idx":11},"children":["Key-value tests"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Conditions for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search_params"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form_data"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_headers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_headers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cookies"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_cookies"]}," are key-value tests. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," sub-keys to match against entries:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Any query parameter starting \"user_\" with a numeric value\nrequest_url:\n  search_params:\n    - name|startswith: user_\n      value|re: ^[\\d-]+$\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Match a form submission containing an email at a specific domain\nform_data:\n  - name: email\n    value|endswith: @example.com\n  - name: password\n    value|exists: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"test-modifiers","__idx":12},"children":["Test modifiers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Append modifiers to a condition key with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Modifier"},"children":["Modifier "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"60%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(none)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Trim the value and check exact equality."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|includes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String contains the match."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|startswith"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String starts with the match."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|endswith"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String ends with the match."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|re"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String matches the regular expression."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|normalize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Collapse whitespace, remove zero-width characters, and lowercase before testing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|exists"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean — whether the named property exists (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},") or does not exist (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|length"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Length of a string, or count of items in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cookies"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form_data"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search_params"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Modifiers can be stacked. Unknown modifiers are ignored, which allows applying multiple tests of the same type to a single key — all must match:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Normalize then check equality\ntext_content|normalize: example text\n\n# All three includes tests must match\ncss_selectors:\n  selector_all: script\n  text_content|includes|a: fetch(\n  text_content|includes|b: atob(\n  text_content|includes|c: document.write(\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Wildcard tests (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["includes"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["re"]},") are performed on values truncated to 500,000 characters."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"extension-version-constraints","__idx":13},"children":["Extension version constraints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specify a list of version ranges. Items in the list are combined with OR. Multiple constraints within a single item are combined with AND."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"extension_version_constraints:\n  - \">=2.5.0\"\n  - \">=1.9.0 <2.0.0\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported operators: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<="]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[">"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[">="]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["!="]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"full-example","__idx":14},"children":["Full example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"---\ndescription: Detect requests using the magnet protocol\ninput: web_request\nmetadata:\n  indicator: TORRENT_MAGNET_LINK_DETECTED\nconditions:\n  request_url:\n    scheme: magnet\n---\ndescription: Detect form submissions to a known data collection endpoint\ninput: web_request\nmetadata:\n  indicator: SUSPICIOUS_FORM_SUBMISSION\nconditions:\n  method: POST\n  request_url:\n    path|endswith: /collect\n  form_data:\n    - name: email\n      value|exists: true\n","lang":"yaml"},"children":[]}]},"headings":[{"value":"Custom detections: Specification","id":"custom-detections-specification","depth":1},{"value":"Rule structure","id":"rule-structure","depth":2},{"value":"input","id":"input","depth":2},{"value":"metadata","id":"metadata","depth":2},{"value":"conditions","id":"conditions","depth":2},{"value":"DOM content rules (input: dom_content)","id":"dom-content-rules-input-dom_content","depth":2},{"value":"CSS selectors","id":"css-selectors","depth":3},{"value":"HTML comments","id":"html-comments","depth":3},{"value":"HTTP request rules (input: web_request)","id":"http-request-rules-input-web_request","depth":2},{"value":"HTTP response rules (input: web_response)","id":"http-response-rules-input-web_response","depth":2},{"value":"URL conditions","id":"url-conditions","depth":2},{"value":"Key-value tests","id":"key-value-tests","depth":2},{"value":"Test modifiers","id":"test-modifiers","depth":2},{"value":"Extension version constraints","id":"extension-version-constraints","depth":2},{"value":"Full example","id":"full-example","depth":2}],"frontmatter":{"seo":{"title":"Custom detections: Specification"}},"lastModified":"2026-05-08T09:46:35.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/resources/custom-detections","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}