codacrash: análise de crash

O codacrash lê o dump de um programa que quebrou e diz por quê: triagem, causa-raiz e explorabilidade, sem acesso à rede por padrão.

Para analisar, você não precisa de WinDbg, DbgHelp nem outro debugger.

Fronteira ética. O codacrash é estritamente defensivo: detecta, classifica e ajuda a corrigir. Nunca gera exploit, PoC ofensiva nem ferramenta de ataque. A telemetria nunca deriva do conteúdo de um dump.

Instalar

Baixe o binário em Download: macOS, Linux x64, Windows x64 e x86. Use o x86 para capturar app de 32 bits, como Delphi 7. O codacrash não roda mais no Windows 7, mas analisa dumps gerados nele. Confira a assinatura (Cadeia de suprimento). Não há pacote npm nem fórmula brew. O pacote Linux x64 traz também os três módulos do codaguard (abaixo).

Licença. Analisar um artefato é livre. Triar ou correlacionar dois ou mais artefatos exige licença Pro, Verified ou Platform no binário público (o Vibe não inclui runtime). Ver planos.

Analisar um dump

codacrash analyze crash.dmp                 # auto-detecta o formato
codacrash analyze core.1234 --format json   # envelope coda-crash/1 (kind: analysis)
codacrash analyze app.hprof                 # heap Java → kind: heap
codacrash analyze hs_err_pid1234.log        # fatal error log da JVM → kind: hserr
codacrash analyze snapshot.heapsnapshot     # heap V8 / Node
codacrash analyze core.1234 --rt-report valgrind.txt   # + quem alocou e quem liberou (Valgrind/ASan)

Formatos: Minidump (Windows), core ELF (Linux), core Mach-O (macOS), HPROF, hs_err, heap V8, core CPython e relatórios de Valgrind, ASan e OSS-Fuzz. Flags úteis: --all-threads, --module-path (pastas com os binários, para nomear funções internas), --managed (heap .NET via dotnet-dump), --dsc (shared cache do macOS).

Num core Linux (glibc), o codacrash aponta double free, escrita após free (nomeando o bloco atingido) e cabeçalho de bloco sobrescrito. Um instantâneo de processo vivo no Linux (gcore, heapdump native) não é tratado como crash: sai 0 com a memória íntegra e 10 só quando o heap está corrompido.

O laudo traz os, arch, fault, fault_address, fault_insn, crash_id (8 hex, a impressão digital do crash), severity e exploitability na escala do coda-finding/1 (critical|high|medium|low · high|medium|low|unknown), heap_corrupt e stack_smash. O rótulo legível só aparece na saída de texto; o campo JSON traz sempre o valor da escala.

Triagem e correlação

codacrash triage dumps/*.dmp        # agrupa por CRASH_ID — quantos crashes distintos há
codacrash correlate core.*          # denominador comum entre vários cores do mesmo app
codacrash correlate core.* --format json   # coda-crash/1 com kind: correlation

Em JSON, a triagem sai como coda-crash/1 com kind: triage e a correlação com kind: correlation. Um arquivo que não abre ou é inválido entra no lote como erro, e os outros seguem.

Capturar

codacrash doctor                              # esta máquina consegue produzir um dump analisável?
codacrash run app.exe -- --config prod.ini    # roda o programa e captura o .dmp no crash (só Windows)
codacrash capture app.exe --out ./dumps       # como o run, mas só captura (só Windows)
codacrash heapdump native <pid>               # instantâneo de processo VIVO: gcore, lldb ou MiniDumpWriteDump
codacrash heapdump java <pid>                 # heap Java (HPROF) · também: dotnet, python

O doctor confere core_pattern, ulimit -c, espaço em disco e ptrace_scope (Linux) e a ferramenta de captura de cada sistema, e sai 1 quando algo impede a captura.

Bancada: `deep-run`

O que o dump não mostra (leitura não inicializada, a instrução exata do acesso inválido, quem escreveu num endereço) aparece rodando o programa sob uma ferramenta de instrumentação que você já tem instalada:

codacrash deep-run ./app -- --config prod.ini   # detecta o motor: drmemory ou memcheck (Valgrind)
CODAFORT_DBI=replay codacrash deep-run ./app    # rr: grava, reexecuta e diz quem escreveu no chunk

memcheck roda em Linux e macOS x86-64; drmemory em Linux, Windows e ARM; replay em Linux com PMU.

Exit codes

código	significado
`0`	análise concluída sem nada a agir: sem crash, instantâneo íntegro, heap dump sem antipadrão; no `run`, o alvo terminou normal
`1`	`doctor`: há falha no ambiente e a captura não vai funcionar aqui
`2`	uso incorreto: argumento, token de licença recusado, `activate` num build sem licenciamento
`10`	há o que agir: crash analisado, heap corrompido num instantâneo, antipadrão num heap dump, erro de memória no `deep-run`
`11`	deadlock Java (`hs_err`)
`20`	dump inválido ou corrompido, inclusive a entrada que derrubaria o analisador
`30`	erro de I/O: não abriu o arquivo, não gravou a saída ou a licença
`40`	falha de captura (ou nenhum motor do `deep-run` no `PATH`)
`41`	capacidade paga sem licença (falha de pré-condição, distinta de dump inválido)

codaguard: detecção em runtime que fica no core

O codaguard é opcional e você o carrega junto com o programa. Ele registra o que o dump sozinho não tem: quem alocou o bloco corrompido e a escrita fora do limite do bloco, conferida no free. Esse registro fica dentro do core. No Linux, carregue-o com LD_PRELOAD; no macOS, compile-o à mão e carregue com DYLD_INSERT_LIBRARIES. SG_DENY_MODULES exclui módulos barulhentos (JVM, CLR, V8, Qt…). Quando satura, ele conta o que deixou de rastrear, e o laudo informa o teto necessário.

LD_PRELOAD=/caminho/codaguard.so SG_DENY_MODULES=libjvm ./meu-app
codacrash analyze core.1234          # o analisador correlaciona o bloco do agente com o heap

O pacote Linux x64 traz codaguard.so e dois módulos irmãos, codaguard-audit.so (registro de chamadas por thread, carregado com LD_AUDIT) e codaguard-chaos.so (perturba o escalonamento para a condição de corrida aparecer), com o guia codaguard.md. Para i386 ou macOS, o guia mostra a linha de compilação.

Profiling

O codacrash mede onde o programa gasta tempo e emite coda-profile/1. A coleta é só no Linux; a ingestão funciona em qualquer sistema.

codacrash profile ./servidor                    # on-CPU
codacrash profile ./servidor --off-cpu          # off-CPU: onde ele ESPERA (mutex, I/O)
codacrash profile --pid 4242 --sample-secs 10   # anexa a um processo vivo
codacrash analyze perf.data                     # ingere perf.data, collapsed stacks ou JFR

O que ele não faz

Não corrige o binário. O analisador não injeta nada no processo (o codaguard é opcional e quem o carrega é você). Não acessa a rede: símbolos só com flag explícita. O codacrash mostra o que aconteceu no processo; se o problema está no código-fonte, quem responde é o codafort.