Checkmarx默认查询规则能够覆盖大量常见安全问题，但在实际项目中，企业通常还需要针对内部编码规范、特殊业务逻辑以及自定义安全要求增加检测能力。自定义查询可以补充默认规则无法覆盖的场景，但由于它涉及查询编写、规则加载、代码解析和扫描配置多个环节，出现“规则已经创建但扫描没有结果”的情况并不少见。围绕“Checkmarx怎么配置自定义查询规则，Checkmarx自定义规则没有触发如何检查”，关键是确认规则是否真正进入扫描流程，并判断问题发生在哪个阶段。

　　一、Checkmarx怎么配置自定义查询规则

　　Checkmarx SAST中的自定义查询主要基于CxQL实现，通过查询逻辑描述需要发现的代码模式。一个完整的自定义规则不仅包括检测逻辑，还需要正确配置语言类型、风险等级以及所属查询集合，否则即使规则本身正确，也可能无法参与实际扫描。

　　1、创建自定义CxQL查询

　　①进入Checkmarx管理后台的查询管理区域，新建【Custom Query】。

　　②根据目标代码语言选择对应查询类型，例如Java、C/C++、C#等。

　　③编写CxQL查询逻辑，定义需要匹配的代码行为。

　　④设置查询名称、描述和所属类别。

　　⑤保存后检查查询是否通过语法校验。

　　编写规则前，需要先明确检测目标：

　　检测危险函数调用；

　　检测输入数据是否流向敏感接口；

　　检测违反内部开发规范的代码模式；

　　检测特定框架中的错误使用方式。

　　如果检测目标不明确，后续很容易出现规则过宽导致误报，或者条件过严导致完全没有结果。

　　2、配置查询风险属性

　　创建查询后，需要补充规则在扫描结果中的展示信息。

　　①设置【Severity】确定漏洞风险等级。

　　②配置查询所属【Query Group】。

　　③根据项目管理方式加入对应【Query Pack】。

　　④添加规则说明，方便开发人员理解漏洞原因。

　　⑤保存并确认查询状态为启用。

　　需要注意，风险等级只影响结果展示和风险统计，不会影响规则是否能够匹配代码。因此排查规则不触发时，应优先检查查询是否执行，而不是修改Severity。

　　3、将规则加入扫描配置

　　很多自定义规则不生效，并不是CxQL编写错误，而是扫描任务根本没有加载该规则。

　　①打开项目使用的【Scan Configuration】。

　　②检查当前配置关联的Query Pack。

　　③确认自定义查询已经加入该Query Pack。

　　④检查执行扫描时使用的配置是否与修改后的配置一致。

　　⑤重新启动一次完整扫描。

　　如果规则只存在于查询库中，但没有被扫描配置引用，那么Checkmarx不会执行该查询。

　　二、Checkmarx自定义规则没有触发如何检查

　　自定义规则没有触发时，需要按照扫描流程逐层排查。不要直接修改CxQL，因为问题可能发生在规则加载之前，也可能是代码本身没有满足匹配条件。

　　1、确认扫描是否加载了自定义查询

　　①查看扫描日志，确认是否包含自定义Query名称。

　　②检查扫描使用的Query Pack是否为最新版本。

　　③确认当前项目没有绑定其他扫描策略。

　　④对比一次默认规则和自定义规则的执行情况。

　　⑤如果日志中完全没有出现该规则信息，应优先检查扫描配置。

　　如果规则没有进入扫描阶段，继续调整查询语句不会产生任何效果。

　　2、使用最小代码验证规则逻辑

　　自定义规则调试时，建议不要直接使用大型业务项目验证，因为复杂调用链会增加判断难度。

　　①创建一个简单测试文件。

　　②编写一段明确符合规则条件的代码。

　　③执行一次扫描观察是否产生结果。

　　④如果测试代码能够触发，再回到真实项目检查代码差异。

