使用工具箱 CLI 来扫描目录和空间

如何使用 IBM® API Connect 工具箱 CLI 在目录和空间上运行监管验证扫描。

关于

API governance 是一项 API Connect 服务，可用于在您的 API 开发流程中验证和执行组织治理策略和最佳实践。以下信息提供了用于在目录和空间上运行和管理验证扫描的工具箱 CLI 命令的详细信息。有关验证扫描的更多信息，请参阅扫描目录和空间。

以下部分详细说明了如何使用工具箱 CLI运行验证扫描命令。

警告：

扫描包含一百多个 API 或产品文档的目录或空间，并使用大量规则集进行扫描，可能需要数小时才能完成，并且可能在完成前超时，这取决于服务器上的工作量。一次只能扫描一个文档，应用的规则集越多，每个单独的扫描所花费的时间就越长。在此场景中，请考虑仅为每个扫描选择几个规则集。

登录到工具箱 CLI

以提供者组织的所有者或管理员身份登录到 Toolkit。

运行 compliance:scan 命令

以下命令详细说明了如何在目录或空间上运行合规性扫描。

创建 JSON COMPLIANCE_REQUEST_FILE ，用于指定要在验证扫描期间使用的目录或空间以及规则集的位置。
例如：
```
{
  "collectionUrl": "https://server/api/catalogs/org/catalog",
  "config": {
    "rulesets": [
      {
        "rulesetName": "spectral-oas",
        "disabled": ["info-contact"]
      },
      {
        "rulesetName": "spectral-owasp",
        "disabled": []
      }
    ]
  }
}
```
其中：
- collectionUrl 是目录或空间的，其中包含您要对其运行验证扫描的API文档，其中是服务器，是提供商组织的名称或ID，是目录或空间的名称或ID。 URL server URL org catalog 例如， https://localhost:3003/api/catalogs/alpha/sandbox。
- rulesets 包含要在验证扫描期间应用于 API 的规则集的列表。
  对于列表中的每个规则集，您可以选择添加 disabled 属性以及要在验证期间忽略的以逗号分隔的规则列表。
使用 compliance:scan 命令运行验证扫描。
```
apic --mode governance compliance:scan --scope org --org <target_org> --server <platform_api_host_name> COMPLIANCE_REQUEST_FILE
```
其中：
- scope 是扫描的作用域，对于目录或空间验证扫描，必须设置为 org 。
- <target_org> 是包含要扫描的目录或空间的提供者组织的名称。
- <platform_api_host_name> 是托管API管理器（“管理服务器”）的服务器的主机名部分。 URL
  
  提示：要确定主机名，您可以在浏览器中打开 API管理器，从地址栏中的 URL 复制主机名（从 https:// 开始，到 /manager 之前结束）。
- COMPLIANCE_REQUEST_FILE 是包含验证扫描的配置详细信息的 JSON 文件的路径和文件名。例如，./documents/validate-apis.json。
此命令对您的 API 进行扫描。
要对产品进行扫描，必须在命令中添加可选参数 "--scan_type，其值为 "product。例如：
```
apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-products.json --scan_type product
```
您可以使用 "api值只扫描 API，或使用 "product值只扫描产品。如果省略，则只扫描 API。
扫描结果将打印到屏幕上。
使用以下可选参数可以完善该命令的结果。
- --scantitle scan_title是一个可选标记，用于将检索到的扫描标题更改为您提供的值。
例如：
```
apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan1
```
使用 compliance:rescan 命令重新运行现有验证扫描。
扫描重新运行将为该扫描创建新报告，但使用先前扫描中使用的目录或空间以及规则集的相同配置。
```
apic --mode governance compliance:rescan --scope org --org <target_org> --server <platform_api_host_name> --scan <scan_name_or_scan_id>
```
其中：
- scope 是扫描的作用域，对于目录或空间验证扫描，必须设置为 org 。
- <target_org> 是包含要重新扫描的目录或空间的提供者组织的名称。
- <platform_api_host_name> 是托管API管理器（“管理服务器”）的服务器的主机名部分。 URL
  
  提示：要确定主机名，您可以在浏览器中打开 API管理器，从地址栏中的 URL 复制主机名（从 https:// 开始，到 /manager 之前结束）。
