Commit 5596b56a authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Link to GitLab CE docs

Since we moved all docs to the GitLab docs with
https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29347,
let's link to them to avoid updating them in two places.
parent a0abbf68
Pipeline #70499840 passed with stages
in 4 minutes and 49 seconds
......@@ -31,47 +31,7 @@ Some tools require to be able to launch Docker containers to scan your applicati
## Settings
Dependency Scanning can be configured using environment variables.
### Docker images
| Environment variable | Function |
|------------------------------|----------|
| DS_ANALYZER_IMAGES | Comma separated list of custom images. Default images are still enabled.|
| DS_ANALYZER_IMAGE_PREFIX | Override the name of the Docker registry providing the default images (proxy). |
| DS_ANALYZER_IMAGE_TAG | Override the Docker tag of the default images. |
| DS_DEFAULT_ANALYZERS | Override the names of default images. |
| DS_PULL_ANALYZER_IMAGES | Pull the images from the Docker registry (set to 0 to disable) |
Read more about [customizing analyzers](./docs/analyzers.md#custom-analyzers).
### Remote checks
| Name | Function |
|--------------------------------|------------------------------------------------------------------------------------|
| DS_DISABLE_REMOTE_CHECKS | Do not send any data to GitLab (Used in the dependency version checker, see below) |
| DEP_SCAN_DISABLE_REMOTE_CHECKS | Deprecated. Renamed to `DS_DISABLE_REMOTE_CHECKS ` |
### Vulnerability filters
| Environment variable | Default | Function |
|-----------------------|-----------|----------|
| DS_EXCLUDED_PATHS | | Exclude vulnerabilities from output based on the paths. |
`DS_EXCLUDED_PATHS` is a comma-separated list of patterns.
Patterns can be globs, file or folder paths. Parent directories will also match patterns.
### Timeouts
| Environment variable | Function |
|--------------------------------------|----------|
| DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT | Time limit for Docker client negotiation |
| DS_PULL_ANALYZER_IMAGE_TIMEOUT | Time limit when pulling the image of an analyzer |
| DS_RUN_ANALYZER_TIMEOUT | Time limit when running an analyzer |
Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration).
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
Examples: "300ms", "1.5h" or "2h45m".
The settings are documented in [GitLab CE](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html).
## Development
......@@ -99,34 +59,6 @@ To run the integration tests:
./test.sh
```
## Supported languages and package managers
The following table shows which languages and package managers are supported and which tools are used.
| Language (package managers) | Scan tool | Introduced in GitLab Version |
|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [Retire.js](https://retirejs.github.io/retire.js) | 10.5 |
| Python ([pip](https://pip.pypa.io/en/stable/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | 10.5 |
| Ruby ([gem](https://rubygems.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [bundler-audit](https://github.com/rubysec/bundler-audit) | 10.5 |
| Java ([Maven](https://maven.apache.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), | 10.5 |
| PHP ([Composer](https://getcomposer.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | 10.5 |
## Remote checks
While some tools pull a local database to check vulnerabilities, some others require sending data to GitLab central servers to analyze them.
You can disable these tools by using the `DS_DISABLE_REMOTE_CHECKS` [environment variable](https://docs.gitlab.com/ee/ci/variables/README.html#gitlab-ci-yml-defined-variables).
Here is the list of tools that are doing such remote checks and what kind of data they send:
**Gemnasium**
* Gemnasium scans the dependencies of your project locally and sends a list of packages to GitLab central servers.
* The servers return the list of known vulnerabilities for all versions of these packages
* Then the client picks up the relevant vulnerabilities by comparing with the versions of the packages that are used by the project.
Gemnasium does *NOT* send the exact package versions your project relies on.
## Versioning and release process
Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).
......
# Dependency Scanning Analyzers
## Overview
Dependency Scanning relies on underlying third party tools that are wrapped into what we call `Analyzers`.
An analyzer is a [dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) that wraps a particular tool to:
- expose its detection logic
- handle its execution
- convert its output to the common format
This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common).
Dependency Scanning currently supports the following official analyzers:
- [bundler-audit](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit)
- [gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium)
- [gemnasium-maven](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven)
- [gemnasium-python](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python)
- [retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js)
The Analyzers are published as Docker images that Dependency Scanning will use to launch dedicated containers for each analysis.
Dependency Scanning is pre-configured with a set of **default images** that are officially maintained by GitLab.
Users can also integrate their own **custom images**.
## Custom Analyzers
You can provide your own analyzers as a comma separated list of Docker images.
Here's how to add `analyzers/nugget` and `analyzers/perl` to the default images:
DS_ANALYZER_IMAGES=analyzers/nugget,analyzers/perl
Please note that this configuration doesn't benefit from the integrated detection step.
Dependency Scanning has to fetch and spawn each Docker image to establish whether the custom analyzer can scan the source code.
## Default analyzers
### Use a Docker mirror
You can switch to a custom Docker registry
that provides the official analyzer images under a different prefix.
For instance, the following instructs Dependency Scanning to pull `my-docker-registry/gl-images/gemnasium`
instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`:
DS_ANALYZER_IMAGE_PREFIX=my-docker-registry/gl-images
Please note that this configuration requires that your custom registry provides images for all the official analyzers.
### Select specific analyers
You can select the official analyzers you want to run.
Here's how to enable `bundler-audit` and `gemnasium` while disabling all the other official analyzers:
DS_DEFAULT_ANALYZERS="bundler-audit,gemnasium
### Disable all analyzers
Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the default analyzers.
DS_DEFAULT_ANALYZERS=""
## Analyzers Data
| Property \ Tool | Gemnasium | bundler-audit | Retire.js |
|---------------------------------------|:------------------:|:------------------:|:------------------:|
| severity | :x: | :white_check_mark: | :white_check_mark: |
| title | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| file | :white_check_mark: | :warning: | :white_check_mark: |
| start line | :x: | :x: | :x: |
| end line | :x: | :x: | :x: |
| external id (e.g. CVE) | :white_check_mark: | :white_check_mark: | :warning: |
| urls | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| internal doc/explanation | :white_check_mark: | :x: | :x: |
| solution | :white_check_mark: | :white_check_mark: | :x: |
| confidence | :x: | :x: | :x: |
| affected item (e.g. class or package) | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| source code extract | :x: | :x: | :x: |
| internal id | :white_check_mark: | :x: | :x: |
| date | :white_check_mark: | :x: | :x: |
| credits | :white_check_mark: | :x: | :x: |
- :white_check_mark: => we have that data
- :warning: => we have that data but it's partially reliable, or we need to extract that data from unstructured content
- :x: => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it.
The values provided by these tools are heterogeneous so they are sometimes normalized into common values (e.g. `severity`, `confidence`, etc).
This mapping usually happens in the analyzer's `convert` command.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment