Nuclei: Beyond the Basic Templates

Nuclei: Beyond the Basic Templates

Speakers: Ben Sadeghipour (Bug Bounty Hunter, Hacking Hub)

Conference: Bug Bounty Village

YouTube: https://www.youtube.com/watch?v=ckLlOaB5JOg

Overview

In his insightful Bug Bounty Village talk, "Nuclei: Beyond the Basic Templates," renowned bug bounty hunter Ben Sadeghipour, famously known as Nahamsk, delivers a compelling critique and practical solution to the common, often ineffective, use of the popular open-source vulnerability scanner, Nuclei. Sadeghipour argues that while Nuclei is an immensely powerful tool, its community-curated templates are frequently overused by a vast number of researchers, leading to a saturation of findings for easily detectable issues and diminishing returns for individual hackers. The core of his presentation revolves around empowering security researchers and bug bounty hunters to transcend generic scanning by crafting highly customized, context-aware templates and sophisticated workflows.

Sadeghipour's talk aims to fundamentally shift the audience's perspective from simply running nuclei -tu (templates update) and generic scans to a more strategic, targeted approach. He meticulously demonstrates how leveraging Nuclei's advanced features—such as custom matchers, intelligent fuzzing techniques across various request parts, and powerful workflow chaining—can significantly increase the likelihood of discovering unique and high-impact vulnerabilities. This methodology is particularly pertinent for bug bounty hunters seeking to differentiate their findings in an increasingly competitive landscape, advocating for a move away from the "fire and forget" mentality that often results in "zero findings."

This presentation is invaluable for anyone aspiring to maximize their efficiency and effectiveness in vulnerability discovery, whether for competitive bug bounty hunting, targeted penetration testing, or internal security assessments. By providing a deep dive into Nuclei's capabilities beyond its basic usage, Sadeghipour equips attendees with the knowledge to transform Nuclei from a generic scanner into a highly specialized, automated reconnaissance and exploitation engine tailored to specific targets, technology stacks, and vulnerability types.

Background

▶ Watch: Speaker intro, free course offer, and talk agenda (0:00)

The pervasive issue in current Nuclei usage, as sharply observed by Ben Sadeghipour, is a widespread over-reliance on community-curated templates. While these templates are undoubtedly valuable for quickly identifying well-known vulnerabilities and establishing a baseline for security scanning, their ubiquitous adoption by thousands of users means that any "low-hanging fruit" they might expose is rapidly discovered and reported. Sadeghipour articulates this with a poignant rhetorical question: "every single one of you probably use the community curated templates... nobody is finding vulnerabilities using these templates, right?" This creates a counterintuitive situation where a robust tool like Nuclei becomes less effective for individual researchers precisely because everyone is employing it in the same manner, on the same targets, leading to a glut of findings for the most easily detectable issues.

This problem fundamentally stems from a superficial engagement with Nuclei's more advanced functionalities. Many users treat Nuclei as an opaque black box, simply initiating scans without a deeper understanding of how to customize, optimize, or even debug its core logic. Sadeghipour openly admits to being "guilty of it," confessing to forgetting about past scans or neglecting to review results due to a consistent lack of meaningful findings. This "fire off and forget" approach not only squanders computational resources but also fosters discouragement, perpetuating a cycle of low returns and missed opportunities.

The root cause of this inefficiency is the inherent lack of context in generic templates. They are not designed to account for specific application behaviors, unique custom paths, or the nuanced characteristics of particular technology stacks (e.g., a bespoke Content Management System, a niche framework, or specific software versions). To surmount these limitations, Sadeghipour advocates for a fundamental paradigm shift: instead of indiscriminately running "10,000 templates at all times," users should prioritize creating or adapting templates that are highly specific to their target's unique attributes and their own hacking methodology. This necessitates a thorough understanding of how to craft custom requests, define precise matchers, implement intelligent fuzzing techniques, and orchestrate complex workflows that intelligently chain multiple actions based on initial findings. This bespoke approach empowers hackers to uncover vulnerabilities that generic scans consistently miss, thereby transforming Nuclei into a truly "overpowered" (OP) tool for highly targeted and effective vulnerability discovery.

Key Findings

▶ Watch: Unlocking Nuclei's power with workflows and fuzzing (2:40)

Ben Sadeghipour's talk unveils several critical findings and innovative methodologies for harnessing Nuclei's full potential, advocating a significant departure "beyond the basic templates" to enable more effective and targeted vulnerability discovery.

