Nuclei Template Writer

Nuclei Template Writer

Turns a finding into a Nuclei template. The template can then be run against thousands of targets to find the same vulnerability at scale.

Protocol

Step 0 — Parse the input

Identify the input type — determines how precise the output can be:

Extract every detail available:

• HTTP method, full path, query parameters
• Request headers (note auth headers — document them, never hardcode values)
• Request body
• Response status code, response headers, response body (key sections)
• Any payload or test string mentioned
• Any error message, leaked string, or behavioral signal described

If input is ambiguous, ask ONE question: "What does the response look like when the vulnerability triggers?"

Step 1 — Classify the vulnerability

Match the finding against references/vuln-classes.md. Identify:

• Primary class — XSS, SQLi, SSRF, LFI, IDOR, etc.
• Severity — from the class table; adjust up if auth not required or down if interaction needed
• Tags — from the class table
• Detection method — response-based, OOB, time-based, or status-based

If the class is not in the table, follow this fallback in order:

1. Does the response contain a unique string when the vuln triggers? → word matcher
2. Does the response contain a pattern (version, key, email)? → regex matcher
3. Is there no response signal at all (blind vuln)? → go to Step 2's interactsh path
4. If none apply, stop and output: [nuclei-template-writer] Cannot determine detection method — provide the response body or describe what changes when the vulnerability triggers.

Step 2 — Choose detection strategy

Use references/matcher-guide.md to select the right matcher. Priority order:

1. Word matcher — if a specific string appears in the response (error message, reflected payload, leaked data). Most reliable, lowest false-positive risk.
2. Regex matcher — if the evidence is a pattern (version number, email, secret format, dynamic value).
3. Status matcher — only as a secondary matcher, never alone (too many false positives).
4. DSL matcher — for time-based blind vulns (response_time > 5) or header condition checks.
5. Interactsh matcher — for blind OOB vulns (SSRF, blind XXE, blind command injection). Requires {{interactsh-url}} as the payload.

Always combine matchers with matchers-condition: and when using status + word/regex to reduce false positives.

Step 2.5 — Determine auth strategy

Check if the original request contains any authentication. Use references/auth-strategies.md to select the right approach.

First — always generate an unauthenticated probe variant: Strip all auth headers/cookies and test the same endpoint. Include this as a separate template or first request block. Reason: the same vuln may be exploitable without auth on other targets even if auth was required on the original. If the unauthenticated probe hits, upgrade severity by one level.

Then — handle the authenticated case based on auth type:

See references/auth-strategies.md for the full template pattern for each auth type.

Step 3 — Generate the template

Follow the Nuclei YAML schema exactly. Build each block:

ID: {vuln-class}-{endpoint-slug} — kebab-case, descriptive, unique. Example: reflected-xss-api-user-export-format

Info block:

info:
  name: [human-readable description of what this detects]
  author: [leave blank or use "custom"]
  severity: [info/low/medium/high/critical]
  description: [one sentence — what triggers it and what the impact is]
  tags: [from vuln-classes.md, comma-separated]

HTTP block:

• Replace the hostname with {{BaseURL}}
• Replace OOB payloads with {{interactsh-url}}
• Replace dynamic/session values (CSRF tokens, timestamps) with notes
• Never hardcode auth tokens — always use variables (see auth strategy from Step 2.5)
• For login-flow templates: use raw: block with cookie-reuse: true and an extractor on the first request
• For multi-step (IDOR): use raw: block with cookie-reuse: true

Matchers:

• Add matchers-condition: and when using multiple matchers
• Word matchers: use the exact string from the response, not a generic one
• Regex matchers: keep patterns tight — prefer anchors and specific character classes
• Always add a status matcher as secondary when the vuln returns a specific code

Variables block — always declare variables for anything target-specific:

variables:
  token: "REPLACE_ME"       # for Bearer/API key auth
  username: "REPLACE_ME"    # for login-flow templates
  password: "REPLACE_ME"    # for login-flow templates

Output order when auth is required: generate two templates:

1. Unauthenticated probe (stripped of auth) — label it [unauthenticated]
2. Authenticated template with chosen auth strategy — label it [authenticated]

Apply the skeleton from references/vuln-classes.md for the matched class, then apply the auth pattern from references/auth-strategies.md.

Step 4 — Output

Produce in this exact order:

1. The complete template — fenced as ```yaml

2. Customize before running — bullet list of exactly what to change before the template works:

• Which headers need real values
• Which payloads need adjustment for the target
• Whether interactsh needs to be set up

3. Test command — show the right command for the auth strategy used:

# No auth — run directly
nuclei -t template-name.yaml -l targets.txt

# Bearer / API key — pass token at runtime
nuclei -t template-name.yaml -l targets.txt -var "token=eyJ..."

# Login-flow — pass credentials at runtime
nuclei -t template-name.yaml -l targets.txt -var "username=test@test.com" -var "password=Test1234"

# OOB template
nuclei -t template-name.yaml -l targets.txt -iserver https://interactsh.com

4. Validate before bulk-running: test on one confirmed-vulnerable target (expect a hit) and one clean target (expect no hit). If both trigger, the matcher is too broad — tighten the word or regex before scaling.

Step 5 — Flag limitations

State clearly if any of the following apply:

• OOB required: "This template uses interactsh — set up a listener before running. Hits will appear in your interactsh dashboard, not in nuclei output directly."
• Auth required (Bearer/API key): "Pass your token at runtime with -var token=YOUR_TOKEN. You need a valid account on each target. The unauthenticated probe is included — check if it hits first."
• Auth required (login flow): "Pass test credentials with -var username=X -var password=Y. The template logs in automatically and extracts the session. You need a registered account on each target."
• Auth required (OAuth/SSO): "Cannot be templated reliably — OAuth flows require browser interaction. Test manually on each target."
• Multi-account required (IDOR): "This template needs two valid accounts on the target. Replace VICTIM_OBJECT_ID and ATTACKER_SESSION with real values."
• Low confidence matchers (Type A/B): "Matchers are inferred from the description — validate against the real response before bulk-running to avoid false positives."

Reference Files

• references/vuln-classes.md — Vulnerability class table with severity, tags, and template skeletons
• references/matcher-guide.md — Matcher type selection guide with examples
• references/auth-strategies.md — Auth patterns and full template examples per auth type