Scanning your catalogs and spaces

How to use the governance service to run validation scans on your catalogs and spaces. You can run scans on both the APIs and the products within your catalogs and spaces.

• Running a validation scan by using the API Manager UI.
  1. In the side menu bar, click Governance.
     The Governance page is displayed.
  2. Ensure the Scans tab is selected, click API or Product depending on what you want to scan, and click New scan.
     The New validation scan wizard opens.
  3. Select the catalog that you want to scan, and click Next.
  4. Optional: If spaces are enabled on the catalog, you can then select the space that you want to scan, and click Next.
  5. Select one or more rulesets, and click Next.
     If there are matching tags in the APIs and in the rulesets, the validation process preselects which rulesets to use for the scan. However, you can override this preselection with rulesets of your choice. For information about how to add tags, see Configuring governance in the API Manager, and Adding tags to an API.
  6. Select one or more rules, and click Next.
  7. Enter a title for the scan, or accept the default title, and click Start scan.
     You scan is started, and appears in the list of scans in the Catalog and space validation table. The scan Status is initially set to Queued, then changes to In progress, and then changes to Complete when it's finished. Note that scans containing a lot of data can take a long time to complete.
  8. When your scan is finished, you have the following options:
     • You can see a Summary of the scan in the table. If there were findings in the report, the summary displays the number of Errors, Warnings, or Hints in the validation, and also how many Rulesets were run in the scan.
     • You can click on the scan Title, or click the options menu icon next to the scan and select View, to view the scan dashboard. The dashboard shows a scorecard summary of the scan, as well as detailed information about any messages and their severity.
• Running a validation scan by using the toolkit CLI.
  1. Create a JSON COMPLIANCE_REQUEST_FILE that specifies the location of the catalog or space and the rulesets to use during the 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. Log in to the toolkit as the owner or an admin of your provider organization.
  3. In the governance mode, run the compliance:scan command:

     apic --mode governance compliance:scan --scope org --org target_org --server mgmt_endpoint_url 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 scan.
     • mgmt_endpoint_url is the management server URL that you use for logging in to the toolkit.
     • COMPLIANCE_REQUEST_FILE is the path and filename 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_server ./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 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_server ./documents/validate-apis.json --scantitle scan1

  4. After the scan is finished, the results of the scan are printed to the screen. For more information about toolkit scan commands, see Using the toolkit CLI to scan your catalogs and spaces.