ALFA

Análise Forense Automatizada de Logs de Auditoria para Google Workspace

Copyright (c) 2026 Invictus Incident Response
Autores originais Greg Charitonos & BertJanCyber mantido por Invictus Incident Response

Antes de começar

Uma nota sobre sistemas operacionais suportados: ALFA é testado em várias distribuições Linux (Debian e Ubuntu).
Embora possa ser possível usá-lo no Windows ou macOS, os resultados podem variar, portanto, prossiga por sua conta e risco.

Instalação

1. Baixe este projeto
2. Navegue até a pasta no seu terminal e execute sudo pip install -e . ou sudo pip3 install -e .

Instalação no macOS

1. Instale o Python 3.9 usando pyenv O ALFA funciona melhor com Python 3.9. Você pode usar pyenv para gerenciar e instalar esta versão.

   • Se você ainda não instalou o pyenv, pode fazê-lo usando o Homebrew:
     root@kitploit:~

     brew install pyenv
     

   • Configure o pyenv no seu shell adicionando o seguinte ao seu arquivo de configuração do shell (por exemplo, ~/.zshrc ou ~/.bashrc):
     root@kitploit:~

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

     Após atualizar o arquivo, recarregue seu shell:
     root@kitploit:~

     source ~/.zshrc  # ou source ~/.bashrc
     

   • Instale o Python 3.9 usando pyenv:
     root@kitploit:~

     pyenv install 3.9
     

   • Defina o Python 3.9 como a versão atual:
     root@kitploit:~

     pyenv global 3.9
     

     ou apenas para a sessão atual:
   root@kitploit:~

    pyenv shell 3.9
   

2. (Opcional) Crie um Ambiente Virtual É uma boa prática executar projetos em um ambiente virtual para manter as dependências isoladas. Usando a versão 3.9 do Python que você acabou de definir, crie um ambiente virtual:

   root@kitploit:~

   python -m venv alfa
   

   • Ative o ambiente virtual:
     root@kitploit:~

     source alfa/bin/activate
     

3. Instale o ALFA Dentro da pasta onde o projeto ALFA está localizado, instale-o usando pip:

   root@kitploit:~

   pip install -e .
   

   Se você não estiver usando um ambiente virtual, pode ser necessário usar sudo:

   root@kitploit:~

   sudo pip install -e .
   

4. Verifique a Instalação Após a instalação, você pode verificar se o ALFA está instalado tentando executar sua ferramenta de linha de comando alfa.

Usando o ALFA

NOTA: Para obter o credentials.json, consulte CREDENTIALS.md

Configuração

1. O primeiro passo é inicializar o ALFA executando alfa init nome_do_projeto. Este comando criará um novo diretório para armazenar sua configuração e dados. Ex.: alfa init projeto_x
2. Um novo projeto foi gerado chamado 'projeto_x'. Dentro dessa pasta, copie seu credentials.json para a pasta config/. **(Consulte CREDENTIALS.md) para obter instruções. **
3. Depois de copiar o arquivo credentials.json, você está pronto para usar o ALFA.

O ALFA tem 3 opções, conforme explicado abaixo:

1. Aquisição com ALFA

Adquirir todos os Logs de Auditoria do Google Workspace

1. De dentro de "projeto_x" (ou qualquer nome que você escolheu antes) execute alfa acquire
2. O ALFA agora obterá todos os tipos de log para todos os usuários e os salvará em um subdiretório na pasta 'data'; um arquivo .json será gerado por tipo de log
3. Para ver quais outras opções você tem, digite alfa acquire -h

Aquisições avançadas com ALFA

Você pode fazer todos os tipos de filtragem para limitar os dados que está adquirindo. Alguns exemplos abaixo:

• Apenas obter o tipo de log 'admin' alfa acquire --logtype=admin
• Salvar a saída em uma pasta específica alfa acquire -d /tmp/project_secret
• Apenas obter logs de um usuário específico alfa acquire --user=insert_username
• Obter logs dentro de um período definido alfa acquire --start-time=2022-07-10T10:00:00Z --end-time=2022-07-11T14:26:01Z o formato de hora é (RFC3339)

Agora você sabe como adquirir dados. Hora de algumas coisas interessantes para liberar o poder do ALFA.

