Nuclei: A YAML-Driven Vulnerability Scanner for the Command Line

The problem Nuclei solves: turning vulnerability checks into reviewable files

Most scanners ship as a binary with a fixed set of checks. You run it, you get findings, and if a check is wrong or missing you wait for the vendor. Nuclei inverts that. Detection logic lives in YAML templates, and the engine is a runtime that executes them. The README describes the project as "a modern, high-performance vulnerability scanner that leverages simple YAML-based templates" and says templates are "contributed by thousands of security professionals to tackle trending vulnerabilities."

The audience is narrow and identifiable: pentesters, security engineers and bug bounty hunters who already have a list of hosts or URLs and want to run specific checks against them. The README names that audience directly in its description of the paid editions ("Ideal for: Pentesters, security teams, and enterprises"), which is a useful hint about who the open source CLI is built for even though the CLI itself is the free artifact.

The design bet is that a check should be a small, readable file that a reviewer can diff in a pull request. That is a real difference from a compiled plugin model. It also means the quality of your results depends on the quality of the templates you run, not only on the engine.

How the template engine and protocol layer fit together

Nuclei is written in Go, and the module path in go.mod is github.com/projectdiscovery/nuclei/v3, with go 1.26.0 as the required toolchain. The dependency list is the clearest available map of the architecture, because each entry corresponds to a capability the engine exposes to templates.

For HTTP work the engine pulls in retryablehttp-go and rawhttp, the latter being what allows templates to send malformed or non-standard requests that a normal HTTP client would refuse to construct. DNS handling comes from miekg/dns and retryabledns, with fastdialer underneath for connection setup. interactsh is the out-of-band interaction component, which is how a template can confirm a vulnerability that produces no visible response, such as a blind server-side request forgery. Browser-driven checks use go-rod. External system integrations are visible too: go-jira for Jira, and SDKs for Gitea and Azure Blob storage.

The README lists the supported protocols as "TCP, DNS, HTTP, SSL, WHOIS, JavaScript, Code and more." The Code protocol is the one worth pausing on: it means templates can execute code, not just send requests, which is a large amount of power to hand to a file format that users download from a shared repository. The repository also ships nuclei-jsonschema.json and SYNTAX-REFERENCE.md, so template authors have a schema and a reference to validate against rather than guessing at field names.

Execution is parallel, and the README claims "request clustering" as a performance measure. The claim that Nuclei produces "zero false positives" appears in the README's opening paragraph; treat that as marketing framing rather than a property of the engine, since a template that matches on a status code alone will produce false positives no matter how good the runtime is.

Installing Nuclei and running a first scan

The README does not inline installation commands. It points to a separate guide: "Install Nuclei on your machine. Get started by following the installation guide here," linking to the ProjectDiscovery documentation site. That is the authoritative source for package manager commands and prebuilt binaries, and it is the place to check rather than a third-party tutorial.

If you prefer to build from source, the repository contains a Makefile with a build target that writes the binary to ./bin/nuclei and compiles cmd/nuclei/main.go. The target enables profile-guided optimization through -pgo=auto and sets CGO_ENABLED=0.

make build

A container image is also defined. The Dockerfile builds with golang:1.27-alpine, runs make verify and make build, then copies the binary into an alpine:latest runtime image that installs bind-tools, chromium and ca-certificates. Chromium is present because browser-based templates need it, and bind-tools supplies DNS utilities. The entrypoint is the nuclei binary itself, so arguments pass straight through:

ENTRYPOINT ["nuclei"]

Once the binary runs, the README's documented starting points are a single target scan, scanning multiple targets, a network scan, and scanning with a custom template. The README gives these as named sections in its table of contents rather than as full command lines, so the exact flags belong to the documentation site. What is safe to say from the repository is that the binary is named nuclei and that templates are the unit of work, which is why the templates repository is linked from the README header as its own project.

A first real use is therefore: install the binary, pull the template set, point it at one host you own, and read the output before pointing it at anything else. The examples/ directory in the repository is organized into examples/simple/, examples/advanced/ and examples/with_speed_control/, which is a reasonable signal that speed control is a first-class concern rather than an afterthought.

The service warning and other limits you should take seriously

