> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 安全扫描

> 了解 Qoder CLI 的分层安全扫描能力，以及如何配置自动检查和手动安全扫描。

Qoder CLI 内置安全扫描能力，可以在代码生成和代码变更过程中辅助发现高风险安全问题。它适合在日常开发中作为一层持续检查机制，帮助你尽早发现危险函数调用、注入风险、敏感信息泄露和跨文件数据流问题。

安全扫描不是替代安全团队审计的完整方案。它主要面向当前任务生成的代码和增量代码变更，帮助你在提交前发现可操作的问题。

## 功能入口

在交互式 TUI 中输入：

```text theme={null}
/security-settings
```

该命令会打开安全扫描设置面板。你可以在面板中查看并切换不同级别的扫描能力。

安全扫描能力默认开启。设置会写入用户级配置，用于控制各层扫描能力的开关。L1 Static Check 免费；L2 Lightweight Scan 和 L3 Deep Scan 可能消耗 Credits，具体以产品内提示和当前账号计费规则为准。

## 扫描级别

Qoder CLI 将安全扫描拆成三个级别。你可以按需要分别开启或关闭。

### L1 Static Check

L1 用于当前任务中生成的代码。它通过高风险模式匹配快速检查常见问题，例如危险函数调用、明显的敏感信息泄露模式和其他容易在生成代码中出现的风险。

L1 Static Check 是免费的基础检查，建议默认保持开启，用于在当前任务中快速发现高风险代码模式。

### L2 Lightweight Scan

L2 面向增量代码变更。它会进一步理解代码语义，识别更复杂的风险，例如 SQL 注入、远程命令执行、敏感数据泄露等。

如果你希望在日常编码时获得更深入的安全反馈，建议开启 L2。

### L3 Deep Scan

L3 面向增量代码变更的深度分析。它会跨文件、跨函数追踪完整数据流，尝试发现单文件视角下不容易暴露的隐藏漏洞。

L3 更适合在提交完成后、评审、推送、创建 PR、发布或部署等交付动作前使用。如果当前只有工作区变更，L3 可能会回退到 L2。

## 配置扫描级别

打开 `/security-settings` 后，可以使用方向键在扫描级别之间移动，按 Enter 或 Space 切换开关。按 `q` 或 Esc 可退出面板。

面板中的每一项会显示当前状态：

* `on` 表示该级别已启用。
* `off` 表示该级别已关闭。
* `default` 表示当前使用默认值。
* `saved` 表示该项已经写入用户级配置。

设置面板只写入用户级配置，不会修改项目级配置。

## 使用配置文件

你也可以在用户级 `settings.json` 中配置安全扫描。配置项位于 `securityScan` 下：

```json theme={null}
{
  "securityScan": {
    "l1StaticCheck": true,
    "l2LightweightScan": true,
    "l3DeepScan": true
  }
}
```

这三个配置项默认都是 `true`。如果你想关闭某个级别，可以将对应字段设为 `false`：

```json theme={null}
{
  "securityScan": {
    "l1StaticCheck": true,
    "l2LightweightScan": false,
    "l3DeepScan": false
  }
}
```

## 自动扫描如何工作

启用安全扫描后，Qoder CLI 会根据你的配置加载内置安全能力，并决定启用哪些检查。

当 L1 开启时，Qoder CLI 会在相关工具调用后触发静态检查能力。关闭 L1 后，这部分自动检查不会加载。

只要 L1、L2、L3 中至少有一个开启，Qoder CLI 就会保留统一的安全扫描能力。如果 L1、L2、L3 全部关闭，安全扫描相关能力不会加载。

## 手动安全扫描

除了自动扫描设置，Qoder CLI 还提供一个手动安全扫描 Skill：

```text theme={null}
/security-scan
```

该命令会根据你的意图进入以下三种工作流之一：

* **项目/文件扫描**：扫描整个仓库，或扫描你明确指定的文件和目录。
* **L2 轻量审查**：审查当前工作区变更。
* **L3 深度审查**：在推送、创建 PR、发布、部署或其他交付动作前，审查尚未审查过的已提交变更。

直接输入 `/security-scan` 会打开选择器，选项包括 L3 深度扫描、L2 轻量扫描和项目/文件扫描。如果选择项目/文件扫描但没有指定范围，Qoder CLI 会继续询问扫描整个仓库还是指定文件和目录。

你也可以直接在命令中写明模式或范围：

```text theme={null}
/security-scan L2 轻量审查
/security-scan L3 深度审查
/security-scan 扫描整个仓库
/security-scan 扫描 src/auth 和 src/export
```

只要任一安全扫描级别开启，项目/文件扫描就可用。L2 和 L3 分别受自己的设置开关控制。显式请求已关闭的 L2 或 L3 时，Qoder CLI 会提示你通过 `/security-settings` 开启；隐式交付场景中的 L3 检查在 L3 关闭时会保持静默。

## 适合使用的场景

安全扫描适合放在以下场景中使用：

* 让 Qoder CLI 生成或修改了安全敏感代码后，例如鉴权、支付、数据导出、文件上传、命令执行等。
* 在提交代码或交付代码前，希望快速检查当前变更是否引入高风险问题。
* 在评审前，希望先得到一份面向真实漏洞的安全风险提示。
* 在使用自动化模式时，希望保留一层持续安全检查。

## 注意事项

安全扫描主要关注当前任务和增量变更。项目/文件扫描可以扫描整个仓库或指定路径，但它仍不是完整安全审计，也不保证发现所有漏洞。

扫描结果依赖当前代码上下文、可访问文件和启用的扫描级别。对于关键业务代码，建议结合人工安全评审、测试、依赖扫描和组织内安全流程一起使用。

如果安全扫描没有按预期工作，可以先检查以下内容：

* `/security-settings` 中对应扫描级别是否为 `on`。
* 用户级 `settings.json` 中是否显式关闭了 `securityScan` 的某些字段。
* 如果通过配置文件修改，确认 JSON 格式正确并已保存到用户级配置。
* 当前任务是否产生了可供扫描的新增或修改代码。

## 相关文档

* [权限](/zh/cli/permissions)：了解工具调用审批、权限模式和允许/拒绝规则。
* [Hooks](/zh/cli/hooks)：了解 Qoder CLI 如何在工具调用和会话生命周期中执行自动化逻辑。
* [Skills](/zh/cli/Skills)：了解如何通过 Skill 扩展 Qoder CLI 的专业能力。