SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场semgrep-sast-scan

semgrep-sast-scan

安全与审计

查看项目

更新于 10-16 05:37

技能介绍

用途

本技能用于对源代码仓库运行 SAST（静态应用安全测试）扫描。它使用 Semgrep Code，并连接到组织的 Semgrep AppSec Platform 云实例。

前置条件

运行扫描前，需确认以下环境变量已配置。若有缺失，需先处理并参考下方环境设置部分。

变量 是否必需 用途
SEMGREP_APP_TOKEN 是 来自 Semgrep AppSec Platform 的认证令牌（Settings > Tokens）
SEMGREP_APP_URL 否 默认为 https://semgrep.dev，仅单租户部署时设置
SEMGREP_REPO_NAME 否 覆盖自动检测的仓库名，用于关联发现项
SEMGREP_TIMEOUT 否 每个文件的扫描超时秒数（默认：5）

快速检查：运行预检脚本以在扫描前验证环境：

bash /path/to/semgrep-sast-scan/scripts/preflight.sh

如果预检失败，不要继续扫描，应先解决问题。

主要能力与扫描模式

  • 全量扫描（semgrep ci --code）：扫描整个代码库。适用于默认/主分支和定时夜间扫描，报告所有发现项。
  • 差异感知扫描（semgrep ci --code 配合 SEMGREP_BASELINE_REF）：仅扫描自基线引用以来变更的文件。适用于 PR/MR 扫描，只报告新引入的发现项。
  • 跨文件分析：启用跨文件与跨函数的程序间分析。可减少误报、增加真阳性，但耗时更长。可在 Semgrep AppSec Platform 的 Settings > General > Code 中启用，或向扫描脚本传递 --cross-file。

使用方式

第 1 步：预检（始终先运行）

bash <skill-dir>/scripts/preflight.sh

该脚本会验证 semgrep 是否已安装、SEMGREP_APP_TOKEN 是否已设置、当前目录是否为 Git 仓库，以及令牌能否成功通过 Semgrep 平台认证。

第 2 步：在目标项目根目录执行扫描

# 全量 SAST 扫描（推荐用于主/默认分支和初始扫描）
bash <skill-dir>/scripts/run-sast-scan.sh

# 差异感知扫描（用于拉取请求 — 仅扫描变更文件）
bash <skill-dir>/scripts/run-sast-scan.sh --diff-aware

# 启用跨文件分析的全量扫描
bash <skill-dir>/scripts/run-sast-scan.sh --cross-file

# 扫描并将 JSON 输出保存到文件
bash <skill-dir>/scripts/run-sast-scan.sh --output json

# 扫描并输出 SARIF（用于 GitHub Advanced Security Dashboard 集成）
bash <skill-dir>/scripts/run-sast-scan.sh --output sarif

第 3 步：查看结果

扫描完成后：终端输出会按严重级别显示发现项摘要；Semgrep AppSec Platform 提供完整发现项仪表板，含代码超链接、分诊工具与 AI 辅助修复；若使用了 --output json 或 --output sarif，报告文件会以 semgrep-sast-results.<format> 保存到当前目录。

项目团队环境设置（一次性）

  1. 生成 SEMGREP_APP_TOKEN：登录 https://semgrep.dev/orgs/vchirrav_personal_org ，进入 Settings > Tokens，点击 Create new token，复制令牌值。

  2. 配置令牌：

  • 本地开发：将 export SEMGREP_APP_TOKEN="your-token-here" 添加到 shell 配置文件（~/.bashrc、~/.zshrc 等）；或在项目根目录创建 .env 文件（并将 .env 加入 .gitignore）：SEMGREP_APP_TOKEN=your-token-here
  • GitHub Actions：在仓库 Settings > Secrets and variables > Actions 添加仓库密钥 SEMGREP_APP_TOKEN，并在工作流中引用：
env:
  SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
  • GitLab CI：在 Settings > CI/CD > Variables 中将 SEMGREP_APP_TOKEN 添加为 masked 变量。
  • 其他 CI：在 CI 提供商的配置中将 SEMGREP_APP_TOKEN 设置为 secret/环境变量，参考 https://semgrep.dev/docs/semgrep-ci/sample-ci-configs 。
  1. 安装 Semgrep CLI：
# macOS
brew install semgrep

# pip（任意操作系统）
pip install semgrep

# Docker（无需本地安装）
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep ci --code
  1. 可选环境变量：
# 覆盖 Semgrep AppSec Platform 中的仓库显示名
export SEMGREP_REPO_DISPLAY_NAME="my-service-name"

# 增加大文件的每文件超时（默认 5 秒）
export SEMGREP_TIMEOUT=30

# 用于差异感知扫描时设置基线分支
export SEMGREP_BASELINE_REF="origin/main"

适用场景

  • 对默认/主分支或初始代码库执行全量 SAST 扫描。
  • 在 PR/MR 中执行差异感知扫描，仅报告新引入的发现项。
  • 需要跨文件/跨函数分析以减少误报时。
  • 将结果集成到 GitHub Advanced Security Dashboard（通过 SARIF 输出）。
  • 在 CI/CD 中自动运行扫描（GitHub Actions、GitLab CI 等）。

限制与故障排查

  • 必须设置 SEMGREP_APP_TOKEN；缺少时不要继续扫描。
  • 预检失败时不得继续扫描。

常见问题与处理：

现象 处理
Error: Not logged in 确保 SEMGREP_APP_TOKEN 已在 shell 中导出
平台未收到发现项 检查 SEMGREP_APP_TOKEN 是否有效且未过期
大文件扫描超时 增大 SEMGREP_TIMEOUT（如 export SEMGREP_TIMEOUT=60）
发现项不显示代码链接 显式设置 SEMGREP_REPO_URL 和 SEMGREP_REPO_NAME
CI 与本地结果不同 确保 Semgrep 版本一致；CI 默认使用差异感知模式

参考

  • Semgrep AppSec Platform：https://semgrep.dev/orgs/vchirrav_personal_org
  • Semgrep 文档：https://semgrep.dev/docs
  • CI 环境变量：https://semgrep.dev/docs/semgrep-ci/ci-environment-variables
  • 示例 CI 配置：https://semgrep.dev/docs/semgrep-ci/sample-ci-configs