Semgrep代码审计工具的使用
1 Semgrep简介
Semgrep（Semantic Grep）是一款开源的轻量级静态代码分析工具（SAST），由安全公司r2c开发和维护。它采用模式匹配的方式在代码中搜索特定模式，从而识别安全漏洞、代码质量问题和不安全的编码实践。与传统静态分析工具相比，Semgrep以其极致的高速扫描、简单的规则编写语法和多语言支持能力而著称，已经成为现代DevSecOps流程中的重要组成部分。
与许多复杂的静态分析工具不同，Semgrep允许开发者和安全工程师使用类似于代码的语法来编写检测规则，大幅降低了自定义规则的门槛。
在代码审计领域，Semgrep填补了简单文本搜索（如grep）和复杂程序分析（如CodeQL）之间的空白。它不像传统grep那样局限于纯文本匹配，也不像完整静态分析工具那样需要复杂的编译环境和学习曲线。这种平衡使得Semgrep特别适合在开发流程早期发现问题和实施代码规范。
表：Semgrep与主流SAST工具的对比
| 特性 | Semgrep | CodeQL | SonarQube |
|---|---|---|---|
| 规则编写难度 | 低（YAML语法） | 高（QL查询语言） | 中（XML/Java API） |
| 扫描速度 | 极快（20K-100K loc/sec/规则） | 慢（约600 loc/sec/规则） | 中等（约400 loc/sec） |
| 支持语言 | 17+种语言 | 5+种主要语言 | 20+种语言 |
| 是否需要编译 | 否 | 是 | 否 |
| 数据流分析 | 基础污点跟踪 | 强大的过程间分析 | 基础分析 |
| 开源协议 | LGPL 2.1 | 商业许可（开源免费） | 社区版+商业版 |
2 核心功能与特性
Semgrep提供了一系列强大功能，使其在代码审计领域具有显著优势。首先是其广泛的语言支持，目前已经覆盖了17种以上编程语言，包括JavaScript、TypeScript、Python、Java、Go、PHP、C/C++、C#、Ruby、Swift、Kotlin等主流语言。这种广泛的支持使得团队可以在多语言项目中保持一致的代码审计标准。
另一个核心特性是Semgrep的规则系统。规则采用直观的YAML格式编写，允许用户定义要查找的模式。规则语法基于代码模式而非抽象文本模式，使得规则看起来就像它们要匹配的代码。关键语法元素包括：元变量（如$X）匹配任意表达式、语句或变量；省略号运算符（...）匹配零个或多个任意元素；模式运算符允许组合多个模式条件。例如，检测PHP中eval使用的规则非常简单：
rules:- id: eval-usepattern: eval(...)message: Using eval is dangerouslanguages: [php]severity: ERROR
Semgrep支持多种检测模式，满足了不同场景下的审计需求：
- search模式：基础模式，用于简单的语法模式匹配
- taint模式：污点跟踪能力，可以检测从用户输入源（source）到危险函数（sink）的数据流，并考虑净化函数（sanitizer）
- join模式：允许组合多个规则的结果进行关联分析
尽管Semgrep的污点跟踪能力不如专业静态分析工具强大，但它仍然能够处理许多常见的数据流安全问题。例如，它可以检测到XSS、SQL注入和命令注入等漏洞模式：
rules:- id: taint-examplelanguages: [python]message: Found dangerous HTML outputmode: taintpattern-sources:- pattern: get_user_input(...)pattern-sinks:- pattern: html_output(...)pattern-sanitizers:- pattern: sanitize_input(...)severity: WARNING
Semgrep还具备自动化修复能力，对于检测到的问题不仅可以报告，还可以提供自动修复建议。通过AutoFix语法，规则可以指定如何修改不安全代码，这大大减少了修复技术债务的工作量。
此外，Semgrep与现代开发流程无缝集成。它提供IDE插件（VSCode、IntelliJ IDEA、Vim）、Git钩子支持、CI/CD集成（GitHub Actions、GitLab CI、Jenkins等）和Docker容器化部署选项。这些特性使得Semgrep可以嵌入到开发流程的各个阶段，从代码编写到提交，再到CI流水线，都能实施质量保障。
表：Semgrep对流行框架的支持情况
| 语言 | 框架 | 支持情况 | 示例 |
|---|---|---|---|
| Python | Django/Flask/SQLAlchemy | 一般 | 检测Django CSRF配置 |
| Java | Spring | 较好 | Spring特定注解检测 |
| JavaScript/TypeScript | Express/React/Vue/Angular | 一般 | Express路由安全检测 |
| Go | Gorilla/gRPC | 一般 | SQL拼接检测 |
| PHP | Laravel | 一般 | 危险函数检测 |
3 工作原理与架构
Semgrep的核心工作机制基于模式匹配，它通过将代码解析为抽象语法树（AST），然后在AST层面进行模式匹配，而不是在纯文本层面进行搜索。这种方法结合了正则表达式的灵活性和AST分析的结构化优势，既能够理解代码结构，又保持了简单易用的特点。
Semgrep的架构分为两个主要组件：semgrep-core和semgrep-cli。semgrep-core是用OCaml编写的核心引擎，负责将代码解析为AST并执行模式匹配。OCaml语言的选择并非偶然，其强大的类型系统和函数式编程特性非常适合实现复杂的代码分析算法。semgrep-cli则是用Python编写的命令行接口，处理文件遍历、输出格式化和工具集成等任务。
当Semgrep执行扫描时，它会经历以下几个关键步骤：
- 解析阶段：将目标代码解析为语言特定的AST
- 转换阶段：将规则模式转换为统一的AST表示
- 匹配阶段：在目标AST中搜索匹配模式的结构
- 报告阶段：将匹配结果转换为指定格式输出
对于使用了taint模式的规则，Semgrep还会执行数据流分析步骤，跟踪从源点到汇聚点的数据传播路径，并考虑净化函数的影响。
Semgrep的模式匹配能力既强大又灵活。元变量（metavariables）是其中的关键特性，以$开头的标识符（如$X、$VAR）可以匹配任意表达式、语句或标识符。这使得规则可以捕捉类似但又不完全相同的代码模式。例如，检测各种调用方式的规则：
rules:- id: dangerous-function-callpattern: dangerous_function($ARG)message: Call to dangerous function with argument $ARG
省略号运算符（...）是另一个强大功能，它可以匹配零个或多个任意元素，包括参数、语句、表达式甚至字段。这使得规则可以忽略不关心的代码部分，专注于关键模式：
rules:- id: nested-loopspattern: |for (...) {...for (...) {...for (...) {...}}}message: Triple nested loop may indicate performance issues
Semgrep还支持等式模式（equivalence matching），能够识别代码结构相同但编写方式不同的模式。例如，它可以识别不同的循环结构（for、while）、不同的语法糖，甚至部分重构的代码。
然而，Semgrep也有一些架构限制。最主要的是其过程间分析能力较弱，难以跨函数边界跟踪数据流。这意味着如果源点和汇点不在同一个函数内，Semgrep可能无法检测到潜在的漏洞。此外，虽然Semgrep支持简单的常量传播和符号执行，但对于复杂的控制流分析，它的能力有限。
4 安装与使用方法
Semgrep的安装过程简单直接，提供了多种安装方式以适应不同环境。最常用的方法是通过Python的pip包管理器安装，这是官方推荐的方式:
# For macOS
$ brew install semgrep# For Ubuntu/WSL/Linux/macOS
$ python3 -m pip install semgrep# To try Semgrep without installation run via Docker
$ docker run -it -v "${PWD}:/src" semgrep/semgrep semgrep login
$ docker run -e SEMGREP_APP_TOKEN=<TOKEN> --rm -v "${PWD}:/src" semgrep/semgrep semgrep ci
安装完成后，基本使用命令非常简单。最常见的用法是使用预定义规则集(https://semgrep.dev/explore)进行扫描，Semgrep社区维护了超过1000条规则，覆盖安全漏洞、代码质量和错误检测等多个方面:
# 使用社区规则扫描当前目录
semgrep --config "p/security-audit"# 使用特定语言规则集
semgrep --config "p/java"# 使用多个规则集
semgrep --config "p/java" --config "p/security-audit"
除了使用预定义规则，还可以使用本地自定义规则文件：
# 使用本地规则文件
semgrep scan --config /Users/linyu/文档/vuln_code/java-sec-code/test.yaml# 使用下载到本地的官方规则
semgrep scan --config java（目录名称）# 扫描并输出JSON结果
semgrep --config "p/security-audit" --json -o results.json .# 扫描并自动应用修复
semgrep --config "p/security-audit" --autofix
Semgrep支持多种输出格式，包括文本、JSON、SARIF和GitLab SAST等，便于集成到不同平台和工具链中。特别是JSON输出格式，包含了详细的代码位置、消息和严重性信息，适合后续自动化处理。
为了将Semgrep集成到CI/CD流程中，可以参考以下GitLab CI示例:
# .gitlab-ci.yml示例
semgrep-scan:image: returntocorp/semgrep:latestscript:- semgrep --config "p/security-audit" --json -o semgrep-results.json .artifacts:reports:sast: semgrep-results.json
或者使用GitHub Actions集成:
# .github/workflows/semgrep.yml示例
name: Semgrep Scan
on: [push, pull_request]
jobs:semgrep:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v2- uses: returntocorp/semgrep-action@v1with:config: p/security-auditoutput_format: sarifoutput_file: semgrep-results.sarif
5 规则开发实践
Semgrep规则采用YAML格式编写，这种设计使得规则既人类可读又机器可处理。一个完整的规则文件通常包含一个或多个规则定义，每个规则由多个组件构成。规则开发是Semgrep最具特色的能力，让用户能够快速创建自定义检测模式以适应项目特定需求。
基本规则结构包含以下必要字段:
- id: 规则的唯一标识符，采用简短描述性命名
- message: 当规则匹配时显示的消息，说明问题及其潜在影响
- languages: 规则适用的编程语言列表
- severity: 问题严重级别（ERROR、WARNING、INFO）
- pattern(s): 定义要匹配的代码模式
以下是一个简单的规则示例，用于检测Python中可能不安全的assert语句使用：
rules:- id: python-assert-uselanguages: [python]message: |Using assert with user input is equivalent to eval and may be dangerous.pattern: assert($ASSERT, ...)pattern-not: assert("...", ...)severity: ERROR
对于更复杂的场景，Semgrep提供了多种模式运算符来精确控制匹配逻辑：
- pattern: 匹配特定代码模式
- patterns: 包含多个子模式，所有模式都必须匹配
- pattern-either: 多个模式中的任意一个匹配即可
- pattern-not: 排除特定模式，用于减少误报
- pattern-inside: 将匹配限制在特定代码结构内部
- pattern-not-inside: 排除特定结构内部的代码
例如，检测SQL拼接漏洞的规则可以使用多个模式组合:
rules:- id: python-sql-concatlanguages: [python]message: |Potential SQL injection vulnerability through string concatenation.patterns:- pattern: execute("...$SQL...")- pattern-not: execute("...")- metavariable-regex:metavariable: $SQLregex: (\+|%\s*\+|f\s*")severity: ERROR
taint模式规则用于数据流分析，需要定义source、sink和可选的sanitizer:
rules:- id: express-injectionmode: taintlanguages: [javascript]pattern-sources:- pattern: req.query.$PARAM- pattern: req.body.$PARAMpattern-sinks:- pattern: execSync(...)pattern-sanitizers:- pattern: sanitizeInput(...)message: |Passing user-controlled Express query parameter to a command injection.severity: ERROR
Semgrep还支持元变量正则表达式过滤，进一步精确匹配内容。这对于检测特定格式的字符串或标识符非常有用：
rules:- id: hardcoded-credentialslanguages: [python]message: |Potential hardcoded credential detected.patterns:- pattern: $VARIABLE = "..."- metavariable-regex:metavariable: $VARIABLEregex: (password|passwd|pwd|secret|key|token)severity: WARNING
为了确保规则质量，在开发过程中应当遵循以下最佳实践：
- 全面测试：使用正例和反例测试规则，确保既能捕捉真正问题又不会产生误报
- 使用具体模式：尽量避免过于宽泛的模式，限定在特定上下文环境中
- 利用排除模式：使用pattern-not排除已知的误报情况
- 提供明确消息：在message中说明问题原因和修复建议
- 添加参考链接：在metadata中提供相关文档链接
