chinmay-sawant/goslop

# goslop **goslop** 是一款**静态分析工具 (SAT)**，拥有一个**多语言引擎** (`LanguagePlugin`)。目前 **Go** 是生产环境的默认语言：它使用纯 Go 解析（`go/parser` + `go/ast`，无 CGO）检查 Go 源码，并报告三大类问题。**Python** 为预留/开发中功能（包含 fixtures + `LanguagePython`；尚无完整的检测器目录）——详见 epic [#39](https://github.com/chinmay-sawant/goslop/issues/39) 和 [`plans/v0.0.2/python-support.md`](./plans/v0.0.2/python-support.md)。 | 家族 | 发现内容 (Go 目录) | 示例 | |--------|-------------------------------|----------| | **性能 (`PERF-*`)** | 热点路径与运行时隐患 | 循环中的内存分配、缺少 HTTP 超时、N+1 模式、框架误用 | | **不良实践 (`BP-*`)** | 代码风格、规范与项目级问题 | 错误处理、服务器关闭、go.mod 规范、冗余 API 模式 | | **CWE (`CWE-*`)** | 安全启发式检测（结构化 + 可选的 taint） | 路径遍历、命令注入、XSS、SQL 注入 (CWE-22/78/79/89 等) | 你可以将其用作本地 linter、CI 门禁，或作为分流管道，导出检测结果供人工或 agent 审查（支持 JSON、SARIF 以及磁盘上的 context chunks）。 ## 核心亮点 - **三大 Go 检测器目录** - **239** 条 Go PERF 规则、**175** 条 Go CWE 规则，外加完整的 Go 不良实践目录 (`BP-*`) - **多语言引擎** - 语言无关的 `LanguagePlugin` 接口；Go 已发布；Python 开发中 (#39) - **产品 profiles** - `recommended`、`perf`、`security`、`style`、`all`（精心调配的规则集 + 失败策略） - **报告器** - 人类可读的 **text**、机器可读的 **JSON**，以及 **SARIF 2.1.0**（适配 GitHub Code Scanning） - **可选的 taint** - 实验性的过程间图分析，用于挖掘高置信度的注入类 CWE - **增量缓存** - `.goslop-cache/` 用于快速重新扫描 - **基线与忽略** - 携带已知的技术债启动；使用 `// goslop-ignore` 抑制告警 - **导出供 agent 使用** - 在 `scripts/findings/functions/` 下导出单条发现的 refs，在 `scripts/chunks/` 下导出批量 **chunks**（Context 默认为**整个包含的函数**；`[goslop.export] whole_function`） - **纯 Go 二进制文件** - 默认 `CGO_ENABLED=0`；易于交叉编译 ## 环境要求 - **Go 1.26.4** (`go.mod` 中声明的版本) - Linux / macOS / Windows - 默认的纯 Go 构建无需 C 工具链 ## 安装 / 构建 ``` # 从 repo 根目录（默认通过 Makefile 设置 CGO_ENABLED=0） make build # 或者： CGO_ENABLED=0 go build -o bin/goslop ./cmd/goslop ``` 二进制文件位于：`./bin/goslop` 可选的多架构打包：[`.goreleaser.stub.yml`](./.goreleaser.stub.yml)。 ## 快速开始 ``` # 扫描当前目录（默认 profile：推荐） ./bin/goslop . # 侧重 Performance 的 pack ./bin/goslop --profile perf . # Security pack（默认开启 taint） ./bin/goslop --profile security ./cmd # 不良实践 / 样式 ./bin/goslop --profile style . # 完整 catalogue ./bin/goslop --profile all . # Starter config ./bin/goslop init ``` ### 机器可读输出 ``` ./bin/goslop --format json . ./bin/goslop --format sarif . > goslop.sarif ``` ### 导出发现结果以供审查 / 委派给 agent ``` # Per-finding refs → scripts/findings/functions/N.txt # Combined batches → scripts/chunks/Chunk_START_END.txt（默认每个包含 25 个 findings） ./bin/goslop --profile all --export-context --export-chunks --no-cache . ``` - **Chunks** = 组合的发现结果，用于向 agent **委派**工作 - **Functions** = 独立的发现 **refs**，用于针对单一问题的深入排查 产品级风格的摘要扫描（构建 + 导出默认值）： ``` make run SCAN_PATH=./your/go/project ``` **注意：** 在 `--profile all` 下扫描**本**代码库会产生大量检测结果。对于一款内置了**模式特征**、**检测器源码**以及**特意设置的 fixtures** 的 SAT 来说，这是符合预期的——就像 **Semgrep**（或其他 SAT）分析自己的规则包和测试语料库时也会出现同类噪音一样。请使用真实应用（或通过默认的 `make run` 使用 `gopdfsuit` 基线）来评估实际的产品信号。详见 [documents/overview.md](./documents/overview.md#scanning-the-goslop-repo-itself-high-finding-counts)。 ### 规则发现 ``` ./bin/goslop --list-rules ./bin/goslop --explain PERF-6 ./bin/goslop --explain CWE-89 ./bin/goslop --version ``` ### 退出码 | 代码 | 含义 | |------|---------| | **0** | 干净通过，或使用了 `--no-fail` | | **1** | 发现结果违反了当前的失败策略 | | **2** | 用法 / 配置错误 | | **3** | 内部错误 | ## goslop 分析什么 当前内置的检测器主要针对 **Go**。下文的目录计数为 **Go** 领域的规则数（并非多语言总和）。 ### 性能 (`PERF-*`) 用于检测请求路径和循环中高开销模式的启发式检测器：循环内的正则表达式编译、循环内的 `defer`、HTTP 服务器超时、body 未关闭问题、特定框架的热点路径等。已注册 **239** 条 Go 规则。 人类可读的说明（部分）：[`documents/perf-rules.md`](./documents/perf-rules.md)。 ### 不良实践 (`BP-*`) 风格与工程规范：缺少包文档、错误处理习惯、测试坏味道、无速率限制的公共 HTTP、优雅关闭、go.mod / 依赖规范以及相关的项目级检查。在 **`style`** 和 **`all`** profiles 下启用（以及在配置中开启 BP 时）。 ### CWE / 安全 (`CWE-*`) **175** 条 Go 结构化的 CWE 启发式规则。对于注入类问题，请启用实验性的 **taint** 追踪： ``` ./bin/goslop --taint --taint-depth 3 --taint-show-paths . # 或 ./bin/goslop --profile security . ``` Taint 模型与限制：[`documents/taint.md`](./documents/taint.md)。 ## Profiles (规则集) | Profile | 别名 | 侧重点 | 默认失败级别 | |---------|---------|--------|--------------| | `recommended` | `ci`, `default` | 高置信度 PERF + 核心 CWE 白名单 | high / critical | | `perf` | `performance` | 更广泛的 PERF 级别 | high / critical | | `security` | `sec` | 安全 CWE + **开启 taint** | high / critical | | `style` | `bp`, `bad-practices` | `BP-*` 目录 | 无 (仅建议) | | `all` | `full` | 完整的 PERF + CWE + BP | medium 及以上 | 详细信息和确切的白名单：[`documents/go-recommended-pack.md`](./documents/go-recommended-pack.md)。 完整的参数列表：[`documents/cli-reference.md`](./documents/cli-reference.md)。 ## 配置 ``` ./bin/goslop init # writes goslop.toml ``` 可选的 `goslop.toml` 支持规则过滤器 (`only` / `skip`)、`fail_on`、include/exclude 匹配符、cache、baseline、taint 以及不良实践的严重级别覆盖。 - 模板：[`templates/goslop.toml`](./templates/goslop.toml) - Schema：[`goslop.schema.json`](./goslop.schema.json) - 合并规则：[`documents/cli-reference.md`](./documents/cli-reference.md#config-file-and-cli-merge) 使用以下方式在代码内联抑制告警： ``` // goslop-ignore: PERF-101 srv := &http.Server{Addr: ":8080"} ``` ## 报告格式 | 格式 | 参数 | 用途 | |--------|------|-----| | **text** | `--format text` (默认) | 终端 / CI 日志 | | **json** | `--format json` | 脚本与自动化处理 | | **sarif** | `--format sarif` | GitHub Code Scanning，IDE SARIF 查看器 | 扫描**摘要**始终输出到 **stderr**；发现的详细 payload 输出到 **stdout**，从而确保 JSON/SARIF 的管道流保持纯净。 示例与 GitHub 上传须知：[`documents/reporting-formats.md`](./documents/reporting-formats.md)。 ## 开发 / 测试 ``` make test # go test ./... make integration # fixture harness under tests/integration make lint # go vet + gofmt check make lint-all # golangci-lint (when configured) make ci # lint + test + build make run # product summary scan + optional exports make reference-metrics # large-corpus metrics gate (see Makefile SCAN_PATH) make help # list targets ``` CI：[`.github/workflows/ci.yml`](./.github/workflows/ci.yml) 将运行 `go vet`、`go test ./...`，并在 `CGO_ENABLED=0` 下执行 `go build`。 ## 文档 详细指南位于 [`documents/`](./documents/) 目录下： | 文档 | 内容 | |----------|----------| | [`documents/README.md`](./documents/README.md) | 文档索引 | | [`documents/overview.md`](./documents/overview.md) | 功能、profiles、cache、baseline、忽略 | | [`documents/cli-reference.md`](./documents/cli-reference.md) | 所有 CLI 参数、退出码、配置合并 | | [`documents/make-run.md`](./documents/make-run.md) | 产品级 `make run` / `make reference-metrics` 工作流 | | [`documents/reporting-formats.md`](./documents/reporting-formats.md) | 包含示例的 Text、JSON 和 **SARIF** 说明 | | [`documents/export-context-and-chunks.md`](./documents/export-context-and-chunks.md) | 用于委派给 agent 的函数 refs 与 chunks | | [`documents/go-recommended-pack.md`](./documents/go-recommended-pack.md) | Recommended 规则集和 profile 表格 | | [`documents/perf-rules.md`](./documents/perf-rules.md) | PERF 规则说明 | | [`documents/taint.md`](./documents/taint.md) | Taint 引擎 | | [`documents/suppressions-and-baselines.md`](./documents/suppressions-and-baselines.md) | 内联忽略与 baseline 推行 | | [`documents/rule-catalog-and-maturity.md`](./documents/rule-catalog-and-maturity.md) | 实时目录发现与成熟度标签 | | [`documents/development.md`](./documents/development.md) | 构建、验证、CI、扫描与基准测试命令 | | [`documents/architecture-performance.md`](./documents/architecture-performance.md) | 引擎 pipeline 与性能设计 | ## 仓库结构 | 路径 | 职责 | |------|------| | `cmd/goslop` | CLI 入口 | | `internal/` | 核心引擎、检测器、报告生成与导出 | | `documents/` | 面向用户的文档 | | `ruleset/` | 规则元数据 (PERF / CWE chunks，BP 目录) | | `templates/` | 起始模板 `goslop.toml` | | `tests/fixtures` | 检测器 fixtures | | `tests/integration` | 集成测试套件 | | `scripts/findings/functions` | 单条发现导出 (`--export-context`) | | `scripts/chunks` | 用于委派的批量发现导出 (`--export-chunks`) | | `.github/workflows/` | CI |

标签：EVTX分析, Go语言, Homebrew安装, SAST, 安全专业人员, 日志审计, 盲注攻击, 程序破解, 自动化payload嵌入, 错误基检测, 静态代码分析