Skip to main content

How to configure and scan an API

Configure Snyk API & Web to scan an API defined by an OpenAPI, Postman Collection, or GraphQL

Written by Tiago Mendo

This article explains how to scan a standalone API target with Snyk API & Web.

How does the API scanning work?

To scan an API, we need its specification, the schema. You can define it with a URL pointing to the schema, upload it to Snyk API & Web, or in the case of GraphQL, perform a schema introspection. When you select URL or introspection, it allows us to fetch the schema before every scan, ensuring we always get the most up-to-date version.

Snyk API & Web supports APIs with different authentication methods. You can set a fixed API key in a custom header or configure a login endpoint from which you obtain an authentication token.

You can also define custom parameter values that replace those found in the schema. This allows you to override example values or to ensure domain-specific values are properly filled.

How do I scan an API?

Scanning an API is a simple three-step process:

  1. Add an API target

  2. Configure the API target

  3. Start the scan

This article describes these steps in detail, covering multiple authentication scenarios.

Step one: Adding an API target

To add a target, do the following:

  1. Go to the Snyk API & Web app.

  2. Access the Targets menu entry and click on Add.

  3. Fill out the Add target form. Make sure to:

    1. Type in a meaningful Name for the target.

    2. Set the URL field to the API base URL, i.e., the domain from which your API is actually serving clients.

    3. Select API and, in API Type, choose between an OpenAPI, Postman Collection or GraphQL. Please note the following:

    4. Choose whether to enter your API schema URL, perform an introspection, or upload it.

  4. Click on Add to create the new target.

Step two: Configure an API target

After adding the API target, go to its settings, where there are some differences when compared with a web target, namely:

  • API Target Authentication section, where you configure the authentication method to scan the API.

  • API Scanning Settings section, where the schema and custom values are set.

  • There's no Seeds List section, as we only crawl and scan endpoints defined in the schema.

  • There's no Extra Hosts section, as this usually applies to web apps that use a different domain for the server-side functionality.

Configure the API Authentication

If the API requires authentication, the configuration depends on whether the API target was configured as OpenAPI, Postman Collection, or GraphQL. In either case, the authentication is configured in the API target settings:

NOTE: GraphQL Introspection enabled is considered a Low Severity vulnerability. When enabled, we recommend that you restrict access to your GraphQL API using authentication.

Configure the API Scanning Settings

In the API Scanning Settings section, you can override or set values for the endpoint parameters described in the schema.

Our scanning engine has predefined values for the most common parameters, such as email, address, and dates.

If we cannot infer an adequate value for a parameter, we use a default value. You can override that behavior by setting specific values, such as email and the product_id, as shown in the example below:

Screenshot with API Parameter Custom Values example for email and product_id

Step three: Start the scan

Press the Scan button, and follow its progress on the scan page.

Afterward, you can download a coverage report in CSV format that lists the endpoints parsed from the schema and the respective HTTP response code. The coverage report is a great tool for identifying failed endpoints. Learn more about it in What is the meaning of the .CSV coverage report?

Did this answer your question?