Matchers

Matchers are the detection mechanism in Nuclei templates that determine whether a request was successful by performing pattern matching on request/response data. They are the core logic that identifies vulnerabilities, misconfigurations, or specific conditions.

Matcher types

Nuclei supports multiple matcher types for different matching scenarios:

Match specific words or phrases in the response.

matchers:
  - type: word
    words:
      - "[core]"
      - "mail.protection.outlook.com"

Match using regular expressions (Go regex engine).

matchers:
  - type: regex
    regex:
      - "(?mi)^Via\\s*?:.*?linkerd.*$"
      - "(?m)^(?:Location\\s*?:\\s*?)(?:https?://|//)?(?:[a-zA-Z0-9\\-_\\.@]*)example\\.com.*$"

Go regex engine does not support lookaheads or lookbehinds.

Match HTTP status codes.

matchers:
  - type: status
    status:
      - 200
      - 302

Match response size in bytes.

matchers:
  - type: size
    size:
      - 3029
      - 2042

Match binary patterns (hex-encoded).

matchers:
  - type: binary
    binary:
      - "4a4156412050524f46494c45"  # JAVA PROFILE
      - "4850524f46"                # HPROF
      - "1f8b080000000000"          # Gunzip magic byte

Match using Domain Specific Language expressions with helper functions.

matchers:
  - type: dsl
    dsl:
      - "contains(body, 'packages') && contains(tolower(all_headers), 'application/octet-stream') && status_code == 200"
      - "!contains(tolower(all_headers), 'strict-transport-security')"

Match using XPath queries on HTML/XML responses.

matchers:
  - type: xpath
    xpath:
      - "/html/head/title[contains(text(), 'How to Find XPath')]"
      - "//a[@target='_blank']"

Matcher conditions

Control how multiple matchers are evaluated using conditions:

condition

string

default:"or"

The logical condition between matcher values within a single matcher.

and - All patterns must match
or - Any pattern can match

matchers-condition

string

default:"or"

The logical condition between multiple matchers in a request.

and - All matchers must succeed
or - Any matcher can succeed

Example with conditions

http:
  - path:
      - "{{BaseURL}}/.git/config"
    matchers-condition: and
    matchers:
      - type: word
        words:
          - "[core]"
      - type: dsl
        condition: and
        dsl:
          - "!contains(tolower(body), '<html')"
          - "!contains(tolower(body), '<body')"
      - type: status
        status:
          - 200

Matcher options

part

string

default:"body"

The part of the response to match against. Each protocol exposes different parts.Common HTTP parts: body, header, all, status_code, raw

negative

boolean

default:"false"

Reverse the match result. Only matches if the condition is NOT true.

matchers:
  - type: word
    negative: true
    words:
      - "ERROR"

name

string

Name for the matcher. Names should be lowercase without spaces or underscores.

matchers:
  - type: word
    name: "cookie-matcher"
    words:
      - "Set-Cookie"

case-insensitive

boolean

default:"false"

Enable case-insensitive matching for word and regex matchers.

matchers:
  - type: word
    case-insensitive: true
    words:
      - "wordpress"

match-all

boolean

default:"false"

Require all values to match, ignoring the condition parameter.

matchers:
  - type: word
    match-all: true
    words:
      - "admin"
      - "password"

encoding

string

Encoding for the words field. Currently supports hex.

matchers:
  - type: word
    encoding: hex
    words:
      - "3c68746d6c3e"  # <html>

internal

boolean

default:"false"

Hide the matcher from output. Useful in flow templates for internal conditions.

matchers:
  - type: word
    internal: true
    words:
      - ".vercel-dns.com"

Multi-request matching

When using req-condition: true or multiple requests, you can match across requests using indexed variables:

http:
  - method: GET
    path:
      - "{{BaseURL}}/200"
      - "{{BaseURL}}/400"
    
    matchers:
      - type: dsl
        dsl:
          - "status_code_1==200 && status_code_2==400"

Real-world examples

id: git-config-exposure

info:
  name: Git Config File Disclosure
  author: pdteam
  severity: medium

http:
  - path:
      - "{{BaseURL}}/.git/config"
    
    matchers-condition: and
    matchers:
      - type: word
        words:
          - "[core]"
      
      - type: dsl
        condition: and
        dsl:
          - "!contains(tolower(body), '<html')"
          - "!contains(tolower(body), '<body')"
      
      - type: status
        status:
          - 200

Protocol-specific parts

HTTP
DNS
Network

body - Response body (default)
header - Response headers
all_headers - All headers concatenated
status_code - HTTP status code
raw - Raw HTTP response
request - HTTP request
content_length - Response content length
duration - Request duration

raw - Raw DNS response (default)
rcode - DNS response code
question - DNS question field
answer - DNS answer field
ns - DNS nameserver field
extra - DNS extra field

raw - Raw network response (default)
request - Network request
data - Response data

When using multiple matchers with matchers-condition: and, all matchers must succeed for the template to match. This is commonly used to reduce false positives.

Best practices

Use specific matchers - Combine multiple matcher types to reduce false positives
Name your matchers - Use descriptive names when working with workflows or debugging
Use DSL for complex logic - DSL matchers provide the most flexibility for complex conditions
Test negative cases - Use negative: true to exclude known false positives
Match on multiple parts - Don’t rely solely on body content; include headers or status codes
Use internal matchers - Hide intermediate matchers in flow templates with internal: true

Extractors

Extract data from responses

Helper Functions

DSL helper functions

Flow Control

Conditional execution

Workflows

Multi-template execution

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

Matcher types

Matcher conditions

Example with conditions

Matcher options

Multi-request matching

Real-world examples

Protocol-specific parts

Best practices

Extractors

Helper Functions

Flow Control

Workflows

Build docs developers (and LLMs) love

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

Documentation Index

​Matcher types

​Matcher conditions

​Example with conditions

​Matcher options

​Multi-request matching

​Real-world examples

​Protocol-specific parts

​Best practices

​Related

Extractors

Helper Functions

Flow Control

Workflows

Build docs developers (and LLMs) love

Matcher types

Matcher conditions

Example with conditions

Matcher options

Multi-request matching

Real-world examples

Protocol-specific parts

Best practices

Related