ツールキット CLI を使用したカタログおよびスペースのスキャン

IBM® API Connect ツールキット CLI を使用して、カタログおよびスペースに対してガバナンス検証スキャンを実行する方法。

製品情報

API governance はAPI Connect サービスで、組織のガバナンスポリシーとベストプラクティスを検証し、API 開発プロセスに適用するために使用できます。以下の情報は、カタログおよびスペースで検証スキャンを実行および管理するためのツールキット CLI コマンドの詳細を示しています。検証スキャンに関する詳細については、「カタログとスペースのスキャン」を参照してください。

以下のセクションでは、ツールキット CLIを使用して検証スキャン・コマンドを実行する方法について詳しく説明します。

注意： 100件以上のAPIドキュメントや製品ドキュメントを含むカタログやスペースをスキャンする場合、またスキャンに多数のルールセットを使用する場合、処理完了までに数時間かかることがあります。サーバーの負荷状況によっては、完了前にタイムアウトとなる可能性があります。一度にスキャンできる文書は 1 つのみです。適用されるルール・セットが多いほど、個々のスキャンにかかる時間が長くなります。このシナリオでは、各スキャンに少数のルールセットのみを選択することを検討する。

ツールキット CLI へのログイン

プロバイダー組織の所有者または管理者としてツールキットにログインします。
例:
```
apic login --server platform-api-host-name --sso
```
ここで、 <platform-api-host-name> はAPI Managerをホストするサーバー（「管理サーバー」）のホスト名部分 URL である。ホスト名を決定するには、ブラウザでAPI Managerを開き、以下の例に示すように、アドレスバーの URL （「 https:// 」の後で始まり、「/manager」の前で終わる）からホスト名をコピーする：
```
https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
```
ツールキットからコンテキストの入力を求めるプロンプトが表示されたら、provider と入力して Enter キーを押します。
```
Context? provider
```
ツールキットCLIの詳細については、 API Connect ツールキットのセットアップを参照してください。

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ドキュメントを含むカタログまたはスペースの URL である。はサーバー server URL、はプロバイダー組織の名前またはID、はカタログまたはスペースの名前またはIDである。 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 Managerをホストするサーバー（「管理サーバー」）のホスト名部分の URL である。
  
  ヒント：ホスト名を決定するには、ブラウザで API Managerを開き、アドレスバーの 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 Managerをホストするサーバー（「管理サーバー」）のホスト名部分の URL である。
  
  ヒント：ホスト名を決定するには、ブラウザで API Managerを開き、アドレスバーの URLからホスト名をコピーします（ https:// の後で始まり、 /manager の前で終わります）。
- scan_name_or_scan_id は、もう一度実行する既存のスキャンの名前または 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 Managerをホストするサーバー（「管理サーバー」）のホスト名部分の URL である。

ヒント：ホスト名を決定するには、ブラウザで API Managerを開き、アドレスバーの URLからホスト名をコピーします（ https:// の後で始まり、 /manager の前で終わります）。

次の例は、APIと製品の2つのスキャンを含むリストの出力例である：

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 は、スキャンのリストをフィルターに掛けるためのカタログまたはスペースの ID または名前のコンマ区切りリストです。
--limit number_of_results は、返されるスキャン結果の数を指定します。
--fields list_of_fields は、返されるフィールド名のコンマ区切りリストです。コンマの後にスペースを入れることはできません。また、1 つのフィールドだけを戻したい場合は、コンマを省略しなければならないことに注意してください。例えば、以下のコマンドを実行します。
```
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'
```

表 1. 有効なステータスコード一覧
コード	状況
`0`	待機中
`1`	完了
`2`	進行中
`-1`	エラー

例:

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 Managerをホストするサーバー（「管理サーバー」）のホスト名部分の URL である。
  
  ヒント：ホスト名を決定するには、ブラウザで API Managerを開き、アドレスバーの 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 Managerをホストするサーバー（「管理サーバー」）のホスト名部分の URL である。
  
  ヒント：ホスト名を決定するには、ブラウザで API Managerを開き、アドレスバーの URLからホスト名をコピーします（ https:// の後で始まり、 /manager の前で終わります）。
- SCAN には、更新するスキャンの ID または名前を指定します。
- 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 は、更新するスキャンの ID または名前です。
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>
```
以下のオプション・パラメーターを使用すると、このコマンドの結果を絞り込むことができます。
- --fields list_of_fields は、返されるフィールド名のコンマ区切りリストです。コンマの後にスペースを入れることはできません。また、1 つのフィールドだけを戻したい場合は、コンマを省略しなければならないことに注意してください。例えば、以下のコマンドを実行します。
```
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 はスキャン・レポートの ID または名前です。
スキャン・レポート結果は、コマンドが実行されたディレクトリーにダウンロードされます。
更新する情報で 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 は、更新したいスキャン・レポートの ID または名前です。
- 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 は、削除するスキャン・レポートの ID または名前です。