Tsunami Templated 插件变量机制完全指南：从硬编码到工作流变量的工程化实践

网络安全应用安全漏洞扫描【免费下载链接】tsunami-security-scannerTsunami is a general purpose network security scanner with an extensible plugin system for detecting high severity vulnerabilities with high confidence.项目地址https://gitcode.com/gh_mirrors/ts/tsunami-security-scanner点击查看免费下载导读本指南围绕 Tsunami 安全扫描器 templated 插件体系中的**变量Variables**机制展开讲解如何将 action 中硬编码的 payload 抽离为 workflow 级变量、如何通过 extractions 从 HTTP 响应中提取动态信息到局部变量、以及 Tsunami 核心引擎内置的T_*预定义变量族。读完本文你将掌握在.textproto插件配置中安全、规范地使用变量的全部技巧并理解变量与回调服务器Callback Server联动、与单元测试配合的完整实战方案。本文以 docs/howto/new-detector/templated/05-variables.md 为骨架并结合本仓库中 templated 插件系列文档01-introduction、04-workflows、06-callback-server、glossary-predefined-variables展开。为什么需要变量告别硬编码在 03-first-actions 教程中我们的 exploitation action 把 payload 直接硬编码在了data字段里actions: { name: exploitation http_request: { method: POST uri: /exploit data: process%{ print(\tsunami_%d_marker\, 1250*13) }% response: { http_status: 200 expect_all: { conditions: [ { body: {} contains: tsunami_1253_marker } ] } } } }这段配置存在明显的工程问题payload 表达式模板注入语法与期望值tsunami_1253_marker散落在 action 内部既不直观也不易维护。一旦 payload 的计算逻辑变化期望值必须同步手改极易遗漏。templated 插件为此提供了**工作流变量Workflow variables**机制把发送什么和期望什么提升到 workflow 层面统一管理。定义与使用工作流变量在 workflow 的variables字段中可以一次性声明多个命名变量。每个变量由name与value两个字段构成workflows: { variables: [ { name: payload value: %{ print(\tsunami_%d_marker\, 1250*13) }% }, { name: payload_result value: tsunami_1253_marker } ] actions: [ fingerprinting, exploitation ] }声明之后action 中即可通过{{ 变量名 }}的模板语法引用这些变量actions: { name: exploitation http_request: { method: POST uri: /exploit data: process{{ payload }} response: { http_status: 200 expect_all: { conditions: [ { body: {} contains: {{ payload_result }} } ] } } } }这样改造后data与contains的内容都指向了 workflow 顶部集中定义的变量payload 逻辑一目了然。语法红线必须恰好一个空格重要变量替换语法对空格极其敏感——{{与变量名之间、变量名与}}之间必须恰好存在一个空格即严格写作{{ payload }}。写成{{payload}}、{{ payload }}两个空格或{{payload }}等任何变体替换都不会发生action 会把整段模板文本原样发送给目标服务导致检测逻辑静默失效。工作流变量的生命周期工作流变量具有以下特性理解它们有助于正确选择变量类型在 workflow 层面定义主要用于承载静态内容在整个 workflow 生命周期内持续存在每次 workflow 运行run之间会被重置为定义时的初始值技术上可变mutable但官方强烈不建议对工作流变量进行修改尤其不要把它们用作 extractions 的写入目标。从响应中提取信息局部变量与 Extractions仅靠静态变量无法应对前一个 action 的结果要传给后一个 action的动态场景。典型例子一个 action 创建了某个 job后续 action 需要这个 job 的名字来触发漏洞或者/version页面返回一个 CSRF token后续/exploit请求必须携带它。此时需要用到extractions与局部变量Local variables。两种变量的分工维度工作流变量Workflow variables局部变量Local variables定义位置workflow 的variables字段由 extraction 在 action 运行时产生内容特性多为静态内容动态内容来自响应解析生命周期整个 workflow 生命周期run 之间重置仅当前 workflow 运行run内有效典型用途承载 payload、固定期望值传递后续 action 需要的信息用 extract_all 捕获响应内容以下示例在 fingerprinting action 中既校验Server头包含MyVulnerableApp又从响应体中提取 CSRF token 存入局部变量csrf_tokenactions: { name: fingerprinting http_request: { method: GET uri: /version response: { http_status: 200 expect_all: { conditions: [ { header: { name: Server } contains: MyVulnerableApp } ] } extract_all: { patterns: [ { from_body: {} regexp: CSRFToken([a-zA-Z0-9_]) variable_name: csrf_token }, ] } } } }这个例子展示了 extraction 的完整工作方式仍然先执行expect_all中的既有校验Server头包含MyVulnerableApp通过extract_all.patterns定义提取模式每个 pattern 有三个关键字段from_body: {}指明提取来源是响应体也可针对 header 等其他位置regexp用于匹配的正则表达式例如CSRFToken([a-zA-Z0-9_])variable_name提取结果存入的局部变量名这里为csrf_token。提取成功后后续 action 中即可通过{{ csrf_token }}引用该局部变量。提取机制的硬性约束extraction 系统恰好支持一个捕获组capture group。正则中的(...)只能出现一次多个捕获组不会被正确处理需要同时提取多条信息时必须拆分成多个 pattern每个 pattern 对应一个独立的variable_name警告使用extract_any进行提取时要格外谨慎。官方强烈建议只在各次 extraction 之间使用相同的 variable_name时才采用extract_any。否则插件可能变得 flaky结果不稳定且难以调试——因为不同提取路径可能命中不同的模式变量内容在不同运行间不可预期。预定义变量引擎内置的T_*变量族除了用户自定义变量Tsunami 核心引擎会向每个 workflow 运行注入一组预定义变量完整清单见 glossary-predefined-variables。这些变量遵循严格的命名约定前缀含义提供方T_Tsunami标识由核心引擎提供的变量核心引擎_UTL_Utility通用工具类变量核心引擎_NS_Network Service当前被扫描网络服务的信息核心引擎_CBS_Callback Server回调服务器相关信息核心引擎_TST_仅用于测试的变量测试环境完整预定义变量清单变量名说明示例值T_UTL_CURRENT_TIMESTAMP_MS当前时间戳毫秒。在一次 workflow 运行开始时计算因此不同服务之间值不同但同一运行内部恒定1735600000000T_NS_BASEURL被扫描网络服务的 base URLhttp://127.0.0.1:9090、http://hostname.lan:1000T_NS_PROTOCOL被扫描服务使用的协议tcpT_NS_HOSTNAME被扫描服务的主机名。仅当 Tsunami 以主机名作为目标启动时可用例如hostname.lanhostname.lanT_NS_PORT被扫描服务的端口1000T_NS_IP被扫描服务的 IP127.0.0.1T_CBS_URI回调服务器触发 URL包含地址与哈希后的 secret。使用回调服务器时的主变量http://tsunami-callback.lan/8fe7d878787d65IP 型地址下为http://xxx.xxx.xxx.xxx/8fe7d878787d65T_CBS_DNS仅回调服务器主机名用于无法发起 HTTP 请求、只能做 DNS 交互的场景为哈希 secret 回调地址前缀形式8fe7d878787d65.tsunami-callback.lanT_CBS_SECRET当前 workflow 运行生成的回调 secret未哈希多数场景用不到somesecretT_CBS_ADDRESS回调服务器地址tsunami-callback.lanT_CBS_PORT回调服务器端口80T_TST_DISABLE_SLEEP引擎内部用于在测试期间禁用sleepaction—预定义变量的实战要点T_UTL_CURRENT_TIMESTAMP_MS的同一次运行内恒定特性非常适合生成需跨 action 一致的唯一标识但要意识到它在不同服务上会刷新T_NS_HOSTNAME的可用性受启动方式约束只有以主机名而非 IP作为扫描目标时才有值编写通用插件时应做好缺失兜底T_CBS_*变量族与回调服务器深度绑定详细用法见下一节。变量 × 回调服务器组合出 OOB 检测回调服务器Callback Server是一种**带外out-of-band**漏洞检测机制在 06-callback-server 中有完整说明。其工作流程为每次 workflow 运行自动生成一个 secret存入T_CBS_SECRET该 secret 被哈希漏洞利用代码使用哈希后的 secret 与回调服务器 URLT_CBS_URI或仅主机名的T_CBS_DNS触发与回调服务器的带外通信之后用 secret 询问回调服务器是否记录到了使用该哈希 secret 的通信从而判定漏洞是否被触发。由于当前 templated 插件系统尚不支持自动 payload 生成回调通信需要半手动处理——这正是变量的用武之地。把 payload 声明为变量并在其中直接模板引用T_CBS_URI{ name: payload value: %{ import os; os.system(curl {{ T_CBS_URI }}) }% }运行时T_CBS_URI会被替换为触发 URL一旦目标执行了该命令回调服务器就会收到对应请求。随后定义回调检查 actionactions: { name: check_callback_server_logs callback_server: { action_type: CHECK } }用变量实现多工作流并存的降级方案回调服务器并不总是可用。templated 插件通过workflows.condition支持条件匹配配合变量可为不同环境准备多套工作流。注意workflow 按定义顺序解释更严格的带 condition 的必须写在前面否则宽松版本永远先被匹配# 依赖 DNS 回调的 workflow workflows: { condition: REQUIRES_DNS_CALLBACK_SERVER variables: [ { name: payload value: %{ import os; os.system(dig {{ T_CBS_DNS }}) }% } ## 注意空字符串总是存在于响应体中用于抵消 body 内容期望 { name: payload_result value: } ] actions: [ fingerprinting, exploitation, check_callback_server_logs ] } # 依赖 HTTP 回调的 workflow workflows: { condition: REQUIRES_CALLBACK_SERVER variables: [ { name: payload value: %{ import os; os.system(curl {{ T_CBS_URI }}) }% } { name: payload_result value: } ] actions: [ fingerprinting, exploitation, check_callback_server_logs ] } # 无回调服务器的兜底 workflow workflows: { variables: [ { name: payload value: %{ print(\tsunami_%d_marker\, 1250*13) }% }, { name: payload_result value: tsunami_1253_marker } ] actions: [ fingerprinting, exploitation ] }三套 workflow 共享同一组 action仅通过变量定义与 condition 区分执行环境体现了变量机制在插件可移植性上的价值。其中payload_result被置为空字符串的技巧值得一提因为空字符串恒存在于响应体中body contains 的期望永远成立从而把基于 body 的校验短路掉——这是官方文档中明确记录的惯用法。变量在单元测试中的角色在 08-writing-unit-tests 中预定义变量与测试机制有直接关联T_TST_DISABLE_SLEEP由引擎在测试期间自动注入用于禁用sleepaction保证测试可确定性执行mock HTTP server 提供两个魔法 URI详见 glossary-tests-magic-uriTSUNAMI_MAGIC_ANY_URI匹配任意请求用于兜底应答TSUNAMI_MAGIC_ECHO_SERVER让服务器原样回显请求引擎用它自动生成测试以探测 flaky 检测器例如服务器仅回显请求时不应报漏洞引擎还会自动为插件生成单元测试用于捕捉变量替换或提取逻辑导致的检测不稳定问题。这些机制共同保证了即便变量内容随目标响应动态变化检测结果依然可被稳定验证。变量使用的最佳实践清单综合 05-variables 及配套文档编写 templated 插件时应遵循以下实践集中声明将 payload 与期望值提升为 workflow 级变量避免散落硬编码严守空格语法{{ variable }}两侧恰好一个空格否则替换静默失败区分变量类型静态内容用工作流变量动态响应数据用 extraction 局部变量尊重不可变性不要对工作流变量做 mutation不要把它们作为 extraction 写入目标单捕获组原则每个 extraction pattern 只含一个捕获组多信息提取拆成多个 pattern慎用 extract_any只有各提取路径使用相同variable_name时才考虑否则插件会 flaky 且难调试善用预定义变量优先使用T_NS_*定位目标、T_CBS_*实现 OOB 检测、T_UTL_CURRENT_TIMESTAMP_MS生成运行内唯一标识条件降级涉及回调服务器的插件用condition 多 workflow 定义提供无回调环境下的兜底路径且把严格条件写在前面。下一步掌握变量机制后可以继续学习回调服务器的深入用法06-callback-server、清理动作07-cleanup-actions以及完整的单元测试编写08-writing-unit-tests。变量是贯穿这一切的基础设施——从 fingerprinting 的信息传递到 exploitation 的 payload 组装再到回调触发的带外校验变量把 templated 插件的各环节粘合为一个可维护、可测试的整体。赞分享网络安全应用安全漏洞扫描【免费下载链接】tsunami-security-scannerTsunami is a general purpose network security scanner with an extensible plugin system for detecting high severity vulnerabilities with high confidence.项目地址https://gitcode.com/gh_mirrors/ts/tsunami-security-scanner点击查看免费下载相关推荐OneUptime 工作流变量完全指南全局变量、局部变量与组件输出的引用、安全与实践OneUptime 工作流变量完全指南全局变量、局部变量与组件输出的引用、安全与实践 导读 OneUptime 的 Workflow工作流本质上是搬运数可观测性后端运维前端云原生微服务AI AgentOneUptime 工作流变量完全指南全局变量、局部变量与组件输出VariablesOneUptime 工作流变量完全指南全局变量、局部变量与组件输出Variables 工作流本质上是在搬运数据——从触发器到第一个组件、从上一个组件到下一可观测性后端运维前端云原生微服务AI AgentOneUptime 工作流变量完全指南全局变量、局部变量与组件输出的数据传递实战OneUptime 工作流变量完全指南全局变量、局部变量与组件输出的数据传递实战 工作流Workflow的本质是数据的流动——从触发器流向第一个模块从一可观测性后端运维前端云原生微服务AI Agent上一篇Hugo 在 Linux 上的安装完全指南Snap、发行版仓库与源码编译全解析下一篇LogicFlow 渐进连线插件 ProximityConnect 完全指南拖拽智能吸附与虚拟边机制详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考