Blog
-

4 min read

Effortless Passive Detection Using Global Matchers in Nuclei

Nuclei & Templates
Effortless Passive Detection Using Global Matchers in Nuclei

Share

If you've ever found yourself repeatedly setting up the same matchers in multiple Nuclei templates, it's time to break free from that cycle. Meet global matchers, a killer feature in Nuclei that simplifies your detection workflow.

Imagine having a single template that automatically hunts for specific patterns (like private keys, sensitive tokens, or webhooks) across every HTTP response from all your other templates. That's what global matchers do — and they do it effortlessly.

In this post, we'll cover everything you need to know about global matchers, why they're a game-changer, and how to use them to make your scans smarter and more efficient.

What Exactly are Global Matchers?

At their core, global matchers are basically matchers that operate on a global level. Instead of being tied to a specific request in a single template, they automatically apply to all HTTP responses received during a scan. Whether you're scanning for misconfigurations, secrets, or vulnerabilities, global matchers let you define your logic once and reuse it across all templates.

Why Should You Care?

Imagine you're hunting for specific patterns — say, private keys or Slack webhooks. Without global matchers, you'd need to define these patterns in every template you run. Not only is that repetitive, but it's also a pain to maintain. Global matchers solve this problem by centralizing your detection logic.

Benefits

  1. Save Time: No more copy-pasting matchers across templates. Define them once, and they work everywhere.
  2. Reduce Errors: Centralized logic means fewer chances of typos or mismatched patterns.
  3. Passive Detection: Global matchers analyze responses without triggering additional requests.
  4. Enhanced Efficiency: Spot secrets, errors, or unusual behavior across multiple templates without duplicating effort.

What Can You Do with Global Matchers?

Global matchers shine in scenarios where you need to:

  • Detect sensitive information: Think API keys, private keys, or credentials accidentally exposed in HTTP responses.
  • Fingerprint systems or technologies: Identify software versions, frameworks, or libraries used by a target.
  • Catch errors and misconfigurations: Look for stack traces, default error messages, or other signs of trouble.
  • Spot WAFs or unusual behaviors: Passively detect security tools and defenses without triggering them directly.

Key Things to Know

Before diving into examples, let's go over some important details about global matchers:

  1. HTTP-protocol-based Only: Global matchers work exclusively with HTTP-protocol-based templates. If you're working with DNS, TCP, or other protocols, this feature won't apply.
  2. No Requests Sent: A global matchers template won't send any HTTP requests on its own. It purely evaluates the responses from other templates.
  3. Matchers and Extractors: You can use global matchers for both matching patterns and extracting data from responses.
  4. Explicit Enablement: You must use the -enable-global-matchers or -egm flag (or enable them programmatically via nuclei.EnableGlobalMatchersTemplates if you're working with the Nuclei SDK) to activate them. Otherwise, the template won’t run.
💡
The global-matchers has been available since Nuclei v3.3.5, and you can refer to the documentation for more details on its usage.

Let's Build a Global Matchers Template

Say you want to hunt for:

  1. Asymmetric private keys: These are often exposed in server misconfigurations or backups.
  2. Slack webhooks: Attackers can exploit these to send unauthorized messages.

Here's how your template might look:

yaml

1# http-template-with-global-matchers.yaml
2http:
3  - global-matchers: true
4    matchers-condition: or
5    matchers:
6      - type: regex
7        name: asymmetric_private_key
8        regex:
9          - '-----BEGIN ((EC|PGP|DSA|RSA|OPENSSH) )?PRIVATE KEY( BLOCK)?-----'
10        part: body
11
12      - type: regex
13        name: slack_webhook
14        regex:
15          - >-
16            https://hooks.slack.com/services/T[a-zA-Z0-9_]{8,10}/B[a-zA-Z0-9_]{8,12}/[a-zA-Z0-9_]{23,24}
17        part: body

This template has global-matchers: true, which tells Nuclei to apply these matchers to every HTTP response it processes during a scan. The matchers-condition: or means it'll flag a response if any of the defined patterns are found.

Running the Scan

Now that you've got your global matchers template, it's time to put it to work. Pair it with some regular templates:

bash

1nuclei -enable-global-matchers \
2  -t http-template-with-global-matchers.yaml \
3  -t http-template-1.yaml \
4  -t http-template-2.yaml \
5  -silent -u http://scanme.sh
📝
Global matchers are NOT applied by default. You need to explicitly enable them using the -enable-global-matchers/-egm flag.

Here's a sample output:

plaintext

1[http-template-with-global-matchers:asymmetric_private_key] http://scanme.sh/request-from-http-template-1
2[http-template-with-global-matchers:slack_webhook] http://scanme.sh/request-from-http-template-2

In this example, the global matchers template found an asymmetric private key in a response from http-template-1 and a Slack webhook in a response from http-template-2. Notice how the matchers didn't need to be defined in either of those templates — they're applied automatically!

Pro Tips

  1. Test Regularly: Run your global matchers on a small set of URLs before scaling up. This helps you fine-tune patterns and avoid false positives.
  2. Use Extractors: Want more than just matches? Add extractors to your global matchers templates to pull out juicy details like API tokens or email addresses.
  3. Think Broadly: Global matchers are great for spotting trends or patterns that span multiple templates. Use them to uncover the unexpected.

Advanced Use Cases

Let's explore some creative ways to use global matchers:

1. Detecting Default Configurations

Look for telltale signs of default installations or misconfigured servers:

  • Admin panels exposed on /admin.
  • Default Apache or Nginx error pages.
  • CMS setup wizards left open to the public.

2. Identifying Sensitive Files

Global matchers can scan for accidentally exposed files like:

  • .env files containing environment variables.
  • Backup files (.bak, .zip, .tar.gz) in web directories.
  • Log files with sensitive details.

3. Passive WAF Detection

Instead of actively probing for WAFs, use global matchers to detect passive indicators in HTTP responses, such as patterns in error messages.

Cloud Support - Coming Soon

We're excited about the possibilities with this new feature and plan to integrate global matchers into ProjectDiscovery Cloud workflows in an upcoming release. Until then, we'd love to hear your ideas! If you have any workflows, feature requests, or suggestions, please share them with us or drop a PR.

Wrapping Up

Global matchers are one of those “aha!” features in Nuclei that can seriously up your game. Whether you're a beginner looking to simplify your workflows or a seasoned pro hunting for advanced detection tricks, global matchers offer a powerful, flexible way to enhance your scans.

By centralizing detection logic, you save time, reduce errors, and make your templates way easier to maintain. So, why not give them a try? Build your first global matchers template today and start spotting those hidden gems in your scans!

References