Nuclei Tutorial: Template-Driven Vulnerability Scanning

What is Nuclei?

Nuclei is a fast, open-source vulnerability scanner from ProjectDiscovery. Its defining idea is simple: every check is a piece of data, not code. Instead of compiling detection logic into the scanner, you describe what to send and what a vulnerable response looks like in a YAML template. The engine reads thousands of these templates and runs them concurrently against your targets.

That design has two big consequences. First, the detection logic is auditable. Anyone can open a template, read exactly what request it sends and what it matches on, and decide whether to trust it. Second, the community can react quickly. When a new CVE is published, a template often appears in the public nuclei-templates repository within hours, and you pull it with one command. The combination of a single static Go binary, high concurrency, and a shared template library is why Nuclei became a common tool in bug-bounty automation, attack-surface monitoring, and CI security gates.

Nuclei is not limited to web applications. Templates can speak HTTP, DNS, TCP, SSL/TLS, raw network protocols, file-system checks, code execution, and even cloud and Kubernetes configuration audits. That breadth lets one tool cover misconfigurations, exposed panels, default credentials, known CVEs, and information leaks across very different surfaces.

How Nuclei works (key concepts)

A run has three moving parts: targets, templates, and the engine that joins them.

A target is a URL or host you feed in with -u for a single value or -l for a file of many. The template is the YAML unit of detection. Every template needs three things: a unique id, an info block with metadata (name, author, severity, tags), and at least one protocol block such as http, dns, or tcp. Inside the protocol block you define the request, then matchers that decide whether the response indicates a finding.

Matchers are where accuracy lives. Nuclei supports several matcher types: word (literal strings), regex, status (HTTP status codes), binary (byte sequences), and dsl (expressions over response variables). You can target a specific part of the response - the body, a header, or the full response - and combine multiple matchers with matchers-condition: and or or. A template that requires both a status of 200 and a unique body string produces far fewer false positives than one that matches a single generic keyword.

Extractors are the other half. While a matcher decides whether to report, an extractor pulls a value out of the response - a version number, a token, a hostname - either to enrich the report or to feed a follow-up request. Nuclei also exposes built-in DSL helper functions and dynamic variables like {{BaseURL}} and {{Hostname}} so templates stay portable across targets.

The engine loads all selected templates, clusters identical base requests where it can, and fires them concurrently with configurable rate limits. Severity tags (info, low, medium, high, critical) and template tags let you scope a scan tightly, for example running only critical CVE templates against production. Community templates are downloaded to $HOME/nuclei-templates/ by default (configuration lives in $HOME/.config/nuclei/) and refreshed with the update commands below.

Installing Nuclei

If you have a recent Go toolchain (check the Nuclei README for the minimum version), go install compiles the latest release:

# Requires a recent Go version (check with: go version)
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Confirm the binary is on your PATH
nuclei -version

If you do not want to build from source, ProjectDiscovery ships prebuilt binaries on the GitHub releases page and an official Docker image:

# Run via Docker without installing anything locally
docker run --rm projectdiscovery/nuclei:latest -version

# Scan a target through the container
docker run --rm projectdiscovery/nuclei:latest -u https://example.com

After the first install, sync the community template library. Nuclei updates these automatically on most runs, but you can force it:

# Update the engine itself
nuclei -update

# Pull the latest community templates into $HOME/nuclei-templates/
nuclei -update-templates

Writing and running your first template

Here is a complete, minimal HTTP template that flags an exposed .env file containing what looks like database credentials. Save it as exposed-env.yaml:

id: exposed-dotenv-file

info:
  name: Exposed .env File With DB Credentials
  author: your-name
  severity: high
  description: Detects a publicly readable .env file leaking database settings.
  tags: exposure,config,misconfig

http:
  - method: GET
    path:
      - "{{BaseURL}}/.env"

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200

      - type: word
        part: body
        words:
          - "DB_PASSWORD"
          - "DB_HOST"
        condition: and

The matchers-condition: and at the request level means both matchers must pass: the server must return HTTP 200 and the body must contain both DB_PASSWORD and DB_HOST. That double condition is what keeps the check from firing on a generic 200 page.

Run it against a single target, then against a list:

# Run one custom template against one target
nuclei -u https://example.com -t exposed-env.yaml

# Run it across many hosts, write JSONL output, and cap the request rate
nuclei -l targets.txt -t exposed-env.yaml -jsonl -o results.jsonl -rate-limit 50

To run curated community templates instead of your own, select by tag or severity. For example, scan only for critical and high CVEs:

nuclei -u https://example.com -tags cve -severity critical,high

When to use Nuclei

Reach for Nuclei when you need repeatable, scriptable detection across many hosts. It is a natural fit for continuous attack-surface monitoring, where you re-run the same template set on a schedule and diff the results. It works well for bug-bounty and pentest reconnaissance, letting you sweep large target lists for known CVEs, exposed panels, and misconfigurations in minutes. Because templates are plain YAML and the binary needs no daemon, it fits easily into CI/CD as a security gate that fails a build when a high-severity template matches a staging environment.

It is less suited to deep, stateful application testing - complex multi-step authentication flows, business-logic abuse, or fuzzing - where an interactive proxy or a purpose-built fuzzer serves you better. Nuclei detects conditions you can describe; it does not reason about intent. Use it to cover known and describable issues at scale, pair it with manual review for high-impact findings, and write your own templates whenever your environment has a check the community library does not cover.