Using the toolkit CLI to scan your catalogs and spaces

How to use the IBM® API Connect toolkit CLI to run governance validation scans on your catalogs and spaces.

About

API governance is an API Connect service that can be used to validate and enforce organizational governance policies and best practices to your API development process. The following information provides details of the toolkit CLI commands for running and managing validation scans on your catalogs and spaces. For more information about validation scanning, see Scanning your catalogs and spaces.

The following sections detail how to run validation scan commands by using the toolkit CLI.

CAUTION:
Scanning catalogs or spaces that contain more than a hundred API or product documents, and using many rulesets for the scan, can take hours to complete, and might time out before completion depending on the workload on your server. Only one document can be scanned at a time, and the more rulesets that are applied, the longer each individual scan will take. In this scenario, consider selecting only a few rulesets for each scan.

Logging in to the toolkit CLI

  1. Log in to the toolkit as the owner or an admin of your provider organization.
    For example:
    apic login --server platform-api-host-name --sso
    Where <platform-api-host-name> is the hostname portion URL of the server that hosts the API Manager (the "management server"). To determine the hostname, open API Manager in a browser, and copy the hostname from the URL in the address bar (beginning after "https://" and ending before "/manager") as shown in the following example:
    https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
    When the toolkit prompts for the context, type provider and press Enter:
    Context? provider
    For more information about the toolkit CLI, see Setting up the API Connect toolkit.

Running compliance:scan commands

The following commands detail how to run a compliance scan on a catalog or space.
  1. Create a JSON COMPLIANCE_REQUEST_FILE that specifies the location of the catalog or space and the rulesets to use during a validation scan.
    For example,:
    {
  "collectionUrl": "https://server/api/catalogs/org/catalog",
  "config": {
    "rulesets": [
      {
        "rulesetName": "spectral-oas",
        "disabled": ["info-contact"]
      },
      {
        "rulesetName": "spectral-owasp",
        "disabled": []
      }
    ]
  }
}
    Where:
    • collectionUrl is the URL of the catalog or space that contains the API documents that you want to run a validation scan on, where server is the server URL, org is the name or ID of the provider organization, and catalog is the name or ID of the catalog or space. For example: https://localhost:3003/api/catalogs/alpha/sandbox.
    • rulesets contains a list of the rulesets to be applied to the APIs during the validation scan.

      For each ruleset in the list, you can optionally add the disabled property with a comma-delimited list of rules to ignore during validation.

  2. Run a validation scan by using the compliance:scan command.
    apic --mode governance compliance:scan --scope org --org <target_org> --server <platform_api_host_name> COMPLIANCE_REQUEST_FILE
    Where:
    • scope is the scope of the scan, and must be set to org for a catalog or space validation scan.
    • <target_org> is the name of the provider organization that contains the catalog or space that you want to rescan.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    • COMPLIANCE_REQUEST_FILE is the path and file name of the JSON file that contains the configuration details for the validation scan. For example, ./documents/validate-apis.json.
    This command runs a scan on your APIs.
    To run a scan on your products, you must add the optional parameter of --scan_type with a value of product to the command. For example, 
    apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-products.json --scan_type product
    you can use the value api to scan only APIs, or product to scan only products. If omitted, only APIs are scanned.
    The results of the scan are printed to the screen.
    The following optional parameter enables you to refine the results of this command.
    • --scantitle scan_title is an optional flag that changes the retrieved scan's title to the value that you provide.
    For example, 
    apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan1
  3. Rerun an existing validation scan by using the compliance:rescan command.
    A scan rerun creates a new report for that scan, but uses the same configuration of catalog or space and rulesets that was used in the previous scan.
    apic --mode governance compliance:rescan --scope org --org <target_org> --server <platform_api_host_name> --scan <scan_name_or_scan_id>
    Where:
    • scope is the scope of the scan, and must be set to org for a catalog or space validation scan.
    • <target_org> is the name of the provider organization that contains the catalog or space that you want to rescan.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    • scan_name_or_scan_id is the name or ID of the existing scan that you want to run again.
    The following optional parameter enables you to refine the results of this command.
    • --scantitle scan_title is an optional flag that changes the title of the rescan to the value you provide.
    For example:
    apic --mode governance compliance:rescan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan2

Running scans commands

