Nuclei自包含模板：告别依赖地狱，实现安全检测标准化

1. 项目概述：告别依赖地狱的终极武器

如果你是一名安全研究员、渗透测试工程师，或者任何需要频繁运行自动化安全扫描工具的人，那么“依赖地狱”这个词对你来说一定不陌生。它描述的是那种令人抓狂的状态：为了运行一个工具，你需要先安装A库，而A库又依赖B库的特定版本，B库又和系统里已有的C库冲突……最终，你花费在解决环境问题上的时间，可能比实际使用工具的时间还要长。Nuclei，作为当前最炙手可热的开源漏洞扫描器，以其海量的社区模板和强大的并发能力著称，但传统的模板运行方式，恰恰是“依赖地狱”的重灾区。一个模板可能需要curl、jq、nmap，甚至特定的Python或Go环境才能完整执行其逻辑。

而“自包含模板”正是为了解决这一痛点而生。它不是一个新工具，而是Nuclei模板编写范式的一次革命性升级。其核心思想是，将模板运行所需的一切——命令、代码、数据——全部打包进一个YAML文件里。当你运行这个模板时，Nuclei引擎会像一个自洽的沙箱，在内部处理好所有依赖，无需你额外配置任何系统环境。想象一下，你拿到一个检测最新Log4j漏洞的模板，不再需要关心本地Java版本、ldap命令是否可用，直接nuclei -u target就能得到准确结果。这不仅仅是方便，更是将安全检测的可靠性和可复现性提升到了新的高度。本指南将深入拆解如何从零开始，构建属于你自己的、强大且优雅的Nuclei自包含模板，让你彻底从环境配置的泥潭中解脱出来。

2. 自包含模板的核心设计哲学与优势

2.1 从“外部调用”到“内聚封装”的范式转变

传统的Nuclei模板严重依赖raw请求和extractors中的run命令。这些命令直接在宿主操作系统上执行。例如，一个模板可能包含这样的片段：

extractors: - type: regex part: body regex: - “\\d+\\.\\d+\\.\\d+” run: - “echo ‘Found version: {{regex}}’ | tee -a output.txt”

这段代码中的tee命令要求目标系统必须安装有GNU coreutils。如果扫描目标是一台精简的Alpine Linux容器，或者Windows服务器，这个模板就会失败。更复杂的情况是，模板可能需要调用一个Python脚本解析响应，那么目标系统上就必须有兼容的Python解释器和requests库。

自包含模板通过引入code和payloads等关键特性，实现了范式的根本转变：

1. 代码内嵌：你可以将JavaScript代码直接写入模板的code字段。Nuclei内置了一个JavaScript解释器（通常是Goja），这段代码会在一个隔离的、受控的沙箱环境中运行，与宿主系统完全无关。这意味着你可以用JS实现复杂的逻辑，如HMAC签名计算、JSON解析、字符串变换，而无需依赖外部的openssl或jq。
2. 载荷内嵌：攻击载荷（payloads）可以直接定义在模板中，或者通过payloads字段内联。你不再需要维护一个外部的payloads.txt文件，并确保它在扫描时能被正确加载。
3. 链式操作自足：整个检测逻辑，从请求生成、响应处理到结果判断，都可以在模板内部完成。模板成为一个真正“开箱即用”的检测单元。

这种设计的巨大优势在于可移植性和确定性。无论你的Nuclei运行在Kali Linux、MacOS、Windows，还是某个CI/CD流水线的Docker容器中，只要Nuclei版本一致，自包含模板的行为就是完全一致的。这为团队协作、知识库归档和自动化流水线集成扫清了障碍。

2.2 关键组件深度解析：code,payloads,self-contained

要掌握自包含模板，必须吃透以下几个核心组件：

