Baiiduu/dsh-semgrep-sast

DeepSeek Harness Semgrep SAST

English

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

默认的托管运行时目前支持 Windows x64。它包含 CPython 3.14.7 和 Semgrep 1.175.0，因此用户无需单独安装 Python 或 Semgrep。

安装

DeepSeek Harness 需要 Node.js 24 或更高版本。将预构建的捆绑包安装到你使用的配置文件中，例如 web：

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

安装后重启该配置文件。智能体随后将看到一个名为 semgrep_scan 的工具。

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

工具行为

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 契约。结果包含扫描器来源、已扫描路径、规范化发现结果、诊断信息、持续时间、发现结果总数和返回数量，以及一个明确的截断标志。默认捆绑包配置将发现结果上限设为 200。partial 状态表示 Semgrep 报告了扫描诊断信息；这并不意味着每个返回的发现结果都是已确认的漏洞。

规范化结果契约

智能体接收的是规范化 JSON，而不是 Semgrep 的原生输出：

{
"schemaVersion": "ssc-sast/v1",
"status": "completed",
"scanner": {
"name": "semgrep",
"version": "1.175.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
}
}

解析器在适配器构造公共契约之前验证原生 Semgrep JSON。可选的元数据和证据是有界的。CWE、OWASP、引用和指纹仅在 Semgrep 输出它们时才保留；适配器不会猜测缺失的元数据。诊断信息与发现结果保持分离，因此不完整的覆盖范围不会被呈现为一次干净的扫描。

Windows 权限批准

Semgrep Core 无法在当前 DeepSeek Harness ACL 沙箱内打开 Windows 系统证书存储。为了保持更广泛权限的显式性，第一次受限调用不会启动 Semgrep。它会返回标准的 Harness 沙箱拒绝标记，并要求模型使用以下内容重试同一扫描：

{
"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 层使用：

- 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 受支持的零安装路径。
开发

pnpm install
pnpm typecheck
pnpm build
pnpm test

该仓库是一个 pnpm 工作区。DSH 组合包位于 packages/bundle 下，托管运行时包位于
packages/runtimes/win32-x64 下。

许可证

组合包代码基于 MIT 许可证发布。托管运行时是一种聚合分发，其各组件保留各自的上游
许可证。详情请参阅 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.175.0，
用户不需要另外安装 Python 或 Semgrep。

安装

DeepSeek Harness 需要 Node.js 24 或更高版本。将已经构建好的 npm 组合包安装到实际
使用的 profile，例如 web：

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 原始输出：

{
"schemaVersion": "ssc-sast/v1",
"status": "completed",
"scanner": {
"name": "semgrep",
"version": "1.175.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 标准的
沙箱拒绝标记，并提示模型使用完全相同的扫描参数，加上以下字段重试：

{
"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 规则。

配置

组合包默认配置为：

- 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 用户的免安装支持路径是默认托管运行时。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test

仓库使用 pnpm workspace。DSH 组合包位于 packages/bundle，托管运行时包位于
packages/runtimes/win32-x64。

许可证

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