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. Установите Python 3.9 с помощью pyenv ALFA лучше всего работает с Python 3.9. Вы можете использовать pyenv для управления и установки этой версии.

   • Если pyenv ещё не установлен, вы можете сделать это через Homebrew:
     root@kitploit:~

     brew install pyenv
     

   • Настройте pyenv в вашей оболочке, добавив следующее в файл конфигурации (например, ~/.zshrc или ~/.bashrc):
     root@kitploit:~

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

     После обновления файла перезагрузите оболочку:
     root@kitploit:~

     source ~/.zshrc  # или source ~/.bashrc
     

   • Установите Python 3.9 с помощью pyenv:
     root@kitploit:~

     pyenv install 3.9
     

   • Установите Python 3.9 как текущую версию:
     root@kitploit:~

     pyenv global 3.9
     

     или только для текущей сессии:
   root@kitploit:~

    pyenv shell 3.9
   

2. (Опционально) Создайте виртуальное окружение Рекомендуется запускать проекты в виртуальном окружении для изоляции зависимостей. Используя версию Python 3.9, которую вы только что установили, создайте виртуальное окружение:

   root@kitploit:~

   python -m venv alfa
   

   • Активируйте виртуальное окружение:
     root@kitploit:~

     source alfa/bin/activate
     

3. Установите ALFA В папке, где находится проект ALFA, установите его с помощью pip:

   root@kitploit:~

   pip install -e .
   

   Если вы не используете виртуальное окружение, возможно, потребуется sudo:

   root@kitploit:~

   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 Acquire

Получить все журналы аудита 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=введите_имя_пользователя
• Получить журналы за определённый период времени: alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z, формат времени: (RFC3339)

Теперь вы знаете, как получать данные, время перейти к интересным вещам, чтобы раскрыть всю мощь ALFA.

2. ALFA Analyze

Функция analyze автоматически анализирует все данные журналов аудита для заданной среды Google Workspace, чтобы выявить подозрительную активность.

Как это работает

1. Категоризация Каждое отдельное событие категоризируется на основе сопоставления, заданного в alfa/config/event_to_mitre.yml. Если событие соответствует записям из этого списка, оно сопоставляется с техникой, входящей в фреймворк MITRE ATT&CK Cloud (https://attack.mitre.org/matrices/enterprise/cloud/).

2. Оценка Затем ALFA анализирует все сопоставленные события в хронологическом порядке, чтобы попытаться выявить цепочки kill chain или логические пути атаки. Например, событие, сопоставленное с фазой Persistence, за которым следует событие, сопоставленное с фазой Credential Access, приведёт к более высокой оценке.

3. Результат В итоге ALFA предоставляет аналитику список выявленных «подцепочек» (subchains), которые можно проанализировать дальше.

Как использовать ALFA analyze?

1. Сначала выполните alfa analyze, который автоматически выявит подцепи (или не выявит, если их нет). Он также откроет интерактивную оболочку, где вы сможете выполнять последующие действия.
2. Чтобы получить больше информации о конкретной подцепи, просто выполните A.subchains() — это покажет цепь в следующем формате: (номер_первого_события_в_цепи, номер_последнего_события_в_цепи, оценка_киллчейна). Оценка 1 означает идеальную цепь, а чем ближе к 0, тем слабее цепь.
3. Чтобы получить доступ к подозрительным событиям, вызвавшим эту цепь, используйте A.aoi(export='activities.json'), чтобы экспортировать все выявленные подцепи в файл, который затем можно использовать для дальнейшего анализа.

3. ALFA Load

Загрузить данные из локального хранилища

Из локального хранилища

Используйте A = Alfa.load([имя_журнала]) для загрузки и анализа журналов из локального хранилища. Используйте A = Alfa.load('all') для загрузки всех журналов. По умолчанию Alfa отфильтровывает безвредные действия. Чтобы загрузить все действия и события без фильтрации, используйте Alfa.load([имя_журнала], filter=False).

Внесение изменений

Добавление новых сопоставлений событий

Вы можете напрямую редактировать файл config/event_to_mitre.yml, но это не рекомендуется. Структура этого файла неинтуитивна. Вместо этого вносите изменения в utils/mappings.yml. Затем заново создайте config/event_to_mitre.yml, выполнив utils/event_mitre_remap.py.

Изменение методов обнаружения kill chain

Функция обнаружения kill chain использует жёстко заданные константы. Их можно найти в файле config/config.yml. Криминалистам рекомендуется просмотреть значения и внести изменения под свою рабочую область при необходимости. Эти константы отвечают как за статистику kill chain (kcs), так и за обнаружение kill chain (подцепи).

Часто задаваемые вопросы

Хотите узнать больше о статистике и алгоритмах, используемых в ALFA? Мы написали об этом пост в блоге: https://medium.com/@invictus-ir/automated-forensic-analysis-of-google-workspace-859ed50c5c92

Известные ошибки

ValueError: missing config/credentials.json

Необходимо добавить файл credentials.json в папку проекта в подкаталог 'config'. Инструкции в файле 'CREDENTIALS.md'.

OSError: [Errno 98] Address already in use

Это означает, что порт 8089 уже используется другим приложением. Это может произойти, если на этом порту запущен веб-сервер, а также Splunk по умолчанию использует порт 8089. Решение — (временно) освободить этот порт, так как он необходим для процесса аутентификации.

ValueError: Authorized user info was not in the expected format, missing fields refresh_token.

Иногда информацию об авторизации необходимо обновить. Проще всего удалить файл 'token.json' из папки project_name/config, а затем повторно выполнить команду. Если это всё ещё вызывает проблемы, удалите token.json и credentials.json и заново зарегистрируйте приложение OAuth, как описано в CREDENTIALS.MD

Access is blocked: This app's request is invalid // Error 400: redirect_uri_mismatch

Убедитесь, что в URI Authorized redirect URIs вашего приложения OAuth 2.0 Client IDs присутствует завершающий слэш (/) в URI http://localhost:8089.