diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-31 21:07:42 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-31 21:07:42 +0300 |
commit | 580622bdb3c762a8e89facd8a3946881ee480442 (patch) | |
tree | 3ac9d759da23f78f95f50684bd238a9f76839538 /doc | |
parent | b211a4ea14d5e9ed9b0c248a4e8c5c1d85b542cb (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/user/application_security/dast/index.md | 91 | ||||
-rw-r--r-- | doc/user/group/saml_sso/index.md | 47 |
2 files changed, 134 insertions, 4 deletions
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index dcbaff70633..af8c6a3feb0 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -253,6 +253,85 @@ LoadModule proxy_http_module modules/mod_proxy_http.so [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. +### API scan + +Using an API specification as a scan's target is a useful way to seed URLs for scanning an API. +Vulnerability rules in an API scan are different than those in a normal website scan. + +#### Specification format + +API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`. + +#### Import API specification from a URL + +If your API specification is accessible at a URL, you can pass that URL in directly as the target. +The specification doesn't have to be hosted on the same host as the API being tested. + +```yml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_API_SPECIFICATION: http://my.api/api-specification.yml +``` + +#### Import API specification from a file + +If your API specification is in your repository, you can provide the specification's filename directly as the target. The specification file is expected to be in the `/zap/wrk` directory. + +```yml +dast: + script: + - mkdir -p /zap/wrk + - cp api-specification.yml /zap/wrk/api-specification.yml + - /analyze -t $DAST_WEBSITE + variables: + GIT_STRATEGY: fetch + DAST_API_SPECIFICATION: api-specification.yml +``` + +#### Full scan + +API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` environment variable. Domain validation isn't supported for full API scans. + +#### Host override + +Specifications often define a host, which contains a domain name and a port. The host referenced may be different than the host of the API's review instance. +This can cause incorrect URLs to be imported, or a scan on an incorrect host. Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values. + +For example, with a OpenAPI V3 specification containing: + +```yml +servers: + - url: https://api.host.com +``` + +If the test version of the API is running at `https://api-test.host.com`, then the following DAST configuration can be used: + +```yml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_API_SPECIFICATION: http://api-test.host.com/api-specification.yml + DAST_API_HOST_OVERRIDE: api-test.host.com +``` + +Note that `DAST_API_HOST_OVERRIDE` is only applied to specifications imported by URL. + +#### Authentication using headers + +Tokens in request headers are often used as a way to authenticate API requests. You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable. Headers are applied to every request DAST makes. + +```yml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_API_SPECIFICATION: http://api-test.api.com/api-specification.yml + DAST_REQUEST_HEADERS: "Authorization: Bearer my.token" +``` + ### Customizing the DAST settings The DAST settings can be changed through environment variables by using the @@ -300,17 +379,21 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | 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_WEBSITE` | no| The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` | no | The API specification to import. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. Not supported for API scans. | | `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_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | | `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`. | -| `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`. | +| `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`. Not supported for API scans. | | `DAST_AUTO_UPDATE_ADDONS` | no | Set to `false` to pin the versions of ZAProxy add-ons to those provided with the DAST image. Defaults to `true`. | +| `DAST_API_HOST_OVERRIDE` | no | Used to override domains defined in API specification files. | +| `DAST_EXCLUDE_RULES` | no | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from scans. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/master/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. | +| `DAST_REQUEST_HEADERS` | no | Set to a comma-separated list of request header names and values. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | ### DAST command-line options diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 359d548e236..cf8d63e1512 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -316,6 +316,53 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | +## Configuring on a self-managed GitLab instance + +For self-managed GitLab instances we strongly recommend using the +[instance-wide SAML OmniAuth Provider](../../../integration/saml.md) instead. + +Group SAML SSO helps if you need to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance. + +To proceed with configuring Group SAML SSO instead, you'll need to enable the `group_saml` OmniAuth provider. This can be done from: + +- `gitlab.rb` for GitLab [Omnibus installations](#omnibus-installations). +- `gitlab/config/gitlab.yml` for [source installations](#source-installations). + +### Limitations + +Group SAML on a self-managed instance is limited when compared to the recommended +[instance-wide SAML](../../../integration/saml.md). The recommended solution allows you to take advantage of: + +- [LDAP compatibility](../../../administration/auth/ldap.md). +- [LDAP group Sync](../../../administration/auth/how_to_configure_ldap_gitlab_ee/index.md#group-sync). +- [Required groups](../../../integration/saml.md#required-groups-starter-only). +- [Admin groups](../../../integration/saml.md#admin-groups-starter-only). +- [Auditor groups](../../../integration/saml.md#auditor-groups-starter-only). + +### Omnibus installations + +1. Make sure GitLab is + [configured with HTTPS](../../../install/installation.md#using-https). +1. Enable OmniAuth and the `group_saml` provider in `gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_enabled'] = true + gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }] + ``` + +### Source installations + +1. Make sure GitLab is + [configured with HTTPS](../../../install/installation.md#using-https). +1. Enable OmniAuth and the `group_saml` provider in `gitlab/config/gitlab.yml`: + + ```yaml + omniauth: + enabled: true + providers: + - { name: 'group_saml' } + ``` + ## Troubleshooting This section contains possible solutions for problems you might encounter. |