Nuclei

Nuclei

Use Nuclei as a declarative security-check engine: templates define requests or actions, operators prove a result, and metadata explains the finding. Produce low-noise, reproducible checks and conservative scan commands for targets the user owns or is explicitly authorized to test.

Start with version and scope

1. Distinguish local authoring/validation from a network scan. Authoring and -validate do not contact a target; scanning does.

2. Before a real scan, establish that the named targets and test class are authorized. Keep targets, redirect destinations, ports, credentials, payload effects, OAST callbacks, rates, and exclusions inside that scope.

3. If nuclei is installed, inspect the runtime before emitting version-sensitive syntax:

   nuclei -version
   nuclei -h
   nuclei -ldf
   

   Use nuclei -lha when designing headless steps. Runtime help and the current schema outrank static aliases in this skill.

4. If exact syntax may have changed, consult the official schema and current documentation linked in references/docs-index.md. The requested nuclei.mintlify.app corpus is a legacy snapshot and contains stale flags.

5. Never claim a template was validated or a target was vulnerable without the corresponding tool output. Treat a Nuclei match as evidence requiring confirmation, not a final vulnerability verdict.

Route the task

• Install, configure, select templates, authenticate, tune performance, export results, or integrate CI/CD: read references/cli-operations.md.
• Create or repair any template: read references/template-schema.md and references/operators-dsl-oob.md, then the relevant protocol reference.
• Build HTTP, raw HTTP, multi-request, authenticated, or request-condition checks: read references/http.md.
• Build payload, fuzzing/DAST, race, pipelining, unsafe/raw, or request-smuggling checks: read references/advanced-http.md.
• Build DNS, TCP, file, SSL, WebSocket, or WHOIS checks: read references/protocols.md.
• Build headless, JavaScript, code, Flow, or multi-protocol checks: read references/execution-engines.md.
• Build conditional workflows or use the hosted editor/API: read references/workflows-editor.md.
• Review quality, reduce false positives, test, sign, or prepare a contribution: read references/quality-testing.md.
• Find every page in the source corpus or resolve legacy/current drift: read references/docs-index.md.

Do not load every reference by default. Read the schema/operator references plus only the protocol and operational references needed for the request.

Author a template

1. Define the proof

Write down:

• the exact product, weakness, affected state, and target form;
• the least-invasive request or observation that distinguishes vulnerable from patched;
• positive evidence, negative controls, expected status/headers/body/protocol data, and any version boundary;
• required authentication, redirects, OAST, payload count, browser actions, code, files, or side effects.

Prefer direct vulnerability proof over version-only detection. Prefer a harmless unique marker, read-only endpoint, response delta, or authorized OAST callback over command execution or state changes.

2. Choose the least-powerful engine

Prefer in this order when each can express the check:

1. Standard protocol request (http, dns, tcp, ssl, websocket, whois, file).
2. Raw HTTP for exact bytes or multi-step request control.
3. Flow for conditional/repeated protocol orchestration.
4. Headless only when browser behavior or client-side execution is essential.
5. JavaScript only when a native protocol module or custom state machine is essential; custom JavaScript templates require a trusted signature on Nuclei v3.11+.
6. unsafe, race, DAST fuzzing, self-contained, global matchers, or OAST only when the detection requires them.
7. External code only as a last resort; inspect and sign it, and require explicit -code at runtime.

Use current keys: http, not deprecated requests; tcp, not deprecated network.

3. Build metadata first

Create a unique id without spaces and an info block with name, author, and severity. Add a precise description, impact, remediation, primary references, specific comma-separated tags, and applicable classification fields (cve-id, cwe-id, cvss-metrics, cvss-score, epss-*, cpe). Do not assert verified: true, CVSS, affected versions, or attribution without evidence.

4. Compose requests and state

• Use built-in variables with exact case (BaseURL, RootURL, Hostname, Host, Port, Path, File, Scheme, FQDN, and protocol-specific values).
• Use template constants for immutable scalar configuration and variables for evaluated values. Use {{randstr}} or numbered variants when one stable random marker must persist for a template run.
• Use named internal extractors to pass tokens or identifiers to later requests. Add request IDs when Flow or per-request DSL fields need them.
• Make payload attack semantics explicit: batteringram, pitchfork, or clusterbomb. Keep wordlists adjacent to the template unless broader local file access was explicitly approved.
• Scope redirects to the same authorized host by default. Do not leak secrets across redirects.
• Remember that current Nuclei reuses cookies by default; set disable-cookie: true only when isolation is required.

5. Prove the result with operators

• Combine independent evidence with matchers-condition: and: expected status, product-specific marker, vulnerability-specific proof, and a negative control where useful.
• Within one matcher, set condition: and|or deliberately. Use negative: true only when absence is meaningful.
• Select the correct response part; avoid searching all when body, header, raw, answer, or protocol data is more precise.
• Use DSL for response relationships, lengths, hashes, response-index comparisons, and version ranges. Keep expressions deterministic and readable.
• Use named internal extractors for state; use public extractors for useful result context. A regex group returns one capture group, while the full match remains group 0.
• For OAST, pair {{interactsh-url}} with explicit interactsh_protocol, interactsh_request, or interactsh_response matchers. Treat public Interactsh metadata as data sent to a third party.

