yaklang-toolchain

SKILL: Yaklang toolchain and plugin verification

AI LOAD INSTRUCTION: After writing a hot-load or codec plugin, the biggest problem is "how do I confirm it's actually correct". This page gives two verification paths: 1) YAK_MAIN self-test block (logic self-proof); 2) four yak verification commands, using the same gRPC execution path as the Yakit UI to run the script on real requests/responses and print rewrite evidence. It also explains how to use the yaklang repository source to look up Hook contracts and debug MITM. The commands require an engine built from the yaklang repository (see below).

0. Related routes

Main entry:yak
Three types of hot-load writing:mitm-hotpatch / webfuzzer-hotpatch / global-hotpatch
Right-click codec plugin programming:yakit-rightclick-plugin
Historical data extraction scanning:yakit-data-extract-plugin

1. Run scripts with the source engine (go run workflow)

cd /Users/v1ll4n/Projects/yaklang
# 跑任意 .yak（拿到最新引擎能力）
go run common/yak/cmd/yak.go path/to/script.yak

# 构建一次复用更快
go build -o /tmp/yak ./common/yak/cmd/yak.go
/tmp/yak path/to/script.yak

Acceptance criteria: complete within 10 seconds, all assert pass,log all in English, and ... self test passed。

2. Four verification commands (same execution path as Yakit gRPC)

These commands feed the script into the enginethe same Hook execution chain actually used（MixPluginCaller / MutateHookCaller / codec handle), rather than writing a separate simulation, so "the command runs == it also runs in Yakit".

Command	Verification target	Underlying path
`yak hotpatch-mitm`	MITM hot-load	`NewMixPluginCaller().LoadHotPatch` + `CallHijackRequest/ResponseEx` + `Mirror` + `HijackSaveHTTPFlow`
`yak hotpatch-global`	Global hot-load	Same as above, plus `CallBeforeRequest/AfterRequest`(global pipeline order)
`yak hotpatch-webfuzzer`	Web Fuzzer hot-load	`MutateHookCaller` returned by `beforeRequest/afterRequest/mirrorFlow/retryHandler/customFailureChecker` + `{{yak(...)}}` fuzztag
`yak codec-plugin`	Right-click codec plugin	Execute the script and call `handle(input)`

2.1 hotpatch-mitm / hotpatch-global

# 准备一个原始请求文件
printf 'POST /api/order/create HTTP/1.1\r\nHost: shop.example.com\r\nContent-Type: application/json\r\n\r\n{"amount":100,"product_id":42}' > /tmp/req.txt

yak hotpatch-mitm --script skills/mitm-hotpatch/examples/hijack-request.yak --request /tmp/req.txt

The output prints evidence such as the original request / rewritten request / drop status / storage tag. Verify response hijacking with a response:

yak hotpatch-mitm --script x.yak --request /tmp/req.txt --response /tmp/rsp.txt [--https] [--url URL]

hotpatch-global Same parameters, additionally drives beforeRequest/afterRequest, suitable for verifying site-wide transparent encryption/decryption scripts.

2.2 hotpatch-webfuzzer

# 验证 beforeRequest/afterRequest/retryHandler/customFailureChecker
yak hotpatch-webfuzzer --script x.yak --request /tmp/req.txt --response /tmp/rsp.txt

# 验证脚本里定义的 {{yak(...)}} fuzztag
yak hotpatch-webfuzzer --script skills/webfuzzer-hotpatch/examples/fuzztag-handle.yak \
    --request /tmp/req.txt --fuzztag '{{yak(hash|md5,hello)}}'
# -> rendered-fuzztag: [5d41402abc4b2a76b9719d911017c592]

2.3 codec-plugin (right-click codec)

yak codec-plugin --script skills/yaklang-toolchain/examples/codec-rot13.yak --input "Hello, Yak!"
# -> output (len=11): Uryyb, Lnx!

# 也支持从文件读 input
yak codec-plugin --script x.yak --input-file /tmp/payload.bin

Example:examples/codec-rot13.yak; for programming and usage of the right-click codec plugin, see yakit-rightclick-plugin。

3. Debug MITM issues with the yaklang repository

When Hook behavior does not match expectations, or you are unsure of a Hook's signature/semantics, checking the source directly is fastest:

cd /Users/v1ll4n/Projects/yaklang

# 1) 查 Hook 签名与调用方式（MITM/全局都在这里）
grep -n "CallHijackRequest\|CallHijackResponseEx\|hijackSaveHTTPFlow\|MirrorHTTPFlow" \
    common/yak/hook_mixed_plugin_caller.go

# 2) 查 Web Fuzzer 的 6 个 hook 闭包定义
grep -n "beforeRequest\|afterRequest\|retryHandler\|customFailureChecker" \
    common/yak/script_engine_for_fuzz.go

# 3) 找现成测试用例当样例
grep -rn "LoadHotPatch\|hijackHTTPRequest" --include="*_test.go" common/

Debugging points:

For MITM hijacking Hooks, forward/drop on the engine side is func() interface{}, wrapped by constClujore (see common/yakgrpc/grpc_mitm.go); in the script, forward(pkt) means write back the rewritten packet,drop() means discard.
IsPassed(url) decides whether to trigger the Hook according to the filter; by default (no filter) it passes through.
In the script, use desc(obj) to print object methods/fields and confirm whether flow.AddTag / flow.Red() etc. exist.
Reproduce the issue: save the problematic request to a file, and use yak hotpatch-mitm --script ... --request ... to step through the rewrite evidence, which is faster than repeatedly clicking in the UI.

4. How to verify the plugin you wrote (recommended closed loop)

flowchart LR
    W[写 hook + YAK_MAIN 自测] --> S[yak file.yak 自测过]
    S --> C[yak hotpatch-* 命令跑真实请求]
    C --> E[stdout 证据符合预期]
    E --> P[粘回 Yakit 使用]

First write if YAK_MAIN { runSelfTest() }，yak file.yak to let the logic self-prove.
Use the corresponding yak hotpatch-* / codec-plugin command to feed real requests/responses and check the stdout evidence.
Once the evidence is correct, paste the script back into Yakit—YAK_MAIN=false, the self-test block does not execute, safe.

For batch validation of the whole repository scripts and persisting the evidence, see yak-skills/scripts/validate-skills.yak; use the mitm module to start supplementary evidence of the real proxy link, see yak-skills/scripts/mitm-live-demo.yak。

5. Command implementation location (for contribution/troubleshooting)

Command definition:yaklang/common/yak/cmd/yakcmds/hotpatch.go(exports HotPatchValidatorCommands）。
Registration point:yaklang/common/yak/cmd/yak.go（cliGroup("Hot Patch Validators", ...)）。
Unit test:yaklang/common/yak/cmd/yakcmds/hotpatch_test.go （go test ./common/yak/cmd/yakcmds/ -run 'HotPatch|Codec'）。