1. 项目概述为什么我们需要Semgrep在代码安全审查和漏洞排查的日常工作中我们常常面临一个困境传统的静态应用安全测试工具SAST要么太重配置复杂、扫描缓慢要么规则不够灵活面对框架更新或自定义代码模式时捉襟见肘。而人工代码审计虽然精准但效率低下难以覆盖海量代码库。正是在这种背景下Semgrep以其“快速、灵活、易上手”的特性迅速成为了开发者和安全工程师手中的利器。简单来说Semgrep是一个开源的、基于模式的静态代码分析工具。它允许你用类似代码本身的语法来编写规则从而在代码库中快速查找特定的模式、漏洞或代码异味。无论是寻找一个已知的Fastjson远程代码执行漏洞模式还是排查一个自定义的、可能导致内存泄漏的API误用Semgrep都能让你像写一段代码一样快速构建出精准的“探测器”。我最初接触Semgrep是为了应对一次紧急的第三方库漏洞排查。当时一个关键的Java服务被爆出使用了存在远程代码执行漏洞的Fastjson版本。面对数十万行代码和错综复杂的依赖关系手动查找所有使用点无异于大海捞针。而传统的SAST工具扫描一次需要数小时且规则库可能还未更新。正是在那时我花了一个下午学习Semgrep写了一条不到10行的规则在几分钟内就定位了所有潜在的风险点。这种“所见即所得”的规则编写方式和闪电般的扫描速度让我彻底被它折服。本指南旨在带你快速跨越从“知道Semgrep”到“能用Semgrep高效解决实际问题”的鸿沟。我们将避开冗长的理论直接切入实战通过构建针对真实场景如Fastjson漏洞、OOM排查、代码泄露检测的规则让你掌握这门能极大提升排查效率的“手工艺”。2. Semgrep核心机制与快速上手要高效使用任何工具理解其核心工作机制是关键。这能帮助你在编写规则和排查问题时做出更合理的决策。2.1 模式匹配引擎它到底是怎么“看”代码的Semgrep的核心是一个高度优化的模式匹配引擎。与基于抽象语法树AST进行复杂分析的工具有所不同Semgrep的匹配更“直观”。你可以把它想象成一个超级增强版的grep但它理解代码的结构。它首先将你的源代码解析成一种语言无关的泛化ASTGeneric AST, GAST。然后你编写的规则模式pattern也会被解析成同样的GAST。最后Semgrep在源代码的GAST中寻找与你规则模式GAST相匹配的子树。这个过程支持元变量Metavariables 用$X、$FUNC这样的符号代表任意表达式、函数名等。这是规则灵活性的基础。省略号Ellipsis...操作符可以匹配零个或多个任意元素如参数、语句、字段。它让你可以忽略模式中不关心的部分。等价匹配Equivalences 引擎知道a b和b a在数学上是等价的foo(1,2)和foo(1, 2)多一个空格在语义上是相同的。这减少了因格式差异导致的漏报。例如你想查找所有调用JSON.parseObject()的地方。一条简单的规则模式可以是JSON.parseObject(...)。这里的...就会匹配任何参数无论是一个字符串变量还是一个复杂的表达式。注意 Semgrep的匹配是“语法层面”的而非“语义层面”。它不会执行数据流分析除非结合taint模式。这意味着它擅长找“代码长什么样”的问题对于需要跟踪变量值传播的复杂漏洞需要更精巧的规则设计或结合其他工具。2.2 五分钟完成安装与第一次扫描Semgrep的安装极其简单这是它友好的第一步。对于个人使用CLI工具 最推荐的方式是通过包管理器安装。在macOS上可以使用Homebrewbrew install semgrep在Linux或WSL中可以使用pipPython包管理器python3 -m pip install semgrep安装完成后在终端输入semgrep --version验证。在CI/CD管道中 Semgrep官方提供了适用于GitHub Actions、GitLab CI、Jenkins等的标准操作步骤。通常你只需要在配置文件中添加一个步骤例如在GitHub Actions中- name: Run Semgrep uses: semgrep/semgrep-actionv1 with: config: p/ci # 使用Semgrep官方的CI规则集现在让我们进行第一次扫描。假设你有一个项目目录./my-project你想用Semgrep社区提供的通用规则集先扫一遍看看。semgrep scan --config auto ./my-project--config auto参数会让Semgrep自动根据项目中的语言文件选择合适的社区规则集进行扫描。几秒到几分钟后取决于项目大小你会在终端看到一个清晰的扫描结果表格包含问题级别、规则ID、位置和简要描述。实操心得 第一次运行时如果网络环境访问GitHub规则仓库较慢可能会在下载规则时卡住。你可以通过设置环境变量SEMGREP_RULES_REPO指向一个镜像源或者先使用离线模式semgrep --config local_rule.yaml ./my-project其中local_rule.yaml是你自己写的或本地保存的规则文件。3. 规则编写实战从漏洞模式到自定义检查Semgrep真正的威力在于自定义规则。官方规则库Semgrep Registry覆盖了常见漏洞但面对内部API误用、特定业务逻辑缺陷或最新的0day漏洞时自己写规则是必经之路。3.1 解剖一条规则以Fastjson远程代码执行漏洞检测为例让我们以近期热门的Fastjson 1.2.83远程代码执行漏洞CVE-2022-25845为例。该漏洞的触发点与特定的autoType开关及反序列化调用有关。一条简化的检测规则可能如下rules: - id: fastjson-unsafe-deserialization pattern: | JSON.parseObject(..., $CLASS) message: 发现使用JSON.parseObject并指定了Class参数可能存在Fastjson反序列化风险。请确保传入的$CLASS是安全可信的或升级至安全版本并校验autoType。 languages: [java] severity: ERROR metadata: cve: CVE-2022-25845 category: security我们来拆解这条规则的每个部分id: 规则的唯一标识符在输出中显示。pattern: 核心匹配模式。JSON.parseObject(..., $CLASS)匹配任何调用parseObject且至少有两个参数...匹配第一个参数$CLASS匹配第二个参数即目标类的代码。$CLASS是一个元变量。message: 当匹配成功时向用户展示的信息。这里给出了风险提示和修复建议。languages: 规则适用的编程语言列表。severity: 问题严重级别ERROR, WARNING, INFO等。metadata: 可选的元数据用于存放CVE编号、分类、引用链接等方便集成到问题跟踪系统。但这规则太宽泛了会误报很多正常代码。我们需要优化。假设漏洞只在parseObject的第二个参数是com.某公司.某模块.Entity这类特定类且未开启SAFE_MODE时触发。我们可以写得更精确rules: - id: fastjson-cve-2022-25845-specific patterns: - pattern: | JSON.parseObject($JSON, $TYPE) - metavariable-pattern: metavariable: $TYPE pattern: | com.某公司.某模块.Entity - pattern-not: | ParserConfig.getGlobalInstance().setSafeMode(true) message: 使用存在漏洞的Fastjson版本反序列化特定类$TYPE且未全局开启安全模式存在CVE-2022-25845远程代码执行风险。 languages: [java] severity: ERROR这里使用了patterns组合和pattern-notpatterns是一个列表所有子模式必须同时匹配。这里第一个模式匹配parseObject调用第二个metavariable-pattern限制$TYPE必须是特定的类。pattern-not是反模式匹配到的代码将被排除。这里排除了已经全局设置了安全模式的代码上下文。注意事项 编写安全规则时平衡“检出率”和“误报率”是艺术。过于宽泛的规则会产生大量噪音让开发团队忽视所有告警过于严格的规则又会漏报。通常建议从精确规则开始再根据实际情况适度放宽。3.2 构建你的排查工具箱OOM与资源泄漏检测安全漏洞之外Semgrep在排查性能问题、资源泄漏方面同样出色。例如OutOfMemoryError: Compressed class space错误通常与大量动态类加载有关比如频繁使用反射或某些框架的动态代理。我们可以编写规则来寻找可能导致类加载器泄漏或过度动态加载的模式rules: - id: potential-classloader-leak patterns: - pattern: | $CLASS.forName(...) - pattern-inside: | public void $METHOD(...) { ... } message: 在方法$METHOD中发现了Class.forName的动态类加载调用。如果在高频执行路径如循环、请求处理中可能导致Compressed Class Space持续增长最终引发OOM。考虑将类加载移至静态块或缓存Class对象。 languages: [java] severity: WARNING这条规则会找到所有在方法体内调用Class.forName的地方。虽然并非所有这样的调用都会导致问题但它能快速帮你定位所有需要人工审查的“嫌疑点”。对于更常见的资源泄漏比如数据库连接、文件流未关闭Semgrep可以轻松检测rules: - id: unclosed-db-connection pattern: | $CONN $DRIVER.getConnection(...); ... message: 发现数据库连接获取但未在相同作用域内看到显式的$CONN.close()调用。请确保在finally块或try-with-resources中关闭连接。 languages: [java] severity: WARNING这条规则利用了...来匹配获取连接和后续代码但它无法进行复杂的控制流分析来确定close()是否一定会被调用。因此它更适用于快速筛查和代码审查提醒。实操心得 对于资源泄漏排查我通常会写两条规则一条宽泛的如上用于初筛另一条更精确的使用pattern-not来匹配已知的安全模式如try ($CONN ...) { ... }Java try-with-resources或finally { if ($CONN ! null) $CONN.close(); }。这样可以有效减少误报。4. 高级技巧与集成将Semgrep融入开发流程掌握了基础规则编写后如何让Semgrep发挥最大价值答案是将其集成到日常开发流程中。4.1 使用taint模式进行数据流追踪当简单的模式匹配不够用时比如需要追踪用户输入源是否未经净化就到达危险函数汇就需要数据流分析。Semgrep的taint模式提供了轻量级的数据流追踪能力。假设我们想检查Spring MVC控制器中用户参数是否直接用于拼接SQL语句一种SQL注入漏洞模式rules: - id: spring-sql-injection-taint mode: taint pattern-sources: - pattern: | RequestMapping(...) public ... $METHOD(RequestParam $PARAM, ...) { ... } - pattern: | GetMapping(...) public ... $METHOD(RequestParam $PARAM, ...) { ... } pattern-sinks: - pattern: | jdbcTemplate.execute(...) - pattern: | $CONN.createStatement().execute(...) message: 用户输入参数$PARAM可能未经检查直接流入SQL执行语句存在SQL注入风险。 languages: [java] severity: ERROR在这个规则中mode: taint启用了污点分析模式。pattern-sources定义了污点源这里匹配Spring的控制器方法参数。pattern-sinks定义了污点汇即危险的SQL执行点。Semgrep会自动分析从source到sink的数据流路径如果存在可达路径则报告问题。注意 Semgrep的污点分析是过程内的intra-procedural默认不跨函数边界进行深度追踪。对于复杂的跨函数调用分析可能受限。但对于控制器到DAO层这种常见的直接调用场景它非常有效。4.2 在CI/CD中自动运行与结果管理将Semgrep嵌入CI/CD可以在代码合并前自动拦截问题。以GitHub Actions为例一个基本的配置如下name: Semgrep SAST on: [pull_request] jobs: semgrep: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Run Semgrep uses: semgrep/semgrep-actionv1 with: config: - p/security-audit p/java .semgrep.yml # 同时使用你的自定义本地规则 output-format: sarif # 输出SARIF格式便于GitHub集成显示 severity: ERROR,WARNING关键点on: [pull_request] 在创建或更新拉取请求时触发。config: 这里同时指定了官方的security-audit安全审计和java规则集以及项目根目录下的自定义规则文件.semgrep.yml。规则集用空格分隔。output-format: sarif: 将结果输出为SARIF格式GitHub Security Tab可以直接解析并展示这些结果提供良好的可视化体验。severity: 只报告ERROR和WARNING级别的问题忽略INFO。常见问题与排查问题CI中扫描时间过长。排查检查是否扫描了node_modules,target,.git等无关目录。在项目根目录创建.semgrepignore文件语法类似.gitignore忽略这些目录。问题自定义规则在CI中不生效。排查确保规则文件路径在config中正确指定且文件语法无误。可以在本地先用semgrep --config .semgrep.yml --validate命令验证规则文件。问题误报太多团队抱怨。排查这是SAST工具的共性问题。不要试图用一条规则覆盖所有情况。可以编写更精确的规则。使用pattern-not排除已知的安全模式。在规则中添加metadata如confidence: LOW并在CI中按置信度过滤。利用Semgrep的--autofix建议如果规则支持或提供清晰的修复指南降低修复成本。最重要的是建立团队对工具结果的信任将其作为辅助审查手段而非绝对判决。4.3 管理自定义规则库当团队积累了大量自定义规则后如何管理推荐两种方式单仓库内管理在项目根目录维护一个.semgrep/目录将规则按功能分类存放如.semgrep/security/、.semgrep/performance/。在主配置文件.semgrep.yml中使用rules:字段引入这些文件rules: - .semgrep/security/fastjson.yml - .semgrep/performance/oom.yml - .semgrep/best-practices/string-concat.yml独立规则仓库创建一个独立的Git仓库专门存放团队或公司的Semgrep规则。在CI配置或项目配置中直接引用该仓库的URL或路径。# 在.semgrep.yml中 rules: - https://raw.githubusercontent.com/your-org/semgrep-rules/main/security/java.yml这种方式便于规则的版本控制、共享和统一更新。我个人更倾向于第二种方式尤其对于拥有多个微服务的中大型团队。它确保了所有服务使用的安全与代码质量规则是统一且最新的。5. 实战案例串联一次完整的漏洞应急响应让我们把上面的知识串联起来模拟一个完整的应急响应场景“紧急线上服务使用的Fastjson被曝出1.2.83版本存在远程代码执行漏洞需要立即排查所有受影响代码并进行修复。”步骤1 快速编写精准检测规则根据漏洞公告我们知道漏洞触发需要同时满足1) 使用了受影响版本的Fastjson2) 调用了JSON.parseObject或JSON.parse且传入了特定的autoType相关参数或特定类。我们优先编写检测“使用点”的规则。为了减少误报我们假设团队有代码规范反序列化类都放在com.company.model.dto包下。# fastjson-emergency-scan.yaml rules: - id: emergency-fastjson-unsafe-call patterns: - pattern-either: - pattern: JSON.parseObject(..., $TYPE) - pattern: JSON.parse(..., $TYPE) - metavariable-regex: metavariable: $TYPE regex: ^com\.company\.model\.dto\. message: 紧急发现使用Fastjson反序列化公司DTO类 $TYPE该用法在Fastjson 1.2.83中可能存在远程代码执行漏洞(CVE-2022-xxxx)。请立即评估并升级Fastjson版本或替换为Jackson/Gson。 languages: [java] severity: CRITICAL这里使用了pattern-either来匹配两种调用方式metavariable-regex来限制类名范围。步骤2 本地快速扫描定位在代码库根目录运行semgrep scan --config ./fastjson-emergency-scan.yaml --severity CRITICAL --json findings.json使用--json输出并将结果重定向到文件便于后续处理。--severity过滤只显示关键问题。步骤3 结果分析与人工复核打开findings.json你会看到一个结构化的结果列表包含每个匹配的文件路径、行号、代码片段。由于我们的规则已经相对精确这些结果就是需要重点审查的“热区”。将结果列表分发给相应模块的负责人。步骤4 制定修复方案并验证修复方案通常是1) 升级Fastjson到安全版本如1.2.83之后的安全补丁版本2) 在无法立即升级时全局开启SAFE_MODE。我们可以写另一条规则来检查修复是否到位rules: - id: check-fastjson-safe-mode pattern-not: | ParserConfig.getGlobalInstance().setSafeMode(true); pattern-inside: | static { ... } message: 建议在静态初始化块中显式设置Fastjson安全模式。如果已升级至安全版本此规则可忽略。 languages: [java] severity: INFO这条规则会寻找那些没有在静态块中设置安全模式的类假设这是团队约定的修复位置。运行此规则可以帮助确认修复措施是否被广泛应用。步骤5 集成到CI防止回溯将紧急检测规则emergency-fastjson-unsafe-call加入团队的中央规则库或关键服务的CI流水线中并设置为阻塞项severity: CRITICAL。这样任何试图再次引入危险调用模式的代码合并都会被自动拒绝。通过这个实战流程Semgrep从一个扫描工具变成了贯穿应急响应“检测-分析-修复-防护”全流程的核心助力。它节省的不仅仅是手动搜索代码的时间更是为团队建立了一种快速响应安全威胁的标准化能力。最后我想分享的一点个人体会是不要把Semgrep仅仅当作一个“找漏洞”的工具。它的本质是一个“代码模式搜索与匹配引擎”。你可以用它来推行代码规范如禁止使用System.out.println、检查API误用、甚至做简单的代码质量度量如查找过长的函数。当你开始用“模式”的思维去看待代码中的问题时你会发现很多重复性的审查工作都可以被自动化从而让你有更多时间聚焦在更复杂、更有创造性的任务上。从一条简单的规则开始逐步构建属于你自己和团队的“自动化代码审查清单”这才是掌握Semgrep带来的最大长期价值。