企业官网建设流程全解析

5步为anti-mage编写新检测节：sectionFunc接口完整开发教程

【免费下载链接】anti-mageFor detecting anti-detect browsers and spoofed profiles through runtime coherence analysis.项目地址: https://gitcode.com/gh_mirrors/an/anti-mage

快速了解：anti-mage 的检测节是什么

anti-mage是一个用 Go 语言编写的浏览器环境一致性检测工具，它不靠"指纹签名"，而是让浏览器自己说的两句话互相作证——一旦矛盾，就记录在案。🔍

整个检测引擎位于 internal/scan/，由22 个检测节（Section）组成：平台声明、字体、屏幕几何、时区、WebRTC、Canvas……每个检测节都是同一个接口sectionFunc的实现。理解了sectionFunc，你就能亲手为 anti-mage 加一节新检测。

本文是一份面向初学者的开发教程：从接口参数到注册上线，5 步走完全流程，并附项目里真实检测节总结的最佳实践。

第 1 步：理解一个检测节的三个输入

sectionFunc的定义只有一行，位于 internal/scan/scan.go：

type sectionFunc func(Request, Inputs, claim) Section

三个参数各有分工，这也是 anti-mage 设计上的巧妙之处：

• Request：客户端按 id 提交的观测值集合。检测节里不用自己解析 JSON，直接用三个辅助方法：r.ran(id)（采没采）、r.unsupported(id)（明确不支持）、r.value(id)（取值），定义见 internal/scan/payload.go。
• Inputs：必须由服务端在扫描发起前就选定（时钟、随机数等），客户端无法预知，防止"背答案"。
• claim：引擎统一从 UserAgent、navigator.platform、UAData 三个表面解析出的系统声明，见 internal/scan/claim.go。

检测节只需要返回一个Section：一个判定（Determination）加若干证据行（Rows）。就这么简单。

第 2 步：给检测节搭骨架

以项目里最简洁的检测节之一"权限状态一致性"为模板，它的完整实现在 internal/scan/sec_permissions.go。骨架如下：

func sectionMyCheck(r Request, in Inputs, c claim) Section { s := Section{Determination: Inconclusive} // 默认"证据不足" raw, ok := r.value("my.probe.id") if !ok { // 没采到数据：如实降级，绝不猜测 s.Determination = Unverified s.Rows = append(s.Rows, Row{Label: "my probe", Value: "not collected"}) return s } // ……比较"浏览器说的两件事"…… // 矛盾 -> Contradiction；一致 -> Consistent return s }

三个要点（来自现有 22 个检测节的共同写法）：

1. 先写"数据缺失"分支。任何探针都可能缺席，缺席就降级为Unverified或Inconclusive，而不是默认通过、更不允许 panic。
2. 判定需要至少两个事实。anti-mage 的哲学是"一致性"：单条读出不产生判定，两个互相矛盾的事实才产生Contradiction。
3. 行内文本要克制。长值用引擎自带的clip()截断（如clip(raw, 200)），保持报告紧凑。

第 3 步：看懂五种判定值及其权重

判定值在 internal/scan/scan.go 定义，共 5 种：

汇总逻辑在 internal/scan/band.go 的summarise()：它把各节权重按独立证据相乘折算，最终给出 0–100 的分数（按 10 取整）和一句话结论。写检测节时不需要关心总分——你只负责诚实地给出判定，权重系统会自己处理。

第 4 步：注册到检测顺序表

anti-mage 的检测节注册是"表格驱动"的，全部顺序表在 internal/scan/scan.go：

var order = []struct { id string title string build sectionFunc }{ // ……现有 22 个检测节…… {"permissions", "Permission state coherence", sectionPermissions}, {"mycheck", "一句话标题说明这一节验什么", sectionMyCheck}, // ← 加在这里 }

• id：小写短标识，用于报告中的section.id，建议与探针 id 前缀呼应；
• title：面向读者的短语，描述"这一节让哪两个事实互证"，而不是"检查了什么 API"。

AnalyzeWith会按此表逐一调用你的检测节，并对返回值做normalise兜底（非法判定自动降级为Inconclusive），所以你无需担心忘了初始化Rows。

第 5 步：为新检测节写测试

项目惯例是"一节一测试文件"。参考 internal/scan/sec_permissions_test.go 的写法，每种判定至少一个用例：

func TestMyCheckContradictsWhenFactsDisagree(t *testing.T) { got := sectionMyCheck(requestWithProbe(`{"a":"x","b":"y"}`), Inputs{}, claim{}) if got.Determination != Contradiction { t.Fatalf("determination = %q, want contradiction", got.Determination) } }

推荐覆盖 4 类场景：无数据、数据畸形、两事实一致、两事实矛盾。跑一遍项目检查即可：

make check

它会自动执行gofmt、go vet和全部测试（见 Makefile）。

最佳实践清单

从现有检测节（如 sec_time.go 时区节、sec_platform.go 平台节）提炼的 6 条经验：

• ✅优雅降级优先：缺探针 →Unverified；探针存在但取值无法核验 → 同样Unverified。浏览器从不因"缺少某功能"被扣分。
• ✅容忍格式漂移：客户端字段常有别名（如时区节同时接受timeZone/zone、offsetMinutes/offset），用多路径取值而不是强求一种格式。
• ✅善用服务端 Inputs：需要随机性时（采样时刻、对照字体），从Inputs取，绝不自己time.Now()——检测节必须是纯函数。
• ✅查无此表就弃权：涉及常量表（如时区库）时，查不到即返回Unverified；引用 reference/ 包的数据要尊重其Verified标志，未验证的表不能当证据。
• ✅一个事实不算矛盾：只有"浏览器说的两件事"（或"说的 vs 能力"）冲突才定Contradiction。
• ✅用调试工具肉眼验证：项目自带 tools/debugscan/，把探针 JSON 喂进去即可打印各节判定，不用起完整服务：

go run ./tools/debugscan probes.json

常见问题

Q：新检测节会影响旧客户端吗？

不会。探针 id 是宽松的：服务端忽略未知 id，新客户端对旧服务端照常工作。你的检测节只在对应探针存在时才产生判定，否则安静地输出Unverified。

Q：判定值能自定义吗？

不建议。五种判定是汇总器 band.go 的契约，normalise会把不认识的判定悄悄降级为Inconclusive——你的节会白跑一趟。

Q：从哪个检测节开始读起最快上手？

推荐顺序：先看最薄的 sec_permissions.go（两个读法互证），再看逻辑最完整的 sec_time.go（多采样、服务端时刻、DST 守护窗口），最后挑战 sec_icestate.go 这类状态机式检测。

写在最后

为 anti-mage 写一个新检测节，本质就是三件事：读两个事实、比较它们、诚实报判定。接口小、契约清晰、注册一步到位——这正是它值得学习的工程范式。动手试试吧，从permissions节复制一份改起，你会发现 30 行代码就能给整个引擎加上一双新眼睛。🚀

【免费下载链接】anti-mageFor detecting anti-detect browsers and spoofed profiles through runtime coherence analysis.项目地址: https://gitcode.com/gh_mirrors/an/anti-mage