ThePhish 是一款基于 TheHive、Cortex 和 MISP 的自动化钓鱼邮件分析工具。它是一个用 Python 3 编写、基于 Flask 的 Web 应用程序，能够自动完成从邮件头与正文中提取可观测指标，到最终（多数情况下）得出判定结果的完整分析流程。此外，它还允许分析人员在必要时介入分析过程，获取关于正在分析的邮件的更多详细信息。为了与 TheHive 和 Cortex 交互，它使用了 TheHive4py 和 Cortex4py，它们分别是访问 TheHive 和 Cortex 提供的 REST API 的 Python 客户端。
下图展示了 ThePhish 的顶层工作原理：
本示例旨在展示用户如何将邮件发送给 ThePhish 进行分析，以及分析人员如何使用 ThePhish 实际分析该邮件。
用户可以将邮件发送到 ThePhish 用于获取待分析邮件的邮箱地址。邮件必须以 EML 格式作为附件转发，以防止污染邮件头。本例中使用的邮件客户端是 Mozilla Thunderbird，使用的邮箱地址是 Gmail 地址。
分析人员导航到 ThePhish 的网页，点击“列出邮件”按钮以获取待分析邮件的列表。
当分析人员点击所选邮件对应的“分析”按钮时，分析开始，进度显示在 Web 界面上。
与此同时，ThePhish 从邮件中提取可观测指标（URL、域名、IP 地址、邮件地址、附件以及这些附件的哈希值），然后与 TheHive 交互以创建案件。
案件内创建了三个任务。
随后，ThePhish 开始将提取的可观测指标添加到案件中。
此时，借助 Mailer 响应器，用户通过电子邮件收到分析已开始的通知。
第一个任务的描述允许 Mailer 响应器通过电子邮件发送通知。
第一个任务关闭后，第二个任务启动，分析器开始分析可观测指标。分析器启动期间，分析进度显示在 Web 界面上。
分析进度也可以通过 TheHive 的实时流查看。
所有分析器执行完毕后，第二个任务关闭，第三个任务启动，然后 ThePhish 计算判定。由于判定为“恶意”，所有被判断为恶意的可观测指标都被标记为 IoC。本例中只有一个可观测指标被标记为 IoC。
案件随后被导出到 MISP 作为一个事件，其中包含一个属性，即上述被标记的可观测指标。
接着，ThePhish 借助 Mailer 响应器将判定结果通过电子邮件发送给用户。
最后，任务和案件均被关闭。第三个任务的描述允许 Mailer 响应器通过电子邮件发送判定结果。此外，案件在五分钟后关闭，并解析为“True Positive”且“No Impact”，意味着攻击在造成任何损害前已被检测到。
案件关闭后，判定结果以及整个分析进度的日志均可在 Web 界面上供分析人员查看。
此时分析人员可以返回并分析另一封邮件。上述案例涉及的是钓鱼邮件，但被分析邮件分类为“安全”时，工作流程类似。案件将被关闭，判定结果通过电子邮件发送给用户。
然后，判定结果也会在 Web 界面上显示给分析人员。
另一方面，当邮件被分类为“可疑”时，判定结果仅显示在 Web 界面上供分析人员查看。
此时分析人员需要使用页面左侧的按钮，通过 TheHive、Cortex 和 MISP 进行进一步分析。这是因为分析尚未完成，用户仅被告知其转发给 ThePhish 的邮件分析已开始。实际上，最后一个任务和案件尚未关闭，需要分析人员本人形成最终判定后才能手动关闭。
分析人员可以在 TheHive 和 Cortex 上查看所有分析器的报告，若仍不足，他还可以下载邮件的 EML 文件并手动分析。
当分析人员完成分析后，他可以在最后一个任务的描述中填充要发送给用户的邮件正文，启动 Mailer 响应器，如果判定为“恶意”，则点击“导出”按钮将案件导出到 MISP，然后关闭案件。
ThePhish 是一个用 Python 3 编写的 Web 应用程序。Web 服务器使用 Flask 实现，而应用的前端部分（即用 HTML、CSS 和 JavaScript 编写的动态页面）使用 Bootstrap 实现。除了 Web 服务器模块外，应用的后端逻辑由三个封装了应用逻辑的 Python 模块和一个用于通过 WebSocket 协议支持日志功能的 Python 类组成。如果您想查看应用逻辑的图形化表示，请点击此处。此外，还有多个配置文件供上述模块使用，用于各种目的。
当分析人员导航到应用的基础 URL 时，ThePhish 网页加载完毕，并与服务器建立双向连接。这是通过网页中使用的 Socket.IO JavaScript 库实现的，该库支持浏览器与服务器之间的实时、双向、基于事件的通信。此连接在可能的情况下使用 WebSocket 连接，否则回退到 HTTP 长轮询。服务器端应用使用 Flask-SocketIO Python 库，该库为 Flask 应用提供了 Socket.IO 集成。ThePhish 利用连接在 Web 界面上显示分析进度。
每当分析人员在 Web 界面上执行操作时，就会向服务器发送一个 AJAX 请求，这是一种异步 HTTP 请求，允许在后台与服务器交换数据并更新页面而无需重新加载。这使得分析人员既能查看待分析邮件的列表，也能启动分析。
ThePhish 通过 TheHive4py 和 Cortex4py 与 TheHive 和 Cortex 交互。此外，它还通过 IMAP 服务器检索要分析的邮件。
由于在生产环境中从零安装和配置 TheHive、Cortex 和 MISP 服务可能不那么直接，TheHive Project 在此处提供了 Docker 镜像和 Docker Compose 模板以简化安装过程。为简单起见，提供的模板较为简单，并未提供每个 Docker 镜像的完整配置选项。
如果您只是想试用 ThePhish 或希望尽快让它运行起来，可以使用 docker 文件夹中提供的 Docker 模板，该模板是 TheHive Project 提供的某个 Docker 模板的修改版，并额外创建了一个 ThePhish 容器。要使用 Docker 和 Docker Compose 安装 ThePhish，请参考此指南。我强烈建议您至少在首次使用时采用此安装方式，以便学习基础知识以及如何以最低配置（应能首次尝试就成功）进行配置。事实上，上述指南还提供了配置 TheHive、Cortex 和 MISP 实例的逐步流程。
本指南仅涉及 ThePhish 的安装，需要满足：
要安装、配置和集成 TheHive、Cortex 和 MISP 实例，请参考其官方文档：
建议 ThePhish 用于获取待分析邮件的邮箱地址使用 Gmail 地址，因为 ThePhish 在此类邮箱上测试最多。最好使用新创建的专用账户，仅供 ThePhish 使用。启用 ThePhish 连接邮箱并获取邮件所需的“应用密码”的步骤，请参见此处。
本安装过程已在运行 Ubuntu 20.04.3 LTS、Python 3.8 的 VM 上测试，TheHive、Cortex 和 MISP 的版本如本 docker-compose.yml 文件所示。
一旦 TheHive、Cortex 和 MISP 配置完毕并在某个 URL 上监听，邮箱地址也已可用，即可安装和配置 ThePhish。
克隆仓库
$ git clone https://github.com/emalderson/ThePhish.git
创建 Python 虚拟环境并激活（这是好的实践，但非必需）
$ cd ThePhish/app
$ sudo apt install python3-venv
$ python3 -m venv venv
$ source venv/bin/activate
安装依赖
$ pip install -r requirements.txt
将 run_responder() 函数添加到 TheHive4py 的 api.py 文件中
为了向用户发送电子邮件，ThePhish 使用了 Mailer 响应器。由于 ThePhish 使用 TheHive4py 与 TheHive 交互，需要一个按其 ID 运行响应器的函数。遗憾的是，此功能尚未包含在 TheHive4py 中，但已经提交了一个拉取请求以将其添加到 TheHive4py（#219）。在等待合并期间，必须手动添加该函数，ThePhish 才能正常工作（如果使用不同版本的 Python，请相应更改命令中的 Python 版本）：
$ (cat << _EOF_
def run_responder(self, responder_id, object_type, object_id):
req = self.url + "/api/connector/cortex/action"
try:
data = json.dumps({ "responderId": responder_id, "objectType": object_type, "objectId": object_id})
return requests.post(req, headers={"Content-Type": "application/json"}, data=data, proxies=self.proxies, auth=self.auth, verify=self.cert)
except requests.exceptions.RequestException as e:
raise TheHiveException("Responder run error: {}".format(e))
_EOF_
) | tee -a venv/lib/python3.8/site-packages/thehive4py/api.py > /dev/null
<ul class="navbar-nav text-light" id="accordionSidebar">
<li class="nav-item"><a class="nav-link active" href="/" style="max-width: 114px;" target="_blank" rel="noopener noreferrer"><img class="img-fluid" data-bss-hover-animate="bounce" src="https://raw.githubusercontent.com/emalderson/thephish/static/assets/img/logo_rounded.png" style="margin-top: 0px;margin-left: 0px;"></a></li>
<li class="nav-item"><a class="nav-link" href="http://thehive:9000" style="max-width: 114px;" target="_blank" rel="noopener noreferrer"><img class="img-fluid" data-bss-hover-animate="bounce" src="https://raw.githubusercontent.com/emalderson/thephish/static/assets/img/thehive.png" style="margin-right: 0px;margin-left: 0px;"></a></li>
<li class="nav-item"><a class="nav-link" href="http://cortex:9001" style="max-width: 114px;" target="_blank" rel="noopener noreferrer"><img class="img-fluid" data-bss-hover-animate="bounce" src="https://raw.githubusercontent.com/emalderson/thephish/static/assets/img/cortex.png" style="transform: translate(0px);"></a></li>
<li class="nav-item"><a class="nav-link" href="https://misp" style="max-width: 114px;" target="_blank" rel="noopener noreferrer"><img class="img-fluid" data-bss-hover-animate="bounce" src="https://raw.githubusercontent.com/emalderson/thephish/static/assets/img/misp.png" style="transform: translate(0px);"></a></li>
</ul>
启动应用
$ python3 thephish_app.py
用于运行应用的服务器是 eventlet 提供的 WSGI 服务器（因为它已列在依赖中）。这是 WebSocket 协议正常工作所必需的，以避免回退到 HTTP 长轮询。如果没有 eventlet，将使用默认的 Flask WSGI 服务器（Werkzeug）。 如果你希望使用其他 WSGI 服务器（例如 Gunicorn）或使用反向代理（例如 NGINX），Flask-SocketIO 文档 说明了如何实现。
现在，应用应该可以通过 http://localhost:8080 访问。
⚠️ 警告：如果你使用 Mozilla Firefox 运行 ThePhish，并且在分析过程中出于某种原因出现错误消息，解决方案可能位于这里。
仅当分析器或响应器在 Cortex 上启用并正确配置后，ThePhish 才能启动它们。这部分 文档说明了如何启用它们，而这部分 列出了可用的分析器和响应器及其配置参数。需要注意的是，虽然许多分析器是免费使用的，但有些需要特殊权限，另一些则需要有效的服务订阅或产品许可证。
每个分析器都会输出一份 JSON 格式的报告，其中包含可观察项的恶意等级，可以是“info”、“safe”、“suspicious”或“malicious”。然而，尽管报告结构通常遵循约定，但该约定并不总是被遵守。此外，在分析了大量分析器的代码并进行多次测试后，发现某些分析器存在缺陷。因此，使用了一些调整和变通方法，要么是为了无论如何都能获取这些分析器提供的恶意等级，要么是为了防止应用因这些缺陷而崩溃。
此外，这些等级并不总是代表可观察项的真实恶意程度。由于这取决于分析器本身的编程方式，ThePhish 附带了一个名为 analyzers_level_conf.json 的配置文件，通过它可以在任何分析器提供的实际恶意等级与分析员决定的等级之间建立映射。除此之外，该文件允许分析员选择这些修改应应用于哪些可观察类型。该文件需要遵循以下示例所示的结构，使用要配置的分析器的确切名称，并在右侧填写所需的等级。如果某个分析器未在此文件中列出，则其提供的恶意等级将保持不变。该文件需要遵循以下示例所示的结构，使用要配置的分析器的确切名称，并在右侧填写所需的等级。如果某个分析器未在此文件中列出，则其提供的恶意等级将保持不变。```json
{
"DomainMailSPFDMARC_Analyzer_1_1" : {
"dataType" : ["url", "ip", "domain", "mail"],
"levelMapping" : {
"malicious" : "suspicious",
"suspicious" : "suspicious",
"safe" : "safe",
"info" : "info"
}
},
"MISP_2_1" : {
"dataType" : ["url", "ip", "domain", "mail"],
"levelMapping" : {
"malicious" : "malicious",
"suspicious" : "malicious",
"safe" : "safe",
"info" : "info"
}
}
}
在这个例子中，*MISP_2_1* 分析器的“可疑”级别被提升为“恶意”，因为它表明当前正在分析的邮件中的某些可观察项已经在之前分析过且判定为“恶意”的邮件中出现过。相反，*DomainMailSPFDMARC_Analyzer_1_1* 分析器的“恶意”级别被降低为“可疑”，因为许多合法域名没有配置 DMARC 和 SPF 记录。
你可以随意在此文件中添加或移除分析器，但我建议保留文件中已有的分析器，因为这些修改是基于对大量不同邮件进行的多次测试得出的结论。
### 已测试的分析器
ThePhish 已与以下分析器进行测试：
- AbuseIPDB_1_0
- AnyRun_Sandbox_Analysis_1_0
- CyberCrime-Tracker_1_0
- Cyberprotect_ThreatScore_3_0
- *DomainMailSPFDMARC_Analyzer_1_1*
- DShield_lookup_1_0
- EmailRep_1_0
- FileInfo_8_0
- Fortiguard_URLCategory_2_1
- IPinfo_Details_1_0
- **IPVoid_1_0**
- KasperskyThreatIntelligencePortal_1_0
- Maltiverse_Report_1_0
- *Malwares_GetReport_1_0*
- *Malwares_Scan_1_0*
- MaxMind_GeoIP_4_0
- MetaDefenderCloud_GetReport_1_0
- *MISP_2_1*
- NERD_1_0
- *Onyphe_Summary_1_0*
- OTXQuery_2_0
- PassiveTotal_Enrichment_2_0
- *PassiveTotal_Malware_2_0*
- PassiveTotal_Osint_2_0
- PassiveTotal_Ssl_Certificate_Details_2_0
- PassiveTotal_Ssl_Certificate_History_2_0
- PassiveTotal_Unique_Resolutions_2_0
- PassiveTotal_Whois_Details_2_0
- PhishTank_CheckURL_2_1
- **Pulsedive_GetIndicator_1_0**
- *Robtex_Forward_PDNS_Query_1_0*
- *Robtex_IP_Query_1_0*
- *Robtex_Reverse_PDNS_Query_1_0*
- Shodan_DNSResolve_1_0
- **Shodan_Host_1_0**
- **Shodan_Host_History_1_0**
- Shodan_InfoDomain_1_0
- **SpamhausDBL_1_0**
- StopForumSpam_1_0
- *Threatcrowd_1_0*
- UnshortenLink_1_2
- **URLhaus_2_0**
- Urlscan_io_Scan_0_1_0
- *Urlscan_io_Search_0_1_1*
- VirusTotal_GetReport_3_1
- VirusTotal_Scan_3_1
- Yara_2_0
以*斜体*强调的分析器是那些级别已被修改的分析器（但可以覆盖，尽管不建议），而以**粗体**强调的分析器是那些直接在 ThePhish 代码中处理的分析器，因为它们要么不遵守报告结构的约定，要么存在 bug。此外，以下分析器在 ThePhish 代码中得到处理，以便以最佳方式使用：
- **DomainMailSPFDMARC_Analyzer_1_1**：仅对被认为能够发送邮件的域名启动。
- **MISP_2_1**：用于与 MISP 集成。
- **UnshortenLink_1_2**：在对 URL 启动任何其他分析器之前启动，以便能够缩短链接并将解缩短后的链接添加为额外的可观察项。
- **Yara_2_0**：唯一在 EML 附件上启动的分析器。
### 启用 *MISP* 分析器
为了将 Cortex 与 MISP 集成，你必须激活 *MISP_2_1* 分析器，并使用 Cortex 在 MISP 上为交互所创建用户的认证密钥进行配置。这意味着必须事先在 MISP 上创建一个组织以及该组织中具有 `sync_user` 角色的用户（你可以在此处 [ThePhish 文档，推荐](https://github.com/emalderson/ThePhish/tree/master/docker#configure-the-misp-container) 或此处 [MISP 文档](https://www.circl.lu/doc/misp/administration/#users) 了解如何操作并获取认证密钥）。
### 启用 *Yara* 分析器
如果你想使用 *Yara_2_0* 分析器，必须在运行 Cortex 的机器上创建一个包含以下内容的文件夹：
- Yara 规则，每条规则是一个扩展名为 `.yar` 的文件
- 一个名为 `index.yar` 的文件，其中包含该文件夹中每条 Yara 规则的一行，语法为：`include "yara_rule_name.yar"`
然后，你必须在 Cortex 上配置此文件夹的路径。例如，如果你在路径 `/opt/cortex` 下创建了文件夹 `yara_rules`，则需要在 Cortex（在 Web 界面上）配置路径 `/opt/cortex/yara_rules`。
## 启用 *Mailer* 响应器
为了向用户发送邮件，必须启用并正确配置 *Mailer* 响应器。启用响应器的步骤与启用分析器完全相同。如果你使用的是 Gmail 地址，以下是正确的参数设置：
- from: `<你的Gmail邮箱地址>`
- smtp_host：`smtp.gmail.com`
- smtp_port：`587`
- smtp_user：`<你的Gmail邮箱地址>`
- smtp_pwd：`<你的Gmail邮箱应用密码>`
## 使用白名单
ThePhish 允许创建白名单，以避免分析可能导致误报的观察项，或分析人员决定在分析中不应考虑的观察项。白名单包含在一个名为 `whitelist.json` 的文件中，由多个不同的列表组成，以便在匹配的可观察项类型和匹配模式方面提供极大的灵活性。它支持以下匹配模式：
- 针对电子邮件地址、IP 地址、URL、域名、文件名、文件类型和哈希值的精确字符串匹配
- 针对电子邮件地址、IP 地址、URL、域名和文件名的正则表达式匹配
- 针对包含指定域名的子域名、电子邮件地址和 URL 的正则表达式匹配
下面展示了 `whitelist.json` 文件的一个示例。```json
{
"exactMatching": {
"mail" : [],
"ip" : [
"127.0.0.1",
"8.8.8.8",
"8.8.4.4"
],
"url" : [],
"domain" : [
"adf.ly",
"paypal.com"
],
"filename" : [],
"filetype" : [
"application/pdf"
],
"hash" : []
},
"domainsInSubdomains" : [
"paypal.com"
],
"domainsInURLs" : [
"paypal.com"
],
"domainsInEmails" : [
"paypal.com"
],
"regexMatching" : {
"mail" : [],
"ip" : [
"10\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}",
"172\\.16\\.\\d{1,3}\\.\\d{1,3}",
"192\\.168\\.\\d{1,3}\\.\\d{1,3}"
],
"url" : [],
"domain" : [],
"filename" : []
}
}
虽然与精确匹配和正则匹配相关的部分均未作任何修改直接使用，但其余部分用于创建另外三个正则表达式列表。你无需设计复杂的正则表达式来启用这些功能，只需将域名添加到正确的列表中即可，ThePhish 会处理其余工作。例如，在上述示例中，不仅域名 "paypal.com" 被过滤，任何包含该域名的子域名、URL 和电子邮件地址也同样被过滤。这些正则表达式旨在避免一些非预期行为，例如防止像 "paypal.com.attacker.com" 这样的域名被错误地加入白名单。
注意：如果你将域名添加到 "domainsInSubdomains" 下，该域名本身也会被过滤。因此，无需再将同一域名添加到 "exactMatching" 的域名列表中。这种区分仅适用于只需将域名（而非其子域名）列入白名单的情况。所以，在此示例中，将 "paypal.com" 同时包含在两个列表中是多此一举。
本仓库中提供的白名单文件已预置了一些白名单可观测项，但这仅是一个示例；你可以（也应当）根据自身需求通过增删元素来编辑该文件。
ThePhish 利用了 TheHive 的一个强大功能，即能够将案例作为事件导出到 MISP。这使得可以使用 MISP_2_1 分析器来匹配案例中的可观测项与 MISP 上某个事件的属性。不幸的是，在 ThePhish 的初期开发阶段，TheHive4py 尚未提供通过 API 在 Python 中执行此操作的函数。为此，我们向 TheHive4py 提交了一个 pull request (#187) 以添加此功能。该 pull request 已被接受，函数 export_to_misp() 已添加至 TheHive4py 的 1.8.0 里程碑。
ThePhish 严重依赖 Cortex 提供的分析器。为确保它们继续按预期工作，我们向包含这些分析器的仓库提交了 pull request。以下是此类 pull request 的最新列表：
ThePhish 是一款基于 AGPL（Affero 通用公共许可证）发布的开源免费软件。
该项目始于2020年，其早期且不完整的版本曾作为我毕业的作品提交给那不勒斯费德里科二世大学举办的 Cybersecurity HackAdemy。在此，我要感谢 Roberto Celletti 提出的最初想法，以及由 gianpor、MrFelpon 和 xdinax 组成的团队，他们在应用开发的早期阶段协助我完成了初步部署和首次测试。
随后，我在功能、Logo 和用户界面方面对该工具进行了全面重新设计，增加了对 Docker 的支持，并编写了详尽的文档，以便在2021年将其作为我于那不勒斯费德里科二世大学计算机工程硕士学位的最终论文提交，导师为 Simon Pietro Romano (spromano)。
我还要感谢 Xavier Mertens (xme) 开发了 IMAP2TheHive 并将其发布到 GitHub，因为它是该项目开发的初始灵感来源，ThePhish 的代码也借鉴了该项目。
配置
configuration.json 是全局配置文件，用于设置连接邮箱以及 TheHive、Cortex 和 MISP 实例的参数。它还允许设置将在 TheHive 上创建的案件的相关参数。
{
"imap" : {
"host" : "imap.gmail.com",
"port" : "993",
"user" : "",
"password" : "",
"folder" : "inbox"
},
"thehive" : {
"url" : "http://thehive:9000",
"apikey" : ""
},
"cortex" : {
"url" : "http://cortex:9001",
"apikey" : "",
"id" : "local"
},
"misp" : {
"id" : "MISP THP"
},
"case" : {
"tlp" : "2",
"pap" : "2",
"tags" : ["email", "ThePhish"]
}
}
您可以在此处（推荐使用 ThePhish 文档）或此处（TheHive 文档）了解如何在 TheHive 上创建组织以及具有 org-admin 角色的用户，并获取其 API 密钥。类似地，您可以在此处（推荐使用 ThePhish 文档）或此处（Cortex 文档）了解如何在 Cortex 上创建组织以及具有 read, analyze 角色的用户，并获取其 API 密钥。
在此文件中设置的 URL 和 ID 必须与 TheHive 的配置文件名 application.conf 中设置的一致，该文件包含与 Cortex 和 MISP 相关的部分。您需要查找的参数是两部分中的 name 和 url，它们分别对应 Cortex 和 MISP 实例的 ID 和 URL。这些 ID 也可以从 TheHive Web 界面的“关于”窗口中找到。下图中显示的 Cortex ID 为字符串 local，MISP ID 为字符串 MISP THP：
application.conf 文件用于将 TheHive 与 Cortex 和 MISP 集成。您可以在此处（推荐使用 ThePhish 文档）或此处（TheHive 文档）了解如何设置与 Cortex 的集成，而关于与 MISP 的集成，您可以查看此处（推荐使用 ThePhish 文档）或此处（TheHive 文档）。能够访问 TheHive、Cortex 和 MISP 实例的 URL 也应替换到文件 templates/index.html 中，以便 Web 界面上的按钮能够访问它们。为此，请替换以下代码片段中的最后三个 href：