yak

SKILL: yak-skills general entry point

AI LOAD INSTRUCTION: This is the general routing for the yak-skills knowledge base. Yaklang is a DSL designed for security research and penetration testing (file extension .yak), and its most core and most error-prone mechanism is "Hot Patch." When encountering Yaklang / Yak hot loading / Yakit related tasks, first read this page to select a topic, then drill down to the corresponding skill as needed. All examples can be tested with go run common/yak/cmd/yak.go <file> or yak <file> .

1. Routing table: which skill a task enters

Task signal	Enter skill
What Yakit is, how to install it, what each UI functional area does, how the engine connects, how beginners get started	yakit-basic
How yak scripts make Yakit display tables/charts/progress bars/cards/website trees: yakit.* library functions and UI interaction mechanisms	yakit-ui-binding
In the MITM proxy, hijack/modify requests and responses, mirror-analyze traffic, store in database with tags and coloring, mock dangerous operations	mitm-hotpatch
Web Fuzzer single-Tab request sending encryption/decryption, signature injection, intelligent retry, business failure determination, fuzztag, associated parameter extraction	webfuzzer-hotpatch
One configuration lets MITM and all Fuzzers share: site-wide transparent encryption/decryption, unified signatures, dynamic challenge, site-wide coloring guardrails	global-hotpatch
Write/read Yaklang syntax: variables, control flow, functions, closures, f-string, error handling ~	yaklang-syntax
Data persistence and querying: SQLite, key-value storage, Payload dictionaries, project configuration	yaklang-database
Write Yakit native plugins (yak/mitm types), cli parameter forms, mitm passive scanning, mitm+cli interactive loading of external parameters	yakit-native-plugin
Write Yakit right-click codec plugins (only handle needed), History right-click reverse lookup and extraction by flow id (progress bar), codec+cli selection of extraction items, Web Fuzzer right-click encoding/decoding/selection transformation	yakit-rightclick-plugin
How to verify written plugins: go run engine, hotpatch-* / codec-plugin verification commands, using the repository to debug MITM	yaklang-toolchain
Extract domain/URI/Cookie from History for path scanning and Fuzz	yakit-data-extract-plugin

2. Three-layer hot loading system (core mental model)

Hot loading allows dynamic takeover of HTTP traffic processing stages with Yaklang code while the service is not interrupted . It is divided into three layers, executed top-down:

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["出站 / 回显 / 入库"]

Layer	Scope	Typical Hook	skill
Global	All system-wide MITM/Fuzzer traffic, executed first	beforeRequest afterRequest hijackSaveHTTPFlow	global-hotpatch
Module - MITM	Current MITM task	hijackHTTPRequest hijackHTTPResponseEx mirror* hijackSaveHTTPFlow mockHTTPRequest	mitm-hotpatch
Module - Fuzzer	Current Fuzzer Tab	beforeRequest afterRequest retryHandler customFailureChecker mirrorHTTPFlow	webfuzzer-hotpatch

Key difference: MITM hijacking types use forward(pkt)/drop() to submit; the Fuzzer's beforeRequest/afterRequest uses return value to submit. The Fuzzer's mirrorHTTPFlow(req, rsp, params) and MITM's mirrorHTTPFlow(isHttps, url, req, rsp, body) signatures are different.

3. Unified writing style: hook function + YAK_MAIN self-test

All hot loading scripts follow the same structure—register hooks as function variables, then use if YAK_MAIN { runSelfTest() } to guard local self-test:

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

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

if YAK_MAIN {
    runSelfTest()
}

Important: yak will not automatically call func main()When a script executes, only top-level statements run from top to bottom,func main(){} is just an ordinary function and must be explicitly called. So the entry convention is to write at the top level if YAK_MAIN { main() }(or if YAK_MAIN { runSelfTest() }), rather than directly main(). Directly main() will cause the self-test logic to also execute when the script is loaded as a module/plugin.

YAK_MAIN is a global boolean variable injected by the yaklang engine:

• yak xxx.yak / go run common/yak/cmd/yak.go xxx.yak Command-line run: the engine goes through ExecuteMain, injects YAK_MAIN = true → runs runSelfTest()。
• yakit MITM / Fuzzer / global hot-reload window loading:YAK_MAIN = false → only registers hooks, the self-test block does not execute.

Therefore:pasting the complete script containing the self-test block back into yakit is absolutely safe—yakit will not run your mock data. This is the safe debugging loop of "first one-click self-test on the command line, then paste back into yakit for use".

4. Testing conventions

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

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

Pass criteria: the script completes within 10 seconds, all assert pass,log output is all in English, and at the end appears ... self test passed。

5. Engineering principles (follow when contributing to this library)

• Comments may be in Chinese, but log output, string contents, and payloads must all be in English.
• For error handling, prefer ~ tilde; verify key results with assert .
• Add // 关键词: ... comments at key code locations, to facilitate grep and AI retrieval.
• Do not use emoji; use only ASCII, Chinese, and necessary punctuation.
• Take pride in carefully consulting references, and be ashamed of guessing interfaces blindly; if unsure, desc(obj) or directly go run to try.
• Concurrency safety: hot-reload hooks will be concurrently called. At the top level, put only read-only constants(keys/IV/rules),never write shared mutable globals inside hooks(bare append global slices, modifying global maps will crash with a data race); for aggregation use sync.Map/sync.NewMutex() or db.*/risk.*。
• Various frontend encryption HACKs / letting users see plaintext: see webfuzzer-hotpatch Section 5 combination recipes (examples/combo-*.yak）。

Reference sources

The content of this library is distilled from Yak Project official account articles (yak-project-public) and the yaklang.github.io official documentation; all Hook signatures are based on the yaklang source code (common/yak/hook_mixed_plugin_caller.go、common/yak/script_engine_for_fuzz.go).