• code字段：这是自包含能力的灵魂。它允许你在模板中定义JavaScript函数。这些函数可以通过{{和}}在请求的任意部分（如URL、Path、Header、Body）中被调用。

  code: - | function generateTimestamp() { return Math.floor(Date.now() / 1000); } function calcHMAC(message, secret) { // 使用内置的CryptoJS模拟库或纯JS实现 // 这是一个简化示例 return “hmac_placeholder_” + message; } requests: - raw: - | GET /api/config?ts={{generateTimestamp()}}&sig={{calcHMAC(“config”, “secret_key”)}} HTTP/1.1 Host: {{Host}}

  在上面的例子中，我们完全用内嵌JS生成了动态的时间戳和HMAC签名，替代了原本需要调用系统命令或外部库的复杂过程。

• payloads字段：将载荷定义从外部文件移入模板内部。这对于需要与模板逻辑紧密耦合的载荷尤其有用。

  payloads: paths: admin: [“/admin”, “/administrator”, “/wp-admin”] backup: [“/backup.zip”, “/www.zip”, “/site.tar.gz”] requests: - raw: - | GET {{path}} HTTP/1.1 Host: {{Host}} attack: pitchfork payloads: path: paths

  这样，模板本身就携带了要扫描的路径字典，无需额外文件。

• self-contained布尔标志：这是一个明确的声明标签。虽然Nuclei引擎会根据模板内容自动判断，但在模板的info部分显式设置self-contained: true是一个好习惯。它向其他使用者清晰地表明：“这个模板无需任何外部依赖即可运行”，同时也便于通过工具对模板库进行筛选和管理。

3. 构建自包含模板的实战步骤

3.1 需求分析与逻辑拆解

在动手编写YAML之前，清晰的规划至关重要。我们以一个实战场景为例：检测目标是否暴露了敏感的.env配置文件，并且该文件内容中包含数据库凭证。

传统非自包含的做法可能是：发起请求获取.env文件 -> 用grep或正则提取内容 -> 调用外部密码强度检查脚本。现在，我们需要将所有步骤内化。

1. 核心检测逻辑：请求/.env，/config/.env等常见路径。
2. 响应处理：如果文件存在（HTTP状态码200），则检查响应体是否包含DB_PASSWORD、DATABASE_URL、API_KEY等关键词。
3. 动态生成：为了增加绕过WAF的可能，可以考虑对路径进行简单的编码变形。
4. 结果提取：提取出发现的密钥值，并作为高严重性漏洞输出。

3.2 编写基础请求与动态路径

首先，我们构建请求部分，并利用code实现简单的路径编码。

id: env-file-exposure info: name: Sensitive .env File Exposure with Credential Check author: your_name severity: high description: Detects exposed .env files and checks for hardcoded credentials. reference: - https://www.example.com/env-leak tags: exposure,env,config,credentials self-contained: true # 明确声明为自包含 code: - | // 1. 定义常见的.env文件路径 function getEnvPaths() { return [‘/.env’, ‘/.env.production’, ‘/config/.env’, ‘/app/.env’, ‘/laravel/.env’]; } // 2. 简单的URL编码函数（用于可能的绕过） function urlEncode(path) { // 这里只对点号进行编码，实际可根据需要扩展 return path.replace(/\./g, ‘%2e’); } // 3. 凭证模式匹配函数 function findCredentials(text) { const patterns = [ /DB_PASSWORD\s*=\s*[‘“]?([^‘“\n\r]+)/i, /DATABASE_URL\s*=\s*[‘“]?([^‘“\n\r]+)/i, /API_KEY\s*=\s*[‘“]?([^‘“\n\r]+)/i, /SECRET_KEY\s*=\s*[‘“]?([^‘“\n\r]+)/i, /AWS_ACCESS_KEY_ID\s*=\s*[‘“]?([^‘“\n\r]+)/i, /AWS_SECRET_ACCESS_KEY\s*=\s*[‘“]?([^‘“\n\r]+)/i, ]; const found = []; for (const pattern of patterns) { const match = text.match(pattern); if (match && match[1]) { found.push(`${pattern.source.split(‘\\’)[0]}: ${match[1].substring(0, 50)}…`); // 截断长密钥 } } return found.length > 0 ? found.join(‘; ‘) : null; } requests: - raw: - | GET {{path}} HTTP/1.1 Host: {{Host}} User-Agent: Mozilla/5.0 (Nuclei) {{randstr}} # 使用code中定义的函数生成攻击载荷 payloads: path: “{{getEnvPaths()}}” # 注意：这里需要将函数调用转为字符串载荷，但更推荐使用迭代器模式 matchers: - type: dsl dsl: - “status_code == 200” # 文件存在 - “findCredentials(body) != null” # 且包含凭证 condition: and

注意：上面的payloads用法是一种尝试，但Nuclei的payloads字段通常期望一个静态列表或字典。直接在payloads中调用JS函数可能无法按预期工作。更可靠的方式是在raw请求的路径中循环，或者使用attack模式配合预定义的列表。下面我们采用更稳妥的“迭代器”方式。

3.3 实现复杂逻辑：循环与条件判断

我们需要对多个路径进行扫描。虽然Nuclei支持payloads，但对于从JS函数动态生成的列表，我们可以利用raw请求的多个块或threads配合attack模式，但最直接的自包含方式是使用“请求链（Request Chains）”的雏形——虽然Nuclei的链式请求主要用于上下文传递，但我们可以通过设计实现循环。

这里，我们调整策略：将路径生成和检查逻辑，全部放在一个请求的预处理阶段（pre-condition）和匹配阶段（matchers）中。但更清晰的做法是，使用code生成路径列表，并通过多个raw请求块来模拟循环。

requests: # 方法一：显式列出所有路径（当路径固定且不多时最直接） - raw: - | GET /.env HTTP/1.1 Host: {{Host}} matchers-condition: and matchers: - type: dsl dsl: - “status_code == 200” - “findCredentials(body) != null” - raw: - | GET /.env.production HTTP/1.1 Host: {{Host}} matchers-condition: and matchers: - type: dsl dsl: - “status_code == 200” - “findCredentials(body) != null” # … 其他路径重复上述块 # 方法二（推荐）：使用一个请求，但路径通过变量控制，并利用Nuclei的引擎进行迭代（这需要结合workflow，但非标准模板语法） # 目前更实用的自包含方案是：将核心检测逻辑（访问路径+检查凭证）封装成一个“通用”请求， # 然后通过外部驱动（如脚本生成多个模板）或使用Nuclei的`-list`输入来扫描多个目标路径。 # 但对于一个真正“自包含”的、针对单个目标进行多路径探测的模板，方法一是最可靠的。

然而，方法一会导致模板冗长。为了平衡，我们可以利用payloads内联定义来实现动态路径，这才是自包含模板的优雅解：

id: env-file-exposure-v2 info: name: Sensitive .env File Exposure with Credential Check (Self-Contained) author: your_name severity: high self-contained: true code: - | // 凭证检查函数同上，此处省略... function findCredentials(text) { /* … */ } # 关键：将路径定义为内联载荷 payloads: env_paths: - “/.env” - “/.env.production” - “/.env.local” - “/config/.env” - “/app/.env” - “/laravel/.env” - “/api/.env” - “/public/.env” - “/%2eenv” # URL编码的路径，用于绕过 requests: - raw: - | GET {{path}} HTTP/1.1 Host: {{Host}} User-Agent: Mozilla/5.0 (Nuclei) {{randstr}} attack: clusterbomb # 或 sniper，这里我们每个路径单独测试 payloads: path: env_paths matchers-condition: and matchers: - type: status status: - 200 - type: dsl dsl: - “findCredentials(body) != null” # 从DSL函数中提取匹配到的凭证信息作为提取器 extractors: - type: dsl dsl: - “findCredentials(body)” name: “exposed_credentials” # 提取出的凭证信息会存储在变量中

在这个改进版中，我们通过内联的payloads定义了所有要扫描的路径，并通过attack: clusterbomb让Nuclei自动迭代每个路径进行请求。findCredentials函数在DSL匹配器中调用，如果匹配成功，extractors会进一步执行同一个函数，将具体的凭证信息提取出来，并命名为exposed_credentials变量，该变量可以在输出时被引用。

3.4 提取与输出优化

为了让结果更具可读性，我们可以优化输出信息，将发现的凭证直接显示出来。

extractors: - type: dsl dsl: - “findCredentials(body)” name: “creds” internal: true # 设置为内部变量，不在默认输出中显示多行，我们自定义输出 matchers-condition: and matchers: - type: status status: - 200 - type: word words: - “DB_PASSWORD=” - “API_KEY=” - “SECRET_KEY=” condition: or - type: dsl dsl: - “creds != null” # 引用提取器得到的变量 # 在info部分或通过matcher-name定义更详细的输出 # 实际上，匹配到的信息会通过Nuclei的默认格式输出。 # 我们可以通过添加自定义的‘matchers’部分来增强输出，但更复杂的输出格式化通常依赖于Nuclei的报告引擎。

最终，当这个模板运行时，它会自动遍历所有内嵌的路径，对每个路径发起请求，并用内嵌的JavaScript函数检查响应中是否包含凭证。整个过程，除了Nuclei引擎本身，不需要任何外部依赖。

4. 高级技巧与最佳实践

4.1 代码模块化与复用

当多个模板需要相同的辅助函数（如HMAC计算、JWT解析、特定解码函数）时，重复定义code块是低效的。虽然Nuclei模板本身不支持直接的跨模板code引用，但你可以通过以下策略实现“准模块化”：

1. 创建基础模板库：编写一个包含所有通用函数的“基础”模板。虽然它不能直接被其他模板include，但你可以将其code块保存为一个独立的文本片段。
2. 使用模板生成器：编写一个简单的脚本（如Python、Shell），以基础code片段为骨架，动态插入特定检测逻辑，生成最终的Nuclei模板YAML文件。这在构建大型自定义模板库时非常有效。
3. 关注社区动态：Nuclei社区和核心团队一直在探索更好的代码复用方式，未来可能会有更正式的模块化支持。

4.2 性能考量与错误处理

在code字段中执行复杂的JavaScript逻辑会带来性能开销。对于要扫描成千上万目标的模板，需要谨慎优化。

• 避免在code中执行阻塞性操作：不要模拟网络请求或执行繁重的同步计算。Nuclei的JS环境是单线程的，会阻塞整个扫描进程。
• 将计算移出热路径：如果有些计算（如生成大型字典）可以在模板加载时完成，就不要放在每个请求的DSL表达式中。可以利用code在全局初始化。
• 添加健壮的错误处理：在自定义的JS函数中，使用try-catch包裹可能出错的代码，返回安全的默认值，避免因为一个目标的异常响应导致整个模板执行中断。

  function safeDecodeBase64(str) { try { return atob(str); // 假设环境支持atob } catch (e) { return “”; // 解码失败返回空字符串 } }

4.3 调试自包含模板

调试包含复杂JavaScript逻辑的模板比调试简单模板更困难。

1. 使用-debug和-verbose标志：运行nuclei -u target -t your-template.yaml -debug -verbose。这会输出更详细的执行过程，有时会显示JS执行错误。
2. 简化与隔离：首先确保你的HTTP请求部分能正常工作。然后，逐步添加code逻辑，并使用dsl打印调试信息。

   matchers: - type: dsl dsl: - “console.log(‘Path:’, path) // 在调试输出中打印变量” - “console.log(‘Body length:’, body.length)” - “true” # 始终匹配，仅用于调试

3. 在外部测试JS代码：将code块中的函数复制到浏览器的开发者工具控制台或Node.js环境中进行测试，确保其逻辑正确，然后再集成到模板中。

5. 常见问题与实战排坑指南

5.1 模板加载失败：语法与格式错误

问题：运行模板时，Nuclei报错could not parse template或invalid yaml。

排查步骤：

1. YAML格式校验：使用在线YAML校验器或yamllint工具检查文件格式。最常见的错误是缩进（必须使用空格，通常2个空格为一个层级）和冒号后的空格。
2. JSON转义：在raw请求或code字符串中，如果包含双引号”，需要小心处理。在YAML中，你可以使用单引号包裹整个字符串，或者在双引号内使用\”转义。
3. JavaScript语法：确保code块内的JavaScript语法正确。特别是当从其他编辑器复制代码时，注意隐藏的特殊字符（如BOM头）或缩进符。

实操心得：我习惯使用VS Code编写模板，并安装redhat.vscode-yaml扩展。它会实时验证YAML语法，并用不同的颜色高亮显示code块中的JavaScript，能提前发现大部分格式和语法错误。

5.2 代码执行无响应或逻辑错误

问题：模板能运行，但自定义的JavaScript函数似乎没有被调用，或者返回的结果不符合预期。

排查步骤：

1. 函数名与调用匹配：检查{{function_name()}}中的函数名是否与code块中定义的完全一致，包括大小写。
2. 作用域与返回值：确保函数在code块中正确定义，并且有返回值。如果函数返回undefined，在DSL中可能被视为false或空值。
3. DSL表达式调试：如前所述，使用console.log在DSL中输出中间变量值。这是最强大的调试手段。
4. 检查Nuclei版本：某些code和DSL功能可能需要较新版本的Nuclei。确保你使用的Nuclei版本支持模板中的所有特性。

避坑技巧：在编写复杂的JS逻辑时，我通常会先写一个极简的测试模板。这个模板只包含code和一个简单的matcher，matcher的DSL就是调用我的函数并打印结果。针对一个已知的测试目标运行，可以快速验证函数逻辑是否正确，然后再集成到完整的检测逻辑中。

5.3 性能瓶颈与优化

问题：使用自包含模板后，扫描速度明显变慢。

排查与优化：

1. 分析code复杂度：检查code中的函数是否在每次请求时都被调用，并且是否包含了不必要的循环或重型计算。尽量将常量计算提升到函数外部。
2. 减少不必要的匹配器和提取器：每个matcher和extractor都会增加处理开销。确保它们都是必要的，并尝试合并DSL条件。
3. 合理设置模板的attack类型：对于clusterbomb等攻击模式，它会生成请求的笛卡尔积。如果payloads很大，请求量会爆炸式增长。评估是否真的需要全组合，或者可以使用sniper模式。
4. 利用缓存：如果多个请求需要使用相同的复杂计算结果，考虑是否可以通过Nuclei的变量机制（尽管在单个模板内变量共享有限）或设计请求链来避免重复计算。

5.4 与其他工具的集成与对比

自包含模板并非银弹，它主要解决的是环境依赖和可移植性问题。在以下场景，你可能仍需结合其他工具：

核心原则：将检测逻辑中轻量级、决定性的判断部分内嵌化，将重量级、资源密集型或强依赖外部系统的操作外置化或通过工作流协调。自包含模板是你的主力武器，用于解决80%的常见、可移植的检测需求。对于剩下的20%，理解其边界，并设计合理的架构（如模板+工作流+外部脚本）来应对。

通过深入理解和应用自包含模板，你构建的漏洞检测能力将变得像集装箱一样标准、独立且易于分发。无论你的队友在世界的哪个角落，使用什么操作系统，都能一键复现你的扫描结果，真正实现安全协作的“一次编写，到处运行”。这不仅仅是技术的提升，更是工作流和团队效能的革命。