yak

SKILL：yak-skills 総合案内

AI LOAD INSTRUCTION：これは yak-skills ナレッジベースの総合ルーティングです。Yaklang はセキュリティ研究とペネトレーションテスト向けに設計された DSL（ファイル拡張子 .yak）です。最も重要で、最も間違いやすい仕組みは「ホットパッチ（Hot Patch）」です。Yaklang／Yak のホットパッチ／Yakit に関するタスクでは、まずこのページを読んで該当するトピックを選び、必要に応じて対応する skill を参照してください。すべての例は go run common/yak/cmd/yak.go <file> または yak <file> で実行して確認できます。

1. ルーティング表：タスクに応じて参照する skill

タスクの内容	参照する skill
Yakit とは何か、インストール方法、各 UI 領域の機能、エンジンの接続方法、初心者向けの使い方	yakit-basic
yak スクリプトで Yakit に表／グラフ／進捗バー／カード／サイトツリーを表示する方法：yakit.* ライブラリ関数と UI の連携メカニズム	yakit-ui-binding
MITM プロキシでリクエスト／レスポンスを傍受・変更する、トラフィックをミラーリングして分析する、データベースに保存してタグや色を付ける、危険な操作をモックする	mitm-hotpatch
Web Fuzzer の単一 Tab でのパケット送信時の暗号化・復号、署名の注入、スマートリトライ、ビジネス上の失敗判定、fuzztag、関連パラメーターの抽出	webfuzzer-hotpatch
1 か所の設定を MITM とすべての Fuzzer で共有する：全サイトの透過的な暗号化・復号、統一署名、動的 challenge、全サイトの色付けガードレール	global-hotpatch
Yaklang の構文を読み書きする：変数、制御フロー、関数、クロージャ、f-string、エラー処理 ~	yaklang-syntax
データの永続化とクエリ：SQLite、キー値ストレージ、Payload 辞書、プロジェクト設定	yaklang-database
Yakit ネイティブプラグイン（yak／mitm タイプ）、cli パラメーターフォーム、mitm パッシブスキャン、mitm+cli による外部パラメーターの対話的な読み込みを作成する	yakit-native-plugin
Yakit の右クリック codec プラグイン（handle のみで可）、History の右クリックから flow id を逆引きして抽出（進捗バー）、codec+cli で抽出項目を選択、Web Fuzzer の右クリックによるエンコード／デコードや選択範囲の変換を作成する	yakit-rightclick-plugin
作成したプラグインの検証方法：go run エンジン、hotpatch-*／codec-plugin 検証コマンド、リポジトリを使った MITM のデバッグ	yaklang-toolchain
History からドメイン／URI／Cookie を抽出してパススキャンや Fuzz を行う	yakit-data-extract-plugin

2. 3 層のホットパッチ体系（基本となるメンタルモデル）

ホットパッチを使うと、サービスを中断することなく、Yaklang コードで HTTP トラフィックの処理段階を動的に引き継げます。ホットパッチは 3 層に分かれており、上から順に実行されます。

flowchart TB
    Global["全局热加载 (Global Hot Patch)\nMITM 与所有 Fuzzer 共享, 同时只启用 1 个"] --> Module
    subgraph Module [模块热加载]
        MITM["MITM 热加载\n代理侧: 劫持/镜像/入库/mock"]
        Fuzzer["Web Fuzzer 热加载\n单 Tab: 加解密/签名/重试/fuzztag"]
    end
    Module --> Done["出站 / 回显 / 入库"]

層	適用範囲	代表的な Hook	skill
グローバル	システム全体のすべての MITM／Fuzzer トラフィック。最初に実行	beforeRequest afterRequest hijackSaveHTTPFlow	global-hotpatch
モジュール - MITM	現在の MITM タスク	hijackHTTPRequest hijackHTTPResponseEx mirror* hijackSaveHTTPFlow mockHTTPRequest	mitm-hotpatch
モジュール - Fuzzer	現在の Fuzzer Tab	beforeRequest afterRequest retryHandler customFailureChecker mirrorHTTPFlow	webfuzzer-hotpatch

