Bogeyman

Ferramenta simples de linha de comando para criptografar e descriptografar arquivos usando chaves simétricas gerenciadas localmente. Os scripts usam cryptography.Fernet para fornecer criptografia autenticada de forma prática, pensada exclusivamente para demonstrações educacionais sobre como funciona um ataque de ransomware e para exercícios de defesa e recuperação.

Aviso legal importante
Esta ferramenta é apenas para fins educativos, auditoria autorizada e demonstrações controladas. Usar em sistemas sem autorização é ilegal e perigoso. Execute apenas em ambientes isolados, com snapshots e backups. Não forneço suporte para uso malicioso.

---

Conteúdo deste repositório

• encrypt.py CLI para criptografar um arquivo in-place, com opções de backup e chave.
• decrypt.py CLI para descriptografar um arquivo in-place usando a mesma chave.
• crypto_utils.py utilitários para criar, carregar e usar chaves Fernet.
• README.md este arquivo, com orientações de uso seguro e opções.
• examples/ diretório sugerido para arquivos de demonstração.

---

Principais features (seguros para demo)

• Operação in-place com backup por padrão.
• --backup para controlar nome e diretório do backup.
• --dry-run para simular ações sem modificar arquivos.
• --key para usar um caminho de chave customizado.
• Modo de demonstração non-destructive que apenas renomeia e marca arquivos, em vez de criptografar.
• Mensagens claras de consentimento e auditoria por log.

---

Requisitos

• Python 3.8 ou superior
• Dependência Python: cryptography

Instalação da dependência:

pip install cryptography

---

Instalação rápida

1. Clone o repositório

git clone https://github.com/SEU_USUARIO/bogeyman.git
cd bogeyman

2. Crie um virtualenv e instale dependências

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# ou
pip install cryptography

---

Uso

Gerar chave e criptografar (padrão)

Se bogeyman.key não existir, uma nova chave é criada e salva no caminho informado.

python encrypt.py caminho/para/arquivo.txt

Descriptografar

python decrypt.py caminho/para/arquivo.txt --key bogeyman.key

Opções principais

usage: encrypt.py [-h] [--key KEY] [--backup BACKUP] [--dry-run] [--yes]
                  [--demo] file

positional arguments:
  file                  Path to the file that should be encrypted.

optional arguments:
  -h, --help            show this help message and exit
  --key KEY             Path to the key file. Default: bogeyman.key
  --backup BACKUP       Create a backup before modifying. Default: <file>.bak
  --dry-run             Simulate actions without modifying files
  --yes                 Skip interactive confirmation (use with caution)
  --demo                Non-destructive demo mode. Does not encrypt contents

---

Recomendações de segurança antes de usar

1. Execute apenas em VM ou container isolado. Habilite snapshots.
2. Faça backup completo dos dados originais. O script também cria backup por padrão.
3. Use o --dry-run para verificar o que seria feito.
4. Use o --demo para apresentações públicas, assim você evita danificar dados reais.
5. Guarde a chave em local seguro. Sem a chave os dados não são recuperáveis.
6. Registre logs de execução para auditoria.

---

Exemplo de fluxo seguro para demonstração em sala

1. Crie uma VM isolada e um snapshot.
2. Coloque arquivos de demonstração em examples/.
3. Rode:

python encrypt.py examples/sample1.txt --backup examples/backup --dry-run
# Verifique a saída e confirme
python encrypt.py examples/sample1.txt --backup examples/backup
# Mostre a vítima recuperando com a chave
python decrypt.py examples/sample1.txt --key bogeyman.key

Para apresentação sem risco:

python encrypt.py examples/sample1.txt --demo
# arquivo permanece legível, mas aparece marcado como "criptografado" para demonstração

---

Boas práticas para gestão de chaves (educacional)

• Para demos simples, bogeyman.key funciona. Nunca deixe chaves em repositórios públicos.
• Para cenários reais e defesa, explique KMS e secret stores: Azure Key Vault, AWS KMS, HashiCorp Vault.
• Mostre derivação de chave via passphrase com PBKDF2 para evitar chave em texto puro. Exemplo conceitual:
  • key = PBKDF2(passphrase, salt, iterations=200000)

---

Deteção e mitigação (para ensinar defesa)

Ao usar Bogeyman em demonstrações, aproveite para mostrar como detectar comportamento similar a ransomware:

• Monitorar processos que abrem e escrevem em muitos arquivos consecutivos.
• Alertar em EDR para criação de arquivos .key em diretórios de usuário.
• Monitorar aumento abrupto de entropia em arquivos.
• Proteger backups com retenção imutável.

---

Testes

Inclua testes que garantam que um arquivo criptografado é recuperável. Exemplo simples:

def test_encrypt_decrypt(tmp_path):
    src = tmp_path / "file.txt"
    src.write_text("conteudo secreto")
    key = ensure_key(tmp_path / "test.key")
    encrypt_file(src, key)
    decrypt_file(src, key)
    assert src.read_text() == "conteudo secreto"

---

Exemplos de comandos úteis

Criar chave alternativa e criptografar:

python encrypt.py secret.txt --key keys/my_bogeyman.key --backup backups/secret.txt.bak

Simular ação sem risco:

python encrypt.py secret.txt --dry-run

Modo demo non-destructive:

python encrypt.py secret.txt --demo

---

Contribuição

Se for contribuir, siga estas regras:

1. Abra issue descrevendo o motivo.
2. Faça branch com nome feat/<descrição> ou fix/<descrição>.
3. Inclua testes automatizados para novas funcionalidades.
4. Nunca introduza funcionalidade que torne a ferramenta arbitrariamente perigosa, como varredura recursiva irrestrita sem confirmação.

---