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

Perché kernagent?

• Senza interfaccia grafica — funziona in CI/Docker; nessuna interfaccia IDA/Ghidra, nessun MCP richiesto
• Prove, non sensazioni — ogni risposta cita funzioni, riferimenti incrociati, importazioni, stringhe e frammenti di decompilazione
• Deterministico e portatile — stesso binario → stessa istantanea → stesso report; facile da confrontare e archiviare
• Indipendente dal modello — funziona con qualsiasi endpoint LLM /v1/chat/completions (OpenAI, Gemini, Ollama, LM Studio, il tuo gateway)

🚀 Avvio rapido

Requisiti

• Docker (Engine o Desktop) e Git
• Sistema operativo a 64 bit (x86_64 o ARM64)
• 4 GB di RAM (8+ GB consigliati per campioni grandi)
• Accesso a un endpoint LLM (internet o un gateway /v1/chat/completions locale come Ollama o LM Studio)

Installazione

Scegli il flusso che si adatta ai tuoi strumenti. Tutte le opzioni montano ~/.config/kernagent/config.env così configuri le credenziali una volta sola.

Opzione 1 — wrapper install.sh (Linux / macOS / WSL2)

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

Se il comando singolo è bloccato:

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

Oppure clona prima:

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

Lo script di installazione fa quanto segue (completamente verificabile in scripts/):

1. Verifica che Docker sia installato e in esecuzione
2. Scarica l'immagine precompilata ghcr.io/karib0u/kernagent:latest dal GitHub Container Registry (nessuna fase di build)
3. Installa questi script shell in /usr/local/bin/:
   • kernagent — wrapper CLI principale (monta automaticamente binari e configurazione)
   • kernagent-config — editor di configurazione interattivo
   • kernagent-update — aggiorna all'ultima versione/taggata
   • kernagent-uninstall — rimuove tutti i file installati
4. Salva le informazioni sulla versione in ~/.config/kernagent/.version

Tutti gli script sono semplici script shell che puoi esaminare in scripts/ prima di eseguirli. Non è richiesto sudo a meno che /usr/local/bin non sia scrivibile.

Avanzato — installazione fissata a un tag/commit

Per installare una versione specifica del wrapper e dell'immagine, punta il bootstrapper a uno script taggato e passa il 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

Puoi anche fissare un commit esatto sostituendo vX.Y.Z con lo SHA del commit nell'URL grezzo.

Opzione 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

# Scarica l'immagine precompilata (consigliato)
docker compose pull

# Oppure compila localmente per sviluppo
docker compose build

docker compose run --rm kernagent --help

Analizza i binari montando la loro directory sotto /data:

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

Su Windows (PowerShell + Docker Desktop), usa percorsi assoluti in stile Windows come C:\malware:/data.

Opzione 3 — Docker diretto (qualsiasi OS con Docker)

Scarica l'immagine precompilata (consigliato):

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

Oppure compila 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

Verifica installazione

Opzione 1 (wrapper):

kernagent --help
kernagent --version

Esegui direttamente:

kernagent summary /path/to/binary.exe
kernagent ask /path/to/binary.exe "Cosa fa questo binario?"
kernagent oneshot /path/to/binary.exe

Opzioni 2 o 3 (Docker Compose / Docker grezzo):

Verifica eseguendo help:

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

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

Disinstallazione

Opzione 1 (wrapper):

kernagent-uninstall

Opzioni 2 o 3 (Docker Compose / Docker grezzo):

Basta eliminare il clone e rimuovere le immagini:

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

Aggiornamento

Opzione 1 (wrapper):

kernagent-update          # passa all'ultima versione
kernagent-update --check  # solo controllo
kernagent-update --tag vX.Y.Z  # fissa a una versione specifica

Opzioni 2 o 3 (Docker Compose / Docker grezzo):

Esegui di nuovo docker compose pull o docker pull ghcr.io/karib0u/kernagent:latest.

Schermate

Summary — panoramica esecutiva con artefatti citati

Ask — domande e risposte mirate con riferimenti incrociati e frammenti di decompilazione

Comandi

Prima esecuzione — se non esiste un'istantanea <nome>_archive/, kernagent la costruisce automaticamente prima di rispondere

summary

Panoramica esecutiva: scopo, capacità, funzioni/importazioni/stringhe chiave, con indirizzi per la verifica

kernagent summary /path/to/binary
# JSON grezzo (per automazione)
kernagent summary /path/to/binary --json

ask

Domande e risposte interattive sull'istantanea usando strumenti sicuri (cerca funzioni/stringhe/importazioni, segui il grafo delle chiamate, leggi decompilazione, risolvi riferimenti incrociati)

kernagent ask /path/to/binary "Mostra la logica C2 sospetta e le prove."

oneshot

Report di triage deterministico per CI/analisi in batch. Classificazione: MALICIOUS | GRAYWARE | BENIGN | UNKNOWN

kernagent oneshot /path/to/binary
# JSON grezzo (per automazione)
kernagent oneshot /path/to/binary --json

Override globali (qualsiasi comando):

# verbosità e override del modello/API per esecuzione
kernagent -v --model gpt-4o \
  --base-url https://api.openai.com/v1 \
  --api-key sk-... \
  summary /path/to/binary

Come funziona (panoramica in 20 secondi)

1. Estrai una volta — costruisci un'istantanea statica con Ghidra/PyGhidra; le regole CAPA aggiungono suggerimenti sulle capacità
2. Strumenti solo lettura — un agente limitato (o i tuoi script) attraversa l'istantanea in sicurezza
3. Risposte citate — i risultati fanno sempre riferimento ad artefatti concreti (indirizzi effettivi, nomi, stringhe, API)

Struttura dell'istantanea (sottoinsieme)

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

Configurazione del modello

Crea una volta (fuori dal repository). Percorso rapido:

kernagent-config

Oppure modifica il file manualmente:

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

Override tramite variabili d'ambiente:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1   # o il tuo gateway
export OPENAI_MODEL=gpt-4o                        # o il tuo modello locale

Qualsiasi endpoint compatibile con /v1/chat/completions funziona.

Confronti (TL;DR)

• Plugin MCP/IDE — necessitano di un disassemblatore in esecuzione e di un progetto, spesso vincolati all'interfaccia grafica
• kernagent — funziona senza interfaccia grafica e produce un'istantanea portatile che puoi analizzare ovunque, anche in ambienti isolati

Garanzie di progettazione

• Sola lettura
• Solo statico
• Deterministico
• Verificabile

Contributi

PR benvenuti

Licenza

Apache 2.0 — vedi LICENSE