　　⑤如果测试代码也无法触发，重点检查CxQL逻辑。

　　例如规则检测某个危险API调用：

　　测试代码直接调用该API可以触发；

　　业务代码经过多层封装无法触发；

　　这说明问题可能来自数据流分析路径，而不是规则失效。

　　3、检查CxQL匹配条件

　　CxQL规则通常包含函数匹配、类型判断、数据流传播等条件，任何一个条件不满足，都可能导致结果为空。

　　①检查目标函数名称是否完全一致。

　　②检查类路径、命名空间是否符合实际源码。

　　③检查参数类型是否匹配。

　　④检查数据来源和数据传播路径是否能够被Checkmarx识别。

　　⑤删除部分限制条件进行逐步验证。

　　对于数据流类型规则，需要特别注意：

　　Source是否定义正确；

　　Sink是否匹配目标函数；

　　中间传播路径是否存在；

　　Sanitizer是否错误过滤了结果。

　　4、确认源码和扫描范围正确

　　有些规则没有结果，是因为扫描内容根本不包含目标代码。

　　①检查上传源码是否为最新版本。

　　②确认目标文件扩展名属于扫描语言范围。

　　③检查是否配置了文件排除规则。

　　④确认目标模块已经包含在项目扫描范围内。

　　⑤对比本地源码和Checkmarx上传内容。

　　尤其是在CI环境中，如果扫描使用的是构建目录或临时目录，很容易出现扫描版本与开发代码不一致的问题。

　　三、如何系统验证自定义规则是否真正有效

　　自定义查询规则能够触发并不代表规则已经达到可用状态。在实际项目中，更需要关注规则是否能够稳定发现目标问题，同时避免产生大量无意义结果。因此，规则验证应同时覆盖“发现能力”和“适用范围”，确保它能够长期用于持续安全检测。

　　1、通过正反向样例验证规则准确性

　　①准备一组明确符合规则条件的代码样例，确认规则能够产生预期结果。

　　②准备不会触发规则的正常代码，检查是否出现误报。

　　③对比不同代码写法下的扫描结果，确认规则匹配的是安全风险本身，而不是某种固定代码形式。

　　④对于涉及数据流传播的查询，增加不同调用层级的测试，验证规则是否能够覆盖真实项目中的调用方式。

　　⑤将验证样例保留下来，作为后续修改规则时的回归测试依据。

　　如果一个自定义规则只能在非常简单的测试代码中触发，而无法覆盖实际业务中的常见写法，通常说明查询逻辑仍需要优化，而不是直接投入生产使用。

　　2、根据实际项目反馈调整规则范围

　　①当规则长期没有触发时，重新检查检测目标是否真实存在于当前代码体系中。

　　②当误报数量过多时，分析误报产生的位置，增加必要限制条件。

　　③当漏报明显时，检查是否遗漏了新的框架调用方式、封装函数或数据传播路径。

　　④对高风险规则保持较严格的检测范围，对规范类规则则重点关注开发体验。

　　⑤定期结合安全事件和代码变化更新规则逻辑。

　　自定义查询的目标不是产生尽可能多的问题，而是在安全覆盖范围和结果有效性之间取得平衡。只有开发人员能够理解并接受扫描结果，规则才能真正融入日常开发流程。

　　总结

　　Checkmarx自定义查询规则的意义，并不只是增加一批新的扫描项，而是让安全检测能力能够贴合企业自身的软件开发特点。一个有效的规则，需要同时具备明确的安全目标、稳定的检测能力以及可维护性。面对规则未触发的问题，重点不是反复修改查询代码，而是判断检测链路中哪个环节没有达到预期。通过持续验证和优化，自定义规则才能从一次性的安全配置，逐渐成为可靠的软件安全保障机制。希望本文对大家理解Checkmarx自定义规则配置与维护有所帮助，如需进一步了解Checkmarx CxQL规则开发与规则异常排查方法，欢迎联系咨询。