Scan REST APIs for vulnerabilities

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, refer to the section at the end of this document.

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. We recommend you:

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 will parse the imported specification file or access the linked URL and add 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 will 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

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.

Select Inventory > Targets from the left-side menu.
Click (⋮) > Edit target by the target to which you will import the file. The Configure target page will open.
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.

Select the type of your REST API specification file, choose your file, then click Upload file. The file will upload automatically and will be listed in the API specification section of the Scan Configuration.

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.

The specification file is now imported to the target.
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 will run a full scan automatically.

When the scan is complete, check the Vulnerabilities tab on the Scan details page for information about detected vulnerabilities in your REST API, which will be 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:

Option B: Link to a URL

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.

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.

How to link a URL to a target and start a scan

Select Inventory > Targets from the left-side menu.
Click (⋮) > Edit target by the target to which you will link the specification. The Configure target page will open.
Click Scan Configuration to navigate to the API specification section and click Link from URL.

Link API specification from URL in Invicti Platform.

Choose the type of your specification file, enter the URL where it’s hosted, then click Link API specification. The URL will be listed in the API specification section of the Scan Configuration.

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.

The URL is now linked to the target.
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 will run a full scan automatically.

When the scan is complete, check the Vulnerabilities tab on the Scan details page for information about detected vulnerabilities in your REST API, which will be 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:

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 in order 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 below, 123 is a parameter and not a directory in the web application:

GET http://www.example.com/rest-api/products/123/