Skip to content

How to Write Unique Matchers in Nuclei Templates

Jump to bottom
Sandeep Singh edited this page Sep 18, 2025 · 2 revisions

Overview

Effective matchers are crucial for accurate template execution and preventing false positives. This guide categorizes matchers into three types with real-world examples and best practices.

Strategic Approach: Think Before You Write

Before diving into matcher implementation, always start by thinking through these three key questions based on the type of template you're creating:

1. What Product/Technology/Service am I targeting?

  • For Detection Templates: What unique identifiers can confirm this is the right product/service?
  • For CVE Templates: What product-specific strings ensure I'm testing the vulnerable application?
  • For Misconfiguration Templates: What service-specific patterns confirm the target technology?

2. What Vulnerability/Issue am I detecting?

  • For CVE Templates: What specific indicators prove this vulnerability exists and was exploited?
  • For XSS/SQLi Templates: What payload responses confirm successful injection?
  • For Misconfiguration Templates: What configuration patterns indicate the security issue?

3. What Supporting Evidence strengthens my detection?

  • For All Templates: What HTTP status codes, headers, or timing patterns support my primary detection?
  • For Web Templates: What content-types, response sizes, or cache headers add confidence?
  • For Network Templates: What protocol responses or connection patterns validate the finding?

Template Type Strategy Guide

Template Type Primary Focus Secondary Focus Supporting Focus
Detection/Tech Product/Service ID Version/Features Status Codes
CVE/Vulnerability Product ID + Vuln Evidence Exploit Results Response Validation
Misconfiguration Service ID + Config Issue Error Messages Protocol Responses
Credential/Auth Product ID + Auth Bypass Login Success Session Evidence

Remember: The order matters! Start with identification, add vulnerability-specific detection, then strengthen with supporting matchers.

1. Product/Technology/Service Identification Matchers

Purpose: Ensure the template matches against the expected target product/technology/service, preventing false positives from unrelated applications or services.

Key Principle: Use unique strings, headers, or patterns that are specific to the target product, technology, or service.

Examples

Strong Product Identification

# TeamSpeak 3 Server Detection
matchers:
  - type: word
    words:
      - "TS3"
      - "TeamSpeak 3 ServerQuery interface"
    condition: and

WordPress Plugin Detection

# Flexmls IDX Plugin Detection
matchers:
  - type: regex
    part: body
    regex:
      - '(?i)Stable.tag:\s?([\w.]+)'

Server Header Identification

# CUPS Server Detection
matchers:
  - type: word
    part: header
    words:
      - "Server: CUPS"

Application-Specific Patterns

# SearXNG Search Engine Detection
matchers:
  - type: word
    part: body
    words:
      - "<title>SearXNG</title>"

Best Practices for Product/Technology/Service Identification

  • Use unique product/service names, version strings, or branded elements
  • Look for distinctive HTML comments, meta tags, or JavaScript variables
  • Utilize specific HTTP headers (Server, X-Powered-By, etc.)
  • Include version detection when possible for better accuracy
  • Identify service-specific protocols, commands, or response patterns
  • Avoid generic terms that could match multiple products/services

2. Vulnerability Identification Matchers

Purpose: Detect specific vulnerabilities or misconfigurations with high precision, ensuring the vulnerability actually exists.

Key Principle: Match on vulnerability-specific indicators, error messages, or exploit results.

Examples

CVE Exploitation Results

# CVE-2022-0543 - Redis RCE
matchers:
  - type: regex
    regex:
      - "root:.*:0:0:"  # /etc/passwd content indicating successful command execution

XSS Vulnerability Detection

# SLiMS XSS Detection
matchers:
  - type: word
    words:
      - '<script>alert(document.domain)</script>'  # Injected payload
      - 'SLiMS'                                   # Product confirmation
      - 'name="author'                            # Additional product marker
    condition: and

Version-Based Vulnerability Detection

