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

Warum kernagent?

• Von Natur aus headless — läuft in CI/Docker; keine IDA/Ghidra-UI, kein MCP erforderlich
• Belege statt Bauchgefühl — jede Antwort zitiert Funktionen, Xrefs, Imports, Strings und Dekompilierungs-Schnipsel
• Deterministisch & portabel — gleiche Binärdatei → gleicher Snapshot → gleicher Bericht; leicht zu diffen und zu archivieren
• Modell-agnostisch — funktioniert mit jedem /v1/chat/completions-LLM-Endpoint (OpenAI, Gemini, Ollama, LM Studio, dein Gateway)

🚀 Schnellstart

Voraussetzungen

• Docker (Engine oder Desktop) und Git
• 64-Bit-Betriebssystem (x86_64 oder ARM64)
• 4 GB RAM (8+ GB empfohlen für große Samples)
• Zugriff auf einen LLM-Endpoint (Internet oder ein lokales /v1/chat/completions-Gateway wie Ollama oder LM Studio)

Installation

Wähle den Ablauf, der zu deinem Tooling passt. Alle Optionen binden ~/.config/kernagent/config.env ein, sodass du Zugangsdaten nur einmal konfigurierst.

Option 1 — install.sh-Wrapper (Linux / macOS / WSL2)

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

Falls der Einzeiler blockiert ist:

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

Oder zuerst klonen:

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

Das Installationsskript führt Folgendes aus (vollständig überprüfbar in scripts/):

1. Prüft, ob Docker installiert ist und läuft
2. Zieht das vorgefertigte ghcr.io/karib0u/kernagent:latest-Image aus der GitHub Container Registry (kein Build-Schritt)
3. Installiert diese Shell-Skripte nach /usr/local/bin/:
   • kernagent — Haupt-CLI-Wrapper (bindet Binärdateien und Konfiguration automatisch ein)
   • kernagent-config — interaktiver Konfigurationseditor
   • kernagent-update — auf neueste/getaggte Version aktualisieren
   • kernagent-uninstall — entfernt alle installierten Dateien
4. Speichert Versionsinformationen unter ~/.config/kernagent/.version

Alle Skripte sind einfacher Shell-Code, den du vor dem Ausführen in scripts/ einsehen kannst. Kein sudo erforderlich, außer /usr/local/bin ist nicht beschreibbar.

Erweitert — Installation auf einen Tag/Commit festlegen

Um eine bestimmte Version des Wrappers und des Images zu installieren, verweist du den Bootstrapper auf ein getaggtes Skript und übergibst den 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

Du kannst auch auf einen exakten Commit festlegen, indem du in der Raw-URL vX.Y.Z durch eine Commit-SHA ersetzt.

Option 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

Analysiere Binärdateien, indem du ihr Verzeichnis unter /data einbindest:

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

Unter Windows (PowerShell + Docker Desktop) verwende Windows-absolute Pfade wie C:\malware:/data.

Option 3 — Direktes Docker (jedes Betriebssystem mit Docker)

Vorgefertigtes Image ziehen (empfohlen):

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

Oder lokal bauen:

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

Installation verifizieren

Option 1 (Wrapper):

kernagent --help
kernagent --version

Direkt ausführen:

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

Optionen 2 oder 3 (Docker Compose / rohes Docker):

Verifizieren, indem du die Hilfe ausführst:

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

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

Deinstallation

Option 1 (Wrapper):

kernagent-uninstall

Optionen 2 oder 3 (Docker Compose / rohes Docker):

Lösche einfach das geklonte Repository und entferne die Images:

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

Aktualisierung

Option 1 (Wrapper):

kernagent-update          # auf neueste Version wechseln
kernagent-update --check  # nur prüfen
kernagent-update --tag vX.Y.Z  # auf bestimmte Version festlegen

Optionen 2 oder 3 (Docker Compose / rohes Docker):

Führe erneut docker compose pull oder docker pull ghcr.io/karib0u/kernagent:latest aus.

Screenshots

Summary — Management-Übersicht mit zitierten Artefakten

Ask — fokussierte Q&A mit Xrefs/Dekompilierungs-Ausschnitten

Befehle

Erster Lauf — falls kein <name>_archive/-Snapshot existiert, erstellt kernagent ihn automatisch, bevor es antwortet

summary

Management-Übersicht: Zweck, Fähigkeiten, Schlüsselfunktionen/Imports/Strings, mit Adressen zur Überprüfung

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

ask

Interaktive Q&A über den Snapshot mit sicheren Werkzeugen (Funktionen/Strings/Imports durchsuchen, Callgraph verfolgen, Dekompilierung lesen, Xrefs auflösen)

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

oneshot

Deterministischer Triage-Bericht für CI/Massenanalyse. Klassifizierung: MALICIOUS | GRAYWARE | BENIGN | UNKNOWN

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

Globale Überschreibungen (beliebiger Befehl):

# 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

So funktioniert's (Überblick in 20 Sekunden)

1. Einmal extrahieren — mit Ghidra/PyGhidra einen statischen Snapshot erstellen; CAPA-Regeln ergänzen Hinweise auf Fähigkeiten
2. Nur-Lese-Werkzeuge — ein eingeschränkter Agent (oder deine Skripte) durchläuft den Snapshot sicher
3. Zitierte Antworten — Ergebnisse verweisen immer auf konkrete Artefakte (EAs, Namen, Strings, APIs)

Snapshot-Layout (Ausschnitt)

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

Modellkonfiguration

Einmal erstellen (außerhalb des Repos). Schneller Weg:

kernagent-config

Oder die Datei manuell bearbeiten:

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

Überschreiben über Umgebungsvariablen:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1   # oder dein Gateway
export OPENAI_MODEL=gpt-4o                        # oder dein lokales Modell

Jeder /v1/chat/completions-kompatible Endpoint funktioniert.

Vergleiche (TL;DR)

• MCP/IDE-Plugins — benötigen einen laufenden Disassembler und ein Projekt, oft an eine GUI gebunden
• kernagent — läuft headless und erzeugt einen portablen Snapshot, den du überall analysieren kannst, auch in abgeschotteten Umgebungen (air-gapped)

Design-Garantien

• Nur-Lese
• Nur statisch
• Deterministisch
• Auditierbar

Mitwirken

PRs willkommen

Lizenz

Apache 2.0 — siehe LICENSE