重要な違い：MITM の傍受系では forward(pkt)/drop() を使って確定します。Fuzzer の beforeRequest/afterRequest では戻り値を使って確定します。Fuzzer の mirrorHTTPFlow(req, rsp, params) と MITM の mirrorHTTPFlow(isHttps, url, req, rsp, body) ではシグネチャが異なります。

3. 共通の書き方：hook 関数 + YAK_MAIN によるセルフテスト

すべてのホットパッチスクリプトは同じ構造に従います。hook を関数変数として登録し、if YAK_MAIN { runSelfTest() } でローカルのセルフテストをガードします。

// 1) 注册 hook (yakit 加载时只做这件事)
hijackHTTPRequest = func(isHttps, url, req, forward, drop) {
    forward(req)
}

// 2) 本地自测 (命令行运行时才跑)
func runSelfTest() {
    // 用 mock 数据 + 自定义 callback + assert 验证 hook 行为
}

if YAK_MAIN {
    runSelfTest()
}

重要：yak は func main() を自動的に呼び出しません。スクリプトの実行時に上から順に実行されるのはトップレベルのステートメントだけです。func main(){} は通常の関数にすぎず、明示的に呼び出す必要があります。そのため、エントリーポイントではトップレベルに if YAK_MAIN { main() }（または if YAK_MAIN { runSelfTest() }）を書くのが規約です。直接 main() を呼び出すと、スクリプトがモジュール／プラグインとして読み込まれた場合にもセルフテストのロジックが実行されてしまいます。

YAK_MAIN は yaklang エンジンから注入されるグローバルブール値です。

• yak xxx.yak／go run common/yak/cmd/yak.go xxx.yak でコマンドラインから実行：エンジンは ExecuteMain を実行し、YAK_MAIN = true を注入します → runSelfTest() が実行されます。
• yakit の MITM／Fuzzer／グローバルホットパッチウィンドウから読み込み：YAK_MAIN = false となります → hook のみが登録され、セルフテストブロックは実行されません。

したがって、セルフテストブロックを含む完全なスクリプトを yakit に貼り付けても絶対に安全です。yakit はモックデータを実行しません。これが「まずコマンドラインでワンクリックセルフテストを行い、その後 yakit に貼り付けて使う」という安全なデバッグサイクルです。

4. テスト規約

# 推荐: 用 yaklang 源码引擎跑 (拿到最新能力)
cd /Users/v1ll4n/Projects/yaklang
go run common/yak/cmd/yak.go <path-to>.yak

# 或用已安装的引擎
yak <path-to>.yak

合格基準：スクリプトが 10 秒以内に完了すること、すべての assert が通ること、log の出力がすべて英語であること、末尾に ... self test passed が表示されること。

5. 開発原則（このライブラリへのコントリビューション時に遵守）

• コメントには中国語を使用できますが、log の出力、文字列の内容、payload はすべて英語にしてください。
• エラー処理には ~ 波浪記号を優先して使い、重要な結果は assert で検証してください。
• grep や AI による検索がしやすいように、重要なコード箇所に // キーワード: ... コメントを追加してください。
• 絵文字は使用せず、ASCII、中文、必要な句読点のみを使用してください。
• きちんと調べることを誇りとし、インターフェースを当て推量することを恥としてください。不明な場合は desc(obj) を使うか、直接 go run で試してください。
• 並行処理の安全性：ホットパッチ hook は並行して呼び出されます。トップレベルのグローバルには読み取り専用の定数（キー／IV／ルール）のみを置いてください。hook 内で共有の可変グローバルを書き換えることは絶対に避けてください（グローバル slice に対する直接の append やグローバル map の変更は data race を起こし、クラッシュにつながります）。集約には sync.Map／sync.NewMutex() または db.*／risk.* を使用してください。
• フロントエンドの暗号化に関する各種 HACK や、ユーザーに平文を見せる方法については、webfuzzer-hotpatch の第 5 節にある組み合わせレシピ（examples/combo-*.yak）を参照してください。

参考資料

このライブラリの内容は、Yak Project の公式アカウント記事（yak-project-public）と yaklang.github.io の公式ドキュメントから要点を抽出しています。すべての Hook シグネチャは yaklang のソースコード（common/yak/hook_mixed_plugin_caller.go、common/yak/script_engine_for_fuzz.go）に準拠しています。