diff options
Diffstat (limited to 'doc/user/application_security/dast_api/index.md')
| -rw-r--r-- | doc/user/application_security/dast_api/index.md | 110 |
1 files changed, 96 insertions, 14 deletions
diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 0cdbb879cfc..d494259ecc4 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -48,6 +48,7 @@ The following projects demonstrate DAST API scanning: - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/postman-example) - [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/graphql-example) - [Example SOAP project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/soap-example) +- [Authentication Token using Selenium](https://gitlab.com/gitlab-org/security-products/demos/api-dast/auth-token-selenium) ## Targeting API for DAST scanning @@ -97,8 +98,6 @@ The environment variables `DAST_API_OPENAPI_ALL_MEDIA_TYPES` and `DAST_API_OPENA #### 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](../../../ci/yaml/index.md#includetemplate) @@ -264,6 +263,8 @@ This example is a minimal configuration for DAST API. From here you can: #### DAST API scanning with a GraphQL Schema file +DAST API can use a GraphQL schema file to understand and test a GraphQL endpoint that has introspection disabled. To use a GraphQL schema file, it must be in the introspection JSON format. A GraphQL schema can be converted to a the introspection JSON format using an online 3rd party tool: [https://transform.tools/graphql-to-introspection-json](https://transform.tools/graphql-to-introspection-json). + To configure DAST API to use a GraphQL schema file that provides information about the target API to test: 1. [Include](../../../ci/yaml/index.md#includetemplate) @@ -997,6 +998,14 @@ repository's root as `.gitlab/gitlab-dast-api-config.yml`. The following profiles are pre-defined in the default configuration file. Profiles can be added, removed, and modified by creating a custom configuration. +#### Passive + +- Application Information Check +- Cleartext Authentication Check +- JSON Hijacking Check +- Sensitive Information Check +- Session Cookie Check + #### Quick - Application Information Check @@ -1924,7 +1933,7 @@ variables: When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During typical operation, the job always succeeds even if vulnerabilities are identified during testing. -Vulnerabilities are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the DAST API vulnerabilities are also shown on the Security & Compliance's Vulnerability Report page. +Vulnerabilities are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the DAST API vulnerabilities are also shown on the Security and Compliance's Vulnerability Report page. To prevent an excessive number of reported vulnerabilities, the DAST API scanner limits the number of vulnerabilities it reports per operation. @@ -1941,7 +1950,7 @@ Follow these steps to view details of a vulnerability: 1. You can view vulnerabilities in a project, or a merge request: - - In a project, go to the project's **Security & Compliance > Vulnerability Report** + - In a project, go to the project's **Security and Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. DAST API vulnerabilities are available in a section labeled @@ -2243,9 +2252,12 @@ dast_api_v1: variables: DAST_API_EXCLUDE_PATHS: /api/v1/** rules: - - if: $DAST_API_DISABLED + - if: $DAST_API_DISABLED == 'true' || $DAST_API_DISABLED == '1' when: never - - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH && + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == 'true' && + $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME + when: never + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == '1' && $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME when: never - if: $CI_COMMIT_BRANCH && @@ -2258,9 +2270,12 @@ dast_api_v2: variables: DAST_API_EXCLUDE_PATHS: /api/v2/** rules: - - if: $DAST_API_DISABLED + - if: $DAST_API_DISABLED == 'true' || $DAST_API_DISABLED == '1' + when: never + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == 'true' && + $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME when: never - - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH && + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == '1' && $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME when: never - if: $CI_COMMIT_BRANCH && @@ -2292,9 +2307,12 @@ dast_api_branch: variables: DAST_API_EXCLUDE_PATHS: /api/large_response_json rules: - - if: $DAST_API_DISABLED + - if: $DAST_API_DISABLED == 'true' || $DAST_API_DISABLED == '1' when: never - - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH && + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == 'true' && + $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME + when: never + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == '1' && $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME when: never - if: $CI_COMMIT_BRANCH && @@ -2310,9 +2328,12 @@ dast_api_branch: dast_api_main: extends: dast_api rules: - - if: $DAST_API_DISABLED + - if: $DAST_API_DISABLED == 'true' || $DAST_API_DISABLED == '1' + when: never + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == 'true' && + $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME when: never - - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH && + - if: $DAST_API_DISABLED_FOR_DEFAULT_BRANCH == '1' && $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME when: never - if: $CI_COMMIT_BRANCH && @@ -2553,14 +2574,75 @@ You can expedite the investigation with the [testssl.sh tool](https://testssl.sh 1. Run `./testssl.sh --log https://specs`. 1. Attach the log file to your support ticket. +### `ERROR: Job failed: failed to pull image` + +This error message occurs when pulling an image from a container registry that requires authentication to access (it is not public). + +In the job console output the error looks like: + +```log +Running with gitlab-runner 15.6.0~beta.186.ga889181a (a889181a) + on blue-2.shared.runners-manager.gitlab.com/default XxUrkriX +Resolving secrets +00:00 +Preparing the "docker+machine" executor +00:06 +Using Docker executor with image registry.gitlab.com/security-products/api-security:2 ... +Starting service registry.example.com/my-target-app:latest ... +Pulling docker image registry.example.com/my-target-app:latest ... +WARNING: Failed to pull image with policy "always": Error response from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s) +ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:latest" with specified policies [always]: Error response from daemon: Get https://registry.example.com/my-target-app/manifests/latest: unauthorized (manager.go:237:0s) +``` + +**Error message** + +- In GitLab 15.9 and earlier, `ERROR: Job failed: failed to pull image` followed by `Error response from daemon: Get IMAGE: unauthorized`. + +**Solution** + +Authentication credentials are provided using the methods outlined in the [Access an image from a private Container Registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a 3rd party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. + +The following example uses the [statically defined credentials](../../../ci/docker/using_docker_images.md#use-statically-defined-credentials) authentication method. In this example the container registry is `registry.example.com` and image is `my-target-app:latest`. + +1. Read how to [Determine your `DOCKER_AUTH_CONFIG` data](../../../ci/docker/using_docker_images.md#determine-your-docker_auth_config-data) to understand how to compute the variable value for `DOCKER_AUTH_CONFIG`. The configuration variable `DOCKER_AUTH_CONFIG` contains the Docker JSON configuration to provide the appropriate authentication information. For example, to access private container registry: `registry.example.com` with the credentials `aGVsbG8gd29ybGQK`, the Docker JSON looks like: + + ```json + { + "auths": { + "registry.example.com": { + "auth": "aGVsbG8gd29ybGQK" + } + } + } + ``` + +1. Add the `DOCKER_AUTH_CONFIG` as a CI/CD variable. Instead of adding the configuration variable directly in your `.gitlab-ci.yml`file you should create a project [CI/CD variable](../../../ci/variables/index.md#for-a-project). +1. Rerun your job, and the statically-defined credentials are now used to sign in to the private container registry `registry.example.com`, and let you pull the image `my-target-app:latest`. If succeeded the job console shows an output like: + + ```log + Running with gitlab-runner 15.6.0~beta.186.ga889181a (a889181a) + on blue-4.shared.runners-manager.gitlab.com/default J2nyww-s + Resolving secrets + 00:00 + Preparing the "docker+machine" executor + 00:56 + Using Docker executor with image registry.gitlab.com/security-products/api-security:2 ... + Starting service registry.example.com/my-target-app:latest ... + Authenticating with credentials from $DOCKER_AUTH_CONFIG + Pulling docker image registry.example.com/my-target-app:latest ... + Using docker image sha256:139c39668e5e4417f7d0eb0eeb74145ba862f4f3c24f7c6594ecb2f82dc4ad06 for registry.example.com/my-target-app:latest with digest registry.example.com/my-target- + app@sha256:2b69fc7c3627dbd0ebaa17674c264fcd2f2ba21ed9552a472acf8b065d39039c ... + Waiting for services to be up and running (timeout 30 seconds)... + ``` + ## Get support or request an improvement To get support for your particular problem, use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and DAST API. -Use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. +Use `~"Category:API Security"` [label](../../../development/labels/index.md) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. -[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. +[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an emoji reaction or join the discussion. When experiencing a behavior not working as expected, consider providing contextual information: |