Semgrep 官方 Docker 镜像文档

镜像概述与主要用途

Semgrep 是一款开源的静态代码分析工具，通过模式匹配识别代码中的错误、安全漏洞及代码规范问题。Semgrep 官方 Docker 镜像提供了便捷的容器化部署方式，无需本地安装依赖，即可快速在各类环境中运行代码扫描任务。

注意：Semgrep 官方 Docker 镜像已迁移至 semgrep/semgrep，旧镜像 returntocorp/semgrep 可能不再维护，建议使用新镜像地址。

核心功能与特性

• 多语言支持：兼容 Python、JavaScript、Java、Go、Ruby 等主流编程语言。
• 模式匹配规则：通过类代码语法的规则定义，快速识别目标代码模式（如未授权访问、硬编码密钥等）。
• 自定义规则：支持用户编写或导入自定义规则文件（.yaml 格式），适配特定项目需求。
• CI/CD 集成：轻量级设计，可无缝集成到 GitHub Actions、GitLab CI、Jenkins 等流水线工具。
• 丰富输出格式：支持文本、JSON、SARIF 等多种输出格式，便于结果解析或对接第三方工具（如代码质量平台）。

使用场景与适用范围

• 开发阶段本地检查：开发者在提交代码前，通过容器快速扫描本地代码，提前发现问题。
• CI/CD 流水线自动化检测：在代码合并或部署前自动运行，阻断不合规代码流入生产环境。
• 代码规范 enforcement：团队统一规则库，确保代码风格、安全实践等符合项目标准。
• 安全漏洞初筛：识别常见安全缺陷（如 SQL 注入、XSS、敏感信息泄露等），降低安全风险。

使用方法与配置说明

基本使用

通过 docker run 命令启动容器，挂载目标代码目录并执行扫描：

# 扫描当前目录代码（默认使用内置规则）
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep scan

参数说明：

• --rm：扫描完成后自动删除容器。
• -v "${PWD}:/src"：将本地当前目录挂载到容器内 /src 目录（Semgrep 默认扫描路径）。
• semgrep scan：容器内执行的 Semgrep 命令（scan 为默认子命令，可省略）。

指定扫描规则

1. 使用官方规则库

通过 --config（或 -c）指定官方规则集（如安全规则 p/security、代码质量规则 p/quality）：

# 使用安全规则库扫描当前目录
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep scan --config p/security

2. 使用自定义规则文件

挂载本地规则文件（如 rules.yaml）并指定路径：

# 使用本地自定义规则扫描
docker run --rm -v "${PWD}:/src" -v "${PWD}/rules.yaml:/rules.yaml" semgrep/semgrep semgrep scan --config /rules.yaml

3. 使用环境变量配置

通过 SEMGREP_CONFIG 环境变量指定规则（优先级低于命令行 --config）：

docker run --rm -v "${PWD}:/src" -e "SEMGREP_CONFIG=p/security" semgrep/semgrep semgrep scan

输出格式配置

通过 --output（或 -o）指定输出文件及格式：

# 输出 JSON 格式结果到本地文件
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep scan --config p/security --output results.json --format json

Docker Compose 配置示例

创建 docker-compose.yml 文件，定义扫描服务：

version: '3'
services:
  semgrep-scan:
    image: semgrep/semgrep
    volumes:
      - ./:/src                  # 挂载目标代码目录
      - ./semgrep-rules:/rules   # 挂载自定义规则目录（可选）
    environment:
      - SEMGREP_CONFIG=/rules    # 指定自定义规则路径（若挂载规则目录）
      - SEMGREP_OUTPUT=results.sarif  # 输出 SARIF 格式结果（适配 GitHub Code Scanning）
    command: semgrep scan --format sarif

启动扫描：

docker-compose up

常用环境变量

注意事项

• 权限问题：若容器内扫描用户（默认 semgrep）无权限访问挂载目录，可通过 --user $(id -u):$(id -g) 调整用户 ID，避免文件权限冲突。
• 规则更新：官方规则库会定期更新，建议通过 docker pull semgrep/semgrep 拉取最新镜像以获取最新规则。
• 网络需求：使用官方规则库（如 p/security）时，容器需联网下载规则，离线环境需提前下载规则文件并本地挂载。

更多详情可参考 Semgrep 官方文档。