- scan_name_or_scan_id 是要再次运行的现有扫描的名称或标识。
使用以下可选参数可以完善该命令的结果。
- --scantitle scan_title是一个可选标记，用于将重新扫描的标题更改为您提供的值。
例如：
```
apic --mode governance compliance:rescan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan2
```

运行 scans 命令

以下命令详细说明了如何管理和更新验证扫描。

使用 scans:list 命令列出针对特定提供者组织存在的所有验证扫描。

返回的内容包括有关所有验证扫描的信息以及有关其扫描报告的一些信息，但是如果需要有关报告的更多详细信息，请使用 scan-reports:list 命令。

apic --mode governance scans:list --scope org --org <target_org> --server <platform_api_host_name>

其中：

scope 是扫描的作用域，对于目录或空间验证扫描，必须设置为 org 。
<target_org> 是要为其提供扫描列表的提供者组织的名称。
<platform_api_host_name> 是托管API管理器（“管理服务器”）的服务器的主机名部分。 URL

提示：要确定主机名，您可以在浏览器中打开 API管理器，从地址栏中的 URL 复制主机名（从 https:// 开始，到 /manager 之前结束）。

下面的示例显示了包含两个扫描（一个是 API，一个是产品）的列表的输出示例：

total_results: 2
results:
  - type: 'scan'
    scan_type: '1'
    api_version: '2.0.0'
    id: 'cd765034-d46b-4b1b-9c74-b63911f42773'
    name: 'cd765034-d46b-4b1b-9c74-b63911f42773'
    title: 'API Scan'
    scope: 'org'
    collection:
      id: 'b6deefe8-6cd5-4bcb-b7b4-116891bc6019'
      name: 'cat1'
      type: 'catalog'
      title: 'cat1'
      location: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41/cat1'
    config:
      - id: 'cf16505a-ae70-438b-be10-bcc7678d1eee'
        url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41/rulesets/cf16505a-ae70-438b-be10-bcc7678d1eee'
        name: 'spectral-async'
        title: 'spectral-async'
        version: '1.15.0'
        disabled: []
      - id: '01562ee7-9a50-4dae-b356-9f50ccb6'
        url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41/rulesets/01562ee7-9a50-4dae-b356-9f50ccb6'
        name: 'spectral-oas'
        title: 'spectral-oas'
        version: '1.15.0'
        disabled: []
    documents:
      - id: '29b04204-8cce-47ab-baac-365ab09f'
        name: 'accountservice'
        title: 'AccountService'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/04d6a185-2c6d-41fd-91e6-d7e83a854745/apis/29b04204-8cce-47ab-baac-365ab09f'
      - id: '964f1df0-dd0b-4671-afee-e70af020'
        name: 'awsecommerceservice'
        title: 'AWSECommerceService'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/04d6a185-2c6d-41fd-91e6-d7e83a854745/apis/964f1df0-dd0b-4671-afee-e70af020'
    progress: 100
    reports:
      created_at: '2024-03-27T10:57:09.921Z'
      report_url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scan-reports/cfd0eac3-cff1-4d66-9057-30426970'
      scan_result:
        hints: '0'
        infos: '20'
        errors: '1396'
        warnings: '24212'
    scan_result: '1396 Errors, 24212 Warnings, 20 Infos, 0 Hints, 6 Rulesets'
    status: 1
    created_at: '2024-03-27T10:55:45.000Z'
    updated_at: '2024-03-27T10:57:12.000Z'
    url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scans/0e84ce18-45ea-4a28-ab68-4da0c492'
  - type: 'scan'
    scan_type: '2'
    api_version: '2.0.0'
    id: 'ddc5da81-0db0-425c-b74c-5fc8300934e6'
    name: 'ddc5da81-0db0-425c-b74c-5fc8300934e6'
    title: 'Product Scan'
    scope: 'org'
    collection:
      id: 'b6deefe8-6cd5-4bcb-b7b4-116891bc6019'
      name: 'cat2'
      type: 'catalog'
      title: 'cat2'
      location: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/cat2'
    config:
      - id: '8e67e57b-a7f6-4c5e-b341-ab0a960d78fd'
        url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/rulesets/8e67e57b-a7f6-4c5e-b341-ab0a960d78fd'
        name: 'Product Ruleset'
        title: 'Product Ruleset'
        version: '1.0.0'
        disabled: []
    documents:
      - id: 'c6c66be4-bd1e-4fe1-85d5-45fd8a4bd3d0'
        name: 'First Product Document'
        title: 'First Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/c6c66be4-bd1e-4fe1-85d5-45fd8a4bd3d0'
      - id: '11266894-524a-410d-babf-ca2488736e40'
        name: 'Second Product Document'
        title: 'Second Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/11266894-524a-410d-babf-ca2488736e40'
      - id: '3b18fd12-c1ea-4faf-9e44-7b9158b437ca'
        name: 'Third Product Document'
        title: 'Third Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/3b18fd12-c1ea-4faf-9e44-7b9158b437ca'
      - id: '1089516f-d7bf-4850-b7e0-7a6ca18c4383'
        name: 'Fourth Product Document'
        title: 'Fourth Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/1089516f-d7bf-4850-b7e0-7a6ca18c4383'
    progress: 100
    reports:
      - created_at: '2024-09-05T09:24:39.784Z'
        report_url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scan-reports/ae166497-b64f-47e7-a23c-5e75d19adbde'
        scan_result:
          hints: '0'
          infos: '0'
          errors: '2'
          warnings: '0'
      - created_at: '2024-09-05T09:24:17.561Z'
        report_url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scan-reports/2d86ca39-56ee-4e2f-adb8-b5b1e5e294a0'
        scan_result:
          hints: '0'
          infos: '0'
          errors: '2'
          warnings: '0'
    scan_result: '2 Errors, 0 Warnings, 0 Infos, 0 Hints, 1 Rulesets'
    status: 1
    created_at: '2024-09-05T09:24:08.000Z'
    updated_at: '2024-09-05T09:24:39.000Z'
    url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scans/ddc5da81-0db0-425c-b74c-5fc8300934e6'

