Skip to main content
Glama

coroner

MCP server read-only para cases forenses do Autopsy. Expõe o autopsy.db como tools MCP para agentes de IA (opencode, Claude Desktop, Cline), preservando a cadeia de custódia: nenhuma escrita é possível no nível do driver.

  • Runtime: Bun (SQLite nativo, zero deps pesadas) | JS vanilla + JSDoc

  • Transportes: stdio (agente local) e HTTP (agente em outra máquina, air-gapped)

  • 21 tools: case/filesystem, blackboard, keywords, tags, timeline, contas de SO, conteúdo (hex/strings/extract), triagem investigativa (find_*, open_sqlite, export_evidence) e perícia (verify_audit_log, seal_audit_log)

  • Read-only e fail-closed: o driver rejeita escrita, e parâmetro desconhecido numa tool vira erro explícito (additionalProperties: false, nomeando a chave) em vez de rodar sem o filtro

Quick start

bun install
cp .env.example .env   # ajuste AUTOPSY_CASES_DIR
bun run start          # stdio — rode a partir do cliente MCP, não direto no terminal
# ou HTTP (agente remoto):
bun run src/index.js --transport http --port 3123

Windows: start.bat (stdio) ou start.bat http 3123.

Related MCP server: autopsy-mcp

Conectar um agente

opencode (local): copie opencode.json.example para o seu opencode.json — a chave é mcp (minúsculo), não mcpServers:

{
  "mcp": {
    "autopsy": {
      "type": "local",
      "command": ["bun", "run", "/caminho/absoluto/coroner/src/index.js"],
      "environment": { "AUTOPSY_CASES_DIR": "~/AutopsyCases" },
      "enabled": true
    }
  }
}

Claude Desktop (Windows, máquina do Autopsy): use claude_desktop_config.json.example. Agente remoto: aponte o cliente para http://<ip-da-maquina>:3123/mcp — o opencode.json.example já traz o bloco autopsy-remote pronto para descomentar.

Tools

Tool

Descrição

list_cases

Cases na pasta base (pastas com autopsy.db)

set_active_case

Ativa um case (valida abrindo read-only)

get_case_summary

Metadata, data sources, contagens, breakdown de artifacts

browse_filesystem

Árvore tsk_files (raízes → dirs → arquivos, paginado)

query_blackboard_artifacts

Blackboard por tipo (web history, email, EXIF, chat...)

search_keywords

Busca em nomes de arquivo e/ou conteúdo de artifacts

get_file_metadata

Hashes MD5/SHA-1/SHA-256, MAC times, known status

browse_tags

Tags do analista com contagens por tipo

browse_timeline

Eventos de MAC time numa janela de datas

get_os_accounts

Contas de SO detectadas (Autopsy 4.19+)

search_keyword_hits

Hits do índice de keywords com excerpt

get_file_hex

Hex dump de slice do conteúdo

get_file_strings

Strings ASCII/UTF-8 do conteúdo

extract_file

Copia conteúdo para fora do case

Camada de análise (triagem investigativa)

Tool

Descrição

find_files

Filtra por MIME, extensão, hash (sha256/md5/sha1), known, tamanho, trecho de caminho e janela de mtime — acha msgstore.db, ChatStorage.sqlite, History do Chromium, ou um hash de IOC

find_artifacts

Busca um termo em todos os atributos de artefatos (mensagens, buscas, URLs, contatos) e devolve o artefato completo

extract_conversations

Agrupa mensagens/chat por participante com corpo, direção e horário, ordenado por tempo

open_sqlite

Abre um SQLite de dentro da imagem (WhatsApp, navegador, iOS) e roda SELECT read-only

export_evidence

Gera extrato JSON citável (hashes, MAC times, artefatos) para o laudo — sempre fora do case

open_sqlite é o atalho para o que mais importa numa triagem: os dados de WhatsApp (msgstore.db) e de navegação (History) são SQLite; com o conteúdo acessível (Export/mount) dá para consultar as tabelas na fonte (message, chat, jid, urls, keyword_search_terms).

Perícia (trilha de auditoria e selo)

Tool

Descrição

verify_audit_log

Verifica a cadeia de hash da trilha (detecta registro editado, removido ou reordenado) — um terceiro pode rodar

seal_audit_log

Sela o encerramento: SHA-256 do log + verificação da cadeia + arquivamento + assinatura + carimbo RFC 3161, gerando o JSON do selo

Detalhes, env vars e os CLIs equivalentes em Perícia: trilha de auditoria e documentos.

Conteúdo de arquivos (hex/strings/extract)

As tools de conteúdo (get_file_hex, get_file_strings, extract_file) não leem o conteúdo do autopsy.db (o Autopsy guarda o conteúdo nas imagens) — elas resolvem por:

  • AUTOPSY_EXPORT_DIR: pasta de arquivos exportados do Autopsy, indexados por SHA-256 (match automático com tsk_files.sha256)

  • AUTOPSY_FILES_ROOT: raiz de um mount read-only da imagem, resolvendo parent_path + name

