Skip to main content
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"

​
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

  • 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
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

  1. Use specific matchers - Combine multiple matcher types to reduce false positives
  2. Name your matchers - Use descriptive names when working with workflows or debugging
  3. Use DSL for complex logic - DSL matchers provide the most flexibility for complex conditions
  4. Test negative cases - Use negative: true to exclude known false positives
  5. Match on multiple parts - Don’t rely solely on body content; include headers or status codes
  6. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us