ALFA

自动化Google Workspace审计日志取证分析

版权所有 (c) 2026 Invictus Incident Response
原作者 Greg Charitonos 和 BertJanCyber，由 Invictus Incident Response 维护

开始之前

关于支持的操作系统的说明：ALFA 已在多个 Linux 发行版（Debian 和 Ubuntu）上测试。
虽然在 Windows 或 macOS 上也可能使用，但结果可能不同，请自行承担风险。

安装

1. 下载本项目
2. 在终端中导航到文件夹，然后运行 sudo pip install -e . 或 sudo pip3 install -e .

在 macOS 上安装

1. 使用 pyenv 安装 Python 3.9 ALFA 最适合与 Python 3.9 一起使用。你可以使用 pyenv 来管理和安装此版本。

   • 如果尚未安装 pyenv，可以使用 Homebrew 安装：

     brew install pyenv
     

   • 通过将以下内容添加到你的 shell 配置文件（例如 ~/.zshrc 或 ~/.bashrc）中来在 shell 中设置 pyenv：

     export PYENV_ROOT="$HOME/.pyenv"
     export PATH="$PYENV_ROOT/bin:$PATH"
     eval "$(pyenv init --path)"
     

     更新文件后，重新加载你的 shell：

     source ~/.zshrc  # 或 source ~/.bashrc
     

   • 使用 pyenv 安装 Python 3.9：

     pyenv install 3.9
     

   • 将 Python 3.9 设置为当前版本：

     pyenv global 3.9
     

     或仅针对当前会话：

     pyenv shell 3.9
     

2. （可选）创建虚拟环境 在虚拟环境中运行项目以保持依赖隔离是一个好做法。使用你刚设置的 Python 3.9 版本，创建一个虚拟环境：

   python -m venv alfa
   

   • 激活虚拟环境：

     source alfa/bin/activate
     

3. 安装 ALFA 在 ALFA 项目所在的文件夹内，使用 pip 安装：

   pip install -e .
   

   如果你没有使用虚拟环境，可能需要 sudo：

   sudo pip install -e .
   

4. 验证安装 安装后，你可以通过尝试运行其命令行工具 alfa 来验证 ALFA 是否已安装。

使用 ALFA

注意：要获取 credentials.json，请参阅 CREDENTIALS.md

设置

1. 第一步是初始化 ALFA，通过运行 alfa init 项目名 来创建新目录以存储配置和数据。例如：alfa init project_x
2. 现在已生成一个名为 'project_x' 的新项目。在该文件夹中，将你的 credentials.json 复制到 config/ 文件夹中。（详见 CREDENTIALS.md）
3. 复制 credentials.json 文件后，你就可以使用 ALFA 了。

ALFA 有以下 3 个选项，说明如下：

1. ALFA 获取

获取所有 Google Workspace 审计日志

1. 在 "project_x"（或你之前选择的任何名称）内部运行 alfa acquire
2. ALFA 现在将获取所有用户的所有日志类型，并将它们保存到 'data' 文件夹的一个子目录中，每个日志类型生成一个 .json 文件
3. 要查看其他选项，请输入 alfa acquire -h

使用 ALFA 进行高级获取

你可以进行各种过滤以限制获取的数据，以下是一些示例：

• 仅获取 'admin' 日志类型 alfa acquire --logtype=admin
• 将输出保存到特定文件夹 alfa acquire -d /tmp/project_secret
• 仅获取特定用户的日志 alfa acquire --user=insert_username
• 在定义的时间段内获取日志 alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z 时间格式为 (RFC3339)

现在你知道了如何获取数据，是时候进行一些高级操作来释放 ALFA 的全部能力了。

2. ALFA 分析

分析功能会自动分析给定 Google Workspace 的所有审计日志数据，以识别可疑活动。

工作原理

1. 分类 每个单独的事件根据 alfa/config/event_to_mitre.yml 中的映射进行分类。如果某个事件匹配该列表，则将其映射到属于 MITRE ATT&CK 云框架 (https://attack.mitre.org/matrices/enterprise/cloud/) 的技术。
2. 评分 接下来，ALFA 将按时间顺序分析所有映射的事件，以尝试识别攻击链或逻辑攻击路径。 例如，一个映射到持久化阶段的事件，随后是一个映射到凭证访问阶段的事件，将导致更高的分数。
3. 结果 最终，ALFA 将向分析人员提供一个已识别的“子链”列表，以供进一步分析。

如何使用 ALFA 分析？

1. 首先运行 alfa analyze，它将自动识别子链（如果没有找到则不会显示）。它还会将你放入一个 shell 中，你可以在其中执行后续操作。
2. 要获取有关给定子链的更多信息，只需运行 A.subchains()，它将使用以下格式显示链： (链中第一个事件编号,链中最后一个事件编号,攻击链分数)。其中分数 1 表示识别出了完美的链，分数越接近 0，链越弱。
3. 要访问导致此链的可疑事件，使用 A.aoi(export='activities.json') 将所有已识别的子链导出到一个文件中，然后你可以使用该文件进行进一步分析。

3. ALFA 加载

从本地存储加载数据

从本地存储

使用 A = Alfa.load([日志名称]) 从本地存储加载和分析日志。使用 A = Alfa.load('all') 加载所有日志。默认情况下，ALFA 会过滤掉良性活动。要加载所有活动和事件（未经过滤），请使用 Alfa.load([日志名称], filter=False)。

进行更改

添加新的事件映射

可以直接编辑 config/event_to_mitre.yml 文件，但建议不要这样做。该文件的布局不够直观。相反，可以考虑对 utils/mappings.yml 进行修改。然后通过运行 utils/event_mitre_remap.py 重新填充 config/event_to_mitre.yml。

修改攻击链发现方法

攻击链发现功能使用硬编码的常量。这些常量可以在 config/config.yml 中找到。 法证分析人员应根据需要审查这些值并根据工作区进行修改。 这些常量负责攻击链统计 (kcs) 和攻击链发现（子链）。

常见问题

想了解更多关于 ALFA 使用的统计数据和算法？我们在这里写了一篇博客文章 https://medium.com/@invictus-ir/automated-forensic-analysis-of-google-workspace-859ed50c5c92

已知错误

ValueError: 缺少 config/credentials.json

你必须将 credentials.json 文件添加到项目文件夹的 'config' 子目录中。说明在 'CREDENTIALS.md' 文件中。

OSError: [Errno 98] 地址已在使用中

这意味着端口 8089 已被另一个应用程序使用。如果你在该端口上运行 Web 服务器，或者 Splunk 默认使用端口 8089，就可能发生这种情况。解决方案是（临时）停止该端口的使用，因为认证流程需要该端口可用。

ValueError: 授权用户信息的格式不符合预期，缺少字段 refresh_token。

有时需要更新授权信息，最简单的方法是删除 project_name/config 文件夹中的 'token.json'，然后重新运行命令。如果仍有问题，则删除 token.json 和 credentials.json，并按照 CREDENTIALS.MD 中的说明重新注册 OAuth 应用程序。

访问被阻止：此应用的请求无效 // 错误 400: redirect_uri_mismatch

确保在你的应用程序的“OAuth 2.0 客户端 ID”的“授权重定向 URI” URI http://localhost:8089 末尾包含斜杠（/）。