Semgrep 静态代码分析：面向新手工程师的代码扫描上手指南

Semgrep 静态代码分析：面向新手工程师的代码扫描上手指南

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

当你需要在存量代码里快速定位缺陷或安全隐患，或者想把团队的编码约定变成自动化检查时，Semgrep 静态代码分析就是为此设计的工具。它把「找问题」这件事压缩成一条命令加一份 YAML 规则。本文假设你没有用过 Semgrep，按安装、首扫、写规则、接入流水线的顺序给出可照做的步骤。

核心定位

Semgrep 的卖点在于「语义化 grep」：普通grep "2"只匹配字面量，而 Semgrep 用形如源码的模式匹配代码结构，例如搜索数字 2 时能命中x = 1; y = x + 1。规则写成你日常写的代码，不需要正则或抽象语法树。它默认在本地分析，代码不会被上传。

维度	Semgrep	常规做法
规则写法	接近源码的模式，$X等元变量表示任意表达式	正则、厂商 DSL 或 AST API
语言覆盖	30+ 种（Python、Java、JS/TS、Go、Rust 等，见 README.md 支持列表）	通常 5–10 种
部署形态	pip 或 Docker 单包，本地运行	企业级平台常需服务端部署

🚀 运行一次首扫

三步跑通：

python3 -m pip install semgrep semgrep --version # 输出版本号即安装成功 semgrep scan --config=auto .

--config=auto会自动选择内置与注册表规则集，按文件类型批量扫描当前目录。验证是否成功：运行结束后看输出的 Findings 区块，列出每条命中的文件、行号和规则说明；若输出 0 findings 且退出码为 0，也表示扫描正常完成。不想本地装依赖时，可用容器替代安装步骤：

docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep scan --config=auto

拆解关键能力

用 -e 做临时查询

不写配置文件也能查。例如找出 Python 里左右操作数相同（大概率是 bug）的等值判断：

semgrep -e '$X == $X' --lang=py path/to/src

$X是元变量，匹配任意表达式，这是 Semgrep 区别于字符串搜索的核心语法。

用 autofix 预览自动修复

规则里可以带fix字段给出改写后的代码。结合--dry-run只展示会发生的修改，加--fix则直接落盘。仓库内 tests/autofix/ 目录保存了大量修复前后的对照样例，可参考其规则写法。

控制扫描范围

--include/--exclude用 glob 过滤文件，--lang限定语言。扫描大仓库时先缩小范围再逐步放宽，比全量跑一遍更能定位性能瓶颈。

📝 编写规则与配置文件

最小规则文件.semgrep.yml长这样：

rules: - id: no-print-in-prod languages: [python] pattern: print(...) message: 用 logging 模块替代 print() severity: WARNING

运行semgrep scan --config=.semgrep.yml .即可。常用参数取舍：

• --config：本地文件、目录或注册表规则集 ID，可多次指定叠加；
• --error：只要有任何 finding 就以非零码退出，是接入自动化的关键开关；
• --severity：按严重级别过滤输出；
• --metrics=off：关闭匿名使用指标上报（使用注册表配置时默认开启）。

🔗 接入开发流程

接入 CI 流水线

登录账号后，CI 中推荐用semgrep ci而不是scan：它同时检查源码与依赖漏洞，且针对 pull request 场景只报告本次改动引入的问题——存量问题不会阻塞合并，适合在大量历史代码的项目上冷启动。

semgrep ci --config=p/security --metrics=off

它适配主流 CI 平台（GitHub Actions、GitLab、Jenkins、CircleCI、Azure Pipelines 等）。

接入 pre-commit 钩子

在本地提交前拦截，避免问题进入仓库：

- repo: local hooks: - id: semgrep name: semgrep entry: semgrep scan --config=.semgrep.yml --error language: system

团队共享同一份.semgrep.yml放进仓库，本地与 CI 的行为就保持一致。

高频问题速查

• 现象：pip 安装失败或依赖冲突。→原因：pip 或 Python 版本过旧。→处理：升级 pip 后重试，或改用 Docker 方式运行，完全绕开本地环境。
• 现象：扫描结果是 0 findings，但人工确认应命中。→原因：规则languages与文件后缀不符，或文件被排除逻辑过滤。→处理：加--verbose查看实际目标文件清单，用--include单独指向目标文件验证规则本身。
• 现象：大仓库扫描明显偏慢。→原因：规则集过大且无范围限制。→处理：用--include限定目录，或在 CI 中只扫变更部分。
• 现象：加了--error后 CI 一直红。→原因：任意 finding 都导致非零退出码。→处理：先修低级别问题或调整--severity，存量问题用semgrep ci的增量报告策略隔离。

延伸资源

• README.md：总览、语言支持、安装与升级方式
• cli/tests/README.md：单测与端到端快照测试结构，改行为前先读
• tests/rules/ 与 tests/patterns/：上千条真实规则与配对测试代码，是规则写法最好的样例库

下一步建议：先对当前项目跑一次--config=auto全量扫描摸底，把最关心的命中固化进.semgrep.yml，再接入 CI 的增量扫描。

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