karim852/kage-dfir-toolkitConsole de triagem DFIR para hosts Windows que encadeia coleta de artefatos, linhas do tempo correlacionadas com Sigma, varreduras YARA, inspeção de sockets e contas, enriquecimento de indicadores e uma pontuação de risco calibrada.
Aponte o Kage para um host Windows suspeito e ele executa toda a triagem em uma única cadeia: o CyLR coleta os artefatos, o Hayabusa correlaciona os logs de eventos com o Sigma, o THOR Lite procura correspondências YARA, o VirusTotal e o AbuseIPDB qualificam os indicadores, e o provedor de IA da sua escolha redige o relatório. Cada etapa é transmitida ao vivo, sela o que produziu e pode ser reproduzida isoladamente.```bash pip install -r requirements.txt python -m dfirconsole # → http://127.0.0.1:8787
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/55114/7d59d87cd6f41f9d8dc66e4da743e6c6728a7156a06f9de9bdc18cdfd1fbb5cd/de22d9f23b6327fc806bbd1febb370cdca42f33eff3718eca9a0864eeb7d87e2-display-v1.webp" alt="Visão geral do Kage" width="100%">
<br><sub>A visão geral: onze etapas seladas à esquerda, o log de
execução em streaming, e a pontuação dividida em seus quatro componentes.</sub>
</p>
---
## 📑 Índice
- [Instalação](#-installation)
- [Executando sua primeira varredura](#-running-your-first-scan)
- [Adicionando o THOR Lite manualmente](#-adding-thor-lite-manually)
- [A cadeia](#-the-chain)
- [Pontuação de risco](#-risk-score)
- [Alertas](#-alerts)
- [Contexto do sistema](#-system-context)
- [Logging e auditoria](#-logging--audit)
- [YARA](#-yara)
- [Selos](#-seals)
- [Visualizações](#-views)
- [Configuração](#-configuration)
- [Referência da CLI](#-cli-reference)
- [Solução de problemas](#-troubleshooting)
- [Versão Linux](#-linux-version--in-progress)
- [Créditos](#-credits)
---
## 📦 Instalação
### Requisitos
| | |
|---|---|
| SO | Windows 10 / 11 ou Windows Server |
| Python | 3.10+ de [python.org](https://www.python.org/downloads/), **instalado para todos os usuários** |
| Permissões | **Administrador** |
| Disco | alguns GB livres para a coleta |
### Instalar```powershell
# 1. Extract Kage anywhere — Desktop, C:\Kage, a USB stick, it does not matter
cd C:\Kage
# 2. Install the dependencies
pip install -r requirements.txt
# 3. Check the environment before touching a host
python preflight.py
preflight.py relata o que está pronto e o que está faltando.```
Workspace : C:\Kage
System : Windows 11
Python : 3.12.3
Dependencies [ok] module fastapi [ok] module uvicorn [ok] module httpx
Rights and disk space [ok] console running as administrator [ok] free space: 84.2 GB
Tooling [!] CyLR in C:\Kage\tools\cylr → the "Locate the tooling" step downloads it [!] THOR Lite → optional step — it will simply be skipped
### Iniciar — como Administrador```powershell
python -m dfirconsole
Ou clique com o botão direito em launch.bat → Executar como administrador, o que trata do
virtualenv, da instalação e abre o navegador por você.```
Kage DFIR Toolkit 1.5.0
code C:\Kage\dfirconsole
workspace C:\Kage
open http://127.0.0.1:8787
> **O workspace é onde você o iniciou.** Nada para configurar. Ferramentas,
> evidências e saída ficam todas ao lado do console.
### Experimente sem risco primeiro```powershell
python -m dfirconsole --demo
O modo de demonstração constrói uma intrusão sintética — anexo malicioso, PowerShell codificado, Defender desativado, roubo de credenciais, persistência, C2, cópias de sombra eliminadas — e executa toda a cadeia sobre ela. Nada na sua máquina é tocado. A melhor forma de aprender a interface antes de um incidente real.
Inicie como administrador, abra http://127.0.0.1:8787 e verifique se a barra de estado mostra live run · Windows e não demonstration mode.
Clique em Settings:
| Campo | Exemplo | Porque é importante |
|---|---|---|
| Referência do caso | INC-2026-0042 | dá nome ao relatório, ao log e ao arquivo |
| Analista | N. Delaunay | aparece no cabeçalho do relatório |
Deixe Workspace folder vazio — ele deteta a pasta de lançamento por si próprio. Clique em Save.
A coluna da esquerda é a cadeia de custódia. Cada passo tem uma caixa de seleção; todas estão marcadas por predefinição exceto a análise YARA.
Para uma primeira execução, desmarque tudo exceto:``` ☑ Prepare the workspace ☑ Exclude the folder from Defender ☑ Locate the tooling ☑ Update the Sigma rules
Clique em **Run 4 steps**. Cerca de um minuto. Isto descarrega o CyLR e o Hayabusa e
confirma que a sua elevação funciona realmente *antes* de começar algo demorado.
### Passo 4 — Recolher e analisar
Assim que esses quatro estiverem selados, marque o resto:```
☑ Collect the artefacts CyLR — a few minutes, several GB
☑ Capture the system context accounts, sockets, disk root, log coverage
☑ Build the timeline Hayabusa correlates against Sigma
☑ Analyse the timeline score, alert families, indicators
Clique em Run e acompanhe o fluxo do log de execução. Cada etapa concluída recebe um selo — um SHA-256 que você pode verificar depois.
| Onde | O que você obtém |
|---|---|
| Overview | pontuação de risco com seus quatro componentes, alertas por família |
| Alerts | todos os alertas, filtráveis por severidade e família |
| System | contas, sockets vinculados a processos, pastas estranhas, cobertura de logs |
| Indicators | hashes, IPs e domínios extraídos da linha do tempo |
Clique em qualquer linha da tabela para abrir o painel de leitura: todos os campos, a linha de comando
completa, todos os dados brutos. ← → para navegar entre os itens, Esc para fechar.
Com as chaves de API configuradas:``` ☑ Enrich the indicators VirusTotal + AbuseIPDB reputation ☑ Write the summary the AI drafts the report
Sem chaves, ambos são marcados como *skipped* e um **write-up local** é produzido
em vez disso — mesma estrutura, sem chamada de rede.
### Passo 7 — Exportação
No canto superior direito do dashboard:
- **Report** — HTML imprimível, treze secções numeradas, pronto para PDF
- **JSON** — o estado completo, selos incluídos
- **Log** — tudo o que a consola produziu
> 💡 **Reproduzir um único passo:** faça duplo clique na sua etiqueta na coluna da esquerda. Útil
> quando o Hayabusa falha mas a recolha está bem — sem necessidade de recolher duas vezes.
---
## 🔦 Adicionar o THOR Lite manualmente
O scan YARA é o único passo que o Kage **não consegue** configurar por si. A Nextron exige
registo, por isso o binário não pode ser obtido por um script. O CyLR e o Hayabusa
descarregam-se sozinhos; o THOR não.
### 1. Obter o arquivo
Registe-se e descarregue em
[nextron-systems.com/thor-lite](https://www.nextron-systems.com/thor-lite/).
Receberá o scanner **e um ficheiro de licença** (`.lic`) — normalmente por email.
### 2. Colocá-lo em `tools\thor\`
O Kage já criou essa pasta por si no primeiro arranque. Copie o conteúdo do arquivo
para lá, **mantendo tudo junto**:```
C:\Kage\
└── tools\
└── thor\ ← everything goes here
├── thor64-lite.exe the scanner
├── yourname.lic the licence — THOR will not start without it
├── config\ from the archive
├── signatures\ from the archive — the YARA rules themselves
└── custom-signatures\ from the archive
Por que mantê-los juntos? O THOR é executado a partir do diretório que contém seu executável e resolve suas assinaturas relativas a esse diretório. Copiar apenas o binário resulta em um scanner sem nada para escanear.
As outras duas ferramentas ficam ao lado dele, cada uma em sua própria pasta:```
tools
├── cylr\ CyLR.exe ← downloaded automatically
├── hayabusa\ hayabusa-.exe ← downloaded automatically
└── thor\ thor64-lite.exe + .lic ← you place this one
### 3. Verificar```powershell
python preflight.py
| -s | --server | string | http://localhost:8080 | URL do servidor |
| -t | --token | string | | Token de autenticação |
| -o | --output | string | ./output | Diretório de saída |
| -f | --format | string | json | Formato de saída (json, yaml, csv) |
| -v | --verbose | bool | false | Ativar saída detalhada |
| -q | --quiet | bool | false | Suprimir toda a saída |
| -c | --config | string | ~/.tool/config.yaml | Caminho do arquivo de configuração |
| -n | --no-color | bool | false | Desativar saída colorida |
| -d | --debug | bool | false | Ativar modo de depuração |
| -h | --help | | | Exibir mensagem de ajuda |
# Basic usage
tool scan --target example.com
# With authentication
tool scan --target example.com --token "your-api-token"
# Output to specific directory
tool scan --target example.com --output /tmp/results
# Verbose mode with JSON output
tool scan --target example.com --verbose --format json
# Using configuration file
tool scan --config /path/to/config.yaml
# Multiple targets
tool scan --target example.com,test.com,localhost
# ~/.tool/config.yaml
server: http://localhost:8080
token: your-api-token
output: ./output
format: json
verbose: false
quiet: false
no_color: false
debug: false
# Scan settings
scan:
timeout: 30
threads: 10
retries: 3
follow_redirects: true
user_agent: "Tool/1.0"
# Filters
filters:
exclude:
- "*.test.com"
- "internal.*"
include:
- "*.example.com"
# Pipe results to other tools
tool scan --target example.com --format json | jq '.vulnerabilities[]'
# Read targets from file
cat targets.txt | tool scan --stdin
# Chain multiple scans
tool scan --target example.com --format json | \
tool analyze --stdin --format table
# .github/workflows/security.yml
name: Security Scan
on:
push:
branches: [main]
schedule:
- cron: '0 0 * * *'
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run security scan
run: |
tool scan --target ${{ github.event.repository.html_url }} \
--token ${{ secrets.TOOL_TOKEN }} \
--format json \
--output results/
- name: Upload results
uses: actions/upload-artifact@v3
with:
name: scan-results
path: results/
# Build image
docker build -t tool:latest .
# Run container
docker run --rm -v $(pwd)/output:/app/output tool:latest \
scan --target example.com
# With environment variables
docker run --rm \
-e TOOL_TOKEN=your-token \
-e TOOL_SERVER=http://localhost:8080 \
tool:latest scan --target example.com
version: '3.8'
services:
tool:
build: .
volumes:
- ./output:/app/output
- ./config:/app/config
environment:
- TOOL_TOKEN=${TOOL_TOKEN}
- TOOL_SERVER=http://tool-server:8080
depends_on:
- tool-server
tool-server:
image: tool-server:latest
ports:
- "8080:8080"
volumes:
- ./data:/data
# Get token
curl -X POST http://localhost:8080/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "password"}'
# Use token
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:8080/api/scan
| Método | Endpoint | Descrição |
|---|---|---|
| GET | /api/health | Verificação de integridade |
| GET | /api/version | Informações da versão |
| POST | /api/auth/login | Autenticar e obter token |
| POST | /api/auth/logout | Invalidar token |
| GET | /api/scans | Listar todos os scans |
| POST | /api/scans | Criar novo scan |
| GET | /api/scans/{id} | Obter detalhes do scan |
| DELETE | /api/scans/{id} | Excluir scan |
| GET | /api/scans/{id}/results | Obter resultados do scan |
| GET | /api/vulnerabilities | Listar vulnerabilidades |
| GET | /api/vulnerabilities/{id} | Obter detalhes da vulnerabilidade |
# Create scan
curl -X POST http://localhost:8080/api/scans \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"target": "example.com",
"options": {
"timeout": 30,
"threads": 10
}
}'
# Get scan results
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:8080/api/scans/123/results
# List vulnerabilities
curl -H "Authorization: Bearer YOUR_TOKEN" \
"http://localhost:8080/api/vulnerabilities?severity=high&limit=10"
| Problema | Solução |
|---|---|
| Conexão recusada | Verifique se o servidor está em execução e se a porta está correta |
| Falha na autenticação | Verifique seu token e certifique-se de que ele não expirou |
| Permissão negada | Execute com privilégios elevados ou ajuste as permissões de arquivo |
| Tempo limite esgotado | Aumente o valor de timeout nas configurações |
| Memória insuficiente | Reduza o número de threads ou aumente a memória disponível |
| Arquivo de configuração não encontrado | Verifique o caminho e certifique-se de que o arquivo existe |
# Enable debug mode
tool scan --target example.com --debug
# With verbose output
tool scan --target example.com --debug --verbose
# Save debug logs
tool scan --target example.com --debug 2> debug.log
# View logs
tail -f /var/log/tool/tool.log
# Filter errors
grep ERROR /var/log/tool/tool.log
# Search by date
grep "2024-01-15" /var/log/tool/tool.log
Contribuições são bem-vindas! Por favor, siga estas diretrizes:
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)# Run tests
make test
# Run linter
make lint
# Format code
make fmt
# Build binary
make build
Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.
Aviso: Esta ferramenta destina-se apenas a testes de segurança autorizados e fins educacionais. Sempre obtenha permissão adequada antes de testar qualquer sistema.``` Tooling [ok] CyLR in C:\Kage\tools\cylr [ok] Hayabusa in C:\Kage\tools\hayabusa [ok] THOR Lite: C:\Kage\tools\thor\thor64-lite.exe [ok] THOR licence file (*.lic)
Se a linha da licença mostrar `[!]`, o THOR inicia e para imediatamente.
### 4. Escolha o escopo — isto decide tudo
**Settings → YARA scan folder:**
| Valor | Examina | Demora |
|---|---|---|
| *(vazio)* | os artefactos que o CyLR acabou de recolher | minutos |
| `C:\Users\target` | um perfil de utilizador | minutos |
| `C:\` | todo o volume do sistema | **horas** |
Marque **YARA scan** na cadeia e execute-a. Os veredictos aparecem em tempo real à medida que os ficheiros são
examinados — alertas, avisos, notificações *e* ficheiros limpos, cada um com o seu hash.
**Sem limite de tempo por predefinição.** Uma varredura de três horas é uma decisão, não uma anomalia.
Defina um em minutos se quiser um teto.
> Sem o THOR, o passo reporta-se como *ignorado* e a cadeia continua.
> Perde o eixo YARA da pontuação — nada mais.
---
## 🔗 A cadeia
Onze passos. Marque o que precisa, faça duplo clique numa etiqueta para repetir um sozinho.
| # | Passo | O que realmente é executado |
|---|---|---|
| 01 | Preparar a área de trabalho | árvore de pastas, verificação de elevação e espaço livre |
| 02 | Excluir do Defender | `Add-MpPreference -ExclusionPath <workspace>` |
| 03 | Localizar as ferramentas | resolve e descarrega o CyLR + Hayabusa das releases do GitHub |
| 04 | Recolher os artefactos | `CyLR.exe -od evidence\ -of <case>.zip -v` |
| 05 | Capturar o contexto do sistema | `systeminfo` · `Get-LocalUser` · `netstat -ano` · `tasklist` · `auditpol` |
| 06 | Atualizar as regras Sigma | `hayabusa update-rules` |
| 07 | Construir a linha temporal | `hayabusa <csv\|dfir>-timeline -d <Logs> -o hayabusa-output.csv -r <rules>` |
| 08 | Analisar a linha temporal | pontuação, famílias de alertas, extração de indicadores |
| 09 | Varredura YARA *(opcional)* | `thor64-lite.exe --nocsv -p <chosen folder>` |
| 10 | Enriquecer os indicadores | VirusTotal v3 · AbuseIPDB v2 |
| 11 | Escrever o resumo | o seu fornecedor de IA, ou um relatório local |
O subcomando do Hayabusa é lido do seu próprio output de ajuda, pelo que v3
(`csv-timeline`) e v4 (`dfir-timeline`) funcionam ambos, e flags não suportadas são
descartadas em vez de fazer falhar o comando.
---
## 🎯 Pontuação de risco
Uma **prioridade de triagem, não uma prova** — e nunca publicada sem o seu detalhamento.```
80 / 100 Compromise confirmed by multiple sources
CONFIDENCE HIGH · 441 events analysed
SEVERITY 45 / 45 8 critical, 10 high, 3 medium
KILL CHAIN 25 / 25 10 ATT&CK tactics, 7 decisive
REPUTATION 0 / 20 no indicator confirmed externally
CORROBORATION 10 / 10 3 YARA detections · 3 active connections to public hosts
Quatro eixos independentes, cada um com limite máximo. É isso que impede que uma regra ruidosa disparada trezentas vezes chegue ao mesmo veredito que uma intrusão genuína em múltiplos estágios.
A confiança é separada da severidade. Ela conta quantas fontes independentes concordam e se a cobertura de logging foi suficiente — portanto, uma pontuação alta baseada apenas no Sigma é lida como uma forte pista, nunca uma confirmação:
| Pontuação | Confiança alta | Confiança baixa |
|---|---|---|
| ≥ 70 | Comprometimento confirmado por múltiplas fontes | Comprometimento altamente provável — corroboração ainda limitada |
| ≥ 45 | Comprometimento provável — contenção recomendada | Fortes indícios de uma única fonte |
| ≥ 25 | Atividade suspeita que requer qualificação | |
| ≥ 10 | Sinais fracos, nenhum comprometimento estabelecido | |
| < 10 | Nada conclusivo |
Recalculada a cada nova fonte que chega — após a linha do tempo, após o YARA, após o enriquecimento.
A severidade diz quão urgente. As famílias dizem de que tipo.``` FAMILIES AUTHENTICATION 4 INFECTION 1 EXECUTION 6 NETWORK 5 EVASION 5 OTHER 0
TIMESTAMP LEVEL FAMILY RULE ID 09/09 10:26 CRITICAL EVASION Windows Defender Disabled 5001 09/09 11:09 CRITICAL EVASION Volume Shadow Copies Deleted 4688 09/09 11:15 CRITICAL EVASION Security Event Log Cleared 1102 09/09 10:32 CRITICAL AUTH LSASS Memory Access 10
Classificado primeiro pelo ID do evento, depois pelo texto. **Quando os dois divergem, o texto prevalece**: um `4688` é uma criação de processo, mas `vssadmin delete shadows` pertence a Evasion, porque é aí que um analista o vai procurar.
**As contagens da família correspondem sempre à tabela.** Calculadas sobre os alertas que realmente chegam à lista — um badge que promete linhas que não consegues encontrar é um bug, não um detalhe.
**O histograma segue a seleção.** Com uma família ativa, a janela observada é redesenhada na cor dessa família e um tick marca o seu momento de maior atividade.
**A triagem não se sinaliza a si própria.** O THOR escreve no registo de eventos do Windows enquanto corre, e analisar uma pasta de binários ofensivos faz com que o Hayabusa sinalize o nosso próprio scanner. Esses eventos são excluídos, contados à parte, e o total é reportado.
---
## 🖥️ Contexto do sistema
O que nenhum registo de eventos te diz, capturado em modo só de leitura:```
NETWORK — 7 listening, 4 established, 8 flagged
RISK PROTO LOCAL REMOTE PROCESS
HIGH TCP 10.20.4.11:52233 45.155.205.233:8443 powershell.exe
→ active connection to the Internet · powershell.exe should not
open a socket · remote port 8443 associated with offensive tooling
HIGH TCP 0.0.0.0:3389 — TermService.exe
→ exposed listener on RDP
ROOT C:\ — 3 flagged entries
HIGH C:\Tools folder created 0 day(s) ago
→ non-standard entry at the disk root · name suggests tooling
HIGH C:\Temp folder → frequently abused location
Cada socket é associado ao seu processo proprietário por PID — essa referência cruzada
é o que torna powershell.exe mantendo uma conexão com um host público legível à
primeira vista.
Contas locais são verificadas quanto à associação ao grupo Administradores, estado dormente-mas-habilitado e último logon. Endereços públicos de conexões estabelecidas entram automaticamente na lista de indicadores: um endereço com o qual se está a comunicar durante a triagem vale pelo menos tanto quanto um lido de uma entrada de log com três dias.
Uma triagem só vale o que a máquina concordou registar.``` LOGGING & AUDIT — coverage 51/100 · partial coverage
Blind spots: Sysmon · PowerShell (script blocks) · Process creation · Credential validation
STATE CHANNEL IMPORTANCE EVENTS ACTIVE Security critical 84 213 MISSING Sysmon critical — EMPTY PowerShell (script blocks) critical — ACTIVE System important 12 045 DISABLED WinRM important —
Dezesseis canais classificados como **ativo / vazio / desativado / ausente** — a
distinção importa: um canal vazio está a um comando de ser corrigido, um ausente
requer uma implantação. Treze subcategorias de `auditpol` lidas em conjunto.
A pontuação de cobertura fica ao lado da pontuação de risco. *Risco 80, cobertura 51* significa que o
veredito baseia-se em metade da informação disponível — e o relatório diz isso.
---
## 🔬 YARA
```
8 verdicts
VERDICT DETECTION FILE HASH SCORE
ALERT YARA rule HKTL_Rubeus C:\AD\Tools\Rubeus.exe 9c4133ee… 100
ALERT YARA rule HKTL_AmsiTrigger C:\AD\Tools\AmsiTrigger.exe af7af55c… 95
ALERT YARA rule PS_Reverse_Shell C:\AD\Tools\PowerShellTcp… ab1e98e8… 80
WARNING Suspicious filename C:\AD\Tools\svchost32.exe 6b6f1901… —
NOTICE File checked - signed C:\AD\Tools\chrome.exe c5a10bff… —
CLEAN Clean C:\AD\Tools\notepad.exe 20eded6a… —
A página é preenchida durante a varredura, não apenas quando algo é encontrado. É isso que separa nada encontrado de nada examinado.
A varredura começa no primeiro achado real. O THOR abre cada execução com uma dúzia de linhas de banner — versão, build, hostname, diretório de trabalho, lista de argumentos, uptime — e encerra com um resumo. Nada disso descreve o host sendo examinado, então nada disso chega à visualização. Hashes de alertas são enviados para a lista de indicadores, prontos para o VirusTotal.
Cada etapa concluída é selada com um SHA-256, e o selo declara o que cobre:``` ✔ Analyse the timeline SEALED 0.1s seal 31d1991a65598de8 — content of hayabusa-output.csv
✔ Exclude the folder from Defender SEALED 6.2s seal 8f2c04b71ae93d55 — execution record (no file produced)
Quando uma etapa produziu arquivos, o selo é o hash **do seu conteúdo** — execute-o novamente mais tarde e terá a prova de que o artefato não foi alterado. Quando não produziu nenhum, o selo cobre apenas o registro de execução, e diz isso em vez de implicar mais.
---
## 🧭 Views
Cada view tem o seu próprio URL, não recarrega nada e não perde nada — a análise vive no servidor e uma atualização completa restaura-a.
| Endereço | Conteúdo |
|---|---|
| `/` | pipeline, registo de execução, detalhe por família |
| `/alerts` | alertas por severidade e família |
| `/indicators` | indicadores com reputação VirusTotal / AbuseIPDB |
| `/system` | máquina, contas, rede, raiz do disco, cobertura |
| `/yara` | veredictos THOR, em direto durante a análise |
| `/attack` | táticas ATT&CK inferidas |
| `/summary` | relatório escrito |
| `/log` | registo completo, descarregável |
### Execução em direto
Cada comando é transmitido à medida que é executado. As etapas selam uma a uma; o relógio para quando a cadeia para.
### Indicadores
Hashes, IPs e domínios extraídos da linha temporal, dos sockets ativos e dos hits YARA — cada um com a sua reputação assim que o enriquecimento é executado.
### Táticas ATT&CK
### Painel de leitura
Qualquer linha, em qualquer lugar, abre em detalhe: todos os campos, a linha de comando completa, os dados brutos do THOR. `←` `→` para navegar entre itens, `Esc` para fechar, **Copy** para JSON.
### Resumo escrito
Factos observados separados dos avaliados, linguagem calibrada e uma secção explícita de lacunas de evidência que nomeia o que o registo não poderia ter mostrado.
### Definições
### Registo de execução
---
## 📄 O relatório
`/api/report.html` — autónomo, escuro, treze secções numeradas, pronto para imprimir em PDF. Sem recursos externos: permanece legível daqui a dez anos numa máquina offline.
### Veredicto e pontuação
A pontuação nunca aparece sem os seus quatro componentes, para que o leitor possa contestar um eixo em vez de um número opaco.
### Constatações e contenção
### Lacunas de evidência e cadeia de custódia
Cada etapa com o seu selo e **o que esse selo cobre** — o conteúdo de um ficheiro nomeado, ou apenas o registo de execução.
> Ao imprimir para PDF, marque *Background graphics* nas opções do navegador, caso contrário o fundo escuro é descartado.
---
## ⚙️ Configuração
### Estrutura das ferramentas
Cada ferramenta tem a sua própria pasta, e cada uma inclui um README a explicar o que deve conter.```
<workspace>/
├── tools/
│ ├── cylr/ CyLR.exe ← downloaded automatically
│ ├── hayabusa/ hayabusa-<version>.exe ← downloaded automatically
│ └── thor/ thor64-lite.exe + .lic ← manual, registration required
├── evidence/ collection archive, unpacked
└── output/ timeline, logs, enrichment cache
CyLR e Hayabusa instalam-se sozinhos. O passo Localizar as ferramentas consulta a API de releases do GitHub, escolhe o asset atual para Windows x64 e descompacta-o na pasta correta. Fixar uma versão significa que o download quebra no dia em que o upstream avança; resolvê-la significa que a consola continua a funcionar sem supervisão. Um URL fixado assume o controlo se a API estiver inacessível.
Tudo funciona sem uma única chave. Os passos não configurados são marcados como skipped, nunca failed.
Onde ficam as credenciais. O repositório inclui apikeys.env.example, um modelo
com valores vazios. Copie-o e mantenha a cópia local:```powershell
copy apikeys.env.example apikeys.env
notepad apikeys.env
| `-s` | `--server` | `SERVER` | `http://localhost:8080` | URL do servidor |
| `-t` | `--token` | `TOKEN` | `null` | Token de autenticação |
| `-u` | `--username` | `USERNAME` | `null` | Nome de usuário para autenticação básica |
| `-p` | `--password` | `PASSWORD` | `null` | Senha para autenticação básica |
| `-k` | `--insecure` | `INSECURE` | `false` | Ignorar erros de certificado TLS |
| `-c` | `--config` | `CONFIG` | `null` | Arquivo de configuração |
| `-v` | `--verbose` | `VERBOSE` | `false` | Saída detalhada |
| `-d` | `--debug` | `DEBUG` | `false` | Saída de depuração |
| `-q` | `--quiet` | `QUIET` | `false` | Modo silencioso |
| `-f` | `--format` | `FORMAT` | `json` | Formato de saída |
| `-o` | `--output` | `OUTPUT` | `null` | Arquivo de saída |
| `-n` | `--no-color` | `NO_COLOR` | `false` | Desabilitar saída colorida |
| `-h` | `--help` | `HELP` | `false` | Mostrar mensagem de ajuda |
| `-V` | `--version` | `VERSION` | `false` | Mostrar versão |
### Exemplos
```bash
# Iniciar o servidor
$ ./server
# Iniciar o servidor em uma porta específica
$ ./server -p 8080
# Iniciar o servidor com um arquivo de configuração
$ ./server -c config.yaml
# Iniciar o servidor com saída detalhada
$ ./server -v
# Iniciar o servidor com saída de depuração
$ ./server -d
# Iniciar o servidor em modo silencioso
$ ./server -q
# Iniciar o servidor com um formato de saída específico
$ ./server -f json
# Iniciar o servidor com um arquivo de saída
$ ./server -o output.json
# Iniciar o servidor com saída colorida desabilitada
$ ./server -n
# Mostrar mensagem de ajuda
$ ./server -h
# Mostrar versão
$ ./server -V
O servidor pode ser configurado usando um arquivo de configuração. O formato do arquivo de configuração é YAML. O arquivo de configuração padrão é config.yaml.
# Endereço do servidor
server:
# Endereço de escuta
address: "0.0.0.0"
# Porta de escuta
port: 8080
# Tempo limite de leitura
read_timeout: 10s
# Tempo limite de escrita
write_timeout: 10s
# Tempo limite de ociosidade
idle_timeout: 10s
# Tempo limite de desligamento
shutdown_timeout: 10s
# Habilitar TLS
tls: false
# Arquivo de certificado TLS
cert_file: ""
# Arquivo de chave TLS
key_file: ""
# Habilitar autenticação
auth: false
# Token de autenticação
token: ""
# Nome de usuário para autenticação básica
username: ""
# Senha para autenticação básica
password: ""
# Habilitar CORS
cors: false
# Origens permitidas para CORS
cors_origins: []
# Habilitar limitação de taxa
rate_limit: false
# Limite de taxa
rate_limit_value: 100
# Habilitar registro de logs
log: false
# Nível de log
log_level: "info"
# Formato de log
log_format: "json"
# Arquivo de log
log_file: ""
# Habilitar métricas
metrics: false
# Caminho das métricas
metrics_path: "/metrics"
# Habilitar verificação de integridade
health: false
# Caminho da verificação de integridade
health_path: "/health"
# Habilitar pprof
pprof: false
# Caminho do pprof
pprof_path: "/debug/pprof"
# Habilitar interface web
web: false
# Caminho da interface web
web_path: "/"
# Habilitar API
api: false
# Caminho da API
api_path: "/api"
# Habilitar GraphQL
graphql: false
# Caminho do GraphQL
graphql_path: "/graphql"
# Habilitar WebSocket
websocket: false
# Caminho do WebSocket
websocket_path: "/ws"
# Habilitar gRPC
grpc: false
# Porta do gRPC
grpc_port: 9090
# Habilitar HTTP/2
http2: false
# Habilitar HTTP/3
http3: false
# Porta do HTTP/3
http3_port: 8443
# Habilitar QUIC
quic: false
# Porta do QUIC
quic_port: 8443
# Habilitar TCP
tcp: false
# Porta do TCP
tcp_port: 8080
# Habilitar UDP
udp: false
# Porta do UDP
udp_port: 8080
# Habilitar Unix Socket
unix: false
# Caminho do Unix Socket
unix_path: "/tmp/server.sock"
# Habilitar systemd
systemd: false
# Habilitar systemd socket
systemd_socket: false
# Habilitar systemd notify
systemd_notify: false
# Habilitar systemd watchdog
systemd_watchdog: false
# Habilitar systemd journal
systemd_journal: false
# Habilitar systemd log
systemd_log: false
# Habilitar systemd log level
systemd_log_level: "info"
# Habilitar systemd log format
systemd_log_format: "json"
# Habilitar systemd log file
systemd_log_file: ""
# Habilitar systemd log output
systemd_log_output: ""
# Habilitar systemd log target
systemd_log_target: ""
# Habilitar systemd log identifier
systemd_log_identifier: ""
# Habilitar systemd log facility
systemd_log_facility: ""
# Habilitar systemd log priority
systemd_log_priority: ""
# Habilitar systemd log tag
systemd_log_tag: ""
# Habilitar systemd log source
systemd_log_source: ""
# Habilitar systemd log line
systemd_log_line: ""
# Habilitar systemd log file
systemd_log_file: ""
# Habilitar systemd log function
systemd_log_function: ""
# Habilitar systemd log code
systemd_log_code: ""
# Habilitar systemd log errno
systemd_log_errno: ""
# Habilitar systemd log user
systemd_log_user: ""
# Habilitar systemd log group
systemd_log_group: ""
# Habilitar systemd log pid
systemd_log_pid: ""
# Habilitar systemd log tid
systemd_log_tid: ""
# Habilitar systemd log comm
systemd_log_comm: ""
# Habilitar systemd log exe
systemd_log_exe: ""
# Habilitar systemd log cmdline
systemd_log_cmdline: ""
# Habilitar systemd log cap
systemd_log_cap: ""
# Habilitar systemd log audit
systemd_log_audit: ""
# Habilitar systemd log unit
systemd_log_unit: ""
# Habilitar systemd log slice
systemd_log_slice: ""
# Habilitar systemd log cgroup
systemd_log_cgroup: ""
# Habilitar systemd log session
systemd_log_session: ""
# Habilitar systemd log owner
systemd_log_owner: ""
# Habilitar systemd log boot
systemd_log_boot: ""
# Habilitar systemd log machine
systemd_log_machine: ""
# Habilitar systemd log hostname
systemd_log_hostname: ""
# Habilitar systemd log kernel
systemd_log_kernel: ""
# Habilitar systemd log architecture
systemd_log_architecture: ""
# Habilitar systemd log os
systemd_log_os: ""
# Habilitar systemd log container
systemd_log_container: ""
# Habilitar systemd log runtime
systemd_log_runtime: ""
# Habilitar systemd log scope
systemd_log_scope: ""
# Habilitar systemd log user unit
systemd_log_user_unit: ""
# Habilitar systemd log user slice
systemd_log_user_slice: ""
# Habilitar systemd log user cgroup
systemd_log_user_cgroup: ""
# Habilitar systemd log user session
systemd_log_user_session: ""
# Habilitar systemd log user owner
systemd_log_user_owner: ""
# Habilitar systemd log user boot
systemd_log_user_boot: ""
# Habilitar systemd log user machine
systemd_log_user_machine: ""
# Habilitar systemd log user hostname
systemd_log_user_hostname: ""
# Habilitar systemd log user kernel
systemd_log_user_kernel: ""
# Habilitar systemd log user architecture
systemd_log_user_architecture: ""
# Habilitar systemd log user os
systemd_log_user_os: ""
# Habilitar systemd log user container
systemd_log_user_container: ""
# Habilitar systemd log user runtime
systemd_log_user_runtime: ""
# Habilitar systemd log user scope
systemd_log_user_scope: ""
# Habilitar systemd log user unit
systemd_log_user_unit: ""
# Habilitar systemd log user slice
systemd_log_user_slice: ""
# Habilitar systemd log user cgroup
systemd_log_user_cgroup: ""
# Habilitar systemd log user session
systemd_log_user_session: ""
# Habilitar systemd log user owner
systemd_log_user_owner: ""
# Habilitar systemd log user boot
systemd_log_user_boot: ""
# Habilitar systemd log user machine
systemd_log_user_machine: ""
# Habilitar systemd log user hostname
systemd_log_user_hostname: ""
# Habilitar systemd log user kernel
systemd_log_user_kernel: ""
# Habilitar systemd log user architecture
systemd_log_user_architecture: ""
# Habilitar systemd log user os
systemd_log_user_os: ""
# Habilitar systemd log user container
systemd_log_user_container: ""
# Habilitar systemd log user runtime
systemd_log_user_runtime: ""
# Habilitar systemd log user scope
systemd_log_user_scope: ""
``````ini
# apikeys.env — sits next to launch.bat
VT_API_KEY=your_virustotal_key
ABUSEIPDB_API_KEY=your_abuseipdb_key
AI_PROVIDER=groq
AI_API_KEY=your_provider_key
AI_MODEL=
Onde obtê-las
| Chave | Nível gratuito | Registo |
|---|---|---|
VT_API_KEY | 4 pedidos/minuto, 500/dia | virustotal.com |
ABUSEIPDB_API_KEY | 1 000 verificações/dia | abuseipdb.com |
AI_API_KEY | varia — Groq e Ollama são gratuitos | consulte a tabela de fornecedores abaixo |
Também as pode definir como variáveis de ambiente em vez de um ficheiro, o que é normalmente o que pretende num contentor ou numa estação de trabalho de resposta partilhada:```powershell $env:VT_API_KEY = "..." python -m dfirconsole
### Provedores de resumo
Cada um tem seu próprio endpoint, conectado explicitamente, então escolher Groq nunca envia sua
chave para OpenAI.
| Provedor | Endpoint | Modelo padrão |
|---|---|---|
| Anthropic | `api.anthropic.com` | `claude-sonnet-4-6` |
| OpenAI | `api.openai.com/v1` | `gpt-4o` |
| Groq | `api.groq.com/openai/v1` | `llama-3.3-70b-versatile` |
| Mistral | `api.mistral.ai/v1` | `mistral-large-latest` |
| OpenRouter | `openrouter.ai/api/v1` | `anthropic/claude-sonnet-4` |
| Ollama | `localhost:11434/v1` | `llama3.1` — sem chave |
| None | — | write-up local |
Camadas gratuitas pequenas são tratadas: Groq permite 12 000 tokens por minuto, então o
payload é medido em relação a esse teto e, em caso de rejeição por tamanho, é reenviado com
menos alertas e detalhes mais curtos. O veredito sobrevive; apenas a evidência de suporte
diminui.
O modelo é mantido a um padrão — observado separado do avaliado, linguagem calibrada,
declarações quantificadas, lacunas de evidência explícitas e a explicação benigna considerada.
---
## 📟 Referência da CLI```
python -m dfirconsole console on 127.0.0.1:8787
python -m dfirconsole --port 9000 custom port
python -m dfirconsole --demo synthetic data, no collection
python preflight.py environment check
python preflight.py D:\CASE42 check another workspace
python -m pytest tests/ -q 115 tests
python tests/ui_check.py browser: full chain, reading pane
python tests/ui_nav.py browser: navigation, counts, histogram
python tests/ui_flood.py browser: 6000 log lines at once
Execuções no navegador precisam de pip install playwright && playwright install chromium.
"Administrator rights required" / exclusão do Defender recusada
O Kage não está elevado. Feche-o, clique com o botão direito em launch.bat → Executar como
administrador, ou abra o PowerShell como administrador primeiro.
did not find executable … python.exe
O seu Python veio da Microsoft Store, que instala por utilizador e desaparece
numa sessão de administrador. Reinstale a partir de python.org, para todos os utilizadores.
O CyLR não produziu nenhum arquivo / a recolha está vazia
Adicione --force-native em Settings → CyLR arguments. Isto abandona a leitura
NTFS em bruto em favor da API do Windows, que funciona quando a deteção de partições falha num disco.
O THOR inicia e depois fica em silêncio
A sua licença está em falta ou expirou, ou signatures\ não foi copiado para junto do
binário. Execute preflight.py para confirmar.
Uma cadeia de triagem Linux está a ser construída na mesma consola, mesmas vistas, mesmo modelo de pontuação. Os parsers já são agnósticos à plataforma; o que muda é a camada de evidência:
| Windows | Linux (em progresso) |
|---|---|
| Recolha CyLR | Recolha UAC / CyLR Linux |
| EVTX + Hayabusa Sigma | journald / auth.log / syslog + Sigma |
Get-LocalUser · auditpol | /etc/passwd · /etc/shadow · regras auditd |
netstat -ano + tasklist | ss -tunap |
| Anomalias na raiz do disco | /tmp · /dev/shm · /var/tmp · cron · unidades systemd |
| THOR Lite | THOR Lite para Linux |
Dê uma estrela ou siga o repositório para acompanhar o lançamento.
O Kage é uma consola, não um coletor nem um scanner. O trabalho pesado pertence a estes projetos, e eles merecem a estrela muito mais do que este repositório:
| Ferramenta | Repositório | Papel na cadeia |
|---|---|---|
| CyLR | orlikoski/CyLR | recolha de artefactos em tempo real sobre NTFS em bruto |
| Hayabusa | Yamato-Security/hayabusa | correlação Sigma, geração de cronologia |
| Sigma | SigmaHQ/sigma | as regras de deteção por trás de cada alerta |
| THOR Lite | NextronSystems/thor-lite | análise YARA e IOC |
| VirusTotal | virustotal.com | reputação de hash, IP e domínio |
| AbuseIPDB | abuseipdb.com | pontuação de abuso de IP |
| MITRE ATT&CK | attack.mitre.org | o framework de táticas por trás do eixo da kill-chain |
Respeite a licença e os termos de utilização de cada projeto — o THOR Lite em particular requer registo na Nextron e não é redistribuível.
| Ferramenta | Domínio | |
|---|---|---|
| ☁️ | Kumo 蜘蛛 | OSINT e reconhecimento de domínios |
| 🌑 | Kage 影 | triagem DFIR de hosts |
⚠️ Apenas para resposta a incidentes autorizada. Execute o Kage apenas em hosts que possui ou para os quais tem permissão escrita explícita de examinar.
Construído para aqueles que chegam depois. 影