Semgrep 静态分析上手指南：30+ 语言语义级代码扫描，从安装到首条规则

Semgrep 静态分析上手指南：30+ 语言语义级代码扫描，从安装到首条规则

【免费下载链接】semgrepLightweight static analysis for many languages. Find bug variants with patterns that look like source code.项目地址: https://gitcode.com/GitHub_Trending/se/semgrep

Semgrep 是一款开源的静态分析工具，用"长得像源码"的规则搜索代码、发现缺陷并强制执行编码规范。它覆盖 30 多种语言，可在本地终端、IDE、pre-commit 钩子或 CI 流水线中运行，扫描全程在本地完成，默认不上传代码。

谁需要用 Semgrep，它和普通 grep 差在哪

判断标准很简单：如果你想在团队里拦住"危险 API 调用"、"同名变量互相比较"这类问题，又不想维护一套正则规则，Semgrep 就是为此设计的。

和grep "2"只匹配字面文本不同，Semgrep 做的是语义匹配——搜2时，x = 1; y = x + 1这种表达式也会被识别出来。规则直接写在代码语法层面，不需要抽象语法树，也不需要和正则表达式较劲。

它适合三类角色：

• 应用开发者：在本地跑规则，编码阶段就拦住低级错误；
• 代码审查者：把规则挂到 CI 上，只关注本次 PR 新引入的问题；
• 安全审计人员：用自定义 pattern 快速排查危险函数、硬编码凭据等隐患。

安装前准备与安装方式选择

先按你的场景选一条路径，再执行对应命令：

你的情况	推荐方式
本地有 Python 环境，想长期用	pip 安装
macOS 开发机	Homebrew 安装
不想装东西，临时扫一次	Docker 容器
要参与贡献或定制核心	源码构建

pip（Linux / macOS / Windows / WSL）

python3 -m pip install semgrep

CLI 要求 Python 3.10 及以上（见 cli/pyproject.toml），老系统上装包失败时先确认python3 --version。

Homebrew（macOS）

brew install semgrep

Docker 试用

docker run -it -v "${PWD}:/src" semgrep/semgrep semgrep --help

源码构建

仓库由 Python CLI 和 OCaml 核心（semgrep-core）两部分组成，详见 AGENTS.md。构建前需要装好 opam、dune、Python 3、uv、C 工具链和 make，然后在仓库根目录依次执行：

make setup # 创建 OCaml 环境并安装依赖，首次必须执行 make all # 编译 OCaml 核心并安装 Python CLI

make setup不需要频繁运行，只有依赖变化或遇到奇怪的构建错误时才重跑。

第一次配置与验证：从版本检查到自定义规则

装完后按"验证安装 → 写第一条规则 → 看命中结果"三步走。

第 1 步，确认命令可用：

semgrep --version

第 2 步，写一个最小规则文件。新建my-rules.yml：

rules: - id: no-debug-print pattern: print(...) message: "用 logger 替代 print，避免调试输出进入生产代码" severity: WARNING languages: [python]

四个字段各司其职：id是规则唯一标识，pattern就是"代码里长什么样"，message命中后展示给开发者的提示，severity控制严重程度。仓库自身也用同样格式给 OCaml/Python 代码立规，可以参考根目录的 semgrep.yml。

第 3 步，跑起来验证：

semgrep scan --config my-rules.yml <你的代码目录>

命中时终端会列出文件路径、行号和 message 里写的那句话——看到这个输出，说明规则链路已经通了。

两个提效用法可以记住：

• 不落盘搜索：semgrep scan -e '$X == $X' --lang=py src/直接找左右同名变量比较的可疑代码（$X是元变量，匹配任意标识符）；
• 控制扫描范围：--exclude排除vendor/、node_modules/这类目录；仓库根目录的.semgrepignore文件则负责长期维护的忽略清单。

常见问题与排查

误报太多，开发同学抵触？先用--exclude砍掉第三方目录，再用metavariable-regex、metavariable-pattern等字段给元变量加约束；确认是"写法本来就该这样"的场景，在规则里补pattern-not排除。把噪声压下来，团队才会真的读报告。

社区版能发现所有安全问题吗？不能。社区版的分析范围限制在单个函数或单个文件内，跨文件、跨函数的数据流追踪需要 Semgrep AppSec Platform。拿它做纯安全审计时要留意这个边界；做编码规范检查、代码搜索则没有影响。

接进 CI 会淹没存量问题吗？不会。Semgrep 配置在 CI 中扫描 PR 时，只报告该 PR 新引入的问题，历史存量不会被反复提及，可以放心从零开始启用。

关于遥测数据使用注册表远程规则（如--config=p/ci）会上报匿名规则指标；只扫本地规则文件时仅在登录状态下上报。想彻底关闭，加--metrics=off。

下一步做什么

1. 选一条官方预置规则跑一遍现有项目，先拿到"有输出"的体感；
2. 针对团队最疼的一类问题写第一条自有规则，放进my-rules.yml并纳入版本管理；
3. 把扫描挂进 CI，只盯增量问题；
4. 需要更大规则库时执行semgrep login登录，解锁 Pro 规则集。

规则是资产，从第一条开始积累，比买一套现成清单更有价值。

【免费下载链接】semgrepLightweight static analysis for many languages. Find bug variants with patterns that look like source code.项目地址: https://gitcode.com/GitHub_Trending/se/semgrep