debian-mirror-gitlab/doc/user/application_security/dast/index.md

372 lines
15 KiB
Markdown
Raw Normal View History

2019-10-12 21:52:04 +05:30
---
type: reference, howto
---
2019-09-30 21:07:59 +05:30
# Dynamic Application Security Testing (DAST) **(ULTIMATE)**
2019-07-31 22:56:46 +05:30
2019-12-04 20:38:33 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4348)
2019-07-31 22:56:46 +05:30
in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
2019-10-12 21:52:04 +05:30
NOTE: **4 of the top 6 attacks were application based.**
Download our whitepaper,
["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/)
to learn how to protect your organization.
2019-07-31 22:56:46 +05:30
Running [static checks](../sast/index.md) on your code is the first step to detect
vulnerabilities that can put the security of your code at risk. Yet, once
deployed, your application is exposed to a new category of possible attacks,
such as cross-site scripting or broken authentication flaws. This is where
Dynamic Application Security Testing (DAST) comes into place.
## Overview
If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s)
for known vulnerabilities using Dynamic Application Security Testing (DAST).
2019-09-30 21:07:59 +05:30
You can take advantage of DAST by either [including the CI job](#configuration) in
2019-07-31 22:56:46 +05:30
your existing `.gitlab-ci.yml` file or by implicitly using
[Auto DAST](../../../topics/autodevops/index.md#auto-dast-ultimate)
that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
GitLab checks the DAST report, compares the found vulnerabilities between the source and target
branches, and shows the information right on the merge request.
![DAST Widget](img/dast_all.png)
By clicking on one of the detected linked vulnerabilities, you will be able to
see the details and the URL(s) affected.
![DAST Widget Clicked](img/dast_single.png)
[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing)
is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
to perform an analysis on your running web application.
By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) and will perform passive scanning only. It will not actively attack your application.
However, DAST can be [configured](#full-scan)
to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report.
It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md).
2019-09-04 21:01:54 +05:30
The [`dast`](https://gitlab.com/gitlab-org/security-products/dast/container_registry) Docker image in GitLab container registry is updated on a weekly basis to have all [`owasp2docker-weekly`](https://hub.docker.com/r/owasp/zap2docker-weekly/) updates in it.
2019-07-31 22:56:46 +05:30
## Use cases
It helps you automatically find security vulnerabilities in your running web
applications while you are developing and testing your applications.
## Requirements
To run a DAST job, you need GitLab Runner with the
2019-09-04 21:01:54 +05:30
[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html).
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
## Configuration
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
For GitLab 11.9 and later, to enable DAST, you must
[include](../../../ci/yaml/README.md#includetemplate) the
2019-12-04 20:38:33 +05:30
[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml)
2019-09-30 21:07:59 +05:30
that's provided as a part of your GitLab installation.
For GitLab versions earlier than 11.9, you can copy and use the job as defined
in that template.
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
Add the following to your `.gitlab-ci.yml` file:
2019-07-31 22:56:46 +05:30
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_WEBSITE: https://example.com
```
2019-09-30 21:07:59 +05:30
There are two ways to define the URL to be scanned by DAST:
2019-12-21 20:55:43 +05:30
1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables).
1. Add it in an `environment_url.txt` file at the root of your project.
This is great for testing in dynamic environments. In order to run DAST against
2020-01-01 13:55:28 +05:30
an app that is dynamically created during a GitLab CI pipeline, have the app
2019-12-21 20:55:43 +05:30
persist its domain in an `environment_url.txt` file, and DAST will
automatically parse that file to find its scan target.
You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
of this in our Auto DevOps CI YML.
2019-09-30 21:07:59 +05:30
2019-12-04 20:38:33 +05:30
If both values are set, the `DAST_WEBSITE` value will take precedence.
2019-07-31 22:56:46 +05:30
The included template will create a `dast` job in your CI/CD pipeline and scan
your project's source code for possible vulnerabilities.
2019-09-30 21:07:59 +05:30
The results will be saved as a
2019-07-31 22:56:46 +05:30
[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
that you can later download and analyze. Due to implementation limitations we
always take the latest DAST artifact available. Behind the scenes, the
[GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
is used to run the tests on the specified URL and scan it for possible vulnerabilities.
2019-09-30 21:07:59 +05:30
### Authenticated scan
2019-07-31 22:56:46 +05:30
It's also possible to authenticate the user before performing the DAST checks:
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_WEBSITE: https://example.com
DAST_AUTH_URL: https://example.com/sign-in
DAST_USERNAME: john.doe@example.com
DAST_PASSWORD: john-doe-password
DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form
DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form
DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between
```
2019-09-30 21:07:59 +05:30
The results will be saved as a
2019-07-31 22:56:46 +05:30
[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
that you can later download and analyze.
Due to implementation limitations, we always take the latest DAST artifact available.
2019-09-30 21:07:59 +05:30
### Full scan
2019-07-31 22:56:46 +05:30
DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which
includes both passive and active scanning against the same target website:
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_FULL_SCAN_ENABLED: "true"
```
2019-12-04 20:38:33 +05:30
#### Domain validation
The DAST job can be run anywhere, which means you can accidentally hit live web servers
and potentially damage them. You could even take down your production environment.
For that reason, you should use domain validation.
Domain validation is not required by default. It can be required by setting the [environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to true.
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_FULL_SCAN_ENABLED: "true"
DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED: "true"
```
Since ZAP full scan actively attacks the target application, DAST sends a ping to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand.
If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is false or unset, the scan will _proceed_ unless the response to the ping
includes a `Gitlab-DAST-Permission` header with a value of `deny`.
If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is true, the scan will _exit_ unless the response to the ping
includes a `Gitlab-DAST-Permission` header with a value of `allow`.
Here are some examples of adding the `Gitlab-DAST-Permission` header to a response in Rails, Django, and Node (with Express).
##### Ruby on Rails
Here's how you would add a [custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers):
```ruby
class DastWebsiteTargetController < ActionController::Base
def dast_website_target
response.headers['Gitlab-DAST-Permission'] = 'allow'
head :ok
end
end
```
##### Django
Here's how you would add a [custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields):
```python
class DastWebsiteTargetView(View):
def head(self, *args, **kwargs):
response = HttpResponse()
response['Gitlab-Dast-Permission'] = 'allow'
return response
```
##### Node (with Express)
Here's how you would add a [custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append):
```javascript
app.get('/dast-website-target', function(req, res) {
res.append('Gitlab-DAST-Permission', 'allow')
res.send('Respond to DAST ping')
})
```
##### Domain validation header via a proxy
It's also possible to add the `Gitlab-DAST-Permission` header via a proxy.
###### NGINX
The following config allows NGINX to act as a reverse proxy and add the `Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header):
```
# default.conf
server {
listen 80;
server_name localhost;
location / {
proxy_pass http://test-application;
add_header Gitlab-DAST-Permission allow;
}
}
```
###### Apache
Apache can also be used as a [reverse proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
2020-01-01 13:55:28 +05:30
to add the `Gitlab-DAST-Permission` [header](https://httpd.apache.org/docs/current/mod/mod_headers.html).
2019-12-04 20:38:33 +05:30
To do so, add the following lines to `httpd.conf`:
```
# httpd.conf
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule proxy_http_module modules/mod_proxy_http.so
<VirtualHost *:80>
ProxyPass "/" "http://test-application.com/"
ProxyPassReverse "/" "http://test-application.com/"
Header set Gitlab-DAST-Permission "allow"
</VirtualHost>
```
[This snippet](https://gitlab.com/gitlab-org/security-products/dast/snippets/1894732) contains a complete `httpd.conf` file
configured to act as a remote proxy and add the `Gitlab-DAST-Permission` header.
2019-09-30 21:07:59 +05:30
### Customizing the DAST settings
2019-07-31 22:56:46 +05:30
2019-09-04 21:01:54 +05:30
The DAST settings can be changed through environment variables by using the
2019-07-31 22:56:46 +05:30
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
2019-12-04 20:38:33 +05:30
These variables are documented in [available variables](#available-variables).
2019-07-31 22:56:46 +05:30
For example:
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_WEBSITE: https://example.com
DAST_TARGET_AVAILABILITY_TIMEOUT: 120
```
Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
configuration, the last mention of the variable will take precedence.
2019-09-30 21:07:59 +05:30
### Overriding the DAST template
2019-07-31 22:56:46 +05:30
If you want to override the job definition (for example, change properties like
`variables` or `dependencies`), you need to declare a `dast` job after the
template inclusion and specify any additional keys under it. For example:
```yaml
include:
template: DAST.gitlab-ci.yml
dast:
stage: dast # IMPORTANT: don't forget to add this
variables:
DAST_WEBSITE: https://example.com
CI_DEBUG_TRACE: "true"
```
As the DAST job belongs to a separate `dast` stage that runs after all
[default stages](../../../ci/yaml/README.md#stages),
don't forget to add `stage: dast` when you override the template job definition.
2019-10-12 21:52:04 +05:30
## Available variables
DAST can be [configured](#customizing-the-dast-settings) using environment variables.
Since it's a wrapper around the ZAP scanning scripts
([baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
or [full](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) scan), it
accepts all arguments those scripts recognize (the arguments are the same).
The choice of the scan type depends on the `DAST_FULL_SCAN_ENABLED` environment
variable value.
| Environment variable | Required | Description |
|-----------------------------| ----------|--------------------------------------------------------------------------------|
| `DAST_WEBSITE` | yes | The URL of the website to scan. |
| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. |
| `DAST_USERNAME` | no | The username to authenticate to in the website. |
| `DAST_PASSWORD` | no | The password to authenticate to in the website. |
| `DAST_USERNAME_FIELD` | no | The name of username field at the sign-in HTML form. |
| `DAST_PASSWORD_FIELD` | no | The name of password field at the sign-in HTML form. |
| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. |
| `DAST_TARGET_AVAILABILITY_TIMEOUT` | no | Time limit in seconds to wait for target availability. Scan is attempted nevertheless if it runs out. Integer. Defaults to `60`. |
| `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
2019-12-04 20:38:33 +05:30
| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | no | Requires [domain validation](#domain-validation) when running DAST full scans. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
2019-10-12 21:52:04 +05:30
2019-07-31 22:56:46 +05:30
## Security Dashboard
The Security Dashboard is a good place to get an overview of all the security
2019-12-04 20:38:33 +05:30
vulnerabilities in your groups, projects and pipelines. Read more about the
2019-07-31 22:56:46 +05:30
[Security Dashboard](../security_dashboard/index.md).
## Interacting with the vulnerabilities
Once a vulnerability is found, you can interact with it. Read more on how to
[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
2019-09-30 21:07:59 +05:30
## Vulnerabilities database update
For more information about the vulnerabilities database update, check the
[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
2019-10-12 21:52:04 +05:30
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
2019-12-26 22:10:19 +05:30
## Troubleshooting
### Running out of memory
By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25%
of the total memory on the host.
Since it keeps most of its information in memory during a scan,
it is possible for DAST to run out of memory while scanning large applications.
This results in the following error:
```
[zap.out] java.lang.OutOfMemoryError: Java heap space
```
Fortunately, it is straightforward to increase the amount of memory available
for DAST by overwriting the `script` key in the DAST template:
```yaml
include:
template: DAST.gitlab-ci.yml
dast:
script:
- export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)}
- /analyze -t $DAST_WEBSITE -z"-Xmx3072m"
```
Here, DAST is being allocated 3072 MB.
Change the number after `-Xmx` to the required memory amount.