---
url: /zh/security/quickstart.md
description: 快速上手 CNB 代码安全扫描，包括公共忽略规则、能力级扫描范围、关闭扫描能力和 include 拆分配置。
---
## 配置公共忽略规则

在仓库根目录新增 `.scanignore`，其中的 gitignore 风格路径规则默认应用到所有扫描能力：

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

# 第三方代码
vendor/
node_modules/

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

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

仅需公共忽略规则时，无需创建 `code_scan_config.yml`。

## 按能力配置扫描范围

需要为某个能力使用不同的忽略规则时，通过 `scan.ignoreFrom` 指定文件：

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

```text title=".cnb/security/scanignore/secrets"
fixtures/
**/testdata/**
```

`secrets` 改用指定文件，其他能力继续使用根目录 `.scanignore`。
两个忽略文件不会合并；指定文件必须存在，并应包含该能力所需的全部规则。

### 关闭某个扫描能力

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

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

```text title=".cnb/security/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: .cnb/security/scanignore/secrets
```

```yaml title=".cnb/security/checks/sca.yml"
software-composition-analysis:
  scan:
    paths:
      # 在根目录 .scanignore 的公共规则基础上，重新纳入指定路径
      - "!third_party/our-fork/**"
```

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

## 配置结果

| 扫描能力 | 生效的忽略文件 |
|---|---|
| 配置了 `ignoreFrom` 的能力 | `ignoreFrom` 指定的文件 |
| 未配置 `ignoreFrom` 的能力 | 根目录 `.scanignore`（如果存在） |

## 下一步

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