Skip to main content

Scan REST APIs

This document is for Invicti Platform

Invicti Platform can scan REST APIs. This document explains how to import a REST API specification file to a target and scan for vulnerabilities in your REST APIs. Alternatively, you can link to a hosted location containing your REST API definitions and scan that location for vulnerabilities. For information about REST APIs, refer to the section at the end of this document.

info

The processes described in this document are different from the Link Target option available with Invicti API Security Standalone or Bundle. To scan REST APIs from your API Inventory in Invicti, refer to the Link or unlink discovered APIs to targets document.

Scanning APIs in production

Scanning production APIs should be conducted with care. Some scanning methods may result in data deletion. It is recommended to:

  • Carefully consider the permissions (authentication) you provide and which methods (PUT, POST, DELETE) are used.
  • Manually exclude API operations (methods with endpoints) from the uploaded/linked file to prevent destroying or making undesirable changes to the production application.

How to scan a REST API for vulnerabilities​

To scan a REST API for vulnerabilities with Invicti, you must provide the scanner with access to the API definitions. There are two ways to do this:

  • Option A: Import from a file

    • This method involves uploading an OpenAPI3, Swagger2, RAML, WADL, or Postman collection specification file to a target.

  • Option B: Link to a URL

    • This method adds a link to the target's URL, pointing to the location of the API definitions (for example, target.com/api/swagger.json).

Once you start a scan of that target, Invicti parses the imported specification file or accesses the linked URL and adds the necessary REST requests to the scanner. The following sections outline each method and provide instructions for starting a scan of your REST APIs.

Option A: Import from a file​

Importing a specification file to a target means that whenever your REST API is updated, you need to replace the imported specification file to ensure you are scanning the latest version of your REST API.

How to import a specification file to a target and start a scan​

  1. Ensure your REST API specification file is accessible for upload on the machine where you are accessing Invicti.

    • The following file formats are supported: .json, .yaml, .yml, .raml, and .wadl.

  2. Select Inventory > Targets from the left-side menu.

  3. Click (⋮) > Edit target by the target to which you import the file. The Configure target page opens.

  4. Click Scan Configuration to navigate to the API specification section and click the Upload specification button.

Upload API specification from a file in Invicti Platform
  1. Select type of your REST API specification file, choose your file, then click Upload file. The file uploads automatically and is listed in the API specification section of the Scan Configuration.
Upload REST API specification file
tip

If you want to scan only the imported file and not all the other paths belonging to the target, select Yes next to Restrict scans to imported files and save before starting the scan.

  1. The specification file is now imported to the target.

  2. To initiate a scan at a later time, click Save Target Configuration. To begin scanning the target now—including the imported file—click Save and Scan. Selecting Save and run scan with defaults runs a full scan automatically.

tip
  • When the scan is complete, go to Vulnerabilities tab on the Scan details page for information about detected vulnerabilities in your REST API, which are marked with an API tag next to the severity label.
  • Filter the list by Target type > API only to limit the displayed results to vulnerabilities identified in your REST API.
  • For more information about viewing scan results and vulnerabilities, refer to the following documents:

Linking a URL to a target means you are adding the URL of the hosted location where your REST API definitions are held. This allows Invicti to always scan the latest version of your REST API without the need to provide a new specification file each time your API is updated.

info

Linked URLs are accessed by the engine. This means the engine or internal agent (if using one for the target) needs to have access to any linked URLs.

  1. Select Inventory > Targets from the left-side menu.

  2. Click (⋮) > Edit target by the target to which you link the specification. The Configure target page opens.

  3. Click Scan Configuration to navigate to the API specification section and click Link from URL.

Link API specification from URL in Invicti Platform
  1. Choose the type of your specification file, enter the URL where it's hosted, then click Link API specification. The URL is listed in the API specification section of the Scan Configuration.
Link REST API specification from URL
info

If you want to scan only the linked API definition and not all the other paths belonging to the target, select Yes next to Restrict scans to imported files and save before starting the scan.

  1. The URL is now linked to the target.

  2. To initiate a scan at a later time, click Save Target Configuration. To begin scanning the target now—including the linked specification—click Save and Scan. Selecting Save and run scan with defaults runs a full scan automatically.

tip
  • When the scan is complete, go to Vulnerabilities tab on the Scan details page for information about detected vulnerabilities in your REST API, which are marked with an API tag next to the severity label.
  • Filter the list by Target type > API only to limit the displayed results to vulnerabilities identified in your REST API.
  • For more information about viewing scan results and vulnerabilities, refer to the following documents:

Preview API specification operations​

After uploading or linking a REST API specification (OpenAPI/Swagger) in target settings, you can preview the operations included in the specification to verify its contents before scanning.

View API operations​

The preview displays a table showing:

  • HTTP methods (GET, POST, PUT, DELETE, etc.)
  • Endpoint paths

To view the preview:

  1. Navigate to Inventory > Targets
  2. Click on the target and then Edit.
  3. Under Scan configuration, choose General.
  4. Select the API specification to open the preview drawer.
Side drawer showing the API operations preview

This helps you understand which API operations will be included in the scan and verify that the specification contains the expected endpoints.

info

The preview feature is currently available only for REST APIs (OpenAPI/Swagger specifications). GraphQL and WSDL specifications don't support preview at this time.

About REST​

REST (Representational State Transfer) is an architectural style that can be used to communicate with web services. REST has a lot in common with protocols such as SOAP. It is used as a communication mechanism between two applications, or between an application and an online service. Many mobile web applications communicate with a REST API at the backend to communicate with the online service.

Differences between a web service and a REST API​

Many web services rely on complex communication mechanisms such as SOAP, RPC and CORBA. REST uses the standard HTTP methods for all four CRUD (Create, Read, Update, Delete) operations.

Commonly used HTTP methods in REST APIs​

This list shows the commonly used HTTP methods (verbs) in REST:

  • POST - create a resource.
  • GET - retrieve a resource.
  • PUT - change the state of a resource or update it.
  • DELETE - remove or delete a resource.

Challenges of scanning REST APIs​

Unlike RPC and others, REST can be easily consumed and understood by users because of its simple structure. For example, many REST-based web services can provide a response in JSON or XML format. But this same benefit is what makes it very difficult for an automated web vulnerability scanner to crawl and attack.

Lack of standards for REST​

There is no consistent standard for REST API, as there is for WSDL and other similar protocols. Most RESTful web services have their own documentation, useful for developers but useless to automated web vulnerability scanners.

A number of projects aim to standardize the REST API:

Using parameters in URLs​

Another challenge automated scanners encounter when scanning RESTful web services for vulnerabilities is that REST APIs use parameters in URLs.

For example, in the HTTP GET request following, 123 is a parameter and not a directory in the web application:

Need help?​

The Support team is ready to provide you with technical help. Go to Help Center

Was this page useful?