其中，"scan_type: '1'指 API 扫描，"scan_type: '2'指产品扫描。

以下可选参数使您能够优化此命令的结果。

--status status_number 是要作为扫描列表过滤依据的状态码的逗号分隔列表。

表 1. 有效状态码表

代码状态

0 已排入队列

1 完成

2 进行中

-1 错误
--type catalog_or_space 列出了类型为 catalog 或 space的扫描。
--scan_type api_or_product是一个可选标记，用于专门列出只对 API 或只对产品进行的扫描。使用 "api只列出 API 扫描，或使用 "product只列出产品扫描。如果省略，则会同时列出 API 和产品类型扫描。
--collections list_of_collections 是要作为扫描列表过滤依据的目录或空间标识或名称的逗号分隔列表。
--limit number_of_results 指定要返回的扫描结果数。

表 1. 有效状态码表
代码	状态
`0`	已排入队列
`1`	完成
`2`	进行中
`-1`	错误

--fields list_of_fields 是要返回的字段名称的逗号分隔列表。请注意，逗号后面不允许有空格，如果只想返回一个字段，那么必须省略逗号。例如，运行以下命令:

apic --mode governance scans:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title

按以下方式返回数据:

total_results: 2
results:
  - id: 'e0b8afbd-e5fa-486e-8800-343e1e31faf1'
    title: 'e0b8afbd-e5fa-486e-8800-343e1e31faf2'
  - id: '436d9db5-ea45-4d91-96c4-cef5957a2c34'
    title: '436d9db5-ea45-4d91-96c4-cef5957a2c34'

例如：

apic --mode governance scans:list --scope org --org demo -s test.ibm.com --collections cat1 --type catalog --status 1

