Semgrep 静态扫描 Baiiduu/dsh-semgrep-sast

DeepSeek Harness Semgrep SAST

@aaub-software/dsh-semgrep-sast 是一个 Cordis bundle，在 DeepSeek Harness 中暴露面向模型的 semgrep_scan 工具。它对当前工作区内的文件和目录执行只读 Semgrep SAST 扫描，返回有界、结构化的结果，供智能体结合源码上下文审查。

默认托管运行时目前支持 Windows x64。它内置 CPython 3.14.7 和 Semgrep 1.163.0，因此你无需单独安装 Python 或 Semgrep。

本版本锁定托管运行时，以规避 Windows Junction 遍历回归问题。参见兼容性决策与回归测试。

Install

DeepSeek Harness 需要 Node.js 24 或更高版本。把预构建 bundle 安装到你使用的配置档，例如 web：

dsh plugin --profile web add @aaub-software/dsh-semgrep-sast

安装后重启该配置档。智能体随后就能看到名为 semgrep_scan 的工具。

bundle 默认使用托管 Windows 运行时。在兼容系统上安装 npm 包时，也会一并安装 @aaub-software/semgrep-runtime-win32-x64。

Tool behavior

semgrep_scan 接受：

| 参数 | 必填 | 说明 |
| paths | 否 | 相对于工作区的文件或目录。默认为工作区根目录。 |
| ruleset | 否 | 规则配置。当前版本仅支持 p/default。 |
| sandbox_permissions | 仅在获批重试时 | workspace-write 或 danger-full-access。 |
| justification | 与 sandbox_permissions 搭配 | 一句话，随权限请求一并展示。 |

绝对路径、逃逸出工作区的路径，以及解析到工作区外的符号链接都会被拒绝。不暴露 Autofix。Semgrep 指标已禁用。

0.2 版本返回来自 @aaub-software/dsh-sast-contract 的公开 ssc-sast/v1 契约。结果包含扫描器来源、已扫描路径、归一化结果、诊断信息、耗时、结果总数与返回数，以及明确的截断标记。默认 bundle 配置将结果上限设为 200 条。状态为 partial 表示 Semgrep 报告了扫描诊断信息，并不表示返回的每条结果都是已确认的漏洞。

Normalized result contract

智能体收到的是归一化 JSON，而非 Semgrep 原生输出：