Firstly, a paramount emphasis is placed on the vital role of custom template creation. Sadeghipour convincingly demonstrates that generic, community-provided templates frequently overlook specific attack surfaces or unique application behaviors. By meticulously crafting bespoke templates, security researchers can define precise HTTP requests, specify multiple custom paths (e.g., /stats, /dashboard, /internal, /admin), and integrate unique application fingerprints (such as copyright notices, distinctive dashboard titles, or "internal use only" banners) for highly accurate detection of target-specific assets or configurations. This includes leveraging various HTTP methods (GET, POST, PUT, DELETE) and even directly embedding raw requests captured from web proxies like Burp Suite or Kaido.

Secondly, the presentation illuminates the often-underestimated power of fuzzing with Nuclei. Unlike traditional, standalone fuzzing tools, Nuclei's integrated fuzzing capabilities empower researchers to systematically alter values within specific parts of an HTTP request—including query parameters, URL paths, HTTP headers, cookies, or the request body—to identify behavioral changes, error conditions, or potential injection points. This enables automated brute-forcing for vulnerabilities such as open redirects, Cross-Site Scripting (XSS), SQL injection, or even default credentials, thereby significantly expanding Nuclei's utility beyond mere static vulnerability signature scanning. The ability to import extensive payload lists from external files (e.g., params.txt, payloads.txt) further amplifies the scalability and effectiveness of this capability.

Thirdly, Sadeghipour introduces Nuclei workflows as the ultimate mechanism for achieving context-aware and chained attack automation. Workflows operate on an "if-then" logical framework, where the detection of a specific technology (e.g., Tomcat, GitLab, Jira, EngineX) or a particular finding (e.g., the discovery of a Swagger or OpenAPI definition file) automatically triggers a subsequent, highly targeted set of templates or fuzzing operations. This intelligent chaining eliminates the inefficiency of running irrelevant scans and instead focuses Nuclei's power precisely on the most relevant attack vectors. A compelling example provided is a workflow that, upon identifying a Tomcat instance, automatically attempts to brute-force its default credentials—a common vulnerability often overlooked by generic CVE-based templates.

Finally, the talk reveals the significantly underutilized capability of API hacking with Nuclei using Swagger and OpenAPI specifications. Sadeghipour explains how Nuclei can directly ingest Swagger or OpenAPI JSON files, parse their defined endpoints and parameters, and then automatically generate and send HTTP requests to test these APIs for vulnerabilities. This transforms Nuclei into a powerful Dynamic Application Security Testing (DAST) tool specifically tailored for API surfaces, a critical finding given the ubiquitous prevalence of APIs in modern application architectures and the common oversight of this feature among Nuclei users. The added ability to extract and export these generated API requests for further manual analysis or integration with other security tools further enhances its overall value.

Technical Deep Dive

▶ Watch: Understanding the basic Nuclei template structure (3:30)

The extended capabilities of Nuclei, as detailed by Ben Sadeghipour, fundamentally stem from the flexibility of its template structure and the sophisticated nature of its matcher logic. A basic Nuclei template is meticulously composed of several essential sections: info, request, and matchers.

The info section encapsulates crucial metadata, vital for template organization and targeted execution. This includes a unique id, a descriptive name, the author, and, most critically, the severity (e.g., info, low, medium, high, critical) and tags. Tags are presented as the "best friends" for organizing templates, enabling users to categorize them by vulnerability type (e.g., xss, sqli), specific technology stack (e.g., tomcat, nginx, jira), methodology (e.g., recon, exposure), or even particular bug bounty programs. This granular tagging system facilitates highly selective template execution, ensuring that only contextually relevant checks are performed, thereby conserving resources and reducing noise.

The request section is where the HTTP interaction is precisely defined. Nuclei supports a comprehensive array of HTTP methods (GET, POST, PUT, DELETE) and allows for the inclusion of custom headers (e.g., Content-Type: application/json, specific User-Agent strings required by bug bounty programs) and request bodies. A particularly potent feature is the ability to utilize raw requests, permitting users to directly paste complete HTTP requests captured from proxy tools like Burp Suite or Kaido. This ensures an exact replication of complex or stateful interactions. Multiple paths can be defined within a single request, enabling Nuclei to efficiently test several related endpoints. For dynamic testing, payloads can be seamlessly incorporated, either as inline lists within the template or by referencing external files (e.g., params.txt, payloads.txt). These payloads are then dynamically inserted into the request, often in conjunction with Nuclei's fuzzing capabilities.