# ZenML Authentication Bypass (CVE-2024-25723)
matchers:
  - type: dsl
    dsl:
      - "compare_versions(version, '< 0.46.7')"
      - "!contains_any(version, '0.44.4', '0.43.1', '0.42.2')"
      - "contains_all(body, 'deployment_type', 'database_type')"
    condition: and

Redirect-Based Detection

# Brother Printer Status Redirect Detection
matchers:
  - type: word
    part: header
    words:
      - "/general/status.html"  # Specific redirect pattern

Best Practices for Vulnerability Identification

  • Match on actual exploit results (command output, injected content)
  • Use vulnerability-specific error messages or responses
  • Implement version checks with precise version ranges
  • Look for unique vulnerability indicators (specific paths, parameters)
  • Combine multiple indicators to reduce false positives

3. Supporting Matchers

Purpose: Provide additional validation to strengthen detection accuracy when primary matchers lack uniqueness.

Key Principle: Use common HTTP elements that support but don't define the detection.

Examples

HTTP Status Codes

# Successful Response Validation
matchers:
  - type: status
    status:
      - 200

Redirect Status Validation

# Redirect Detection Support
matchers:
  - type: status
    status:
      - 301

Content-Type Validation

# HTML Content Validation
matchers:
  - type: word
    part: content_type
    words:
      - "text/html"

Cache Control Headers

# Cache Behavior Validation
matchers:
  - type: word
    part: header
    words:
      - "no-store"
      - "no-cache"
    condition: or

Response Timing (for specific vulnerabilities)

# Time-based Detection Support
matchers:
  - type: dsl
    dsl:
      - "duration >= 5"

Best Practices for Supporting Matchers

  • Never use supporting matchers as the primary detection method
  • Combine with product or vulnerability identification matchers
  • Use matchers-condition: and to ensure all conditions are met
  • Common supporting matchers include:
    • HTTP status codes (200, 301, 302, 403, 404, 500)
    • Content-Type headers
    • Response size ranges
    • Response timing patterns
    • Generic cache control headers

Matcher Combination Strategies

AND Logic for Strict Matching

matchers-condition: and
matchers:
  - type: word
    words:
      - "Product-Specific-String"  # Product identification
  - type: word
    words:
      - "vulnerability-indicator"  # Vulnerability identification
  - type: status
    status:
      - 200                       # Supporting matcher

OR Logic for Multiple Paths

matchers-condition: or
matchers:
  - type: word
    words:
      - "path1-specific-indicator"
  - type: word
    words:
      - "path2-specific-indicator"

Common Anti-Patterns to Avoid

❌ Overly Generic Matchers

# BAD: Too generic, matches many applications
matchers:
  - type: word
    words:
      - "admin"
      - "login"

❌ Status Code Only Detection

# BAD: Status codes alone are not unique
matchers:
  - type: status
    status:
      - 200

❌ Single Generic String

# BAD: "error" appears in many applications
matchers:
  - type: word
    words:
      - "error"

✅ Improved Versions

Strong Product + Vulnerability + Support

matchers-condition: and
matchers:
  - type: word
    words:
      - "MySpecificProduct v"     # Unique product identifier
      - "vulnerability-specific"  # Vulnerability indicator
    condition: and
  - type: status
    status:
      - 200                      # Supporting validation

Template Structure Best Practices

  1. Start with Product/Service Identification: Always confirm you're testing the right product/service
  2. Add Vulnerability Specifics: Include unique vulnerability indicators
  3. Use Supporting Matchers: Add status codes, content-types for additional validation
  4. Test Thoroughly: Verify against both vulnerable and non-vulnerable instances
  5. Document Reasoning: Explain why each matcher was chosen

Matcher Priority Order

  1. Primary: Product/Technology/Service identification (most important)
  2. Secondary: Vulnerability-specific indicators
  3. Tertiary: Supporting matchers (status, content-type, etc.)

This hierarchy ensures templates are both accurate and maintainable.

Clone this wiki locally