[](https://github.com/vortacity/anglerfish/actions/workflows/ci.yml) Anglerfish 是一款专为 Microsoft 365 环境下安全团队设计的 CLI。它通过 Microsoft Graph 植入 Outlook canary 消息，随后将 Microsoft 365 Unified Audit Log 中的 `MailItemsAccessed` 事件与本地部署记录进行匹配来检测邮箱访问行为——将租户自身的审计遥测数据作为检测平面。识别访问行为无需回调接收器、DNS 区域、webhook 或外部 SIEM；相关性匹配是针对您保存在磁盘上的记录进行的。 它支持隐藏文件夹草稿 canary、收件箱发送 canary、针对草稿部署的本地健康检查，以及无需回调基础设施的审计日志监控。 ## 演示 **非交互式演示部署** (`anglerfish --demo --non-interactive ...`)：  **告警检测** (`anglerfish monitor`)：  ## 示例记录 部署 canary 会写入一条本地部署记录；当 canary 被读取时， `MailItemsAccessed` 事件会进入 Unified Audit Log，Anglerfish 将其与该记录进行关联。这些经过脱敏处理的工件展示了 证据的结构形式，而不会暴露租户数据： - [草稿部署记录](docs/examples/outlook-draft-record.json) - [发送部署记录](docs/examples/outlook-send-record.json) - [MailItemsAccessed 事件](docs/examples/ual-mailitemsaccessed-event.json) ## 文档 - [演示租户设置指南](docs/demo-tenant-setup.md) - [生产环境部署指南](docs/production-deployment.md) - [将 Mail.ReadWrite 限定于 canary 邮箱](docs/scoping-permissions.md) - [监控操作参考](docs/monitoring.md) - [隐私与数据处理](docs/privacy.md) - [架构说明](docs/architecture.md) - [威胁模型](docs/threat-model.md) - [Sentinel KQL 验证代码片段](docs/sentinel-kql.md) - [路线图](ROADMAP.md) ## 工作原理 ``` 1. Deploy anglerfish -> Microsoft Graph -> Outlook draft or inbox canary 2. Access mailbox activity -> Microsoft 365 Unified Audit Log -> MailItemsAccessed 3. Detect anglerfish monitor -> matches MailItemsAccessed to deployment record -> alert ``` 在此版本中，Anglerfish 的适用范围有意保持狭窄：仅支持 Outlook，仅支持应用程序身份验证，以及一个围绕 deploy、list、verify、cleanup 和 monitor 构建的主要工作流。 草稿部署会在隐藏文件夹名称中添加每个 canary 的 ID，并要求在部署记录中提供 `internetMessageId` 关联密钥。 ## 定位 | 工具 | 开源 | 自托管 | 第三方数据平面 | 租户原生遥测 | |---|---|---|---|---| | Anglerfish | 是 (MIT) | 是 | 否 | 是 (UAL) | | 托管型 Canarytokens / Canarytools | 否 | 否 (SaaS) | 是 (Thinkst) | 不适用 (回调模式) | | 自托管 Canarytokens | 是 | 是 | 由运营者控制 | 不适用 (回调模式) | | Defender for Office 365 异常邮箱检测 | 否 | 不适用 (Microsoft 托管) | 不适用 | 是 (UAL) | | 基于 `MailItemsAccessed` 的 DIY Sentinel KQL | 是 (运营者构建的内容) | 否 (Microsoft 托管 SIEM) | 否 | 是 (UAL) | **Anglerfish 的适用场景。** Anglerfish 并非 Canarytokens 的替代品。对于希望通过原生 UAL 关联进行 canary 部署，且无需搭建单独的 canary 平台、配置 webhook 接收器或维护自己的 KQL 搜寻的团队来说，它是一个更垂直的 M365 原生选项。如果您已经在运行 Sentinel 并编写自己的查询，[Sentinel KQL 片段](docs/sentinel-kql.md) 可以为您提供相同的相关性基础组件而无需使用 CLI；如果您想要一个处理部署、列表、验证、清理和检测的独立 CLI，Anglerfish 能够满足这一需求。 ## 相关工作 Anglerfish 与几种现有方法并存；每种方法都有 Anglerfish 不具备的功能。 - **[Thinkst Canary / Canarytokens](https://canarytokens.org/)** — 最成熟的 canary 平台；提供商业托管设备以及开源的[自托管 token 服务器](https://github.com/thinkst/canarytokens)。检测基于回调 (DNS、HTTP、SMTP)。Anglerfish 仅限 M365，没有 token 服务器，也不使用回调传输——相反，它通过租户现有的审计日志进行关联。 - **基于 `MailItemsAccessed` 的 DIY Sentinel KQL 搜寻** — 相同的审计基础组件，通过 Microsoft Sentinel 查询呈现（[Microsoft Sentinel 社区代码库](https://github.com/Azure/Azure-Sentinel)是标准的示例库）。Anglerfish 添加了部署端，并为运营者提供了一条非 SIEM 路径；提供内置的 [`docs/sentinel-kql.md`](docs/sentinel-kql.md) 片段是为了让 Sentinel 用户能够根据他们自己的查询来验证 Anglerfish 的相关性。 - **Defender for Office 365 异常邮箱检测** — Microsoft 托管、基于统计，且无法针对单个 canary 实现确定性检测。Anglerfish 是确定性的：部署的 canary 加上包含 canary 的 `internetMessageId` 的 `MailItemsAccessed` 事件即为告警。 - **Mailoney / 开源邮件蜜罐** — 不同的威胁模型（入站网络/SMTP）；非 M365 原生，且不与 Exchange Online 或 Unified Audit Log 交互。 ## 支持面 | 命令 | 用途 | | --- | --- | | `anglerfish` | 交互式 Outlook canary 部署 | | `anglerfish list` | 列出部署记录 | | `anglerfish verify` | 检查活动草稿模式的 Outlook canary | | `anglerfish cleanup ` | 移除已部署的 Outlook canary | | `anglerfish demo-access ` | 通过 Graph 读取已部署的 canary 以生成授权的审计证据 | | `anglerfish monitor` | 轮询 Outlook 访问告警 | 注意： - `draft` 是默认且支持度最高的运营路径。 - `send` 支持部署、清理、列表和监控。 - `verify` 仅适用于草稿模式，因为发送模式记录不需要保留隐藏文件夹以供检查。 ## 快速开始 ``` git clone https://github.com/vortacity/anglerfish.git cd anglerfish python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -e . ``` [`scripts/quickstart.sh`](scripts/quickstart.sh) 自动化了上述 venv 和安装步骤。 Anglerfish 从进程环境中读取凭证。它不会自动加载 `.env`，因此在运行命令之前，请直接导出值或自行 source 文件。 ``` export ANGLERFISH_TENANT_ID="..." export ANGLERFISH_CLIENT_ID="..." export ANGLERFISH_APP_CREDENTIAL_MODE="secret" export ANGLERFISH_CLIENT_SECRET="..." ``` 试运行默认的 Outlook 工作流： ``` anglerfish --dry-run --non-interactive \ --canary-type outlook \ --template "Fake Password Reset" \ --target adele.vance@contoso.com \ --delivery-mode draft ``` 部署真实的 canary 并写入本地记录： ``` export RECORD="$HOME/.anglerfish/records/adele-password-reset.json" anglerfish --non-interactive \ --canary-type outlook \ --template "Fake Password Reset" \ --target adele.vance@contoso.com \ --delivery-mode draft \ --output-json "$RECORD" ``` 为演示租户触发授权访问，然后在 UAL 摄入后进行轮询： ``` anglerfish demo-access --non-interactive "$RECORD" anglerfish monitor --once --records-dir "$HOME/.anglerfish/records" ``` 离线试用产品： ``` anglerfish --demo anglerfish monitor --demo --count 2 ``` 有关完整的 Entra 应用注册演练，请参阅[演示租户设置指南](docs/demo-tenant-setup.md)。 ## 身份验证 应用程序身份验证是此版本中唯一支持的身份验证模型。 凭证选择： - `--credential-mode secret` 或 `ANGLERFISH_APP_CREDENTIAL_MODE=secret` - `--credential-mode certificate` 或 `ANGLERFISH_APP_CREDENTIAL_MODE=certificate` - `auto` 同样被接受，并将选择已配置的单一凭证类型 密钥模式： ``` export ANGLERFISH_TENANT_ID="" export ANGLERFISH_CLIENT_ID="" export ANGLERFISH_APP_CREDENTIAL_MODE="secret" export ANGLERFISH_CLIENT_SECRET="" ``` 证书模式： ``` export ANGLERFISH_TENANT_ID="" export ANGLERFISH_CLIENT_ID="" export ANGLERFISH_APP_CREDENTIAL_MODE="certificate" export ANGLERFISH_CLIENT_CERT_PFX_PATH="/path/to/app-cert.pfx" export ANGLERFISH_CLIENT_CERT_PASSPHRASE="" ``` 同样支持 PEM 证书配置。有关完整的变量集，请参见 `.env.example`。 ## 所需权限 | 工作流 | 权限 | API | | --- | --- | --- | | 草稿部署、清理、验证 | `Mail.ReadWrite` | Microsoft Graph | | 发送部署 | `Mail.ReadWrite`, `Mail.Send` | Microsoft Graph | | 监控 | `ActivityFeed.Read` | Office 365 Management Activity API | 添加权限后授予管理员同意。 ## 模板 内置 Outlook 模板： - `Fake Password Reset` - `Fake Wire Transfer` - `IT Compliance Audit Notice` - `Payroll Direct Deposit Update` 通过 `ANGLERFISH_TEMPLATES_DIR` 支持自定义 Outlook YAML 模板： ``` export ANGLERFISH_TEMPLATES_DIR="$PWD/custom-templates" anglerfish --non-interactive \ --canary-type outlook \ --template "Fake Password Reset" \ --target adele.vance@contoso.com \ --delivery-mode draft \ --var company_name="Contoso" ``` `--template` 名称不区分大小写。重复使用 `--var KEY=VALUE` 来填充模板变量。 ## 用法 交互式部署： ``` anglerfish ``` 非交互式草稿部署： ``` anglerfish --non-interactive \ --canary-type outlook \ --template "Fake Password Reset" \ --target adele.vance@contoso.com \ --delivery-mode draft \ --output-json ~/.anglerfish/records/adele-draft.json ``` 非交互式发送部署： ``` anglerfish --non-interactive \ --canary-type outlook \ --template "Fake Wire Transfer" \ --target adele.vance@contoso.com \ --delivery-mode send \ --output-json ~/.anglerfish/records/adele-send.json ``` 列出记录： ``` anglerfish list --records-dir ~/.anglerfish/records ``` 验证草稿模式记录： ``` anglerfish verify --records-dir ~/.anglerfish/records anglerfish verify ~/.anglerfish/records/adele-draft.json ``` 清理： ``` anglerfish cleanup --non-interactive ~/.anglerfish/records/adele-draft.json anglerfish cleanup --non-interactive ~/.anglerfish/records/adele-send.json ``` 触发授权访问以生成审计证据： ``` anglerfish demo-access --non-interactive ~/.anglerfish/records/adele-draft.json anglerfish demo-access --non-interactive ~/.anglerfish/records/adele-send.json ``` `demo-access` 对已部署的 canary 执行 Graph 读取操作，以便获得许可的演示租户能够生成真实的 `MailItemsAccessed` 事件。它不会绕过 Unified Audit Log 的延迟；请在事件可用后进行轮询。 监控访问和篡改： ``` anglerfish monitor --records-dir ~/.anglerfish/records anglerfish monitor --once --records-dir ~/.anglerfish/records anglerfish monitor --records-dir ~/.anglerfish/records \ --alert-log ~/.anglerfish/alerts.jsonl \ --slack-webhook-url https://hooks.slack.com/services/... \ --teams-webhook-url https://prod-01.westus.logic.azure.com/workflows/... \ --webhook-url https://siem.example.com/anglerfish ``` 监控器会在 canary 被**读取** (`MailItemsAccessed`) 以及被**篡改**（即被删除、移动或修改，对应 `HardDelete`、 `SoftDelete`、`MoveToDeletedItems`、`Move`、`Update`）时发出告警。针对植入工件的 反取证清理本身就是高置信度的攻击者行为。 监控标志也可以通过环境变量进行设置 （`ANGLERFISH_MONITOR_STATE_FILE`, `ANGLERFISH_MONITOR_ALERT_LOG`、 `ANGLERFISH_SLACK_WEBHOOK_URL`, `ANGLERFISH_TEAMS_WEBHOOK_URL`、 `ANGLERFISH_WEBHOOK_URL`, `ANGLERFISH_WEBHOOK_HMAC_SECRET`、 `ANGLERFISH_MONITOR_NO_CONSOLE`）；CLI 标志 优先级更高。有关完整的变量集，请参见 `.env.example`。 Unified Audit Log 轮询是延迟的，而不是即时流。Microsoft 不保证审计记录的返回时间；核心服务记录通常在 60 到 90 分钟后可用。请参见 [Microsoft 审计搜索指南](https://learn.microsoft.com/en-us/purview/audit-search)。 为了在无人值守的情况下保持轮询循环运行，[`examples/anglerfish-monitor.service`](examples/anglerfish-monitor.service) 是一个可选的 systemd 示例单元，用于监管 `anglerfish monitor --no-console`。它是为运营者提供的便捷示例，而不是内置的 daemon 模式。 关于无第三方数据平面的声明仅适用于检测。可选的 Slack 告警功能会将检测后的通知发送到配置的 webhook。 屏蔽已知的正常操作者： ``` anglerfish monitor --exclude-app-id "" ``` `--exclude-app-id` 是针对已知正常操作者（例如备份、DLP 或 eDiscovery 工具）的静态白名单。当需要从匹配中排除多个已知正常应用主体时，该选项可重复使用。请勿排除用于生成演示证据的操作者或应用。 演示模式： ``` anglerfish list --records-dir examples/demo-records anglerfish cleanup --demo --non-interactive examples/demo-records/outlook-draft-record.json anglerfish cleanup --demo --non-interactive examples/demo-records/outlook-send-record.json anglerfish monitor --demo --count 2 ``` `anglerfish verify --demo` 有意包含已消失/错误的记录行并以非零状态退出，因此在复制粘贴的演示代码块中被省略。 ## CLI 帮助 ``` anglerfish --help anglerfish verify --help anglerfish demo-access --help anglerfish monitor --help ``` 这些帮助界面是当前命令操作的唯一事实来源。此版本仅支持 Outlook 部署/检测工作流。

标签：AMSI绕过, Microsoft 365, 威胁检测, 蜜罐, 证书利用, 逆向工具