DAST API

You can add dynamic application security testing (DAST) of web APIs to your GitLab CI/CD pipelines. This helps you discover bugs and potential security issues that other QA processes may miss.

We recommend that you use DAST API testing in addition to GitLab Secure’s other security scanners and your own test processes. If you’re using GitLab CI/CD, you can run DAST API tests as part your CI/CD workflow.

caution
Do not run DAST API testing against a production server. Not only can it perform any function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run DAST API against a test server.

You can run DAST API scanning against the following web API types:

  • REST API
  • SOAP
  • GraphQL
  • Form bodies, JSON, or XML

When DAST API scans run

DAST API scanning runs in the dast stage by default. To ensure DAST API scanning examines the latest code, ensure your CI/CD pipeline deploys changes to a test environment in a stage before the dast stage.

If your pipeline is configured to deploy to the same web server on each run, running a pipeline while another is still running could cause a race condition in which one pipeline overwrites the code from another. The API to be scanned should be excluded from changes for the duration of a DAST API scan. The only changes to the API should be from the DAST API scanner. Changes made to the API (for example, by users, scheduled tasks, database changes, code changes, other pipelines, or other scanners) during a scan could cause inaccurate results.

Example DAST API scanning configurations

The following projects demonstrate DAST API scanning:

Targeting API for DAST scanning

You can specify the API you want to scan by using:

OpenAPI Specification

Version history
  • Support for OpenAPI Specification using YAML format was introduced in GitLab 14.0.
  • Support to generate media type application/xml was introduced in GitLab 14.8.
  • Support to media types was introduced in GitLab 14.10.

The OpenAPI Specification (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure DAST API scanning using an OpenAPI Specification to provide information about the target API to test. OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported.

DAST API uses an OpenAPI document to generate the request body. When a request body is required, the body generation is limited to these body types:

  • application/x-www-form-urlencoded
  • multipart/form-data
  • application/json
  • application/xml

OpenAPI and media types

A media type (formerly known as MIME type) is an identifier for file formats and format contents transmitted. A OpenAPI document lets you specify that a given operation can accept different media types, hence a given request can send data using different file content. As for example, a PUT /user operation to update user data could accept data in either XML (media type application/xml) or JSON (media type application/json) format. OpenAPI 2.x lets you specify the accepted media types globally or per operation, and OpenAPI 3.x lets you specify the accepted media types per operation. DAST API will check the listed media types, and try to produce sample data for each supported media type.

  • In GitLab 14.10 and later, the default behavior is to select one of the supported media types to use. The first supported media type is chosen from the list. This behavior is configurable.
  • In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, application/json and application/xml), testing are performed using JSON, and then the same tests using XML.

Testing the same operation (for example, POST /user) using different media types (for example, application/json and application/xml) is not always desirable. For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicated vulnerabilities related to the request body depending on the target app.

The environment variable DAST_API_OPENAPI_ALL_MEDIA_TYPES lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environment variable DAST_API_OPENAPI_ALL_MEDIA_TYPES is set to any value, DAST API tries to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type.

Alternatively, the variable DAST_API_OPENAPI_MEDIA_TYPES is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable DAST_API_OPENAPI_MEDIA_TYPES is set to a list of media types, only the listed media types are included when creating requests.

Multiple media types in DAST_API_OPENAPI_MEDIA_TYPES are separated by a colon (:). For example, to limit request generation to the media types application/x-www-form-urlencoded and multipart/form-data, set the environment variable DAST_API_OPENAPI_MEDIA_TYPES to application/x-www-form-urlencoded:multipart/form-data. Only supported media types in this list are included when creating requests, though non-supported media types are always skipped. A media type text may contain different sections. For example, application/vnd.api+json; charset=UTF-8, is a compound of type "/" [tree "."] subtype ["+" suffix]* [";" parameter]. Parameters are not taken into account when performing the filtering media types on request generation.

The environment variables DAST_API_OPENAPI_ALL_MEDIA_TYPES and DAST_API_OPENAPI_MEDIA_TYPES allow you to decide how to handle media types. These settings are mutually exclusive. If both are enabled, DAST API reports an error.

Configure DAST API with an OpenAPI Specification

To configure DAST API scanning with an OpenAPI specification:

To configure DAST API scanning with an OpenAPI Specification:

  1. Include the DAST-API.gitlab-ci.yml template in your .gitlab-ci.yml file.

  2. The configuration file has several testing profiles defined with different checks enabled. We recommend that you start with the Quick profile. Testing with this profile completes faster, allowing for easier configuration validation. Provide the profile by adding the DAST_API_PROFILE CI/CD variable to your .gitlab-ci.yml file.

  3. Provide the location of the OpenAPI Specification as either a file or URL. Specify the location by adding the DAST_API_OPENAPI variable.

  4. The target API instance’s base URL is also required. Provide it by using the DAST_API_TARGET_URL variable or an environment_url.txt file.

    Adding the URL in an environment_url.txt file at your project’s root is great for testing in dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an environment_url.txt file. DAST API automatically parses that file to find its scan target. You can see an example of this in our Auto DevOps CI YAML.

Complete example configuration of using an OpenAPI Specification:

stages:
  - dast

include:
  - template: DAST-API.gitlab-ci.yml

variables:
  DAST_API_PROFILE: Quick
  DAST_API_OPENAPI: test-api-specification.json
  DAST_API_TARGET_URL: http://test-deployment/

This is a minimal configuration for DAST API. From here you can:

HTTP Archive (HAR)

The HTTP Archive format (HAR) is an archive file format for logging HTTP transactions. When used with the GitLab