_                                            _
    | | _____ _ __ _ __   __ _  __ _  ___ _ __ | |_
    | |/ / _ \ '__| '_ \ / _` |/ _` |/ _ \ '_ \| __|
    |   <  __/ |  | | | | (_| | (_| |  __/ | | | |_
    |_|\_\___|_|  |_| |_|\__,_|\__, |\___|_| |_|\__|
                                |___/

Por que kernagent?

• Headless por design — roda em CI/Docker; sem UI do IDA/Ghidra, sem necessidade de MCP
• Evidências em vez de achismos — toda resposta cita funções, xrefs, imports, strings e trechos de decompilação
• Determinístico e portátil — mesmo binário → mesmo instantâneo → mesmo relatório; fácil de fazer diff e arquivar
• Agnóstico de modelo — funciona com qualquer endpoint LLM /v1/chat/completions (OpenAI, Gemini, Ollama, LM Studio, seu gateway)

🚀 Início rápido

Requisitos

• Docker (Engine ou Desktop) e Git
• SO de 64 bits (x86_64 ou ARM64)
• 4 GB de RAM (8+ GB recomendados para amostras grandes)
• Acesso a um endpoint LLM (internet ou um gateway local /v1/chat/completions, como Ollama ou LM Studio)

Instalação

Escolha o fluxo que corresponde às suas ferramentas. Todas as opções montam ~/.config/kernagent/config.env para que você configure as credenciais uma única vez.

Opção 1 — wrapper install.sh (Linux / macOS / WSL2)

bash <(curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/install.sh)

Se o comando de uma linha for bloqueado:

curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/install.sh -o install.sh
bash install.sh

Ou clone primeiro:

git clone https://github.com/Karib0u/kernagent.git
cd kernagent
bash install.sh

O script de instalação faz o seguinte (totalmente auditável em scripts/):

1. Verifica se o Docker está instalado e em execução
2. Baixa a imagem pré-construída ghcr.io/karib0u/kernagent:latest do GitHub Container Registry (sem etapa de build)
3. Instala estes scripts shell em /usr/local/bin/:
   • kernagent — wrapper principal de CLI (monta automaticamente binários e configuração)
   • kernagent-config — editor interativo de configuração
   • kernagent-update — atualiza para a versão mais recente/com tag
   • kernagent-uninstall — remove todos os arquivos instalados
4. Salva informações de versão em ~/.config/kernagent/.version

Todos os scripts são código shell simples que você pode revisar em scripts/ antes de executar. Não é necessário sudo, a menos que /usr/local/bin não seja gravável.

Avançado — fixar a instalação em uma tag/commit

Para instalar uma versão específica do wrapper e da imagem, aponte o bootstrapper para um script com tag e passe a tag:

KERNAGENT_INSTALL_URL="https://raw.githubusercontent.com/Karib0u/kernagent/vX.Y.Z/scripts/install.sh" \
  bash <(curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/install.sh) --tag vX.Y.Z

Você também pode fixar em um commit exato substituindo vX.Y.Z por um SHA de commit na URL raw.

Opção 2 — Docker Compose (Linux / macOS / Windows + Docker Desktop)

git clone https://github.com/Karib0u/kernagent.git
cd kernagent
mkdir -p ~/.config/kernagent
cp config.env.example ~/.config/kernagent/config.env

# Pull pre-built image (recommended)
docker compose pull

# Or build locally for development
docker compose build

docker compose run --rm kernagent --help

Analise binários montando o diretório deles em /data:

docker compose run --rm \
  -v /absolute/path/to/binaries:/data \
  kernagent summary /data/sample.exe

No Windows (PowerShell + Docker Desktop), use caminhos absolutos no estilo Windows, como C:\malware:/data.

Opção 3 — Docker direto (qualquer SO com Docker)

Baixe a imagem pré-construída (recomendado):

mkdir -p ~/.config/kernagent
curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/config.env.example \
  -o ~/.config/kernagent/config.env

docker pull ghcr.io/karib0u/kernagent:latest
docker run --rm \
  -v /absolute/path/to/binaries:/data \
  -v ~/.config/kernagent/config.env:/config/config.env:ro \
  ghcr.io/karib0u/kernagent:latest summary /data/sample.exe

Ou construa localmente:

git clone https://github.com/Karib0u/kernagent.git
cd kernagent
docker build -t kernagent:local .
docker run --rm \
  -v /absolute/path/to/binaries:/data \
  -v ~/.config/kernagent/config.env:/config/config.env:ro \
  kernagent:local summary /data/sample.exe

Verificar instalação

Opção 1 (wrapper):

kernagent --help
kernagent --version

Execute diretamente:

kernagent summary /path/to/binary.exe
kernagent ask /path/to/binary.exe "What does this binary do?"
kernagent oneshot /path/to/binary.exe

Opções 2 ou 3 (Docker Compose / Docker puro):

Verifique executando o help:

# Docker Compose
docker compose run --rm kernagent --help

# Raw Docker
docker run --rm ghcr.io/karib0u/kernagent:latest --help

Desinstalação

Opção 1 (wrapper):

kernagent-uninstall

Opções 2 ou 3 (Docker Compose / Docker puro):

Basta excluir o clone e remover as imagens:

docker image rm ghcr.io/karib0u/kernagent:latest
# or
docker image rm kernagent:local

Atualização

Opção 1 (wrapper):

kernagent-update          # switch to latest
kernagent-update --check  # check only
kernagent-update --tag vX.Y.Z  # pin to specific version

Opções 2 ou 3 (Docker Compose / Docker puro):

Execute novamente docker compose pull ou docker pull ghcr.io/karib0u/kernagent:latest.

Capturas de tela

Summary — visão geral executiva com artefatos citados

Ask — perguntas e respostas focadas com trechos de xrefs/decompilação

Comandos

Primeira execução — se não existir um instantâneo <name>_archive/, o kernagent o constrói automaticamente antes de responder

summary

Visão geral executiva: propósito, capacidades, funções/imports/strings principais, com endereços para verificação

kernagent summary /path/to/binary
# raw JSON (for automation)
kernagent summary /path/to/binary --json

ask

Perguntas e respostas interativas sobre o instantâneo usando ferramentas seguras (pesquisar funções/strings/imports, seguir o grafo de chamadas, ler decompilação, resolver xrefs)

kernagent ask /path/to/binary "Show suspected C2 logic and evidence."

oneshot

Relatório de triagem determinístico para CI/análise em lote. Classificação: MALICIOUS | GRAYWARE | BENIGN | UNKNOWN

kernagent oneshot /path/to/binary
# raw JSON (for automation)
kernagent oneshot /path/to/binary --json

Sobrescritas globais (qualquer comando):

# verbosity and per-run model/API overrides
kernagent -v --model gpt-4o \
  --base-url https://api.openai.com/v1 \
  --api-key sk-... \
  summary /path/to/binary

Como funciona (visão geral de 20 segundos)

1. Extraia uma vez — construa um instantâneo estático com Ghidra/PyGhidra; as regras CAPA adicionam dicas de capacidade
2. Ferramentas somente leitura — um agente limitado (ou seus scripts) percorre o instantâneo com segurança
3. Respostas com citações — os resultados sempre referenciam artefatos concretos (EAs, nomes, strings, APIs)

Layout do instantâneo (subconjunto)

<name>_archive/
├─ meta.json
├─ functions.jsonl
├─ strings.jsonl
├─ imports_exports.json
├─ callgraph.jsonl
├─ capa_summary.json
└─ decomp/*.c

Configuração do modelo

Crie uma vez (fora do repositório). Caminho rápido:

kernagent-config

Ou edite o arquivo manualmente:

mkdir -p ~/.config/kernagent
cp config.env.example ~/.config/kernagent/config.env
$EDITOR ~/.config/kernagent/config.env

Sobrescreva via variáveis de ambiente:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1   # or your gateway
export OPENAI_MODEL=gpt-4o                        # or your local model

Qualquer endpoint compatível com /v1/chat/completions funciona.

Comparações (TL;DR)

• Plugins MCP/IDE — exigem um disassembler e um projeto em execução, geralmente vinculados à GUI
• kernagent — roda headless e emite um instantâneo portátil que você pode analisar em qualquer lugar, inclusive em redes isoladas (air-gapped)

Garantias de design

• Somente leitura
• Somente estático
• Determinístico
• Auditável

Contribuindo

PRs são bem-vindos

Licença

Apache 2.0 — consulte LICENSE