The README carries an explicit warning box, and it is unusual enough to quote: "This project is primarily built to be used as a standalone CLI tool. Running nuclei as a service may pose security risks. It's recommended to use with caution and additional security measures." That is the project telling you not to wrap the engine in an HTTP API and expose it to a network. A scanner that accepts template input and can execute code is an obvious remote code execution surface if you put it behind a web endpoint without heavy isolation.

The second warning is about version stability: "This project is in active development. Expect breaking changes with releases. Review the release changelog before updating." The release history supports the caution. Three releases landed in roughly six weeks: v3.10.0 on 2026-06-30, v3.11.0 on 2026-07-06, and v3.11.1 on 2026-08-08. The last push to the repository was on 2026-09-10. Frequent minor releases are normal for this project, and pinning a version is the sensible response.

A third limit is conceptual rather than technical. Nuclei is a template executor. It does not crawl your application, it does not maintain a login session across a multi-step workflow unless a template encodes that flow, and it does not reason about business logic. If your target is a single-page application behind authentication where the interesting flaws live in state transitions, a scanner built around request templates will miss most of them. Nuclei is also the wrong tool for continuous monitoring of a live production system if you have not scoped your target list: the engine is built to run fast and in parallel, and speed cuts both ways.

Nuclei compared with a scripted scanner such as Nikto or a fuzzer

The natural comparison is with a signature-based web scanner in the Nikto tradition. Nikto carries its checks inside the program and runs a broad, opinionated set of probes against a web server, reporting what it finds with limited configuration. Nuclei carries almost no checks in the binary; the engine is a runtime and the checks arrive as templates from a separate repository. The practical difference is who owns the check. With Nikto, the maintainers do. With Nuclei, you do, or the community does.

That has a concrete consequence for updating. A new CVE needs a new template, and the README frames this as the project's whole point: templates are contributed "to tackle trending vulnerabilities." You get faster coverage of a fresh CVE, at the cost of trusting an external template author. The JSON schema and syntax reference in the repository exist so you can read a template before running it, and you should.

The other comparison is with a general-purpose fuzzer such as ffuf or a Burp Suite extension. A fuzzer generates requests from a wordlist and you interpret the responses. Nuclei encodes the interpretation in the template: the matcher decides whether a response is a finding. That is more repeatable and easier to put in CI, and it is also more brittle, because a matcher written against one application's response body will not transfer to another. Fuzzers find unknowns; Nuclei confirms knowns.

Licence, maintenance and the cost of staying current

Nuclei is released under the MIT licence, and the repository carries LICENSE.md at its top level. MIT is permissive: you can use, modify and redistribute the code, including in commercial products, provided the copyright notice and licence text are preserved. That applies to the engine. It does not automatically apply to templates you download from elsewhere, and template licensing is a separate question the README does not address. If you plan to redistribute a template bundle, check that bundle's own terms rather than assuming the engine's licence covers it. This is a description of the licence text, not legal advice.

The maintenance picture is straightforward. The repository is not archived, and the last push was on 2026-09-10, which is recent. Releases arrive on a roughly monthly cadence, and the project states that breaking changes are expected. Budget for that: a pinned version with a scheduled review of the changelog before each bump is cheaper than upgrading on release day and debugging a changed template schema in production.

Upgrade cost also includes templates. The engine and the template set version independently, and a template that uses a newer DSL feature will fail on an older binary. The repository ships a template-validate target in the Makefile, which is the mechanism for checking templates against the current engine before you rely on them. There is also a helm/ directory at the top level, so a Kubernetes deployment path exists in the repository even though the README's own warning about running as a service still applies to how you configure it. The README does not document a rollback procedure for a bad template update, so plan for that yourself.

Editorial conclusion

Adopt Nuclei if you already have a target list and want repeatable, template-defined checks in a pipeline or on a laptop. Do not adopt it if you need authenticated application testing with session state, or if you intend to expose the engine as a long-running network service; the README states plainly that running nuclei as a service may pose security risks. Before trusting a scan, verify which template set you are running and read the release changelog for the version you pin, because the project states that breaking changes are expected between releases.

Frequently asked questions

Official sources

1. License: MIT
2. projectdiscovery/nuclei on GitHub
3. Project website
4. README
5. Releases