为 Go 函数生成确定性的语义指纹。使用静态单赋值(SSA)分析和标量演化(Scalar Evolution)检测 xz 风格后门并验证语义等价性。
sfw 是一个针对 Go 源码的静态分析器。它使用 golang.org/x/tools/go/ssa 构建 SSA,将每个函数重写为规范化的 IR,并以该 IR 的 SHA-256 作为函数的指纹。在指纹之上:
sfw diff 逐函数比较两个文件。它通过拓扑结构匹配被重命名的函数,并根据每个变更新触及的能力以及移除的防护、检查和安全设置对其进行评分。sfw deps diff 比较模块的两棵目录树编译进来的第三方代码:发生变更的函数、新触及某项能力的导出函数,以及分析无法看到的变更文件。sfw audit 将 diff 中的高风险变更、其源码和提交信息发送给 LLM,由 LLM(通过工具、使用 Claude 模型)阅读代码,并判断提交信息是否描述了该变更。sfw index 和 sfw scan 将函数拓扑与签名库(PebbleDB 或 JSON)进行匹配。该分析从不执行被测代码。
[!CAUTION] 本工具仅供防御性安全研究和授权测试使用。请勿使用它创建、分发或部署恶意软件。用户有责任遵守适用法律和组织政策。作者对滥用不承担任何责任。
go install github.com/BlackVectorOps/semantic_firewall/v7/cmd/[email protected]
go.mod 声明 go 1.27.2。sfw version 会打印构建信息:
Semantic Firewall CLI
Build: v7.1.1 (Pebble/Gob+PackedIdx)
标志必须放在位置参数之前。CLI 使用 Go 的 flag 包解析每个命令,该包会在遇到第一个非标志参数时停止;放在文件名之后的标志会被静默忽略。
| 命令 | 标志(默认值) | 参数 | 沙箱化 |
|---|---|---|---|
check | --strict (false), --scan (false), --db (""), --no-sandbox (false) | <file.go|dir> | 是 |
diff | --no-sandbox (false), --batch ("") | <old.go> <new.go>,或使用 --batch <pairs-file> 时不带参数 | 是 |
deps diff | --no-sandbox (false) | <old-module-dir> <new-module-dir> | 是 |
audit | --model (claude-opus-5-5), --api-key (""), --api-base (""), --no-sandbox (false) | <old.go> <new.go> "<commit message>" | 是(diff 步骤) |
index | --name(必填), --severity (HIGH), --category (malware), --db ("") | <file.go|dir> | 否 |
scan | --db (""), --threshold (0.75), --exact (false), --deps (false), --deps-depth (direct), --no-sandbox (false) | <file.go|dir> | 是 |
migrate | --from(必填), --to(必填) | 无 | 否 |
stats | --db ("") | 无 | 否 |
version | 无 | 无 | 否 |
sfw <command> -h 会列出某个命令的标志。--severity 按给定值存储,不做校验。任何不是 transitive 的 --deps-depth 值都会被当作 direct 处理。
退出码:
| 命令 | 退出码 0 | 退出码 1 |
|---|---|---|
check | 分析已运行,即使某个文件加载失败(在该文件的 error 字段中报告) | 使用 --strict 且任何文件出错;致命错误 |
diff | 已生成 diff,无论风险如何 | 致命错误 |
diff --batch | 每一对都已 diff,无论风险如何 | 任何一对失败(在打印所有结果之后);致命错误 |
deps diff | 已生成 diff,无论风险如何 | 任一树加载失败;致命错误 |
scan | 扫描已运行,无论是否有告警 | 致命错误(例如没有数据库) |
audit | 判定为 MATCH | 判定为 LIE、SUSPICIOUS 或 ERROR |
diff 会将缺失的输入文件视为空文件。
打印一个 JSON 数组,每个文件对应一个条目。目录会被递归遍历,跳过 vendor/、隐藏目录和 _test.go 文件。函数名带有包限定:单独加载的文件属于 command-line-arguments。
sfw check --no-sandbox new.go
[
{
"file": "new.go",
"functions": [
{ "function": "command-line-arguments.Handle", "fingerprint": "4acdccda3895dd4cec3af2d55ad43489f91860cd226f82091eaf0a2429849e2f", "file": "/work/new.go", "line": 5 },
{ "function": "command-line-arguments.Handle$1", "fingerprint": "1777c5c3ae9a69e395f6bbe8f35a1e447d25534afec7bb907eacf873e7d4917c", "file": "/work/new.go", "line": 7 },
{ "function": "command-line-arguments.Sum", "fingerprint": "7cc1efa6ef6ca643863de5dcb0a68f7c80cd6dae8c530697706f40ce737030ae", "file": "/work/new.go", "line": 10 },
{ "function": "command-line-arguments.init", "fingerprint": "825a2d206f4eb4ea4413c050e4ca9e4b8e439c2067219829a8fef891031a1850", "file": "" }
]
}
]
上面的输出捕获自一次真实运行,其中绝对路径被缩短为 /work,每个对象各占一行。new.go 是 sfw diff 示例中的文件。
--strict: 遇到未处理的 SSA 指令时,规范化器会直接失败,而不是输出 UnhandledInstr<T>;并且任何单文件错误都会使命令以退出码 1 结束。--scan: 每个函数的拓扑结构还会以固定阈值 0.75 与签名数据库(--db,或默认解析)进行匹配。匹配结果会写入 scan_results 字段。数据库缺失属于致命错误。输入:
// old.go
package p
import "fmt"
func Handle(cmd string) { fmt.Println(cmd) }
func Add(a, b int) int { return a + b }
// new.go
package p
import "net"
func Handle(cmd string) {
net.Dial("tcp", cmd)
go func() {}()
}
func Sum(a, b int) int { return a + b }
sfw diff --no-sandbox old.go new.go 会输出以下内容。这是完整输出,只是 init 条目被简写为它的状态和增量。
{
"old_file": "old.go",
"new_file": "new.go",
"summary": {
"total_functions": 4,
"preserved": 0,
"modified": 3,
"added": 1,
"removed": 0,
"semantic_match_pct": 0,
"topology_matched_pct": 75,
"renamed_functions": 1,
"high_risk_changes": 1
},
"functions": [
{
"function": "Handle",
"status": "modified",
"fingerprint_match": false,
"old_fingerprint": "f735eacc97909969c02c6c115696e44282599242dfb7ebc5f8450894210caecf",
"new_fingerprint": "4acdccda3895dd4cec3af2d55ad43489f91860cd226f82091eaf0a2429849e2f",
"matched_nodes": 1,
"added_ops": ["go Handle$1()", "t0 = net.Dial(\"tcp\":string, cmd)"],
"removed_ops": ["*t1 = t2", "t0 = new [1]any (varargs)", "t1 = &t0[0:int]", "t2 = make any <- string (cmd)", "t3 = slice t0[:]", "t4 = fmt.Println(t3...)"],
"risk_score": 30,
"topology_delta": "Capability+network(net.Dial), Calls-1, AddedGoroutine, StringLiterals~, Entropy+1.6"
},
{
"function": "init",
"status": "modified",
"...": "...",
"topology_delta": "NoStructuralChange"
},
{
"function": "Add → Sum",
"status": "renamed",
"fingerprint_match": true,
"old_fingerprint": "7cc1efa6ef6ca643863de5dcb0a68f7c80cd6dae8c530697706f40ce737030ae",
"new_fingerprint": "7cc1efa6ef6ca643863de5dcb0a68f7c80cd6dae8c530697706f40ce737030ae"
},
{
"function": "Handle$1",
"status": "added",
"fingerprint_match": false,
"new_fingerprint": "1777c5c3ae9a69e395f6bbe8f35a1e447d25534afec7bb907eacf873e7d4917c",
"risk_score": 5,
"topology_delta": "NewFunction"
}
],
"topology_matches": [
{ "old_function": "Handle", "new_function": "Handle", "similarity": 0.7048387096774194, "matched_by_name": true, "old_topology": "L0B0I7[fmt.Println]", "new_topology": "L0B0I3[go:closure:func(),net.Dial]" },
{ "old_function": "init", "new_function": "init", "similarity": 0.7419354838709677, "matched_by_name": true, "old_topology": "L0B1I6[fmt.init]", "new_topology": "L0B1I6[net.init]" },
{ "old_function": "Add", "new_function": "Sum", "similarity": 1, "matched_by_name": false, "old_topology": "L0B0I2[]", "new_topology": "L0B0I2[]" }
]
}
Handle 得分为 30:+20 是因为它新到达了网络能力,+10 是因为新增的 goroutine。added_ops 和 removed_ops 是 go/ssa 文本形式的 SSA 指令。*_topology 字符串的格式为 L<loops>B<branches>I<instructions>[<call signatures>]。调用签名经过排序;当超过三个时,只显示前三个,后跟 ...(<total>)。
| 状态 | 含义 |
|---|---|
preserved | 按名称匹配。默认指纹相等,保留全部字面量的指纹相等,且没有新到达任何能力。 |
modified | 按名称匹配,但不满足上述条件 |
renamed | 按拓扑匹配,而非按名称匹配。计入 modified。 |
added | 仅存在于新文件中。按新函数计分,基础分为 5。 |
removed | 仅存在于旧文件中。计 0 分,但包含验证调用的函数计 10 分(RemovedCheck(...))。 |
preserved 测试在两种字面量策略下比较指纹。默认策略会屏蔽 [-16, 16] 之外的字符串和整数,因此其指纹在字面量改变后仍保持不变;保留全部策略则不会。因此,更改的 URL、命令、限制或文件模式会产生 modified,其字面量出现在 added_ops/removed_ops 中。