Matchers represent the core mechanism for identifying successful findings within HTTP responses. Nuclei offers an extensive array of matcher types:

• Status: Matches specific HTTP status codes (e.g., 200, 301, 302, 400, 401).
• Words: Matches specific strings or lists of strings within the response body or headers.
• Regex (reax): Matches intricate patterns using regular expressions, offering highly flexible and powerful content matching. This is particularly useful for fingerprinting specific software versions or extracting dynamic data.
• Size: Matches the byte size of the response, which can be invaluable for detecting anomalies (e.g., an error page having a distinct, predictable size).
• Binary / Hex: Matches specific binary or hexadecimal byte sequences, useful for identifying non-textual patterns or embedded data.
• DSL (Domain Specific Language): Provides a powerful mechanism for crafting complex, single-line conditional logic. For instance, len(body)>1000 && status_code == 200 could match responses where the body length exceeds a certain threshold and the status code is 200, potentially indicating a non-standard or vulnerable behavior.

Crucially, individual matchers can be combined using matcher conditions (and or or), and multiple matchers can be grouped with matcher-group conditions (and or or). A condition: and at the matcher level dictates that all specified words or regex patterns must be present for a match. Conversely, a matcher-condition: or at the group level means that any one of the defined matchers within that group must be true. Understanding this distinction is paramount to avoid generating false positives or negatives, a point underscored by Sadeghipour's anecdote of debugging a template for 35 minutes due to an or instead of an and. Negative matchers (negative: true) are also extremely powerful, allowing Nuclei to alert when the absence of a certain condition (e.g., a 400 error for a missing parameter) indicates a finding.

Fuzzing significantly expands Nuclei's dynamic testing capabilities. Users can precisely specify which part of the HTTP request to fuzz:

• Query: Fuzzes URL parameters (e.g., id=10).
• Path: Fuzzes segments of the URL path (e.g., /admin, /internal).
• Header: Fuzzes specific HTTP header values (e.g., User-Agent, Host). It's important to note that Cookie is treated as a distinct part.
• Cookie: Fuzzes specific cookie values.
• Body: Fuzzes values within the request body (e.g., username, password in a POST request).

Nuclei supports different fuzzing modes to control how payloads are applied:

• Single: Fuzzes each parameter individually, which is useful for avoiding confusion when multiple parameters are present in a request.
• Cluster Bomb: (primarily used in workflows for brute-forcing) This mode combines every payload from one list with every payload from another list, making it essential for comprehensive username/password brute-forcing scenarios.

When performing fuzzing, payloads are explicitly defined and referenced. For instance, an open redirect template might define a payload named redirect with a value like https://nomsec.com. The fuzz section then dictates how these payloads are applied, such as prepending https:// to the redirect payload value within a query parameter.

Finally, workflows provide the overarching automation and orchestration framework. They operate on an "if-then" logical basis, enabling the conditional execution of templates or other workflows. A workflow can detect a specific technology or match the output of a prior template, and then run a series of highly targeted templates (identified by tags or specific template-paths). This allows for intelligent chaining, such as: "If a Tomcat instance is detected, then run templates tagged tomcat-default-creds." Workflows drastically improve efficiency by ensuring that resource-intensive scans (like brute-forcing) are only initiated when contextually appropriate. The open-api-json input mode is a powerful feature that allows Nuclei to parse Swagger/OpenAPI specifications, automatically generating and executing requests for all defined API endpoints and parameters. This effectively transforms Nuclei into a DAST scanner specifically for APIs. This capability, combined with the ability to export all generated requests, offers immense value for comprehensive API security testing.

Demo / Proof of Concept

▶ Watch: Targeted scanning by invoking templates based on tags/severity (5:15)

Ben Sadeghipour effectively illustrates Nuclei's advanced capabilities through a series of practical demonstrations and proof-of-concept examples, translating theoretical concepts into concrete applications.

The first example showcases fingerprinting an exposed internal dashboard. Sadeghipour presents a visual of a "Service Status Dashboard" featuring elements like "Internal Use Only" and "Copyright" information. He then constructs a custom Nuclei template designed to detect this specific dashboard. The template incorporates multiple paths (e.g., /stats, /dashboard, /internal, /admin) and employs matchers to look for a status: 200 combined with specific words in the response body, such as "service status," "dashboard," and "internal use only." It also includes a regex matcher to identify the EngineX version, demonstrating the versatility of combining different matcher types. This example underscores the power of creating highly specific fingerprints for unique internal assets that generic, broad-scope templates would likely miss.

