How to Write Unique Matchers in Nuclei Templates

How to Write Unique Matchers in Nuclei Templates

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.