{
"schemaVersion": "ssc-sast/v1",
"status": "completed",
"scanner": {
"name": "semgrep",
"version": "1.163.0",
"configuration": "p/default"
},
"scannedPaths": ["src/server.js"],
"findings": [
{
"id": "semgrep:f2b91e32bb169fc1",
"scanner": "semgrep",
"rule": {
"id": "javascript.lang.security.audit.detect-eval-with-expression",
"severity": "error",
"cwe": ["CWE-95"],
"owasp": ["A03:2021"]
},json
{
"message": "检测到使用了非字面量表达式的 eval。",
"location": {
"path": "src/server.js",
"startLine": 2,
"startColumn": 18,
"endLine": 2,
"endColumn": 44
},
"fingerprint": "f2b91e32bb169fc1",
"evidence": [
{
"type": "semgrep.matched-code",
"data": { "text": "eval(req.query.expression)" }
},
{
"type": "semgrep.metavariables",
"data": { "$EXPR": "req.query.expression" }
}
]
}
],
"diagnostics": [],
"summary": {
"totalFindings": 1,
"returnedFindings": 1,
"truncated": false,
"durationMs": 125
}
}

适配器构造公开契约之前，解析器会先校验原生 Semgrep JSON。可选元数据和证据都有大小限制。CWE、OWASP、引用和指纹只在 Semgrep 输出时保留；适配器不会猜测缺失的元数据。诊断信息与发现结果分开存放，这样覆盖不完整时不会被当成一次干净的扫描。

Windows 权限审批

在当前 DeepSeek Harness ACL 沙箱内，Semgrep Core 打不开 Windows 系统证书存储。为了让更宽的权限保持显式，第一次受限调用不会启动 Semgrep。它会返回标准的 Harness 沙箱拒绝标记，并要求模型用下面的参数重试同一次扫描： json { "sandbox_permissions": "danger-full-access", "justification": "Run the requested Semgrep scan because Semgrep Core cannot access the Windows certificate store inside the Harness ACL sandbox." }

随后 Harness 会向用户请求批准。只有批准之后扫描才会运行。这个工具绝不会悄悄申请更宽的权限，也不会把它当成长期有效的权限。

安全与资源控制

- 扫描目标必须留在当前工作区内。
- 扫描是只读的，不提供自动修复。
- 用 --metrics=off 和 SEMGREP_SEND_METRICS=off 关闭指标上报。
- 缓存、配置、设置、版本缓存和日志位置都重定向到本次扫描的临时环境。
- Harness 进程服务负责取消、默认五分钟超时、两秒终止宽限期，以及进程树终止。
- 捕获的 stdout 上限为 32 MiB，stderr 上限为 1 MiB。JSON 输出超出上限时直接失败，而不是返回不完整的 JSON。
- 面向模型的发现结果按确定顺序排列并有数量上限；截断与扫描覆盖不完整会分开报告。

默认的 p/default 规则集在扫描时从 Semgrep Registry 拉取，所以当临时环境里还没有这些规则时，扫描需要网络访问。本项目不再分发 Registry 规则。

配置

随附的 bundle 层使用： yaml
- insert:
- id: semgrep-sast
name: '@aaub-software/dsh-semgrep-sast'
config:
runtimeMode: bundled
defaultRuleset: p/default
timeoutMs: 300000
maxFindings: 200

高级部署可以选择 runtimeMode: system，但必须同时提供明确的 executable。托管运行时是 Windows x64 上受支持的零安装路径。

开发 powershell
pnpm install
pnpm typecheck
pnpm build
pnpm test

仓库是 pnpm workspace。DSH 组合包位于 packages/bundle，托管运行时包位于 packages/runtimes/win32-x64。开发时会链接本地运行时包。在运行真实扫描或打包运行时之前，先组装它被忽略的二进制载荷，并运行离线回归。

许可证

组合包代码以 MIT License 发布。托管运行时是聚合分发，其各组件保留各自的上游许可证。详见 packages/runtimes/win32-x64/THIRD_PARTY_NOTICES.md 和打包的许可证文件。Semgrep Registry 规则受其自身的规则许可证约束。

@aaub-software/dsh-semgrep-sast 是一个面向 DeepSeek Harness 的 Cordis 组合包，向模型注册 semgrep_scan 工具。它只扫描当前工作区内的文件或目录，并返回有大小限制的结构化结果，供 Agent 结合源码上下文继续复核。

当前默认托管运行时支持 Windows x64，内置 CPython 3.14.7 和 Semgrep 1.163.0，用户不需要另外安装 Python 或 Semgrep。

此版本固定托管运行时版本，以避开 Windows Junction 循环遍历回归。
详见兼容方案与回归测试。

安装

DeepSeek Harness 需要 Node.js 24 或更高版本。将已经构建好的 npm 组合包安装到实际使用的 profile，例如 web： powershell
dsh plugin --profile web add @aaub-software/dsh-semgrep-sast

安装后重启该 profile，模型即可看到 semgrep_scan 工具。在兼容平台上，npm 会同时安装 @aaub-software/semgrep-runtime-win32-x64 托管运行时。

工具行为

semgrep_scan 接受以下参数：

| 参数 | 是否必需 | 说明 |
| paths | 否 | 工作区相对文件或目录；默认扫描工作区根目录。 |
| ruleset | 否 | 规则配置；当前版本只支持 p/default。 |
| sandbox_permissions | 仅批准重试时 | 可选值为 workspace-write 或 danger-full-access。 |
| justification | 与权限参数一起使用 | 展示给用户的一句话权限申请理由。 |

插件会拒绝绝对路径、逃逸工作区的路径，以及最终解析到工作区外的符号链接。它不提供 autofix，并关闭 Semgrep 指标上报。

0.2 版本返回 @aaub-software/dsh-sast-contract 定义的公开 ssc-sast/v1 协议。
结果包含扫描器溯源信息、实际扫描路径、规范化发现、诊断信息、耗时、发现总数、返回数量以及明确的截断标志。默认最多向模型返回 200 条发现。partial 表示 Semgrep 报告了影响覆盖范围的诊断，并不表示返回的每一项都已经被确认是漏洞。

规范化结果协议

Agent 接收规范化 JSON，而不是 Semgrep 原始输出： json { "schemaVersion": "ssc-sast/v1", "status": "completed",
"scanner": {
"name": "semgrep",
"version": "1.163.0",
"configuration": "p/default"
},
"scannedPaths": ["src/server.js"],
"findings": [
{
"id": "semgrep:f2b91e32bb169fc1",
"scanner": "semgrep",
"rule": {
"id": "javascript.lang.security.audit.detect-eval-with-expression",
"severity": "error",
"cwe": ["CWE-95"],
"owasp": ["A03:2021"]
},
"message": "Detected eval with a non-literal expression.",
"location": {
"path": "src/server.js",
"startLine": 2,
"startColumn": 18,
"endLine": 2,
"endColumn": 44
},
"fingerprint": "f2b91e32bb169fc1",
"evidence": [
{
"type": "semgrep.matched-code",
"data": { "text": "eval(req.query.expression)" }
},
{
"type": "semgrep.metavariables",
"data": { "$EXPR": "req.query.expression" }
}
]
}
],
"diagnostics": [],
"summary": {
"totalFindings": 1,
"returnedFindings": 1,
"truncated": false,
"durationMs": 125
}
}

parser 先校验 Semgrep 原始 JSON，再由适配器构造公共协议。可选 metadata 和 evidence 都限制长度与数量。只有 Semgrep 实际输出的 CWE、OWASP、references 和 fingerprint 才会保留，适配器不会猜测缺失信息。diagnostics 与 findings 分开，避免把扫描覆盖不完整错误解释成「没有漏洞」。

Windows 权限批准流程

Semgrep Core 在当前 DeepSeek Harness Windows ACL 沙箱内无法打开系统证书库。为了让扩大权限始终经过明确批准，第一次受限调用不会启动 Semgrep，而是返回 Harness 标准的沙箱拒绝标记，并提示模型使用完全相同的扫描参数，加上以下字段重试： json { "sandbox_permissions": "danger-full-access", "justification": "运行用户要求的 Semgrep 扫描，因为 Semgrep Core 无法在 Harness Windows ACL 沙箱内访问系统证书库。"
}

随后由 Harness 向用户请求批准，只有批准后才会运行扫描。插件不会静默扩大权限，也不会把这次批准当作工具自身的永久权限。

安全与资源控制

- 扫描目标必须位于当前工作区。
- 扫描只读，不提供 autofix。
- 通过 --metrics=off 和 SEMGREP_SEND_METRICS=off 关闭指标上报。
- 缓存、配置、设置、版本缓存和日志位置被重定向到本次扫描的临时环境。
- 使用 Harness 进程服务实现取消、默认五分钟超时、两秒终止宽限期和进程树终止。
- stdout 最大 32 MiB，stderr 最大 1 MiB；JSON 输出超限时直接失败，不返回残缺 JSON。
- 发现按确定顺序排列并限制数量；结果截断与扫描覆盖不完整分别报告。

默认 p/default 规则集在扫描时从 Semgrep Registry 获取。因此，当规则尚未存在于临时环境中时，扫描需要网络访问。本项目不重新分发 Registry 规则。

配置

组合包默认配置为： yaml
- insert:
- id: semgrep-sast
name: '@aaub-software/dsh-semgrep-sast'
config:
runtimeMode: bundled
defaultRuleset: p/default
timeoutMs: 300000
maxFindings: 200

高级部署可以选择 runtimeMode: system，但必须同时提供明确的 executable。Windows x64 用户的免安装支持路径是默认托管运行时。

开发 powershell
pnpm install
pnpm typecheck
pnpm build
pnpm test

仓库使用 pnpm workspace。DSH 组合包位于 packages/bundle，托管运行时包位于 packages/runtimes/win32-x64。
开发环境链接本地运行时包。执行真实扫描或打包运行时之前，需要组装未纳入 Git 的二进制文件，并运行离线回归测试。

许可证

组合包代码使用 MIT 许可证。托管运行时是聚合二进制发行包，其中各组件继续适用各自的上游许可证。详细信息见 packages/runtimes/win32-x64/THIRD_PARTY_NOTICES.md 及包内许可证文件；Semgrep Registry 规则另行适用其规则许可证。