Sem nenhum dos dois, as tools respondem com hint explicando a configuração.

Agente remoto (Windows com Autopsy + agente no Mac/Linux)

O server roda na máquina do Autopsy e o agente consome via túnel SSH — nenhuma porta extra exposta (o server escuta só em 127.0.0.1).

# 1. na máquina do Autopsy: sobe o HTTP em localhost
bun run src/index.js --transport http --port 3123     # Windows: start.bat http 3123

# 2. na máquina do agente: túnel
ssh -f -N -L 3123:127.0.0.1:3123 usuario@IP-DO-WINDOWS

# 3. no opencode.json da máquina do agente
#    { "mcp": { "autopsy": { "type": "remote", "url": "http://127.0.0.1:3123/mcp", "enabled": true } } }

No Windows, para o server sobreviver a logoff/boot, registre uma tarefa agendada (rodando como SYSTEM, com o caminho absoluto do bun — o PATH do SYSTEM não tem ~/.bun/bin):

$action = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument '/c C:\code\coroner\run-http.cmd >> C:\code\coroner\mcp-http.log 2>&1'
$trigger = New-ScheduledTaskTrigger -AtStartup
$principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -LogonType ServiceAccount -RunLevel Highest
Register-ScheduledTask -TaskName 'coroner-http' -Action $action -Trigger $trigger -Principal $principal -Force
Start-ScheduledTask -TaskName 'coroner-http'

Cadeia de custódia

  • SQLite aberto com readonly: true — o driver rejeita qualquer INSERT/UPDATE/DELETE/DDL

  • Testes verificam a invariância do SHA-256 do autopsy.db após rodar todas as tools

  • extract_file recusa destinos dentro da pasta do case

  • Nenhuma tool aceita SQL arbitrário do LLM — queries são pré-definidas e parametrizadas

  • Boa prática: analise uma cópia do case; se o Autopsy estiver em ingest, o banco pode estar travado (a tool retorna hint e você tenta de novo)

Perícia: trilha de auditoria e documentos

Para uso pericial, ligue a trilha de auditoria (AUTOPSY_AUDIT_LOG, sempre fora do case):

AUTOPSY_AUDIT_LOG=/caminho/fora-do-case/autopsy-audit.ndjson bun run src/index.js
  • Cada chamada de tool vira um registro NDJSON com seq, ts_utc, session, case ativo, consulta/args, resultado (resumo numérico, sem conteúdo de evidência) e duração

  • Trilha por caso: aponte AUTOPSY_AUDIT_LOG para um diretório (ex.: C:\code\audit\trilhas) e cada case ganha seu arquivo audit-<case>-<hash>.ndjson (antes de ativar um case, vai para audit-_session-<hash>.ndjson); um caminho de arquivo (com extensão) mantém a trilha única

  • Os registros são encadeados por hash (prev/hash): editar, remover ou reordenar uma linha quebra a cadeia e é detectável

  • Fail-closed: se o log não puder ser gravado, a operação falha (sem log não há validade)

  • Verificação por terceiro — pela tool verify_audit_log ou pelo CLI:

    bun scripts/audit-verify.mjs /caminho/autopsy-audit.ndjson   # exit 0 = íntegro

Selo do encerramento (hash + arquivamento + assinatura + carimbo RFC 3161):

bun scripts/audit-seal.mjs /caminho/audit.ndjson /caminho/selo.json \
    --archive /arquivo/audit-<data>.ndjson --key chave.pem --cert cadeia.pem \
    --tsa https://freetsa.org/tsr
bun scripts/audit-seal.mjs --verify /caminho/selo.json                        # exit 0 = íntegro
bun scripts/tsa-verify.mjs --seal /caminho/selo.json --ca freetsa-cacert.pem  # valida o carimbo

O algoritmo da assinatura segue a chave: Ed25519, RSA ou EC. Com --cert (AUTOPSY_SEAL_CERT_FILE) de um certificado ICP-Brasil, o certificado e a cadeia entram no selo e a chave é conferida contra ele (não repúdio). Pela interface MCP: tool seal_audit_log (requer AUTOPSY_AUDIT_LOG; opcionais AUTOPSY_TSA_URL, AUTOPSY_SEAL_KEY_FILE, AUTOPSY_SEAL_CERT_FILE). O ato de selar é registrado antes de selar, então o selo cobre esse registro; novos registros depois invalidam o selo (refaça ao encerrar). O carimbo é best-effort: sem TSA acessível o selo sai com timestamp.ok=false e o motivo. A verificação não confia no próprio código: audit-seal.mjs --verify roda um oráculo externo (openssl) para conferir a assinatura, e tsa-verify.mjs confere o imprint e a cadeia do carimbo.

