SpiderFoot 关联规则Correlations完全指南从 YAML 规则编写到 OSINT 分析自动化【免费下载链接】spiderfootSpiderFoot automates OSINT for threat intelligence and mapping your attack surface.项目地址: https://gitcode.com/GitHub_Trending/sp/spiderfootSpiderFoot 作为自动化 OSINT 侦察与攻击面测绘工具其数据收集能力极为强大但如何从海量扫描结果中自动筛选出真正值得关注的线索一直是用户的痛点。本文以 correlations/README.md 为骨架结合 spiderfoot/correlation.py 等源码实现系统讲解 SpiderFoot 4.0 引入的 Correlations关联规则机制——从规则结构、YAML 语法、六大内置分析器到child./source./entity.字段前缀你将掌握如何编写、调试并部署自己的关联规则让扫描结果自动开口说话。背景为什么 SpiderFoot 需要 CorrelationsSpiderFoot 的核心目标是尽可能自动化地完成 OSINT 收集与分析。从项目诞生起SpiderFoot 就专注于自动化数据收集与实体提取但常规分析任务——除了一些报表与可视化之外——几乎完全交给用户手工完成。正如 correlations/README.md 所述这意味着数据收集能力的强大有时反而成了短板面对如此多的数据用户常常需要把结果导出到其他工具中去剔除真正感兴趣的数据。2019 年推出的 SpiderFoot HX 通过引入Correlations关联规则功能填补了这一分析空白约 30 条关联规则随每次扫描运行对数据进行分析并呈现 SpiderFoot 对什么可能重要或有趣的观点。典型规则包括被多个数据源标记为恶意的主机/IP离群 Web 服务器可能是影子 IT 的迹象暴露在公网上的数据库开放端口泄露的软件版本以及更多其他规则。SpiderFoot 4.0 将这一能力从 HX 带到社区版并重新设计社区成员不仅能运行官方提供的规则还能编写自己的关联规则并回馈项目。这意味着规则机制的设计目标就是像模块modules一样形成长期贡献生态。核心概念规则的本质与结构为什么选择 YAML规则本身使用 YAML 编写。选型理由见 correlations/README.md易读、易写、支持注释且在现代工具中越来越普及。规则结构最简单的理解方式一条 SpiderFoot 关联规则就像一条数据库查询由几个部分组成定义规则本身id、version和meta段声明要从扫描结果中提取什么collections段对数据分组aggregation段可选对数据进行分析analysis段可选呈现结果headline段。注意id、version、meta、collections、headline是强制组件。这一点在源码 spiderfoot/correlation.py 中有明确体现mandatory_components [meta, collections, headline]校验逻辑位于check_rule_validity()方法中。示例规则逐行解读下面这条规则对应仓库中的 correlations/open_port_version.yaml用于发现开放 TCP 端口的 banner连接端口时返回的数据中泄露软件版本的情况。它通过对TCP_PORT_OPEN_BANNER数据元素的 content 应用正则、过滤误报、再按 banner 分组最终为每个泄露版本的 banner 生成一条关联结果id: open_port_version version: 1 meta: name: Open TCP port reveals version description: A possible software version has been revealed on an open port. Such information may reveal the use of old/unpatched software used by the target. risk: INFO collections: - collect: - method: exact field: type value: TCP_PORT_OPEN_BANNER - method: regex field: data value: .*[0-9]\.[0-9].* - method: regex field: data value: not .*Mime-Version.* - method: regex field: data value: not .*HTTP/1.* aggregation: field: data headline: Software version revealed on open port: {data}逐段解析第一个method块exact/type/TCP_PORT_OPEN_BANNER从数据库拉取所有类型为TCP_PORT_OPEN_BANNER的数据元素。这是唯一真正查询数据库的步骤后续所有method块都只对已取回的数据做内存中过滤以避免加重数据库负担对应源码 spiderfoot/correlation.py 中collect_events()的实现逻辑。第二个method块regex/data/.*[0-9]\.[0-9].*只保留 data 字段匹配数字.数字模式即疑似版本号的元素。第三、四个method块利用not前缀做正则否定排除Mime-Version与HTTP/1.*等误报源。aggregation.field: data按 banner 文本分组同一 banner 归为一个桶从而每条 banner 只生成一条结果。headline用{data}占位符把分组字段值嵌入标题。运行结果演示在真实目标上运行一个只做 DNS 解析与端口扫描的扫描- # python3.9 ./sf.py -s www.binarypool.com -m sfp_dnsresolve,sfp_portscan_tcp 2022-04-06 08:14:58,476 [INFO] sflib : Scan [94EB5F0B] for www.binarypool.com initiated. ... sfp_portscan_tcp Open TCP Port Banner SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.10 ... 2022-04-06 08:15:23,110 [INFO] correlation : New correlation [open_port_version]: Software version revealed on open port: SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.10 2022-04-06 08:15:23,244 [INFO] sflib : Scan [94EB5F0B] completed.可以看到sfp_portscan_tcp模块发现了一个开放端口其 banner 恰好包含版本信息规则open_port_version随即捕获并报告了它日志中New correlation [open_port_version]即由 spiderfoot/correlation.py 的create_correlation()打印。这类结果也会显示在 Web 界面中。重要提示规则只有在扫描结果中确实存在相关数据时才会成功触发。换言之关联规则分析的是扫描数据它本身不收集目标数据——先要有模块产生事件规则才能从中提炼结论。工作原理从 YAML 到数据库查询从源码结构看SpiderFoot 的关联引擎由 spiderfoot/correlation.py 中的SpiderFootCorrelator类实现其执行流水线如下规则加载与语法校验__init__()通过yaml.safe_load解析每个规则的原始 YAML并调用check_ruleset_validity()/check_rule_validity()做字段级校验强制组件、合法字段、合法方法等。语法错误会抛出SyntaxError并中止启动——这正是文档所说SpiderFoot 会在启动时中止并给出错误位置的实现基础。构建数据库查询build_db_criteria()将每个collect中的第一个method块翻译成SpiderFootDb.scanResultEvent()的查询参数按type、module或data匹配type支持正则展开。注意源码中有三条硬性约束第一个method的字段必须是data、type或module不允许带前缀第一个method不能在data字段上用regex按module收集时不支持regex。内存内过滤后续method块通过refine_collection()/event_keep()就地剔除不匹配的事件支持exact与regex两种匹配、not前缀取反、re.IGNORECASE忽略大小写见 spiderfoot/correlation.py。聚合aggregate_events()按指定字段把事件分桶。分析analyze_events()按method分发到analysis_threshold、analysis_outlier、analysis_first_collection_only、analysis_match_all_to_first_collection等实现。落库create_correlation()调用SpiderFootDb.correlationResultCreate()写入数据库。扫描结束时sfscan.py 的runCorrelations()方法会从配置中取出所有规则__correlationrules__构建ruleset字典并调用SpiderFootCorrelator(...).run_correlations()。run_correlations()还会拒绝在运行中的扫描上执行关联见 spiderfoot/correlation.py因此规则通常在扫描完成后统一运行。结果如何存储关联结果写入 SQLite 数据库的两张表表结构定义于 spiderfoot/db.pytbl_scan_correlation_results保存关联结果本身字段包括id、scan_instance_id、title、rule_name、rule_descr、rule_risk、rule_id、rule_logic即原始规则 YAML。创建逻辑见 spiderfoot/db.py。tbl_scan_correlation_results_events把事件数据元素哈希映射到关联结果用于追溯这条结论由哪些数据元素支撑。这些结果可以在 SpiderFoot Web 界面、CLI 中查看也可以直接从 SQLite 数据库查询scanCorrelationSummary()/scanCorrelationList()封装了按规则或按风险分组的聚合查询见 spiderfoot/db.py。内置规则一览每条规则是 SpiderFoot 安装路径下correlations/文件夹中的一个 YAML 文件。SpiderFoot 4.0 自带的规则清单当前仓库 correlations/ 目录与之对应且已扩展更多规则cert_expired.yaml host_only_from_certificatetransparency.yaml outlier_ipaddress.yaml cloud_bucket_open.yaml http_errors.yaml outlier_registrar.yaml cloud_bucket_open_related.yaml human_name_in_whois.yaml outlier_webserver.yaml data_from_base64.yaml internal_host.yaml remote_desktop_exposed.yaml data_from_docmeta.yaml multiple_malicious.yaml root_path_needs_auth.yaml database_exposed.yaml multiple_malicious_affiliate.yaml stale_host.yaml dev_or_test_system.yaml multiple_malicious_cohost.yaml strong_affiliate_certs.yaml dns_zone_transfer_possible.yaml name_only_from_pasteleak_site.yaml strong_similardomain_crossref.yaml egress_ip_from_wikipedia.yaml open_port_version.yaml template.yaml email_in_multiple_breaches.yaml outlier_cloud.yaml vulnerability_critical.yaml email_in_whois.yaml outlier_country.yaml vulnerability_high.yaml email_only_from_pasteleak_site.yaml outlier_email.yaml vulnerability_mediumlow.yaml host_only_from_bruteforce.yaml outlier_hostname.yaml官方期望这份清单随社区贡献持续增长——就像模块生态一样。template.yaml是空规则模板*.yaml则是可直接参考的实战范例。规则组件详解Meta描述规则本身让人类理解规则做什么、结果的风险级别如何。这些信息主要用于 Web 界面和 CLI 展示。包含name简短可读名称、description可多段的长描述与risk结果风险级别。源码还允许可选的author与url字段见 spiderfoot/correlation.py。Collections收集一个 collection 代表从扫描结果中拉取的一组数据供后续聚合与分析阶段使用。每条规则可以有多个 collection。Aggregations聚合把收集到的数据按分组字段装进桶bucket以便按不同的数据元素组进行分析。聚合只做一件事遍历每个 collection 中的数据元素按field指定的字段分组。例如按type分组所有相同type的元素会聚在一起。分组的目的有二支撑分析阶段若没有分析阶段则决定关联结果如何向用户分组展示。Analysis分析对数据执行分析把最终要报告的数据元素精炼出来。例如分析阶段可能只关注某个数据字段在数据集中重复出现多次的情况从而丢弃只出现一次的元素。Headline标题代表关联结果的标题概括发现了什么。可以类比为菜名如牛肉炖菜而所有数据元素就是食材牛肉、番茄、洋葱等。要把数据中的字段值嵌入标题必须用{}包裹字段名如{entity.data}。编写你自己的关联规则创建自定义规则非常简单复制 correlations/template.yaml 到与你的id相匹配的有意义文件名例如aws_cloud_usage.yaml编辑规则内容以适配你的需求保存后重启 SpiderFoot使规则生效。如果存在语法错误SpiderFoot 会在启动时中止并但愿给出足够的信息定位错误位置。template.yaml本身也是理解规则结构的最佳参考。以模板内容为例节选id: set_a_meaningful_id_here version: 1 meta: name: This is a briefly descriptive name. description: This is a more detailed description about the rule and ideally includes some rationale explaining the risk posed... risk: MEDIUM collections: - collect: - method: exact field: type value: INTERNET_NAME - method: regex field: data value: - .*foo.* - .*bar.* aggregation: field: data analysis: - method: threshold minimum: 2 field: data headline: A foo or bar host was found more than once: {data}模板揭示了几个关键约定id必须与文件名不含.yaml后缀一致且不含空格等特殊字符version目前固定为1risk可取INFO、LOW、MEDIUM、HIGH模板注释更细化了语义HIGH保留给需要立即行动的真实案例MEDIUM是潜在高风险需深入检查LOW是低风险或可能是误报INFO是无风险但可能有趣的信息regex的value可以是列表多个正则任一命中即保留模板规则的效果找出所有匹配foo或bar的主机且同一主机出现至少 2 次时生成一条关联结果。模板中的risk: MEDIUM与threshold: minimum 2正好呼应文档 Creating a rule 一节也是理解analysis.threshold用法的直接范例。Rule Reference完整参数参考顶层字段id规则内部 ID必须与文件名匹配。version规则语法版本目前必须是1。enabled从源码组件表可见spiderfoot/correlation.py规则还支持enabled字段用于启停控制。metaname简短的人类可读名称。description较长可多段的描述。risk该规则发现结果的风险级别可取INFO、LOW、MEDIUM、HIGH。collections/collect/method一条规则包含一个或多个collect块每个collect块包含一个或多个method块collect技术上每个collect块中第一个method块负责真正从数据库拉取数据后续每个method逐步把数据集精炼到你所寻求的目标。你可以有多个collect块但规则不变在每个collect内第一个method从数据库取数后续method做细化。method告诉 SpiderFoot 如何收集与细化数据。每个collect至少需要一个method。合法值为exact对所选field与提供的value做精确匹配和regex正则表达式匹配。field执行匹配所依据的字段。合法字段为type如INTERNET_NAME、module如sfp_whois和data数据元素的值例如INTERNET_NAME的data就是主机名。在第一个method之后还可以给字段加source.、child.或entity.前缀分别指代被收集数据的来源、子节点与相关实体参见 correlations/multiple_malicious.yaml 与 correlations/data_from_docmeta.yaml 的实际用法。源码校验的白名单为type/module/data及其带child.、source.、entity.前缀的九种组合spiderfoot/correlation.py。value要与field匹配的值或值列表。若method是regex则为正则表达式。aggregation所有数据元素进入各自的 collection 后可以聚合为桶以进一步分析或直接生成规则结果。收集阶段关注从数据库取数并过滤出目标数据聚合阶段则关注以不同方式分组以支撑分析或分组展示结果。field定义数据元素的分组方式。与method中的field一样可以加source.、child.、entity.前缀。例如若要查找同一主机名出现多次的情况应在此指定data因为你要统计data字段值出现的次数。analysis分析段对聚合结果若未聚合则直接对 collection施加分析逻辑不满足条件的候选结果会被丢弃。多种method类型各有不同选项threshold阈值丢弃未达到定义阈值的 collection/聚合组。用于仅当某数据元素出现超过或低于某次数时才生成结果的场景例如报告某个邮箱只出现一次、或出现超过 100 次。field应用阈值的字段同样支持child.、source.、entity.前缀count_unique_only默认对指定字段的所有数据元素计数设为true时只对唯一值计数排除重复minimumcollection/聚合组内必须出现的最少数据元素数maximumcollection/聚合组内允许的最多数据元素数。源码实现analysis_thresholdspiderfoot/correlation.py不满足minimum count maximum的桶会被删除count_unique_only为真时按桶内唯一值数量判断。outlier离群只保留 collection/聚合组中的离群值。maximum_percent某个聚合组可占总体结果的最大百分比。此方法要求先对某字段做聚合。例如按data字段聚合后若某个桶占总体比例不足 10%就会被报告为离群。noisy_percent默认10。若所有桶的平均占比低于 10%说明数据集本身异常不报告离群。源码实现analysis_outlierspiderfoot/correlation.py先计算各桶占比若平均占比低于noisy_percent默认 10则清空所有桶否则删除占比超过maximum_percent的桶留下离群桶。first_collection_only仅第一集合只保留出现在第一个 collection、但未出现在其他 collection 中的数据元素。例如用于找出从某个或某几个数据源发现、但其他数据源没有发现的数据。field用于在 collection 之间查重的字段。实战范例correlations/email_only_from_pasteleak_site.yaml 用两个 collection 分别收集来源为LEAKSITE_CONTENT的邮箱与来源不是LEAKSITE_CONTENT的邮箱再用first_collection_only只保留只在泄露站点出现的邮箱。match_all_to_first_collection全部匹配第一集合只保留以某种方式与第一个 collection 匹配上的数据元素。此方法要求先做聚合因为用于匹配的字段就是聚合字段。match_method所有 collection 与第一个 collection 的匹配方式contains简单通配匹配、exact精确匹配、subnet若字段含 IP 地址且该 IP 落在第一集合字段所代表的子网内则视为匹配。源码中subnet匹配基于netaddr库的IPAddress in IPNetwork判断spiderfoot/correlation.py。实战范例correlations/egress_ip_from_wikipedia.yaml 用第一个 collection 收集NETBLOCK_OWNER目标拥有的网段第二个 collection 收集child.type为WIKIPEDIA_PAGE_EDIT的IP_ADDRESS再以subnet匹配找出从目标自有网段编辑维基百科的出口 IP。headline所有数据元素经过收集、过滤、聚合与分析后仍保留下来的就是correlation results关联结果。这些结果需要一个headline来概括发现。要把数据中的字段值放进标题必须用{}包裹字段如{entity.data}。headline 有两种写法简单写法headline: titletexthere块写法可以更精细地控制结果的发布方式text如上所述的标题文本publish_collections希望与关联结果关联的 collection。通常不需要但常与match_all_to_first_collection组合使用——当第一个 collection 仅作为参照点、并不包含你想随结果发布的数据元素时。参见 correlations/egress_ip_from_wikipedia.yaml 中publish_collections: [1]的实战用法只发布第二个 collection 的数据。标题中的字段替换由build_correlation_title()实现用正则{([a-z\.])}提取占位符再从结果数据中取值替换spiderfoot/correlation.py。深入理解child.、source.与entity.字段前缀collection 中第一个match规则拉取的每个数据元素都附带三类关联信息children子节点由该数据元素产生的数据source来源生成该数据元素的父数据元素entity实体来源、或来源的来源……中最接近的那一个实体如 IP 地址、域名等。这使你能在**后续且仅限后续**的 match 块字段名前加child.、source.、entity.前缀进行匹配。这些前缀同样可用于aggregation、analysis和headline段。极其重要这些前缀始终相对于每个collect块内的第一个match块而言——因为后续每个match块都是对第一个match块的细化。一个直观的例子假设扫描发现了主机名INTERNET_NAME类型foo它出现在某网页内容TARGET_WEB_CONTENT类型This is some web content: foo中该内容来自 URLLINKED_URL_INTERNAL类型https://bar/page.html而这个 URL 又来自另一台主机bar。数据发现路径为bar [INTERNET_NAME] - https://bar/page.html [LINKED_URL_INTERNAL] - This is some web content: foo [TARGET_WEB_CONTENT] - foo [INTERNET_NAME]如果我们在规则中关注This is some web content: foo你会期望存在以下data与type字段module也存在此处省略data:This is some web content: footype:TARGET_WEB_CONTENTsource.data:https://bar/page.htmlsource.type:LINKED_URL_INTERNALchild.data:foochild.type:INTERNET_NAMEentity.type:INTERNET_NAMEentity.data:bar注意This is some web content: foo的entity.type/entity.data不是LINKED_URL_INTERNAL数据元素而是bar这个INTERNET_NAME数据元素。原因在于INTERNET_NAME是实体而LINKED_URL_INTERNAL不是。哪些数据类型是实体、哪些不是可以在 spiderfoot/db.py 的eventDetails定义中查询对应源码中type_entity_map的构建见 spiderfoot/correlation.py。实体的判断在enrich_event_entities()中实现它沿 source 链向上遍历直到找到entity_type为ENTITY或INTERNAL的节点spiderfoot/correlation.py。source./child./entity.数据的获取分别由enrich_event_sources()、enrich_event_children()、enrich_event_entities()完成且按 5000 条一批分块查询以避免数据库压力。实战规则赏析以下几条规则覆盖了聚合与分析的典型组合是学习编写高质量规则的最佳范本多源恶意判定correlations/multiple_malicious.yaml收集所有MALICIOUS_*/BLACKLIST_*类型事件用not正则剔除子网source.data含/与 COHOST/AFFILIATE 相关类型按source.data聚合要求同一实体出现至少 2 次——多源交叉印证降低误报collections: - collect: - method: regex field: type value: - MALICIOUS_* - BLACKLIST_* - method: regex field: source.data value: not .*/.* - method: regex field: type value: - not .*COHOST.* - not .*AFFILIATE.* aggregation: field: source.data analysis: - method: threshold field: source.data minimum: 2 headline: Entity considered malicious by multiple sources: {source.data}离群 Web 服务器correlations/outlier_webserver.yaml收集WEBSERVER_BANNER按data聚合后仅保留占比不超过 10% 的桶——Web 服务器场景下的离群常是影子 IT 或未维护基础设施的信号collections: - collect: - method: exact field: type value: WEBSERVER_BANNER aggregation: field: data analysis: - method: outlier maximum_percent: 10 headline: Outlier web server found: {data}仅出现在泄露站的邮箱correlations/email_only_from_pasteleak_site.yaml双 collection first_collection_only的典型用法已在上一节详述。规则质量的验证与测试仓库为关联引擎提供了完整的单元测试test/unit/spiderfoot/test_spiderfootcorrelator.py覆盖了构造参数类型检查非法dbh、非法ruleset类型应抛TypeError非法 YAML 规则应抛SyntaxError对不存在或运行中的扫描执行关联应抛ValueErrorprocess_rule()、build_correlation_title()、create_correlation()等核心方法的参数校验check_ruleset_validity()/check_rule_validity()对缺失强制字段、非法字段、非法方法等的校验行为。这些测试既是回归保障也精确说明了引擎对规则的预期——编写自定义规则时可对照测试中ruleset的构造方式来验证自己的规则格式是否合法。此外引擎内置的check_rule_validity()spiderfoot/correlation.py会在启动时自动完成大部分校验包括强制组件meta、collections、headline必须存在顶层不允许出现未知字段collect内的method只能是exact/regexfield必须命中白名单含三种前缀组合每个method必须提供value分析方法的method只能是threshold、outlier、first_collection_only、both_collections、match_all_to_first_collection其中both_collections在源码中标注为 TODO尚未实现见 spiderfoot/correlation.py各段的必填选项strict必须齐全。小结Correlations 把 SpiderFoot 从收集数据的工具升级为理解数据的工具以 YAML 声明式规则描述什么值得关注引擎负责翻译成数据库查询与分析逻辑最终在扫描结束后自动产出带风险分级的关联结果并通过 Web 界面、CLI 或 SQLite 直接查询tbl_scan_correlation_results与tbl_scan_correlation_results_events消费。编写规则的要点可归纳为四条第一个method从库取数其余method内存精炼not前缀用于反向过滤聚合决定分组方式分析决定取舍标准阈值、离群、跨集合对比child./source./entity.前缀永远指向每个collect的第一个match从 correlations/template.yaml 出发参考 correlations/ 下现有规则命名遵循id与文件名一致、version: 1保存后重启 SpiderFoot 即可加载。掌握这套机制后你就可以针对自己的侦察场景定制规则——无论是发现影子 IT、识别出口代理还是交叉验证恶意指标——让每一次扫描自动输出高价值的分析结论。【免费下载链接】spiderfootSpiderFoot automates OSINT for threat intelligence and mapping your attack surface.项目地址: https://gitcode.com/GitHub_Trending/sp/spiderfoot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考