很多团队在Checkmarx里加了自定义规则后，扫描结果却毫无变化，或者CI里一会儿能命中一会儿不命中；另一类常见现象是升级或打了内容包后，预置规则集变了，项目突然出现查询为空、规则列表空白、命中数量异常波动。要把问题一次定位清楚，建议把排查顺序固定成两条线：先确认自定义规则到底有没有被“加载并启用”，再确认扫描时有没有“按正确的规则包与预置集执行”。

　　一、Checkmarx自定义规则不生效怎么办

　　自定义规则不生效，最常见不是规则写错，而是规则存在但没有进到扫描链路里，或者被错误的层级覆盖掉了。按下面顺序排，基本能把原因缩到一两处。

　　1、先确认你用的是CxSAST门户还是Checkmarx One

　　在CxSAST门户里，自定义规则通常以导入查询XML与配置Preset为主，入口集中在【Settings】下的查询与Preset管理界面。

　　在Checkmarx One里，更常见的做法是用Query Editor做租户级、应用级或项目级的Override，然后在Query Editor里直接运行验证。

　　2、CxSAST门户里确认查询已导入且能在Query Viewer里看到

　　依次进入【Settings】→【Scan Settings】→【Query Viewer】，在左侧Queries列表里搜索你的自定义查询名，确保它确实出现在Queries树里。

　　如果查不到，直接在【Query Viewer】里点击【Import Queries】，选择你的查询XML导入，导入后再回到Queries树里二次确认。

　　3、把自定义查询加入Preset并确保项目扫描时选的就是这个Preset

　　仅仅导入查询还不够，扫描是否执行取决于Preset是否包含该查询。进入【Settings】→【Scan Settings】→【Preset Manager】，点击【Create New Preset】新建或编辑既有Preset，先选代码语言，再在查询列表里勾选你的自定义查询，最后点【Save】保存。

　　回到项目配置页面，检查该项目扫描时选择的Preset名称是否就是你刚保存的那个，很多“不生效”其实是项目仍在用旧Preset或默认Preset。

　　4、用最小验证法判断是规则没跑还是规则跑了但没产出结果

　　在CxSAST里先挑一个你确信会触发该规则的最小样例代码，单独建一个测试项目，Preset只勾这一条自定义查询与必要的语言基础查询，跑一次扫描看是否命中。这样能快速排除“业务代码没覆盖到触发路径”“扫描范围被排除”“语言识别不一致”等干扰项。

　　如果测试项目能命中，回到真实项目重点查扫描范围与排除规则、源码打包内容是否完整、以及CI里是否覆盖了同一Preset参数。

　　5、Checkmarx One里用Query Editor直接运行与Override层级核对

　　在Checkmarx One里，进入左侧【Scan Management】后打开【Query Editor】，或在项目的SAST区域通过菜单进入【Audit Scan】打开对应项目的Query Editor会话，然后用运行按钮直接Run Query，看Results里是否产出漏洞。

　　如果你做了Override，务必确认Override施加的层级：租户级Override会影响该租户下所有应用与项目；项目级Override只影响单个项目。层级放错会出现你以为改了规则但实际扫描仍在跑旧规则的情况。

　　二、Checkmarx规则包加载怎么检查

　　规则包是否正确加载，决定了查询库版本与预置集内容是否符合预期，尤其在升级、安装内容包或引擎包后，这是必须先做的核对动作。

　　1、在CxSAST门户里查看已安装的Checkmarx Queries Pack版本

　　进入【Management】→【Application Settings】→【Installation Information】，找到【Checkmarx Queries Pack】条目，记录显示的版本号，用它来对照你期望的内容包或升级目标版本。

　　如果团队近期做过内容包安装，建议把版本号截图留档，方便回溯“命中变化”到底来自规则库更新还是配置改动。

　　2、在扫描日志里核对CHECKMARX_QUERIES_PACK标记

　　下载或打开一次扫描的日志，在配置标记里查找CHECKMARX_QUERIES_PACK字段，它会直接标出本次扫描加载的Queries Pack版本。

　　这一招对CI场景特别有用，因为它能区分“门户里看着是新版本”与“流水线实际跑的还是旧引擎或旧规则库”的差异。

　　3、遇到Preset查询列表空白或提示无查询时优先怀疑规则包与Preset被重置

　　内容包更新会带来查询与Preset的变化，并且可能把内置Preset重置回默认查询集，导致你原来依赖的规则选择集发生改变。

　　一旦发现Preset里右侧查询列表为空、扫描提示无查询或命中突然归零，先回到【Preset Manager】确认Preset是否还包含查询，再核对Queries Pack版本是否匹配当前CxSAST版本与热修要求。

　　三、Checkmarx自定义规则与规则包版本如何对齐

　　自定义规则要长期稳定生效，关键是把“规则内容”“启用方式”“升级后的回归检查”三件事固化下来，避免每次升级都靠猜。

　　1、用自建Preset承载自定义查询并定期导出备份

　　不要把自定义查询长期依赖在内置Preset上，优先建一个团队自用Preset来承载自定义查询与必要的官方查询组合；每次大版本升级或内容包更新前，在【Scan Settings】里把Preset导出为XML备份，更新后再对照导入验证，避免被重置后悄悄丢查询。

　　2、避免同名覆盖造成你改的是A实际跑的是B

　　导入Preset或查询时，如果名称与现有查询同名，系统可能发生覆盖，结果是你以为在跑新规则，实际跑的是被覆盖后的另一份。导入前先统一命名规范，例如在查询名前加团队前缀，在Preset名里包含语言与用途。

　　3、升级或安装内容包后做一次固定的回归核对

　　更新完成后按固定清单走一遍：先看【Installation Information】里的Queries Pack版本，再从最新一次扫描日志里核对CHECKMARX_QUERIES_PACK版本，最后打开【Query Viewer】确认自定义查询仍在Queries树里且Preset仍勾选。

　　4、把验证样例沉淀成一份最小触发仓库

　　为每条关键自定义规则准备一段最小触发代码，放在专门的验证仓库里，升级后只跑这个仓库一次就能确认规则是否还会命中；这样比在大项目里盲找命中点更省时间，也更容易把问题定位到规则库变化还是项目配置变化。

　　总结

　　自定义规则不生效时，优先按“查询是否存在、是否进Preset、项目是否用对Preset或Override层级、最小样例是否能命中”这条链路排；规则包加载则用门户里的Queries Pack版本与扫描日志里的CHECKMARX_QUERIES_PACK双重核对，并把升级后的Preset重置风险纳入回归清单里，基本就能把Checkmarx规则相关的异常稳定住。