Sigma 占位符规则（Placeholder Rules）完全指南：用可复用模板构建灵活检测
【免费下载链接】sigmaMain Sigma Rule Repository项目地址: https://gitcode.com/GitHub_Trending/si/sigma
导读
Sigma 占位符规则（Placeholder Rules）是 SigmaHQ 主规则仓库中一类特殊的检测模板，用于把与具体环境强相关的信息（如内网域名、可信 IP、管理员账户、服务器主机名等）从规则逻辑中抽象出来，交给使用者按需填充。本文以 rules-placeholder/README.md 为骨架，结合仓库内 23 个真实占位符规则实例，讲解占位符的设计动机、六种 pySigma 占位符转换、|expand修饰符的写法，以及如何在 Windows、AWS、Azure、Okta 等场景中落地使用，帮助你写出既能共享给社区、又能无缝适配自家环境的 Sigma 规则。
什么是占位符规则
在 rules-placeholder 目录下存放的规则，本质上是可定制化的检测模板（flexible detection templates）。README 开篇即点明其定位：
The rules available in this folder, are flexible detection templates that can be customized for your environments or use cases.
典型的使用场景包括：
- 需要域名或工作站变体的检测，例如"仅监控公司内部的服务器系统"；
- 与公司特定环境强相关的检测逻辑，例如"只有少数管理员被允许邀请访客用户"；
- 每家企业各不相同、无法在通用规则中写死的值，例如"合法登录国家/地区列表"。
因此，占位符规则扮演的是抽象检测模板的角色：规则作者把环境相关值写成占位符，使用者在部署时替换为自己的值即可。正如 README 所述：
placeholder rules serve as an abstract detection template, where you adjust the placeholder value to fit your use case.
设计动机：让私有规则保持干净、让环境信息可复用
占位符机制解决的是 Sigma 生态中一个真实痛点：企业往往需要在社区规则之上叠加自己的"私有规则"（private rules），而这些私有规则里充斥着%DomainControllers%、%Approved_Inviters%之类的环境专属信息。如果这些信息散落在规则正文中：
- 难以共享：发布到社区前必须逐一脱敏；
- 难以维护：环境变化（如新增网段）需要同步修改大量规则；
- 复用成本高：同一组环境信息在不同规则里被重复硬编码。
README 明确指出，占位符机制正是为了：
keep private rules clean and make any environment-specific information reusable to the community
也就是说：规则作者只需选用一种占位符转换（placeholder transformation），后续使用该规则的人就能直接调整占位符的值来适配自己的环境，而无需改动检测逻辑本身。
六种 pySigma 占位符转换
占位符需要映射到 pySigma 提供的转换（transformations）才能被正确处理。README 给出了完整清单：
| 占位符转换 | 适用场景 | 仓库实例 |
|---|---|---|
command_placeholders | 命令行、可执行文件路径等 | proc_creation_win_userdomain_variable_enumeration.yml 中匹配%userdomain%环境变量 |
file_placeholders | 文件路径、目录、扩展名 | 适用于文件创建/访问类规则 |
http_placeholders | URL、URI、请求头等 HTTP 字段 | 适用于代理日志、Web 日志类规则 |
query_expression_placeholders | 查询表达式整体替换 | 适用于需要整体替换查询语句的场景 |
value_placeholders | 标量值，如 IP、账号名、事件值 | 如%Legitimate_Countries%、%Administrators% |
wildcard_placeholders | 含通配符的字符串 | 如%internal_domains%这类可展开为多域列表的值 |
完整且持续更新的转换清单，始终以 pySigma 仓库的 sigma/processing/transformations/init.py（对应 pySigma 的 transformations 模块）为准；实际使用时请以你安装的 pySigma 版本为准。
核心语法：|expand修饰符与占位符书写
占位符规则的检测逻辑与普通规则几乎一致，唯一的区别是：需要环境化的字段使用字段|expand: '%占位符%'语法。|expand告诉转换器：这个值不是字面量，而是需要在处理阶段展开的环境变量。
占位符的命名惯例是左右各一个百分号包裹、使用大驼峰命名，例如：
%ServerSystems%%DomainControllers%%Workstations%%Legitimate_Countries%%Legitimate_IP_Ranges%%internal_domains%%Approved_Inviters%%Administrators%%legtimate_identifiers%%legit_ips%
实例一：Windows 交互式登录监控（值列表展开）
win_security_susp_interactive_logons.yml 是一则典型的值占位符规则：它检测对服务器系统的交互式控制台登录（EventID 528/529/4624/4625 + LogonType 2），而"哪些机器算服务器/域控/工作站"由环境决定：
detection: selection: EventID: - 528 - 529 - 4624 - 4625 LogonType: 2 ComputerName|expand: - '%ServerSystems%' - '%DomainControllers%' filter_main_advapi: LogonProcessName: 'Advapi' ComputerName|expand: '%Workstations%' condition: selection and not 1 of filter_main_*注意这里ComputerName|expand既可以接收单个占位符字符串，也可以接收一个占位符列表——多个列表项最终会被展开合并为一个集合。这种写法让规则作者无需关心使用者到底有几个服务器网段。
实例二：AWS 控制台登录地理监控（双占位符过滤）
aws_cloudtrail_console_login_success_from_susp_locations.yml 展示了一种更常见的模式——"命中可疑 + 排除合法"双过滤器：
detection: selection: eventName: 'ConsoleLogin' responseElements.ConsoleLogin: 'Success' filter_main_country: src_country|expand: '%Legitimate_Countries%' # Add legitimate countries here filter_main_ip: src_ip|expand: '%Legitimate_IP_Ranges%' # Add legitimate src_ip ranges here condition: selection and not 1 of filter_main_*检测主体（ConsoleLogin 成功）是通用的，只有"合法国家"和"合法 IP 段"是占位符。新用户部署时只需把自家办公地国家代码和出口 IP 段填入占位符即可，检测逻辑零改动。
实例三：证书服务出站连接监控（带回环过滤的混合写法）
net_connection_win_certsvc_outbound_smb_ldap.yml 展示了占位符与硬编码过滤器共存的结构：filter_main_loopback硬编码排除回环地址，filter_main_known_legit_ips用%legit_ips%排除 CA 服务器已知合法的对端 IP（如其他域控、LDAP 服务器）：
detection: selection: Image|endswith: '\certsrv.exe' Initiated: 'true' DestinationPort: - 389 - 445 filter_main_loopback: DestinationIp: - '127.0.0.1' - '::1' - '0:0:0:0:0:0:0:1' filter_main_known_legit_ips: DestinationIp|expand: '%legit_ips%' # Including known legitimate IPs for the CA server (e.g. other DCs, LDAP servers, etc.) condition: selection and not 1 of filter_main_*这则规则用于捕捉 certsrv.exe 主动向非域控主机发起 445/389 出站连接的异常行为（如 CVE-2026-54121 "Certighost" 所利用的 CA chase fallback 路径），检测价值很高，但误报控制完全依赖%legit_ips%的准确性。
实例四：域控机器账户登录监控（命名规范）
win_security_dc_machine_account_logon_non_dc_ip.yml 等三则 DC 相关规则均依赖%DomainControllers%占位符，检测"域控机器账户从非域控 IP 登录/获取 TGT/TGS"。这类规则对占位符值的依赖度极高——占位符填错，整条规则要么漏报要么全量误报，是理解占位符价值的最佳反面教材。
占位符的使用与部署流程
从 rules-placeholder 目录中 23 个规则实例可以总结出标准的落地步骤：
1. 识别环境相关字段。逐字段自问："这个值在所有企业都一样吗？" 一样则硬编码，不一样则占位符化。仓库中的高频占位符包括：
%DomainControllers%、%ServerSystems%、%Workstations%（Windows 主机分组，见 win_security_susp_interactive_logons.yml）；%Administrators%（特权账户组，见 win_security_modification_of_msds_dmsa_link_attribute.yml）；%internal_domains%（内网域名列表，见 dns_query_win_wscript_cscript_resolution.yml）；%Legitimate_Countries%、%Legitimate_IP_Ranges%（云环境地理基线，见 azure_ad_authentications_from_countries_you_do_not_operate_out_of.yml 与 aws_cloudtrail_console_login_success_from_susp_locations.yml）；%Approved_Inviters%（受邀人白名单，见 azure_ad_guest_users_invited_to_tenant_by_non_approved_inviters.yml）；%legtimate_identifiers%（可信身份标识，见 okta_session_impersonation_granted.yml）；%userdomain%（环境变量字符串，见 proc_creation_win_userdomain_variable_enumeration.yml）。
2. 选择合适的转换类型。对照上文六种转换：路径类用command_placeholders/file_placeholders，URL 类用http_placeholders，标量值用value_placeholders，带通配的域名/路径用wildcard_placeholders。
3. 用|expand标记占位符字段。按实例一至四的写法组织selection与filter_main_*，注意占位符规则在 condition 中通常要求"排除过滤为主"，即selection and not 1 of filter_main_*。
4. 通过 pySigma 转换后部署。占位符只有在经过对应 pySigma transformation 处理后才会被真实值替换，因此生产链路必须包含转换步骤；未配置转换器时，%xxx%会被当作字面量参与匹配，导致规则不可用。
最佳实践与注意事项
结合仓库规则的实际写法，可以提炼出以下实践要点：
- 过滤器命名规范：仓库统一采用
filter_main_*（主过滤）与filter_optional_*（可选过滤）前缀，并用not 1 of/not 1 of filter_optional_*语法区分。占位符过滤器应放入filter_main_*，因为它们是规则正确性的一部分；filter_optional_*留给可选的已知信任域（参见 dns_query_win_wscript_cscript_resolution.yml 中的filter_optional_trusted_domains）。 - 占位符内联注释：仓库规则几乎都为每个占位符附上了注释，说明应填入什么值，例如
# Add legitimate countries here、# Your trusted domain goes here。这既是给使用者的提示，也是良好的文档习惯。 - 默认值留空而非硬编码猜测：占位符规则刻意不做默认值假设——作者不知道你的域控列表，胡乱猜测反而有害。部署时务必把全部
%...%值替换完再做验证。 - 警惕"占位符即规则"的失效模式：像 net_connection_win_certsvc_outbound_smb_ldap.yml 这类高价值但高环境依赖的规则，误报率完全由占位符质量决定，建议先在模拟环境用历史日志回放验证。
参考资料
- 占位符的权威规范定义见 Sigma 规范文档中的 Placeholders 章节（Sigma Specification - Placeholders）；
- Sigma 官方博客《Building Flexible Detections with Sigma Placeholders》系统阐述了占位符的设计思路与使用方式；
- pySigma 仓库的 sigma/processing/transformations/init.py 维护着完整的最新转换清单；
- 仓库内全部可参考的占位符规则实例位于 rules-placeholder 目录，覆盖 cloud（AWS/Azure）、identity（Okta）、windows（builtin/dns_query/network_connection/process_creation）多个产品线，是学习和二次开发的最佳语料。
【免费下载链接】sigmaMain Sigma Rule Repository项目地址: https://gitcode.com/GitHub_Trending/si/sigma
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
