yakit-native-plugin

SKILL：Yakit ネイティブプラグイン（yak / mitm）と cli パラメーター

AI LOAD INSTRUCTION：Yakit プラグインには、「ネイティブプラグイン」（YakScript として保存され、専用の実行ページとパラメーターフォームがある）と「ホットリロード」（MITM/Fuzzer タブ内のインラインコード）があります。このページでは、ネイティブプラグインと cli パラメーター体系に焦点を当てます。cli.* の呼び出しは Yakit によって静的にスキャンされ、パラメーターフォームに変換されます。実行時には、ユーザーが入力した値がスクリプトに注入されます。実行可能なサンプルを3つ紹介します。cli で入力を受け取る yak ネイティブプラグイン、複雑なコンテンツを受動的にスキャンする mitm ネイティブプラグイン、外部パラメーターを読み込む mitm + cli の対話型プラグインです。すべての例は yak <file> でのセルフテストに合格しています。

0. 関連ルート

• 総合エントリーポイント：yak
• MITM のすべての hook と重複排除の仕様（ホットリロードの観点ですが、hook の仕様はネイティブ mitm プラグインと共通です）：mitm-hotpatch
• 右クリック codec プラグイン + cli による抽出項目の選択：yakit-rightclick-plugin
• 履歴データの抽出／辞書／パケット送信：yakit-data-extract-plugin
• データベース／Payload 辞書／risk：yaklang-database
• 検証ツールチェーン：yaklang-toolchain

1. ネイティブプラグインとホットリロード（まず違いを把握する）

観点	ネイティブプラグイン（本ページ）	ホットリロード（hot patch）
形式	YakScript として保存され、名前／種類／パラメーターを持つ	MITM/Fuzzer タブ内のインラインコード片
パラメーター	cli.* で定義し、Yakit がフォームを描画する	専用フォームはなく、コードを直接変更する
エントリーポイント	トップレベルのステートメントを直接実行する（yak タイプ）。mitm タイプは hook を登録する	hook 関数を登録する
用途	チームで再利用する「完成済みツール」	トラフィックの一時的な変更／迅速な試行
本リポジトリの関連項目	本ページ	mitm-hotpatch / webfuzzer-hotpatch / global-hotpatch

重要：mitm ネイティブプラグインと MITM ホットリロードでは、同じ hook（hijackHTTPRequest / mirror* / hijackSaveHTTPFlow ...）を使用します。仕様については mitm-hotpatch を参照してください。違いは、ネイティブプラグインでは cli パラメーターフォームを追加でき、完成品として保存／配布できる点だけです。

2. cli パラメーターから Yakit フォームコントロールへの対応（主要な対応表）

cli.* はすべてトップレベル（モジュールの読み込み時に実行）に記述します。これにより、Yakit がパラメーターを静的にスキャンできるようになります。実行時には、エンジンがユーザーの入力値を注入します。

cli 関数	戻り値の型	Yakit コントロール	説明
cli.String(name)	string	1行テキスト	最もよく使います
cli.Text(name)	string	複数行テキストボックス	長文向け
cli.Int(name)	int	数値
cli.Float(name)	float	数値
cli.Bool(name)	bool	スイッチ	値が存在すれば true
cli.Urls(name)	[]string	URL リスト	http(s):// を自動補完
cli.Ports(name)	[]int	ポート	80,443,8000-8010 に対応
cli.Hosts(name)	[]string	ネットワークターゲット	CIDR の展開に対応
cli.StringSlice(name)	[]string	ドロップダウン／複数選択	setSelectOption と組み合わせてドロップダウンを設定
cli.File(name)	[]byte	ファイル	ファイルの内容を読み込む
cli.FileOrContent(name)	[]byte	ファイルまたはテキスト	ファイルを読み込めない場合はテキストとして扱う
cli.LineDict(name)	[]string	ファイルまたは複数行	行単位で分割（カンマではありません）
cli.YakitPlugin()	[]string	プラグイン選択	yakit-plugin-file を読み込む
cli.Json(name)	map	複雑なフォーム	setJsonSchema と組み合わせて設定

オプション関数（option。後続の引数として渡します）：

オプション	役割
cli.setRequired(true)	必須項目にします。未入力の場合、cli.check() がヘルプを表示して終了します
cli.setDefault(v)	デフォルト値
cli.setVerboseName("中文名")	フォームに表示するラベル
cli.setHelp("...")	ヘルプの説明
cli.setCliGroup("分组名")	パラメーターのグループ
cli.setSelectOption("显示名","值")	ドロップダウンの選択肢（cli.StringSlice のみ）
cli.setMultipleSelect(false)	複数選択の可否（cli.StringSlice のみ）

最後に必ず cli.check() を呼び出してください。必須項目を検証し、未入力の場合は Usage を表示して os.Exit(1) を実行します。

target = cli.String("target", cli.setVerboseName("目标"), cli.setRequired(true))
ports  = cli.Ports("ports", cli.setDefault("80,443"))
mode   = cli.StringSlice("mode",
    cli.setSelectOption("快速", "fast"), cli.setSelectOption("深度", "deep"),
    cli.setMultipleSelect(false), cli.setDefault("fast"))
cli.check()

3. 優れたサンプル3選（examples/）