Next, Sadeghipour demonstrates fuzzing for open redirects. He details a template that defines a payload named redirect and assigns https://nomsec.com as its value. The template then specifies a fuzz section targeting the query part, with mode: single, and instructs Nuclei to prepend https:// to the redirect payload. The matchers are configured to look for status: 301, 302, 307 (common redirect status codes) and a regex pattern in the location header that confirms the redirection to nomsec.com. This setup systematically brute-forces various URL parameters for open redirect vulnerabilities. The speaker highlights the importance of using the -v (verbose) flag during initial template testing to observe all sent requests and responses, ensuring the template functions as intended. He further suggests replacing the single payload with a params.txt file containing thousands of potential redirect payloads, illustrating how to scale fuzzing operations. The same principle is extended to XSS fuzzing, where XSS payloads are fed into parameters, and matchers are configured to look for the reflected payloads (e.g., <test1234>) in the response body.

A more sophisticated fuzzing scenario involves parameter discovery and vulnerability scanning (paramining). Sadeghipour shows how Nuclei can be used to identify hidden or undocumented parameters. A template is configured to fuzz for parameters listed in an external parameters.txt file. The matchers here utilize a negative: true condition on status: 400, meaning the template will alert if the response is not a 400 (which typically indicates a missing parameter). If a parameter is found and the status changes (e.g., to 200 or a different error), it signals a potentially valid parameter. Taking this a step further, he combines parameter discovery with vulnerability scanning. By defining both params and payloads placeholders in the base URL and employing an attack: clusterbomb mode, Nuclei can simultaneously iterate through a list of parameters and a list of vulnerability payloads (e.g., etc/passwd for Local File Inclusion, various XSS payloads). The matchers then look for specific evidence of these vulnerabilities (e.g., root:x:0:0 for LFI) within the response.

The talk then transitions into API hacking with Swagger/OpenAPI. Sadeghipour demonstrates how to directly feed a swagger.json or openapi.json file to Nuclei using nuclei -im openapi.json -dast. He highlights a common pitfall: API documentation often lacks a full server URL, which typically needs to be hardcoded into the JSON file for Nuclei to correctly send requests. Once properly configured, Nuclei automatically generates and tests requests for all defined API endpoints, effectively performing dynamic API security testing. He also illustrates how to extract all generated requests from a Swagger file, enabling further analysis or integration with other security tools.

The pinnacle of the demonstrations is the creation of a context-aware workflow for default credentials. Sadeghipour identifies a critical gap: while Nuclei has templates to detect Tomcat instances, it doesn't automatically brute-force default credentials. He presents a workflow that first identifies tag: tomcat and then, if true, triggers a custom template. This custom template performs a raw HTTP GET request to a typical Tomcat manager path (/manager/html), including an Authorization: Basic header with base64(username:password). It utilizes an attack: clusterbomb mode with separate usernames.txt and passwords.txt files. The matchers are configured to look for a status: 200 (indicating successful authentication) and the words: Tomcat Application Manager in the response. This powerful workflow automates the often-manual process of checking for default credentials once a specific technology is identified, significantly improving efficiency in bug bounty hunting.

Throughout these demonstrations, Sadeghipour consistently emphasizes the importance of validation (-validate) for template correctness, debug mode (-debug) for observing raw request/response pairs, and creating local labs (e.g., simple Python HTTP servers) for safe and efficient template development and testing.

Defensive Implications

▶ Watch: Creating advanced custom POST requests with body and matchers (6:00)

The detailed insights shared by Ben Sadeghipour regarding advanced Nuclei usage carry profound defensive implications for organizations and security teams. Understanding how skilled attackers, particularly bug bounty hunters, leverage tools like Nuclei beyond basic CVE scanning is paramount for building more robust and resilient defenses.

Firstly, the strong emphasis on custom template creation and fingerprinting means defenders must recognize that merely patching known CVEs is an insufficient security strategy. Attackers are actively creating templates to identify unique, custom-developed applications, internal dashboards, and specific configurations that may not have an associated CVE but still represent a significant exposure. Defenders should proactively identify unique strings, headers, or response patterns within their own internal and external applications that could serve as distinct fingerprints for sensitive assets. This intelligence can then be utilized either to remove those fingerprints from public-facing assets or, ironically, to develop internal Nuclei templates to continuously scan for their own exposed assets.