Documentos operacionais em docs/pericia/:

Documento

Uso

laudo-pericial-template.md

Laudo em 10 seções, com o formato de citação de achado

cadeia-de-custodia.md

Ficha de custódia, etapas do art. 158-B e tabela de hashes

checklist-validade.md

Checklist antes/durante/depois + o que fazer quando algo falha

A skill pericia-forense (config do agente) e o agente perito-forense aplicam este fluxo automaticamente: validade jurídica primeiro, análise depois.

Compatibilidade com versões do Autopsy

O server fala com o autopsy.db, então funciona com cases de qualquer Autopsy 4.x: não depende de qual versão criou o case, nem do Autopsy estar instalado. Testamos contra o schema 9 (incluindo o 9.6 dos cases reais que examinamos), que é o dos 4.x mais antigos, e contra o schema atual.

Na prática ele detecta o que existe em vez de assumir:

Como

Onde

Tabelas/colunas opcionais são detectadas antes do uso (hasTable, columns)

src/tools.js

Tags: usa knownStatus quando existe, senão content_tags, senão blackboard_artifact_tags

browse_tags

Timeline: usa tsk_events quando existe (eventos com tipo/descrição) e cai para os MAC times de tsk_files quando não

browse_timeline

Contas de SO (tabela tsk_os_accounts, Autopsy 4.19+): sem ela, a tool degrada explicando

get_os_accounts

get_case_summary devolve schema_major, schema_minor e tsk_version e avisa o que o schema não guarda (ex.: nome/número/data do case, que o 4.x mantém fora do DB)

get_case_summary

Tabela ausente vira erro com hint explicativo ("no such table → ..."), não stack trace

src/db.js

Regressão: tests/legacy-schema.test.js cobre esses caminhos com um schema 9.6 sintético.

Isto é sobre ler cases. O MCP oficial do Autopsy é outro produto — veja Conformidade.

Conformidade com a spec do MCP

O MCP oficial do Autopsy só existe a partir do 4.23.0 (2026-04-15, "MCP over STDIO Server (Windows only)"; o 4.23.1, de 2026-05-07, é o atual) — antes disso não havia MCP no Autopsy, e ele só enxerga o case aberto no Autopsy rodando.

Nosso server anuncia additionalProperties: false em toda tool e recusa parâmetro desconhecido com um erro que nomeia a chave (via strictSchema()). Num contexto pericial isso não é cosmético: um typo no filtro não pode devolver resultado não filtrado como se fosse filtrado. Regressão em tests/strict-input.test.js.

Também contribuímos com os defeitos equivalentes encontrados no MCP oficial do Autopsy — só conformidade, sem nenhuma feature nossa:

Onde

O quê

PR sleuthkit/autopsy#8039

envelope ListToolsResult no tools/list, passagem direta no wrapper de stdio e additionalProperties: false (4 arquivos)

docs/upstream/coroner-conformance/

patch, ISSUE.md com a reprodução e a seção "o que não é bug"

probe-conformance.mjs

sonda HTTP crua (sem SDK) que lista as violações do bridge

verify/run.sh

JUnit real, vermelho→verde, sem precisar do build do Autopsy

verify/run-wrapper.sh

lado JS: self-test do wrapper + cliente do SDK oficial por stdio, vermelho→verde

Benchmark

nosso MCP × os de Autopsy/DFIR existentes, com fontes e o roadmap

Lição que ficou do episódio: o tools/list do Java devolvia um array e o wrapper de stdio criava o envelope — consertar só o Java duplicaria o envelope ({"tools":{"tools":[…]}}) e quebraria o Claude Desktop. Formato que atravessa mais de um componente tem consumidor real em cada ponta.

Desenvolvimento

bun test                # 120 testes: tools, readonly, custódia, protocolo MCP, auditoria/selo, entrada estrita
bun run test:coverage   # idem, com cobertura
bun run lint            # biome
bun run typecheck       # JSDoc via tsc

Arquitetura: src/db.js (readonly + hints) → src/tools.js (funções puras) → src/server.js (camada MCP). Veja AGENTS.md.

Licença

GPL-3.0-or-later — veja LICENSE. Copyright (C) 2026 Gutem.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform digital forensics analysis including memory analysis, file metadata inspection, and threat-intelligence lookups.
      8 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server that exposes Autopsy digital forensics case data as tools, enabling LLM clients like Cline to browse filesystems, query artifacts, and search keywords without modifying the case.
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to perform digital forensics and incident response tasks by dynamically discovering and utilizing host tools for memory analysis, metadata extraction, threat detection, and file dissection.
      5
      1
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to run container forensics, generate container obituaries, and audit git repository history as native MCP tools, producing markdown reports they can reason over.
      3
      6
      MIT