nuclei-dast

nuclei-dast

Overview

Per docs.projectdiscovery.io/tools/nuclei/overview:

"Nuclei is a fast and customisable vulnerability scanner powered by simple YAML-based templates."

Each template is a YAML file that defines the request to send plus matchers that decide whether the response constitutes a finding. The community template library ships 6,500+ templates covering CVEs, misconfigurations, exposed panels, and default credentials. Custom templates add app-specific checks without modifying the tool itself.

Nuclei complements ZAP: ZAP's spider + passive analysis gives broad HTTP coverage; Nuclei's template corpus gives deep, targeted CVE and misconfiguration coverage from a structured community library. Both output feeds the dast-finding-triager.

When to use

• The repo needs CVE-specific or misconfiguration checks beyond ZAP passive scan.
• A CI pipeline should gate on critical/high template matches without active spider coverage.
• The team maintains custom YAML templates for proprietary endpoints.
• Nuclei output must be unified with ZAP findings in dast-finding-triager.

Step 1 - Install

Per docs.projectdiscovery.io/tools/nuclei/install:

Go (recommended for CI):

go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

Requires the latest Go toolchain version.

Homebrew (macOS/Linux):

brew install nuclei

Docker:

docker pull projectdiscovery/nuclei:latest

Precompiled binary: download from github.com/projectdiscovery/nuclei/releases and place on PATH.

After install, update the default template library:

nuclei -update-templates

Step 2 - First scan

Per docs.projectdiscovery.io/tools/nuclei/running:

nuclei -u https://staging.example.com -j -o nuclei-report.jsonl

-j writes JSONL output; -o names the file. Each line is one finding, ready for dast-finding-triager. The default template set is applied; DOS-capable templates are excluded from the default run (see Step 6).

Step 3 - Common flags

Per nuclei-running:

Flag	Default	Use
-u <url>	(required)	Single target URL or host
-l <file>	-	File of targets, one per line
-t <path>	community templates	Template file or directory
-tags <tag,...>	-	Run only templates with matching tags
-severity <level,...>	-	Filter by info, low, medium, high, critical
-etags <tag,...>	-	Exclude templates by tag
-exclude-severity <level,...>	-	Skip severity levels
-rl <int>	150	Max requests per second
-c <int>	25	Parallel templates to execute
-bs <int>	25	Hosts processed per template
-timeout <int>	10	Request timeout in seconds
-retries <int>	1	Retries on failure
-j / -jsonl	off	JSONL output (feeds triager)
-o <file>	stdout	Output file path
-se <file>	-	SARIF export (GitHub Code Scanning)
-stats	off	Show live scan statistics
-validate	off	Syntax-check templates without running
-debug	off	Print all requests and responses

Per nuclei-running, -rl takes precedence over -c and -bs: the request rate cannot exceed the value set by -rl regardless of concurrency settings.

Step 4 - Severity filtering and CI gating

Run only high and critical templates for a fast CI gate:

nuclei -u https://staging.example.com \
  -severity high,critical \
  -rl 50 \
  -j -o nuclei-critical.jsonl

Then count findings and gate:

count=$(wc -l < nuclei-critical.jsonl)
if [ "$count" -gt 0 ]; then
  echo "FAIL: $count critical/high findings" >&2
  exit 1
fi

For a softer gate (fail on critical only, warn on high):

nuclei -u https://staging.example.com -severity critical -j -o nuclei-crit.jsonl
nuclei -u https://staging.example.com -severity high    -j -o nuclei-high.jsonl

Run both, fail CI on any line in nuclei-crit.jsonl, log nuclei-high.jsonl as advisory.

Step 5 - Template selection

Per docs.projectdiscovery.io/templates/introduction and docs.projectdiscovery.io/templates/structure:

Community templates are organized by tag. Common tags include cve, rce, sqli, xss, misconfig, exposure, default-login.

Run all CVE templates:

nuclei -u https://staging.example.com -tags cve -j -o nuclei-cves.jsonl

Run a specific template file:

nuclei -u https://staging.example.com -t nuclei-templates/cves/2024/CVE-2024-1234.yaml

Run all templates in a local directory:

nuclei -u https://staging.example.com -t ./custom-templates/ -j -o nuclei-custom.jsonl

List templates that would run without executing:

nuclei -tl -tags misconfig -severity high,critical

Step 6 - Custom YAML templates

Per template-struct, every template requires: a unique id, an info block, and at least one protocol request with matchers.

Minimal HTTP template:

id: custom-debug-endpoint

info:
  name: Debug Endpoint Exposed
  author: your-team
  severity: high
  description: "Detects an exposed /debug endpoint returning sensitive runtime info."
  tags: exposure,custom

