---
url: /zh/security/quickstart.md
description: 快速上手 CNB 代码安全扫描，包括最小可用配置、扫描范围调整、关闭扫描能力和 include 拆分配置。
---
本文引导你完成以下配置：

1. 创建 `.cnb/security/code_scan_config.yml`。
2. 使用 `.scanignore` 排除无需扫描的路径。
3. 按需关闭某个扫描能力，或用 `include` 拆分配置。

## 第一步：创建配置文件

在仓库中新增 `.cnb/security/code_scan_config.yml`，让多项扫描能力共享同一个 `.scanignore`：

```yaml title=".cnb/security/code_scan_config.yml"
secrets:
  scan:
    ignoreFrom: .scanignore
software-composition-analysis:
  scan:
    ignoreFrom: .scanignore
```

未声明的能力会沿用平台默认配置。未提供该文件时，平台也会使用内置默认配置，扫描照常进行。

## 第二步：添加忽略文件

在仓库根目录新增 `.scanignore`，使用 gitignore 语法声明无需扫描的路径：

```text title=".scanignore"
# 仓库根路径
/go.mod

# 第三方代码
vendor/
node_modules/

# 测试装置
**/testdata/**

# 构建产物
dist/
build/
```

`ignoreFrom` 一旦显式声明，目标文件必须存在；如果文件不存在，配置加载会失败。

## 第三步：按需调整配置

### 关闭某个扫描能力

将对应能力的 `ignoreFrom` 指向一个内容为 `**` 的文件，该能力即跳过所有路径。例如只关闭 `secrets`：

```yaml title=".cnb/security/code_scan_config.yml"
secrets:
  scan:
    ignoreFrom: .scanignore-disabled # 指向内容为 ** 的文件，secrets 跳过所有路径
```

```text title=".scanignore-disabled"
**
```

### 拆分配置

当配置较长时，可以拆到独立的子文件中。所有 include 路径均**相对仓库根目录**解析：

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - .cnb/security/checks/secrets.yml
  - .cnb/security/checks/sca.yml
```

```yaml title=".cnb/security/checks/secrets.yml"
secrets:
  scan:
    ignoreFrom: .scanignore
```

```yaml title=".cnb/security/checks/sca.yml"
software-composition-analysis:
  scan:
    ignoreFrom: .scanignore
    paths:
      # 即使 .scanignore 排除了 vendor，这里的取反规则仍可强制扫描
      - "!third_party/our-fork/**"
```

:::: warning 注意
include 路径必须相对仓库根目录，不支持 URL 或跨仓库引用。include 文件会递归解析，单次最多解析 50 个文件。
更多规则见[配置文件](./config-file.md)。
::::

## 下一步

* [配置文件](./config-file.md) —— include 细节与合并规则
* [语法手册](./syntax-reference.md) —— 字段完整参考