Script de Submissão em Lote para Hybrid Analysis

Este script Python percorre recursivamente uma pasta e submete arquivos executáveis, scripts, documentos e outros tipos relevantes ao Hybrid Analysis (Falcon Sandbox) para análise automatizada de malware.

Funcionalidades

• Percorre diretórios recursivamente
• Submete apenas tipos de arquivo suportados (veja a lista abaixo)
• Ignora arquivos vazios, muito grandes ou já submetidos
• Previne ataques de path traversal – garante que os arquivos estejam dentro da raiz de verificação
• Ignora links simbólicos para evitar submissões duplicadas ou não intencionais
• Utiliza uma Session persistente do requests para comunicação eficiente com a API
• Armazena cache num diretório de usuário dedicado (~/.hybrid_analysis_submitter/) para não poluir as pastas verificadas
• Usa um cache local de SHA‑256 para evitar submissões duplicadas
• Lida graciosamente com limitação de taxa da API (erros 429)
• Para automaticamente quando a cota da API é esgotada
• Suporta configuração via linha de comando da pasta, limite de tamanho de arquivo, ID de ambiente e nome do arquivo de cache
• Lê a chave da API de um arquivo .env por segurança

Requisitos

• Python 3.6+
• Uma chave de API do Hybrid Analysis válida (plano gratuito disponível)

Instalação

1. Clone ou baixe este script para sua máquina local.

2. Instale os pacotes necessários:

pip install requests python-dotenv

3. Crie um arquivo .env no mesmo diretório do script com sua chave de API:

HYBRID_API_KEY=sua_chave_api_aqui

Você pode obter uma chave de API registrando-se em Hybrid Analysis.

Uso

Execute o script a partir da linha de comando, especificando a pasta a ser verificada:

python submit_to_hybrid.py /caminho/para/pasta

Argumentos da Linha de Comando

Exemplos

Verificar uma pasta com configurações padrão:

python submit_to_hybrid.py C:\arquivos_suspeitos

Verificar uma pasta mas aumentar o limite de tamanho para 200 MB e usar um ambiente diferente (ex.: Android):

python submit_to_hybrid.py /home/usuario/amostras --max-file-size 200 --environment-id 300

Usar um nome personalizado para o arquivo de cache:

python submit_to_hybrid.py ./malware --cache-file meu_cache.json

Exemplo de Saída

Scanning folder: C:\arquivos_suspeitos

Submitting: C:\arquivos_suspeitos\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\arquivos_suspeitos\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\arquivos_suspeitos\malware.exe
Skipping symlink: C:\arquivos_suspeitos\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

Tipos de Arquivos Suportados

• Executáveis Windows (PE): .exe, .scr, .pif, .dll, .com, .cpl
• Instaladores e pacotes: .msi
• Scripts Windows: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, ,

Para a lista oficial de todos os tipos de arquivo suportados, consulte o FAQ do Hybrid Analysis.

Como Funciona

1. Percorrimento recursivo – O script usa os.walk() para percorrer todas as subpastas.
2. Verificações de segurança – Ele verifica se cada arquivo resolve para um caminho dentro da raiz de verificação (impede path traversal) e ignora links simbólicos.
3. Filtragem de arquivos – Ele verifica a extensão do arquivo, o tamanho (arquivos com 0 bytes ou > --max-file-size são ignorados) e se o arquivo já foi submetido (cache SHA‑256).
4. Submissão – Cada arquivo é enviado para o endpoint https://hybrid-analysis.com/api/v2/submit/file usando uma Session persistente do requests com sua chave de API.
5. Limitação de taxa – Após cada submissão o script aguarda 2 segundos. Se receber uma resposta HTTP 429 (Too Many Requests), conta o erro. Após 3 erros 429 consecutivos, a verificação para automaticamente.
6. Persistência do cache – Arquivos submetidos com sucesso são armazenados num arquivo JSON de cache dentro de ~/.hybrid_analysis_submitter/ para não serem reenviados em execuções futuras. O cache é salvo ordenado para facilitar a leitura.

Limitação de Taxa e Cotas

• Contas gratuitas do Hybrid Analysis possuem limites de submissão por hora/dia.
• O script detecta respostas HTTP 429 e para após 3 desses erros para evitar repetições infinitas.
• Um atraso de 2 segundos é adicionado entre as submissões para respeitar a API.

Notas Importantes

• A chave da API é lida apenas do arquivo .env – não a codifique diretamente.
• Arquivos vazios (0 bytes) são sempre ignorados.
• Arquivos maiores que --max-file-size são ignorados.
• Apenas arquivos com extensões em ALLOWED_EXTENSIONS são submetidos.
• Links simbólicos são ignorados para evitar submissões duplicadas e confusão de caminhos.
• Path traversal é impedido – o script ignorará qualquer arquivo que resolva para fora do diretório de verificação especificado.
• O cache evita o reenvio de arquivos idênticos em várias execuções e é armazenado no seu diretório de usuário (~/.hybrid_analysis_submitter/).
• O script usa um tempo limite de 120 segundos para cada requisição HTTP.
• Os arquivos de cache são armazenados em um diretório dedicado – não misturados com o conteúdo verificado.

Solução de Problemas

Licença

Este script é fornecido "como está" para fins educacionais e de análise de segurança. Use com responsabilidade e de acordo com os Termos de Serviço do Hybrid Analysis.

Aviso Legal

Enviar arquivos para um sandbox de terceiros pode expor conteúdo potencialmente sensível. Certifique-se de que você tem o direito de compartilhar os arquivos antes de fazer o upload.