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

なぜ kernagent なのか？

• 設計上ヘッドレス — CI/Dockerで動作。IDA/GhidraのUI不要、MCP不要
• 雰囲気ではなく証拠 — すべての回答に関数、クロスリファレンス、インポート、文字列、逆コンパイルスニペットを引用
• 決定論的でポータブル — 同じバイナリ→同じスナップショット→同じレポート。差分比較やアーカイブが容易
• モデル非依存 — 任意の /v1/chat/completions LLMエンドポイント（OpenAI、Gemini、Ollama、LM Studio、独自ゲートウェイ）で動作

🚀 クイックスタート

必要条件

• Docker（Engine または Desktop）と Git
• 64ビットOS（x86_64 または ARM64）
• 4 GB RAM（大規模サンプルでは 8 GB以上推奨）
• LLMエンドポイントへのアクセス（インターネットまたは Ollama / LM Studio などのローカル /v1/chat/completions ゲートウェイ）

インストール

使用するツールに応じた方法を選んでください。どの選択肢でも ~/.config/kernagent/config.env をマウントするので、認証情報は一度設定するだけです。

オプション 1 — install.sh ラッパー（Linux / macOS / WSL2）

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

ワンライナーがブロックされた場合:

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

または先にクローン:

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

インストールスクリプトは以下の処理を行います（scripts/ で完全に監査可能）:

1. Docker がインストールされ実行中であることを確認
2. GitHub Container Registry からビルド済みイメージ ghcr.io/karib0u/kernagent:latest をプル（ビルド手順不要）
3. 以下のシェルスクリプトを /usr/local/bin/ にインストール:
   • kernagent — メイン CLI ラッパー（バイナリと設定を自動マウント）
   • kernagent-config — 対話型設定エディタ
   • kernagent-update — 最新版/指定バージョンへの更新
   • kernagent-uninstall — インストールファイルの完全削除
4. バージョン情報を ~/.config/kernagent/.version に保存

すべてのスクリプトはプレーンなシェルコードで、実行前に scripts/ で確認できます。/usr/local/bin が書き込み可能でない場合を除き、sudo は不要です。

上級 — タグ/コミットを指定してインストール

特定のバージョンのラッパーとイメージをインストールするには、ブートストラッパーをタグ付きスクリプトに指定し、タグを渡します:

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

また、raw URL 内の vX.Y.Z をコミットSHAに置き換えることで、正確なコミットに固定することもできます。

オプション 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

# ビルド済みイメージをプル（推奨）
docker compose pull

# または開発用にローカルビルド
docker compose build

docker compose run --rm kernagent --help

バイナリのディレクトリを /data にマウントして解析:

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

Windows（PowerShell + Docker Desktop）では、C:\malware:/data のように Windows 形式の絶対パスを使用してください。

オプション 3 — 直接 Docker 実行（Docker が動作する任意の OS）

ビルド済みイメージをプル（推奨）:

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

またはローカルビルド:

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

インストールの確認

オプション 1（ラッパー）:

kernagent --help
kernagent --version

直接実行:

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

オプション 2 または 3（Docker Compose / raw Docker）:

help を実行して確認:

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

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

アンインストール

オプション 1（ラッパー）:

kernagent-uninstall

オプション 2 または 3（Docker Compose / raw Docker）:

クローンを削除し、イメージを削除するだけ:

docker image rm ghcr.io/karib0u/kernagent:latest
# または
docker image rm kernagent:local

アップデート

オプション 1（ラッパー）:

kernagent-update          # 最新版に切り替え
kernagent-update --check  # 確認のみ
kernagent-update --tag vX.Y.Z  # 特定バージョンに固定

オプション 2 または 3（Docker Compose / raw Docker）:

再度 docker compose pull または docker pull ghcr.io/karib0u/kernagent:latest を実行。

スクリーンショット

サマリー — 証拠付きの概要

Ask — クロスリファレンスと逆コンパイルスライスを用いた集中Q&A

コマンド

初回実行 — <name>_archive/ スナップショットが存在しない場合、kernagent は回答前に自動でビルドします。

summary

概要: 目的、機能、主要関数/インポート/文字列、アドレス付きで検証可能

kernagent summary /path/to/binary
# raw JSON（自動化向け）
kernagent summary /path/to/binary --json

ask

スナップショットに対する対話型Q&A。安全なツール（関数/文字列/インポートの検索、コールグラフの追跡、逆コンパイルの読み取り、クロスリファレンスの解決）を使用

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

oneshot

CI/バルク解析向けの決定論的トリアージレポート。分類: MALICIOUS | GRAYWARE | BENIGN | UNKNOWN

kernagent oneshot /path/to/binary
# raw JSON（自動化向け）
kernagent oneshot /path/to/binary --json

グローバルオーバーライド（任意のコマンド）:

# 詳細度と実行ごとのモデル/APIオーバーライド
kernagent -v --model gpt-4o \
  --base-url https://api.openai.com/v1 \
  --api-key sk-... \
  summary /path/to/binary

動作の仕組み（20秒概要）

1. 一度だけ抽出 — Ghidra/PyGhidra で静的スナップショットを構築。CAPAルールが機能ヒントを追加
2. 読み取り専用ツール — 制限されたエージェント（またはスクリプト）がスナップショットを安全に走査
3. 引用付き回答 — 結果は常に具体的な成果物（EA、名前、文字列、API）を参照

スナップショット構成（一部）

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

モデル設定

一度だけ作成（リポジトリ外）。簡単な方法:

kernagent-config

または手動でファイルを編集:

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

環境変数で上書き:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1   # または自作ゲートウェイ
export OPENAI_MODEL=gpt-4o                        # またはローカルモデル

任意の /v1/chat/completions 互換エンドポイントが使用可能です。

比較（要約）

• MCP/IDE プラグイン — 実行中の逆アセンブラとプロジェクトが必要で、GUIに依存することが多い
• kernagent — ヘッドレスで動作し、どこでも（エアギャップ環境でも）解析可能なポータブルスナップショットを出力

設計上の保証

• 読み取り専用
• 静的のみ
• 決定論的
• 監査可能

コントリビューション

PR大歓迎

ライセンス

Apache 2.0 — LICENSE を参照