http:
  - method: GET
    path:
      - "{{BaseURL}}/debug"
    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
      - type: word
        words:
          - "goroutine"
          - "heap"
        condition: or

Matcher types per template-intro:

Type	Matches against
word	Response body or headers contain literal string(s)
regex	Response body matches a regular expression
status	HTTP response status code
dsl	Boolean expression using Nuclei DSL functions

Validate before running:

nuclei -t ./custom-templates/custom-debug-endpoint.yaml -validate

Step 7 - JSONL output for dast-finding-triager

Each JSONL line represents one match. Key fields:

{
  "template-id": "cve-2024-1234",
  "info": { "name": "...", "severity": "high", "tags": ["cve"] },
  "host": "https://staging.example.com",
  "matched-at": "https://staging.example.com/vulnerable-path",
  "timestamp": "2026-06-04T12:00:00Z"
}

Pass to dast-finding-triager:

nuclei -u https://staging.example.com -j -o nuclei-report.jsonl
# feed nuclei-report.jsonl to dast-finding-triager alongside zap-report.json

For SARIF output (GitHub Code Scanning):

nuclei -u https://staging.example.com -se nuclei.sarif

Step 8 - Rate limiting and responsible use

Per nuclei-running, the default rate is 150 req/s. Nuclei generates several thousand requests when the full template set runs against a single target. Per the Nuclei FAQ:

"After detecting a security issue we always recommend that you validate it a second time before reporting it." Use -debug to confirm the matcher fired against the expected response content.

DOS-capable templates are tagged and excluded from default scans. To run them explicitly (staging only, never production):

nuclei -u https://staging.example.com -tags dos -rl 5

Default-safe limits for shared infrastructure:

nuclei -u https://staging.example.com -rl 30 -c 10 -bs 10

Only scan targets you are authorized to test. Nuclei is an active probe tool; running it against a target without authorization may violate computer abuse laws.

Step 9 - CI integration

GitHub Actions:

jobs:
  nuclei-dast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install Nuclei
        run: go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

      - name: Update templates
        run: nuclei -update-templates

      - name: Run Nuclei scan
        run: |
          nuclei \
            -u ${{ vars.STAGING_URL }} \
            -severity high,critical \
            -rl 50 \
            -j -o nuclei-report.jsonl

      - name: Gate on findings
        run: |
          count=$(wc -l < nuclei-report.jsonl 2>/dev/null || echo 0)
          echo "Nuclei findings: $count"
          [ "$count" -eq 0 ]

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: nuclei-report
          path: nuclei-report.jsonl

Use -se nuclei.sarif and the github/codeql-action/upload-sarif action to surface findings inline in pull request diffs.

Anti-patterns

Anti-pattern	Why it fails	Fix
Run all templates against production	Active probes may trigger WAF blocks, corrupt data, or run DOS-tagged templates	Staging only; use -etags dos on shared envs
Skip -j / -jsonl output	Findings are stdout-only; can't feed dast-finding-triager	Always pass -j -o <file> (Step 7)
Skip -rl in CI on shared infra	Default 150 req/s spikes load on shared staging	Set -rl 30 or lower (Step 8)
Run -validate only, skip a real scan	Syntax passes but matchers may produce no output	Always run a real scan against a known-vulnerable target to confirm match
Suppress findings without a tracked justification	Invisible risk debt	Use an IGNORE list with date + ticket, same pattern as ZAP config TSV (see zap-baseline Step 6)
Treat info severity as noise	info templates surface exposed panels, paths, and tech stack - useful for reconnaissance hardening	Route info findings to dast-finding-triager for triage, not direct suppression

Limitations

• Nuclei is active: every template sends at least one HTTP request. It is not safe to run the full template set against production.
• Template coverage is only as current as the last nuclei -update-templates; pin template versions in CI to avoid scan variance between runs.
• Matchers are per-template; a misconfigured custom template silently returns no findings. Always -validate and smoke-test against a known-vulnerable endpoint before trusting zero-finding output.
• Nuclei does not spider the target; it probes specific paths defined in templates. Use alongside ZAP for crawl-based coverage.
• -rl controls outbound rate but not the total request count; large template sets against a slow target may run for tens of minutes.

References

• nuclei-overview - official Nuclei overview
• nuclei-install - installation methods
• nuclei-running - CLI flags reference (rate limiting, output, filters)
• template-intro - template introduction and matcher types
• template-struct - YAML template structure and info block fields
• nuclei-faq - validation and responsible use guidance
• github.com/projectdiscovery/nuclei-templates - community template library
• zap-baseline - companion passive DAST scanner
• dast-finding-triager - unifier agent for Nuclei + ZAP output
• dast-baseline-runner - layered DAST workflow (baseline + full + optional Nuclei)