2. Análise com ALFA

A função de análise automaticamente analisa todos os dados de log de auditoria de um determinado Google Workspace para identificar atividades suspeitas.

Como funciona

1. Categorização Cada evento individual é categorizado com base em um mapeamento feito em alfa/config/event_to_mitre.yml. Se um evento corresponder a essa lista, ele é mapeado para uma técnica que faz parte do MITRE ATT&CK Cloud Framework (https://attack.mitre.org/matrices/enterprise/cloud/).

2. Pontuação Em seguida, o ALFA analisará todos os eventos mapeados em ordem cronológica para tentar identificar kill chains ou caminhos de ataque lógicos. Ex.: Um evento mapeado para a fase de Persistência seguido por um evento mapeado para a fase de Acesso a Credenciais resultará em uma pontuação mais alta.

3. Resultado Por fim, o ALFA fornecerá ao analista uma lista de 'subcadeias' identificadas que podem ser analisadas posteriormente.

Como usar a análise do ALFA?

1. Primeiro execute alfa analyze que identificará automaticamente (ou não, se nenhuma for encontrada). Também o colocará em um shell onde você pode realizar atividades de acompanhamento.
2. Para obter mais informações sobre uma determinada subcadeia, você pode simplesmente executar A.subchains(), que mostrará a cadeia usando o seguinte formato (número_do_primeiro_evento_na_cadeia, número_do_último_evento_na_cadeia, pontuação_da_killchain). Onde uma pontuação 1 significa que uma cadeia perfeita foi identificada e quanto mais próxima de 0, mais fraca é a cadeia.
3. Para acessar os eventos suspeitos que causaram esta cadeia, use A.aoi(export='activities.json') para exportar todas as subcadeias identificadas para um arquivo, que você pode usar para análises posteriores.

3. Carregamento com ALFA

Carregar dados do armazenamento local

Do Armazenamento Local

Use A = Alfa.load([nome_do_log]) para carregar e analisar logs do armazenamento local. Use A = Alfa.load('all') para carregar todos os logs. Por padrão, o Alfa filtra atividades benignas. Para carregar todas as atividades e eventos, sem filtro, use Alfa.load([nome_do_log], filter=False).

Fazendo Alterações

Adicionando novos mapeamentos de eventos.

É possível editar o arquivo config/event_to_mitre.yml diretamente, mas não é recomendado. O layout deste arquivo não é intuitivo. Em vez disso, considere fazer alterações em utils/mappings.yml. Em seguida, repopule config/event_to_mitre.yml executando utils/event_mitre_remap.py

Alterando os métodos de descoberta de Kill Chain

A função de descoberta de kill chain utiliza constantes codificadas. Elas podem ser encontradas em config/config.yml. Os analistas forenses são aconselhados a revisar os valores e fazer alterações para seu workspace conforme necessário. Essas constantes são responsáveis tanto pela estatística da kill chain (kcs) quanto pela descoberta da kill chain (subchains).

FAQ

Quer saber mais sobre as estatísticas e o algoritmo usado para o ALFA? Escrevemos um post no blog sobre isso aqui(https://medium.com/@invictus-ir/automated-forensic-analysis-of-google-workspace-859ed50c5c92)

Erros Conhecidos

ValueError: missing config/credentials.json

Você precisa adicionar um arquivo credentials.json à pasta do projeto no subdiretório 'config'. Instruções no arquivo 'CREDENTIALS.md'.

OSError: [Errno 98] Address already in use

Isso significa que a porta 8089 já está em uso por outra aplicação. Isso pode acontecer se você tiver um servidor web rodando nesta porta e também o Splunk usa a porta 8089 por padrão. A solução é (temporariamente) parar o uso dessa porta, pois ela é necessária para o fluxo de autenticação.

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

Às vezes, as informações de autorização precisam ser atualizadas. A maneira mais fácil de fazer isso é remover o 'token.json' da pasta project_name/config e depois executar novamente o comando. Se isso ainda causar problemas, remova token.json e credentials.json e registre novamente a aplicação OAuth conforme descrito em CREDENTIALS.MD

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

Certifique-se de ter a barra invertida (/) no final da URI Authorized redirect URIs http://localhost:8089 dos IDs do Cliente OAuth 2.0 da sua aplicação.