The following commands detail how to manage and update your validation scans.
  1. List all validation scans that exist for a specific provider organization by using the scans:list command.

    The return includes information about all of the validation scans, and some information about their scan reports, but if you want more detailed information about the reports, use the scan-reports:list command. 

    apic --mode governance scans:list --scope org --org <target_org> --server <platform_api_host_name>
    Where:
    • scope is the scope of the scan, and must be set to org for a catalog or space validation scan.
    • <target_org> is the name of the provider organization that you want a list of scans for.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    The following example shows the sample output for a list containing two scans, one of APIs, and one of products:
    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'
    Where scan_type: '1' refers to an API scan, and scan_type: '2' refers to a product scan.
    The following optional parameters enable you to refine the results of this command.
    • --status status_number is a comma separated list of status codes to filter the list of scans by.
      Table 1. Table of valid status codes
      Code Status
      0 Queued
      1 Complete
      2 In progress
      -1 Error
    • --type catalog_or_space lists the scans that are of the type catalog or space.
    • --scan_type api_or_product is an optional flag to specifically list the scans of only APIs or only products. Use the value api to list only API scans, or product to list only product scans. If omitted, both API and product type scans are listed.
    • --collections list_of_collections is a comma separated list of catalog or space IDs or names to filter the list of scans by.
    • --limit number_of_results specifies how many scan results to return.
    • --fields list_of_fields is a comma separated list of field names to return. Note that no spaces are allowed after a comma, and if you want to return only one field you must omit the comma. For example, running the following command:
      apic --mode governance scans:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title
      Returns the data in the following way:
      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'
    For example:
    apic --mode governance scans:list --scope org --org demo -s test.ibm.com --collections cat1 --type catalog --status 1
  2. Get a specific scan using the scans:get command:
    apic --mode governance scans:get --scope org --org <target_org> --server <platform_api_host_name> SCAN
    Where:
    • scope is the scope of the scan, and must be set to org for a catalog or space validation scan.
    • <target_org> is the name of the provider organization that contains the scan that you want to get.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    • SCAN is the ID or name of the scan that you want to retrieve.
    The scan results are downloaded to the directory where the command was run.
  3. Update the scan title and summary properties by creating a SCAN_FILE with the information to be updated, and running the scans:update command.
    apic --mode governance scans:update --scope org --org <target_org> --server <platform_api_host_name> SCAN SCAN_FILE
    Where:
    • scope is the scope of the scan, and must be set to org for a catalog or space validation scan.
    • <target_org> is the name of the provider organization that contains the scan that you want to update.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    • SCAN is the ID or name of the scan that you want to update.
    • SCAN_FILE is the path to a JSON file that contains the properties to be updated.
    The SCAN_FILE can contain the following properties:
    {
  "title": "<updated_title>",
  "summary": "<updated_summary>"
}
  4. Delete a scan by using the scans:delete command. This command deletes the specified scan and all of its reports.
    apic --mode governance scans:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN
    Where SCAN is the ID or name of the scan that you want to update.
  5. Delete all of the scans for a particular provider organization by using the scans:clear command. This command clears all of the scans and all of their reports for the specified organization.
    apic --mode governance scans:clear --scope org --org <target_org> --server <platform_api_host_name> --confirm organisation_confirmed
    Where organisation_confirmed is the name of the provider organization again, to confirm that you want to clear all of the scans from this organization.

Running scan-reports commands

The following commands detail how to manage and update your scan reports.
  1. List all of the scan reports for a particular provider organization by using the scan-reports:list command.
    apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name>
    The following optional parameters enable you to refine the results of this command.
    • --fields list_of_fields is a comma separated list of field names to return. Note that no spaces are allowed after a comma, and if you want to return only one field you must omit the comma. For example, running the following command:
      apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title
      Returns the data in the following way:
      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 specifies how many scan report results to return.
  2. Get a specific scan report by using the scans:get command.
    apic --mode governance scan-reports:get --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
    Where SCAN_REPORT is the ID or name of the scan report.

    The scan report results are downloaded to the directory where the command was run.

  3. Update the scan report summary property by creating a SCAN_REPORT_FILE with the information to be updated, and running the scan-reports:update command.
    apic --mode governance scan-reports:update --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT SCAN_REPORT_FILE
    Where:
    • SCAN_REPORT is the ID or name of the scan report that you want to update.
    • SCAN_REPORT_FILE is the path to a JSON file that contains the properties to be updated.
    The SCAN_REPORT_FILE can contain the following properties:
    {
  "summary": "updated_summary"
}
  4. Delete a scan report by using the scan-reports:delete command. This command deletes the specified scan report, and removes the reference to it from the scan. Note that you cannot delete the last report in a scan. If you want to delete all of the reports of a scan, you must delete the scan itself by using the scans:delete command.
    apic --mode governance scan-reports:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
    Where SCAN_REPORT is the ID or name of the scan report that you want to delete.