使用 scans:get 命令获取特定扫描结果：
```
apic --mode governance scans:get --scope org --org <target_org> --server <platform_api_host_name> SCAN
```
其中：
- scope 是扫描的作用域，对于目录或空间验证扫描，必须设置为 org 。
- <target_org> 是包含要获取的扫描的提供者组织的名称。
- <platform_api_host_name> 是托管API管理器（“管理服务器”）的服务器的主机名部分。 URL
  
  提示：要确定主机名，您可以在浏览器中打开 API管理器，从地址栏中的 URL 复制主机名（从 https:// 开始，到 /manager 之前结束）。
- SCAN 是要检索的扫描的 ID 或名称。
扫描结果将下载到运行该命令的目录。
通过使用要更新的信息创建 SCAN_FILE 并运行 scans:update 命令来更新扫描 title 和 summary 属性。
```
apic --mode governance scans:update --scope org --org <target_org> --server <platform_api_host_name> SCAN SCAN_FILE
```
其中：
- scope 是扫描的作用域，对于目录或空间验证扫描，必须设置为 org 。
- <target_org> 是包含要更新的扫描的提供者组织的名称。
- <platform_api_host_name> 是托管API管理器（“管理服务器”）的服务器的主机名部分。 URL
  
  提示：要确定主机名，您可以在浏览器中打开 API管理器，从地址栏中的 URL 复制主机名（从 https:// 开始，到 /manager 之前结束）。
- SCAN 是要更新的扫描的标识或名称。
- SCAN_FILE 是包含要更新的属性的 JSON 文件的路径。
SCAN_FILE 可以包含以下属性:
```
{
  "title": "<updated_title>",
  "summary": "<updated_summary>"
}
```
使用 scans:delete 命令删除扫描。此命令将删除指定的扫描及其所有报告。
```
apic --mode governance scans:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN
```
其中， SCAN 是要更新的扫描的标识或名称。
使用 scans:clear 命令删除特定提供者组织的所有扫描。此命令将清除指定组织的所有扫描及其所有报告。
```
apic --mode governance scans:clear --scope org --org <target_org> --server <platform_api_host_name> --confirm organisation_confirmed
```
其中， organisation_confirmed 是提供者组织的名称，以确认您要从此组织中清除所有扫描。

运行 scan-reports 命令

以下命令详细说明了如何管理和更新扫描报告。

使用 scan-reports:list 命令列出特定提供者组织的所有扫描报告。

apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name>

以下可选参数使您能够优化此命令的结果。

apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title

按以下方式返回数据:

total_results: 2
results:
  - id: '3e3189a3-6359-4113-9cf9-9bde9f303884'
    title: '3e3189a3-6359-4113-9cf9-9bde9f303882'
  - id: '58a975cf-a503-4297-9450-237db102cb24'
    title: '58a975cf-a503-4297-9450-237db102cb24'

--limit number_of_results 指定要返回的扫描报告结果数。

使用 scans:get 命令获取特定扫描报告。
```
apic --mode governance scan-reports:get --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
```
其中 SCAN_REPORT 是扫描报告的标识或名称。
扫描报告结果将下载到运行该命令的目录中。
通过使用要更新的信息创建 SCAN_REPORT_FILE 并运行 scan-reports:update 命令来更新扫描报告 summary 属性。
```
apic --mode governance scan-reports:update --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT SCAN_REPORT_FILE
```
其中：
- SCAN_REPORT 是要更新的扫描报告的标识或名称。
- SCAN_REPORT_FILE 是包含要更新的属性的 JSON 文件的路径。
SCAN_REPORT_FILE 可以包含以下属性:
```
{
  "summary": "updated_summary"
}
```
使用 scan-reports:delete 命令删除扫描报告。此命令将删除指定的扫描报告，并从扫描中除去对该报告的引用。请注意，无法删除扫描中的最后一个报告。如果要删除扫描的所有报告，那么必须使用 scans:delete 命令来删除扫描本身。
```
apic --mode governance scan-reports:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
```
其中， SCAN_REPORT 是要删除的扫描报告的标识或名称。

使用 工具箱 CLI 来扫描目录和空间

关于

登录到 工具箱 CLI

运行 compliance:scan 命令

运行 scans 命令

运行 scan-reports 命令

使用工具箱 CLI 来扫描目录和空间

登录到工具箱 CLI