- When DAST API scans run
- Example DAST API scanning configurations
- Targeting API for DAST scanning
- Authentication
- Configuration files
- Available CI/CD variables
- Overrides
-
Exclude Paths
- Examples
-
Exclude parameters
- Exclude parameters using a JSON document
-
Examples
- Excluding a single header
- Excluding both a header and two cookies
- Excluding a
body-form
parameter - Excluding a specific JSON nodes using JSON Path
- Excluding multiple JSON nodes using JSON Path
- Excluding a XML attribute
- Excluding a XML text’s element
- Excluding an XML element
- Excluding an XML node with namespaces
- Using a JSON string
- Using a file
- Exclude URLs
- Running your first scan
- Viewing DAST API vulnerabilities
- Running DAST API in an offline environment
-
Troubleshooting
- Error waiting for API Security ‘http://127.0.0.1:5000’ to become available
- Failed to start scanner session (version header not found)
- Application cannot determine the base URL for the target API
- Use OpenAPI with an invalid schema
- No operation in the OpenAPI document is consuming any supported media type
- Get support or request an improvement
- Glossary
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.
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:
- Example OpenAPI v2 Specification project
- Example HTTP Archive (HAR) project
- Example Postman Collection project
- Example GraphQL project
- Example SOAP project
Targeting API for DAST scanning
You can specify the API you want to scan by using:
OpenAPI Specification
- 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
andapplication/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:
-
Include the
DAST-API.gitlab-ci.yml
template in your.gitlab-ci.yml
file. -
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 theDAST_API_PROFILE
CI/CD variable to your.gitlab-ci.yml
file. -
Provide the location of the OpenAPI Specification as either a file or URL. Specify the location by adding the
DAST_API_OPENAPI
variable. -
The target API instance’s base URL is also required. Provide it by using the
DAST_API_TARGET_URL
variable or anenvironment_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 anenvironment_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:
- Run your first scan.
- Add authentication.
- Learn how to handle false positives.
HTTP Archive (HAR)
The HTTP Archive format (HAR) is an archive file format for logging HTTP transactions. When used with the GitLab