サンプル	ファイル	要点
cli で入力を受け取る yak ネイティブプラグイン	examples/yak-cli-input.yak	cli.Urls/Ports/Int/Bool + cli.check()。主要なロジックを純粋関数に分離し、セルフテストしやすくする
複雑なコンテンツを受動的にスキャンする mitm ネイティブプラグイン	examples/mitm-passive-scan.yak	mirrorNewWebsitePathParams でレスポンスボディ内の携帯電話番号／身分証番号／JWT／AKSK をスキャンし、検出時に risk.NewRisk を呼び出す
外部パラメーターを対話的に読み込む mitm + cli	examples/mitm-cli-interactive.yak	cli.LineDict で外部のキーワード辞書を読み込み、cli.String でスコープを限定する。hook のクロージャーが値をキャプチャしてスキャンを実行する

3.1 yak ネイティブプラグイン + cli（優れたサンプル 1）

yak タイプのプラグインでは、トップレベルのステートメントがエントリーポイントです（yak は func main() を自動的に呼び出しません）。実際のプラグインでは、トップレベルで cli パラメーターを読み込み、メインの処理を実行します。

func runPlugin() {
    targets = cli.Urls("target", cli.setRequired(true))
    ports = cli.Ports("ports", cli.setDefault("80,443"))
    cli.check()
    // ... 用参数做扫描/发包
}
runPlugin()   // 真实插件: 顶层直接调用

主要なロジック（ターゲットの正規化、重複排除）を純粋関数に分離することで、YAK_MAIN セルフテストブロック内でコマンドラインやネットワークから切り離し、繰り返し検証できるようになります。

3.2 mitm ネイティブプラグインによる受動スキャン（優れたサンプル 2）

mitm プラグインでは main を記述せず、hook を登録します。受動スキャンには mirrorNewWebsitePathParams が最適です（パスとパラメーターの構造で重複を排除するため、計算コストを抑えられ、読み取り専用で転送に影響しません）。

mirrorNewWebsitePathParams = func(isHttps, url, req, rsp, body) {
    for f in scanSensitive(string(body)) {      // scanSensitive 是纯函数, 可自测
        risk.NewRisk(url, risk.title(...), risk.type("info-leak"),
            risk.severity("low"), risk.payload(f.value))
    }
}

• ルールテーブルはトップレベルの読み取り専用定数にします（並行実行される hook 内でグローバル変数を変更しないでください。データ競合が発生します）。
• 検出結果は risk.NewRisk(...) で生成し、Yakit の「リスクと脆弱性」パネルに表示できます。
• セルフテストでは scanSensitive の純粋なロジックだけをテストし、risk は呼び出しません（データベースへの書き込みを避けるため）。

3.3 mitm + cli による対話型プラグイン（優れたサンプル 3）

同じ mitm プラグインで、cli を使って「キーワード辞書」と「スコープ」をパラメーターにできます。対象を変更してもコードを編集する必要はありません。

KEYWORDS = cli.LineDict("keywords", cli.setDefault("password\ntoken\nsecret"))  // 顶层读取
SCOPE    = cli.String("scope", cli.setDefault(""))
cli.check()

mirrorHTTPFlow = func(isHttps, url, req, rsp, body) {   // 闭包捕获 KEYWORDS/SCOPE
    if !inScope(url, SCOPE) { return }
    for kw in matchKeywords(string(rsp), KEYWORDS) { risk.NewRisk(url, ...) }
}

連携のポイント：cli はトップレベルで一度だけ読み込み、hook のクロージャーは実行時にこれらの値を繰り返し使用します。cli.LineDict は行単位で分割します。CSV にも対応させる場合は、独自に str.Split(line, ",") でもう一度分割してください（サンプルの flattenKeywords を参照）。

4. 标准写法: 入口 + YAK_MAIN 自测

// yak 类型: 顶层执行; mitm 类型: 注册 hook + 顶层 cli
mirrorHTTPFlow = func(isHttps, url, req, rsp, body) { /* ... */ }

func runSelfTest() { /* 用纯函数 + mock 数据 + assert 验证 */ }

if YAK_MAIN {
    runSelfTest()
}

YAK_MAIN 是引擎注入的全局布尔:

• yak xxx.yak 命令行运行: YAK_MAIN = true -> 跑自测。
• Yakit 加载插件: 顶层 cli/hook 注册照常执行, 自测块按需守卫。

注意: cli.Args() 永远包含脚本文件名(长度 >= 1)。想区分"自测 / 真实带参运行"用 len(cli.Args()) > 1 判断(见 yak-cli-input.yak)。

5. 验证

cd /Users/v1ll4n/Projects/yaklang
# 自测(走默认/纯逻辑)
yak skills/yakit-native-plugin/examples/yak-cli-input.yak
# 体验真实参数注入
yak skills/yakit-native-plugin/examples/yak-cli-input.yak --target "yaklang.com,example.com:8443" --ports 80,443 --probe

合格标准: 10 秒内完成、所有 assert 通过、log 全英文、末尾出现 ... self test passed。 mitm 原生插件可进一步用 yak hotpatch-mitm 喂真实请求验证(见 yaklang-toolchain)。

参考来源

• cli 参数体系: yaklang/common/utils/cli/cli.go(CliExports)
• mitm hook 契约: yaklang/common/yak/hook_mixed_plugin_caller.go
• risk API: yaklang/common/yak/yaklib/risk.go(risk.NewRisk / risk.title / risk.severity ...)
• 训练素材交叉引用: yaklang-ai-training-materials/library-usage/cli、.../risk