SpiderFoot 添加关联规则后启动即中止报错怎么排查是哪个 YAML 规则无效【免费下载链接】spiderfootSpiderFoot automates OSINT for threat intelligence and mapping your attack surface.项目地址: https://gitcode.com/GitHub_Trending/sp/spiderfoot在 SpiderFoot 4.0 中如果你按 correlations/README.md 的说明在correlations/目录下添加了一个自定义关联规则YAML 文件却发现 SpiderFoot 启动时直接中止终端打出 CRITICAL 级别报错后进程退出就需要先定位到底是哪一个 YAML 规则无效否则任何入口扫描、Web UI、-C关联都跑不起来。correlations/README.md 明确说明了这一行为规则如果存在语法错误SpiderFoot 会在启动时中止abort at startup并希望能给你足够的信息让你知道错误在哪里。下面给出基于源码实际行为的排查路径。启动报错时你会看到什么SpiderFoot 的所有入口sf.py 命令行、sfwebui.py Web 界面在启动时都会完成同一件事读取安装路径下correlations/目录里每一个.yaml文件并对整套规则做语法校验。这一步在 sf.py 中的顺序是SpiderFootHelpers.loadCorrelationRulesRaw 遍历correlations/目录只跳过template.yaml它作为模板被显式忽略其余.yaml文件一律以文件名去掉扩展名作为规则 ID 读入内存。把这套原始规则交给 SpiderFootCorrelator 初始化。任何一个环节出错sf.py 都会打出 CRITICAL 日志并以退出码 -1 终止目录读取阶段失败Failed to load correlation rules: ...校验阶段失败Failure initializing correlation rules: ...所以你的第一步就是完整保留这段 CRITICAL 输出和它后面的异常堆栈它是后续定位的主要线索。从报错信息直接读出是哪个规则SpiderFootCorrelator 的init对每条规则单独做yaml.safe_load并逐条打印Parsing rule {rule_id}...的 debug 日志。YAML 解析失败时抛出的是SyntaxError: Unable to process a YAML correlation rule [{rule_id}]其中{rule_id}就是出问题的文件名去掉.yaml的部分见 helpers.pyruleName filename.split(.)[0]。例如报错为Unable to process a YAML correlation rule [my_new_rule]那么无效文件就是correlations/my_new_rule.yaml。这条信息对应的是纯 YAML 语法错误——缩进错误、引号不闭合、重复 key 等。另一类失败走不同的提示当 YAML 本身能解析、但规则内容不符合 SpiderFoot 的结构约定时check_ruleset_validity校验不通过最终抛出SyntaxError: Sanity check of correlation rules failed.这类报错不会直接带上文件名需要靠下面一节的日志或隔离法定位。无论哪类报错建议先开启 debug 输出再启动一次让Parsing rule ...这类逐条解析日志可见python3 ./sf.py -d -M-M--modules会在模块与规则加载成功后直接列出可用模块并退出sf.py因此它是一个不用真正发起扫描就能触发完整规则加载流程的触发方式规则无效时它同样会中止。启动正常时你会看到Modules available:列表启动失败时对照 correlations/README.md 中 debug 日志停在哪个Parsing rule {rule_id}之后也能缩小范围。用日志定位 Sanity check 失败的具体原因YAML 语法能通过、但结构校验失败时check_rule_validity 会先打印带规则 ID 的 ERROR 日志再返回失败常见形式包括Rule has no ID.—— 文件缺少id字段。Mandatory rule component, {f}, not found in {rule_id}.—— 缺少meta、collections或headline三个必选组件之一mandatory_components定义见 correlation.py。Unexpected field(s) in correlation rule {rule_id}: [...]—— 出现了 correlation.py 组件表之外的顶层字段拼错顶层 key 名时会落到这里。Invalid collection method: .../Invalid collection field: ...——collect里的method不是exact/regex或field不在type、module、data及child./source./entity.前缀变体之中。Unknown analysis method ... defined for {rule_id}.——analysis的method不在threshold、outlier、first_collection_only、both_collections、match_all_to_first_collection之内。Required field for {field} missing in {rule_id}, item {item}: {opt}—— 例如meta缺少name/description/risk中的某一项。所以加-d启动在 CRITICAL 行之前找spiderfoot.correlator打出的 ERROR 行里面的{rule_id}和组件名基本就是修改入口。二分隔离法不确定时逐个排除如果报错信息不足以指认文件例如你一次性放入了多个规则文件用隔离法收敛范围把correlations/里除template.yaml外、你自己新增或修改过的.yaml文件临时移出该目录例如挪到仓库外的一个备份目录。注意只移动、不要删除文件loadCorrelationRulesRaw只忽略template.yaml目录里任何.yaml都会被加载sf.py。用触发完整加载的流程启动一次如python3 ./sf.py -d -M确认恢复为正常启动。每放回一个规则文件就再启动一次第一次触发 CRITICAL 中止时放回去的那个文件就是无效规则。定位后对文件做修改再按上文从报错信息直接读出是哪个规则一节的方式复查。这一步没有额外的工具依赖整个加载过程只发生在进程启动阶段且中止是确定性的适合做反复试验。修完规则后如何确认已经恢复正常规则文件按 correlations/README.md 的要求保存后重启 SpiderFoot 才会被加载所以每次修改后都要重新启动进程。确认恢复正常的方式用python3 ./sf.py -d -M启动若能走到Modules available:列表输出说明全部.yaml规则已通过yaml.safe_load和check_ruleset_validity两道检查sf.py 中规则校验不通过会在此前以 -1 退出。若要确认你的规则真正参与关联可以对一个已完成的扫描运行run_correlations对处于 RUNNING/STARTING/STARTED 的扫描会抛出 ValueError见 correlation.pypython3 ./sf.py -C scanID其中scanID替换为你自己的扫描实例 ID。正常时会先打印Running N correlation rules against scan, scanID.之后每条命中规则的日志形如Rule {rule_id} returned N results.correlation.py。另外提醒一点边界correlations/README.md 说明关联规则只分析扫描数据、不从目标采集数据所以规则加载成功但没有结果不等于故障可能是该扫描结果中没有命中规则的数据。写作自定义规则时最容易触发中止的几处对照 correlations/template.yaml 和 Rule Reference自定义文件里最常被写坏的点id必须与文件名一致不含.yaml扩展名且不含空格等特殊字符version目前必须是1顶层只允许id、version、meta、collections、aggregation、analysis、headline以及内部的enabled、rawYaml多余顶层字段会直接触发Unexpected field(s)meta必须同时提供name、description、riskrisk取INFO/LOW/MEDIUM/HIGH每个collect的第一个method是从数据库取数的条件后续method才是本地细化第一个匹配块也不能用source./child./entity.前缀字段。按 correlations/README.md 的建议动手前先通读template.yaml和现有规则如multiple_malicious.yaml、data_from_docmeta.yaml展示了前缀字段的用法作为参照能显著减少进入启动即中止这类问题的概率。小结排查链条固定为三步保留启动时的 CRITICAL 输出与堆栈 → 用-d启动并读Unable to process a YAML correlation rule [id]或 correlator 的 ERROR 行确定规则 ID → 不确定时用移出/放回 YAML 文件 重复触发加载的二分法收敛。规则 ID 对应correlations/下同名文件修改后重启验证python3 ./sf.py -d -M能走完模块列表输出即为规则集恢复正常。【免费下载链接】spiderfootSpiderFoot automates OSINT for threat intelligence and mapping your attack surface.项目地址: https://gitcode.com/GitHub_Trending/sp/spiderfoot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考