6. Validate and test

Run the bundled validator from the skill directory:

python3 scripts/validate_template.py path/to/template.yaml

It invokes strict nuclei -validate, uses -w for workflow documents, checks loader warnings, enforces a timeout, and reports elevated capabilities without scanning. Unsigned JavaScript/code fails by default; use --allow-unsigned-authoring only for an intermediate structural pass, then review, sign, and rerun. Do not use -nss to make an invalid template pass.

Then test in layers:

1. Validate YAML/schema with the installed engine.
2. Inspect the rendered template with nuclei -t template.yaml -td.
3. Run against a controlled, known-vulnerable authorized lab with conservative -rl, -c, and -bs.
4. Run against a patched instance and at least one similar non-vulnerable product.
5. Inspect -dreq, -dresp, or -debug; redact secrets before sharing logs.
6. Measure request count, retries, payload expansion, redirects, and OAST delay. Confirm the matcher still proves the claimed issue.

When no positive lab is available, label the template structurally validated but behaviorally unverified.

Operate a scan

1. Verify the installed version and health: nuclei -version, nuclei -hc, and optionally nuclei -tv.
2. Normalize targets and exclusions. Prefer a file for nontrivial scope and use -eh for explicit exclusions. Use -lna when untrusted inputs/templates must not reach private networks.
3. Select narrowly by explicit template, ID, tag, type, severity, or profile. Preview broad selection with -tl.
4. Start with conservative limits. A safe initial shape for a small authorized test is -rl 5 -c 2 -bs 2; tune from measured behavior and program limits.
5. Keep special capabilities opt-in: -headless, -code, -file, -dast, -esc, -egm, and -lfa. Never broadly include dos or fuzz tags or bypass the maintained ignore list. An exact, reviewed custom DAST file may require both -dast and -it ./template.yaml because its safety tags are excluded by default.
6. Scope authentication with -sf domain rules. Never generate catch-all secret scope, print live secrets, or combine sensitive auth with raw debug output unless the user explicitly accepts the exposure.
7. Prefer machine-readable output with -jle; use -or, -ot, and -rd when raw traffic, templates, or secrets must not be persisted.
8. Report the command, version, selected templates, scope, rate settings, output path, limitations, and validation status.

Example shape—replace only with an authorized target and verified current flags:

nuclei -duc -u https://authorized.example \
  -t ./template.yaml -rl 5 -c 2 -bs 2 \
  -jle results.jsonl -or

-duc avoids update network traffic; it does not make the target scan passive.

Apply elevated-feature guardrails

• DAST/fuzzing: Require an explicit authorized scope, tight -cs/-cos, conservative aggression and rate, and an understood payload count. Do not treat legacy -fuzz as current; prefer runtime help, which currently uses -dast.
• Unsafe/smuggling/race/pipeline: These can desynchronize servers, duplicate transactions, or create high load. Use only in an isolated lab or with explicit authorization for that test class. Keep race counts and connections minimal.
• Headless: Browser actions can submit forms, download files, and execute page scripts. Review every action. Linux root disables the browser sandbox; avoid that deployment.
• JavaScript: Treat imported Go-backed modules as executable scanner-side capability. Review destinations, loops, exports, file/network access, and timeouts. Nuclei v3.11+ skips unsigned custom JavaScript templates; sign only after review and re-sign after edits.
• Code: Treat the template as executable software on the scanner host. Review source and referenced files, require a trusted signature, re-sign after intentional edits, and never strip another signer's digest automatically.
• File: -file reads local content; -lfa expands access. Limit roots and avoid logging discovered secrets.
• OAST: Prefer an approved self-hosted Interactsh service for sensitive environments. Account for polling/cooldown before declaring a negative result.
• Remote templates/API/editor: Treat downloaded, AI-generated, base64-encoded, or shared templates as untrusted input. Base64 is not encryption; unlisted share URLs behave like bearer secrets.

Use bundled starters

Starter files in assets/template-starters/ demonstrate current structure without embedding real exploit payloads. Copy the closest starter, replace every change-me marker, and validate it. Copy workflow.yaml with both adjacent workflow-*.yaml children. The JavaScript starter is intentionally unsigned: edit and review first, then sign it. Do not present a starter as a finished detection rule.

Deliver complete work

For a created or repaired template, return:

• the template file;
• the exact validation command and result;
• a conservative authorized-lab run command;
• expected positive and negative evidence;
• required flags/capabilities and estimated request expansion;
• assumptions, unverified claims, and security/privacy caveats.

For a scan plan or command, return the resolved scope, selector preview strategy, limits, secret handling, output/redaction strategy, and rollback/stop condition. Never execute a network scan merely because the user asked to write or validate a template.