🔒 File Integrity Monitor (FIM)

Uma ferramenta de linha de comando leve que detecta alterações não autorizadas em arquivos dentro de um diretório monitorado, usando hashing criptográfico (SHA-256 por padrão).

Inspirado em ferramentas reais de FIM como Tripwire e OSSEC, construído como projeto prático para aprender conceitos centrais de cibersegurança + Python: hashing de arquivos, criação de baseline e detecção de mudanças — o mesmo princípio por trás de sistemas de detecção de intrusão/adulteração usados em ferramentas de segurança em produção.

---

📌 Como funciona

1. init — varre um diretório alvo, calcula o hash SHA-256 de cada arquivo, e armazena isso como uma baseline (.fim_baseline.json).
2. scan — varre o mesmo diretório novamente e compara os hashes atuais contra a baseline, reportando qualquer arquivo que foi modificado, adicionado ou removido.

                 ┌──────────────┐
   fim init  ──▶ │   Baseline    │  (.fim_baseline.json — hash SHA-256 por arquivo)
                 └──────┬───────┘
                        │
   fim scan  ───────────┴──▶  compara hashes atuais vs baseline
                                       │
                          ┌────────────┼────────────┐
                          ▼            ▼             ▼
                      MODIFICADO   ADICIONADO     REMOVIDO

🚀 Começando

# Clone o repositório
git clone https://github.com/ewbenigno/file-integrity-monitor.git
cd file-integrity-monitor

# Sem dependências externas — apenas biblioteca padrão do Python
python3 --version   # requer Python 3.10+

# Cria uma baseline para o diretório que você quer monitorar
python -m fim.cli init /caminho/para/monitorar --ignore "*.log" ".git/*"

# Depois, verifica se houve mudanças
python -m fim.cli scan

Exemplo de saída

$ python -m fim.cli scan
2026-08-10 09:15:02 [WARNING] 2 change(s) detected:
2026-08-10 09:15:02 [WARNING]   [MODIFIED] src/main.py
2026-08-10 09:15:02 [WARNING]   [ADDED]    src/backdoor.py

Códigos de saída (exit codes)

Pensado para ser usado em scripts — cron jobs, pipelines de CI, ou alertas via shell:

Código	Significado
0	Nenhuma mudança detectada — integridade OK
1	Erro (ex: baseline não encontrada, diretório inválido)
2	Mudanças detectadas

python -m fim.cli scan
if [ $? -eq 2 ]; then
    echo "⚠️  Falha de integridade — mudanças detectadas" | mail -s "Alerta FIM" voce@exemplo.com
fi

🗂️ Estrutura do projeto

file-integrity-monitor/
├── fim/
│   ├── __init__.py
│   ├── hasher.py      # Hashing SHA-256 de arquivos/diretórios (em blocos, seguro para memória)
│   ├── baseline.py    # Cria/salva/carrega a baseline em JSON
│   ├── scanner.py     # Compara o estado atual com a baseline
│   └── cli.py          # Ponto de entrada da linha de comando (init / scan)
├── tests/
├── requirements.txt
└── README.md

🛠️ Decisões de projeto

• SHA-256 em vez de MD5/SHA-1: ambos são considerados criptograficamente quebrados para fins de integridade (ataques de colisão conhecidos) — um atacante poderia adulterar um arquivo mantendo o mesmo hash.
• Leitura de arquivo em blocos (chunks de 64 KB): os hashes são calculados de forma incremental em vez de carregar o arquivo inteiro na memória, então escanear arquivos grandes não estoura o uso de RAM.
• Baseline autodescritiva: ela armazena o algoritmo, os padrões ignorados e o diretório alvo junto com os hashes, então um scan nunca depende do usuário lembrar como a baseline foi gerada.
• JSON em vez de banco de dados: nessa escala, JSON é legível por humanos, permite diff no Git, e não exige dependências. SQLite é uma evolução planejada — veja o roadmap.

Uma explicação detalhada, linha a linha, de cada decisão técnica (com explicação também para iniciantes) está disponível em docs/EXPLANATION.md.

🧭 Roadmap

• Monitoramento em tempo real usando watchdog (baseado em eventos, em vez de polling)
• Backend em SQLite como alternativa ao JSON para árvores de arquivos grandes
• Alertas: notificação por e-mail / webhook / Slack quando houver mudança
• Suporte a arquivo .fimignore (como .gitignore)
• Modo daemon (fim watch --interval 60)
• Testes unitários com pytest (hasher, baseline, scanner)
• Baseline assinada com HMAC, para detectar adulteração da própria baseline

📄 Licença

Este projeto está licenciado sob a Licença MIT.

👤 Autor

Ewerson Benigno Desenvolvedor front-end em transição de carreira, estudando Python & Cibersegurança.

• GitHub: @ewbenigno
• LinkedIn: ewerson-benigno
• dev.to: @ewbenigno