summaryrefslogtreecommitdiff
path: root/doc/user
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/application_security/dast/index.md91
-rw-r--r--doc/user/group/saml_sso/index.md47
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.
View Lorry Controller Status