faustbrian/go-analysis

# go-analysis `go-analysis` 是一个面向 Go 组织的确定性 `go/analysis` 策略套件。它强制执行仓库架构、context 传播、生命周期所有权、HTTP 所有权、安全 API 迁移和类型化敏感信息处理，以及共享可变状态策略，且不会替代编译器、`go vet`、Staticcheck、golangci-lint、gosec、govulncheck、CodeQL、竞态测试、模糊测试或 NilAway。 本项目处于 v1 之前的阶段。在语料库证据支持明确的阻断性升级之前，发布的每条规则默认均为建议性规则。 项目参考： - [贡献者指南](CONTRIBUTING.md) - [安全策略](SECURITY.md) - [安全与威胁模型](docs/security.md) - [更新日志](CHANGELOG.md) - [完整规则目录](docs/rules.md) - [命令、API、SARIF 和性能参考](docs/reference.md) - [规则治理与冲突矩阵](docs/governance.md) - [组织强化证据](docs/hardening.md) - [仓库推行与建议性升级](docs/rollout.md) - [语料库精度与性能](docs/corpus.md) - [发布流程](docs/release.md) - [兼容性策略](docs/compatibility.md) - [自定义规则设计]() - [常见问题解答](docs/faq.md) ## 要求 - Go 1.26 或更新版本 - 无需目标程序执行，且无需配置插件 ## 五分钟快速入门 构建固定的本地二进制文件： ``` make build ``` ### 独立分析器 原始的 multichecker 运行无需配置的规则，以及带有空策略的已配置规则包： ``` ./.build/go-analysis ./... ``` 组织策略应使用已配置的报告命令： ``` ./.build/go-analysis validate-config go-analysis.yml ./.build/go-analysis check -config go-analysis.yml -format json ./... ./.build/go-analysis check -config go-analysis.yml -format sarif ./... \ > go-analysis.sarif ``` 当策略由规范化检出目录集中管理时，请显式同步它，并将策略偏移作为本地和 CI 失败项： ``` make policy-update CANONICAL_POLICY=../mono/policies/service.yml make policy-check CANONICAL_POLICY=../mono/policies/service.yml ``` `LOCAL_POLICY` 默认为 `go-analysis.yml`。这两个命令均为离线执行。在更新前会验证规范化文件，并且 `check` 要求精确的字节一致性，因此格式化或注释的偏移也是可审查的。 当没有阻断性发现剩余时，`check` 以 0 退出；对于阻断性发现，以 1 退出；对于无效参数、无效策略、加载失败或分析器错误，以 2 退出。建议性诊断永远不会将退出状态更改为 1。 使用以下命令打印精确的嵌入发布版本： ``` ./.build/go-analysis version ``` ### go vet vettool ``` go vet -vettool="$PWD/.build/go-analysis" ./... ``` vettool 接口没有 YAML 策略通道。因此，它运行无需配置的规则以及已配置分析器的空策略形式。当需要仓库策略时，请使用 `go-analysis check`。go vet 将每个发出的诊断视为失败结果，并且没有建议性状态通道；当必须保留建议性与阻断性行为的区分时，请使用已配置的 `check`。 ### CI 使用与开发时相同的本地构建二进制文件和已提交的策略： ``` make test make coverage make docs make compatibility make reproducible make corpus make performance make release-verify VERSION=0.1.0 make vettool make fuzz-smoke make benchmark make mutation make policy-check CANONICAL_POLICY=../mono/policies/service.yml ./.build/go-analysis validate-config go-analysis.yml ./.build/go-analysis check -config go-analysis.yml -format sarif ./... \ > go-analysis.sarif ``` `make coverage` 将单元测试覆盖率与经过插桩的命令二进制文件相结合。它会测试进程以 0、1 和 2 退出的情况，并且除非每个生产包都具有精确的 100.0% 语句覆盖率，否则就会失败。 ## 配置 配置采用严格的 YAML。未知字段、未知规则 ID、多个 YAML 文档、格式错误的分析器策略以及不支持的版本都将被拒绝。 路径和包模式是从包含配置文件的目录解析的，而不是从调用目录解析的。当策略存储在被分析的检出目录之外时，规范化策略运行器会使用显式的绝对路径 `-root` 覆盖。 ``` version: 1 entrypoints: - example.com/service/cmd/service init_packages: - example.com/service/internal/runtimeinit context_owners: - example.com/service/internal/requeststate generated: exclude: true paths: - internal/protocol/client.gen.go layers: - name: domain may_import: [shared] - name: infrastructure may_import: [domain, shared] - name: shared contexts: - name: orders may_import: [shared] - name: shared packages: - pattern: example.com/service/domain/... layer: domain context: orders deny_imports: - example.com/service/infrastructure/... allow_imports: - example.com/service/infrastructure/approved - pattern: example.com/service/internal/repository blocking_functions: - Repository.Load constructors: - package: example.com/service/internal/worker symbols: - New - Builder.Build transactions: - package: database/sql symbol: DB.BeginTx result: 0 rollback_method: Rollback forbidden_apis: - package: example.com/legacy/backend symbol: NewClient replacement: example.com/service/internal/adapter.NewClient allowed_packages: - example.com/service/internal/adapter backend_clients: - package: database/sql allowed_packages: - example.com/service/internal/adapter/sql/... mutable_globals: - package: example.com/service/internal/... interface_provider_packages: - example.com/service/internal/providers/... interface_names: - package: example.com/service/internal/ports/... required_suffix: Port allowed_names: - Compatibility metric_label_types: - package: example.com/service/internal/model name: UserID metric_label_sinks: - package: example.com/service/internal/metrics symbol: Counter.Label arguments: [0] metric_label_name_types: - package: example.com/service/internal/request name: MetricName metric_label_name_sinks: - package: example.com/service/internal/metrics symbol: Counter.LabelName arguments: [0] backend_error_boundaries: - example.com/service/api/... backend_error_sources: - package: example.com/backend symbol: Client.Load result: 1 backend_error_passthroughs: - package: fmt symbol: Errorf result: 0 variadic_from: 1 goroutine_fanout: - package: example.com/service/internal/worker/... max_static: 8 exceptions: - rule: security/no-unsafe package: example.com/service/internal/bridge path: internal/bridge/abi.go reason: reviewed operating-system ABI bridge issue: SEC-42 expires: 2027-01-31 sensitive_types: - package: example.com/security name: Token sensitive_sinks: - package: log/slog symbol: Logger.Log arguments: [2] variadic_from: 3 allowed_packages: - example.com/service/internal/audit rules: architecture/import-boundary: status: blocking promotion: version: 0.1.0 evidence: ARCH-101 reviewed owned-corpus baseline security/sensitive-sink: status: advisory severity: error ``` 状态包括 `disabled`、`advisory` 或 `blocking`。每个阻断性覆盖都需要一个语义化的 `promotion.version` 和一条非空的 `promotion.evidence` 记录。严重程度分为 `info`、`warning` 或 `error`。严重程度会影响报告；只有状态能控制阻断性退出代码。 层和限界上下文名称使用 lower-kebab-case。每个 `may_import` 列表会列出可以导入的其他分区；同一层或上下文内的导入是隐式允许的。配置的层和上下文图必须是无环的；在加载包之前，验证过程会报告确定性的循环追踪。包的分类不能重叠。方向检查仅在导入者和被导入包都针对该维度进行了分类时才会运行，因此不会对未分类的依赖项进行猜测。在同一导入位置，显式的 `deny_imports` 具有优先权。 `backend_clients` 反转了边界声明：每个后端包树都指定了允许导入它的、不重叠的适配器包树。这防止了新的服务包仅仅因为尚未被面向源的包策略命名而绕过适配器。客户端和适配器条目都使用精确的导入路径或以 `/...` 包树后缀结尾。 `transactions` 标识了精确的事务构造函数、它们基于零索引的事务结果，以及必须在构造函数的精确终止错误检查之后立即被 defer 的 rollback 方法。这闭环了事务所有权，而无需重复 `sqlclosecheck` 的查询和语句关闭操作。 `mutable_globals` 显式地将精确的包路径或包树纳入类型化的共享状态强制执行。未配置的分析器处于非活动状态，因此 vettool 永远不会将建议性的组织策略转变为隐式的全局风格检查门。已审查的声明使用普通的精确抑制或已审查的配置例外清单，而不是单独的全局允许列表。 `interface_provider_packages` 标识了导出的运行时接口会反转所有权的精确提供者包或以 `/...` 结尾的包树。仅作为泛型约束的接口仍然被接受；不会从目录名称推断消费者包。 `metric_label_types` 指定了已知携带无界值的组织类型，而 `metric_label_sinks` 标识了精确函数或 `Type.Method` 符号上基于零索引的 metric-label 位置。像 `string(userID)` 这样的直接转换会保留源类型证据；显式的分桶函数是移除该证据的已审查边界。 `metric_label_name_types` 指定了已证明携带受攻击者控制的标签名称的类型，而 `metric_label_name_sinks` 标识了精确的名称位置。请通过固定的允许列表映射请求值；不要将它们变成 metric schema。 `backend_error_boundaries` 标识了导出的 API 包树。 `backend_error_sources` 标识了精确后端可调用对象中基于零索引的结果，而 `backend_error_passthroughs` 标识了保留这些错误的包装器。未列出的映射辅助函数是一个显式的分类边界；请仅配置已证明能保留后端标识的包装器。 `goroutine_fanout` 将精确的包或以 `/...` 结尾的包树纳入针对循环展开 goroutine 启动的建议性上限。`max_static` 接受常量大小的工作，而运行时大小的循环则需要 worker pool 或静态证明的同步边界。 特定于规则的行为使用类型化的顶层策略，例如 `constructors` 和 `sensitive_sinks`；任意的 `rules..options` 会被拒绝。保留的 `adapter_roots` 字段会被拒绝，因为无关联的全局根无法表达每个适配器拥有哪个依赖项；请改用类型化的 `backend_clients` 契约。 默认情况下，生成的文件仍会被分析。`generated.exclude: true` 仅排除 `generated.paths` 中列出的、同时也使用了 Go 生成文件约定的精确仓库相对文件：即在 package 声明之前带有匹配的 `// Code generated ... DO NOT EDIT.` 头部。头部、显式排除和精确的可信路径这三者都是必需的。通配符、目录、遍历符、重复路径和非 Go 文件将被拒绝。像 `generated.go` 这样的文件名或未列出路径上的伪造头部不会受到特殊对待，因此它们的诊断和抑制指令仍然会被验证。来自明确受信任的生成文件的诊断和抑制指令将被一并省略。 配置例外是集中的、经过审查的策略记录，而不是源代码抑制。每个例外都指定一个已知规则、一个精确的包、一个非空原因，以及可选的一个精确仓库相对斜杠路径、一个 issue 和一个过期日期。包模式、绝对路径、遍历符、重复项、重叠、过期条目以及与任何诊断都不匹配的例外都将被拒绝。配置例外优先于源代码指令；因此，针对已设置例外的发现的指令将被作为过期项拒绝。应用的例外将被保留在确定性的 JSON 和 SARIF 清单中。 ## 抑制 抑制仅适用于紧随其后的行上的诊断。它必须指定一个已知规则并包含非空原因： ``` //go-analysis:ignore security/no-unsafe -- required ABI bridge; issue=SEC-42; expires=2027-01-31 import _ "unsafe" ``` 支持的元数据为 `issue=` 和 `expires=YYYY-MM-DD`。 格式错误、未知、重复、过期或未使用的抑制会导致分析失败。JSON 和 SARIF 运行会保留已使用的抑制清单以供审计。 ## 清单和报告 ``` ./.build/go-analysis rules ``` `go-analysis rules` 会为每条规则输出稳定的 JSON 元数据和治理所有权。已配置的 `check` 报告使用仓库相对斜杠路径、稳定的排序、无源代码片段且无绝对仓库路径。有关基本原理、示例、配置和工具所有权，请参阅[规则目录](docs/rules.md)。 ## 开发 ``` make test make coverage make vettool make fuzz-smoke make benchmark make mutation ``` 分析器固定数据使用 `analysistest`。生产环境行为通过红-绿-重构周期进行开发，每条规则都包含正向、已接受、别名、近似失误以及相关的多包或泛型证据。 ## 范围 本项目不格式化代码、不派生编译器、不执行目标程序，也不声称具有所有权、借用或数据竞争证明。NilAway 保持单独固定和建议性状态；在稍后规范化报告时，不得隐藏其退出状态。

标签：EVTX分析, Go, Ruby工具, SARIF, SOC Prime, 云安全监控, 安全检查, 开发工具, 日志审计, 架构规范, 静态分析