Secondly, the comprehensive explanation of fuzzing techniques across parameters, paths, headers, and cookies highlights common attack vectors that extend beyond simple injection flaws. Defenders must implement robust and pervasive input validation and sanitization across all components of an HTTP request—not just the body or query parameters. The demonstrations of fuzzing for open redirects, XSS, and parameter discovery underscore the critical need for comprehensive security testing that covers a wide spectrum of behavioral anomalies, not solely known vulnerability signatures. Organizations should also consider deploying Nuclei internally with custom fuzzing templates to proactively identify potential open redirects, reflected XSS, or discover undocumented parameters in their APIs and web applications before malicious actors do.

Thirdly, the concept of workflows for context-aware scanning provides an invaluable blueprint for effective internal security automation. Instead of executing a monolithic scan of all known vulnerabilities, security teams can develop intelligent workflows that first identify specific technologies or frameworks (e.g., Tomcat, Jira, Nginx) and then automatically trigger highly targeted checks relevant only to those identified technologies. This includes checks for default credentials, common misconfigurations, or known vulnerabilities specific to their version. This intelligent chaining reduces scan noise, significantly improves scan efficiency, and helps prioritize remediation efforts by focusing on high-impact, contextually relevant findings.

Finally, the focused discussion on API hacking with Swagger/OpenAPI serves as a direct call to action for organizations heavily reliant on APIs. The demonstrated ability for Nuclei to ingest API specifications and automatically test endpoints means that API security can no longer be an afterthought. Defenders must ensure their API specifications are accurate, complete, and up-to-date. Crucially, they should leverage tools like Nuclei (or similar DAST solutions) to regularly test their APIs against these specifications for common vulnerabilities, misconfigurations, and deviations from expected behavior. This includes verifying access controls, implementing rigorous input validation on all parameters (as demonstrated by paramining), and ensuring sensitive data is not inadvertently exposed through API endpoints. Furthermore, understanding that attackers can easily extract all API endpoints and parameters from publicly accessible Swagger files should prompt organizations to secure access to these files, especially in production environments.

In essence, Sadeghipour's talk empowers defenders by revealing the sophisticated methods employed by advanced attackers. By adopting a similar mindset—creating custom checks, implementing intelligent fuzzing, building context-driven workflows, and meticulously testing APIs—organizations can significantly strengthen their proactive security posture and substantially reduce their attack surface against both generic and highly targeted threats.

Key Takeaways

• Customization is Key: Move beyond generic, community-curated Nuclei templates; custom, context-aware templates are paramount for discovering unique vulnerabilities and achieving higher success rates.
• Master Nuclei's Matchers: Leverage the diverse array of matcher types (status, words, regex, DSL) and combine them intelligently with and/or conditions to precisely identify findings and drastically reduce false positives.
• Embrace Nuclei Fuzzing: Utilize Nuclei's integrated fuzzing capabilities to systematically test various parts of HTTP requests (query, path, headers, cookies, body) with custom payloads for vulnerabilities like open redirects, XSS, and hidden parameter discovery.
• Implement Workflows for Contextual Scanning: Build "if-then" workflows to chain scans, automatically triggering highly targeted templates (e.g., default credential brute-forcing) only when specific technologies or conditions are accurately detected.
• Leverage Nuclei for API Security: Utilize Nuclei's powerful ability to ingest Swagger/OpenAPI specifications for automated dynamic testing of API endpoints, a critical yet often overlooked feature for modern applications.
• Practice and Validate Diligently: Always validate new templates with -validate, use -debug mode for in-depth troubleshooting, and create local labs for safe and efficient template development and testing before deploying against live targets.

About the Speaker(s)

Ben Sadeghipour, widely recognized online as Nahamsk, is an accomplished and highly successful bug bounty hunter, having amassed nearly $2 million in bounties. A significant portion of these earnings, approximately 70%, has been achieved since he transitioned to full-time bug bounty hunting in 2022 or 2023. Prior to his full-time hacking career, Sadeghipour served as the Head of Hacker Education at HackerOne, a leading bug bounty platform. He is also the co-founder of Hacking Hub, a company he established with Adam, dedicated to educating and mentoring the next generation of security researchers. Furthermore, Ben Sadeghipour is a prolific content creator, sharing his extensive expertise in bug bounty hunting and hacking across various social media platforms, including YouTube, X (formerly Twitter), Instagram, and Twitch.