2020-07-28 23:09:34 +05:30
---
type: reference, howto
stage: Secure
group: Composition Analysis
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
2019-09-30 21:07:59 +05:30
# Dependency Scanning Analyzers **(ULTIMATE)**
2020-10-24 23:57:45 +05:30
Dependency Scanning relies on underlying third-party tools that are wrapped into
2019-09-30 21:07:59 +05:30
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 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 )
2020-10-24 23:57:45 +05:30
The analyzers are published as Docker images, which Dependency Scanning uses
2019-09-30 21:07:59 +05:30
to launch dedicated containers for each analysis.
Dependency Scanning is pre-configured with a set of **default images** that are
maintained by GitLab, but users can also integrate their own **custom images** .
## Official default analyzers
Any custom change to the official analyzers can be achieved by using an
[environment variable in your `.gitlab-ci.yml` ](index.md#customizing-the-dependency-scanning-settings ).
### Using a custom 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` .
In `.gitlab-ci.yml` define:
```yaml
include:
template: Dependency-Scanning.gitlab-ci.yml
variables:
2020-05-24 23:13:21 +05:30
SECURE_ANALYZERS_PREFIX: my-docker-registry/gl-images
2019-09-30 21:07:59 +05:30
```
This configuration requires that your custom registry provides images for all
the official analyzers.
### Selecting specific analyzers
You can select the official analyzers you want to run. Here's how to enable
`bundler-audit` and `gemnasium` while disabling all the other default ones.
In `.gitlab-ci.yml` define:
```yaml
include:
template: Dependency-Scanning.gitlab-ci.yml
variables:
DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium"
```
2020-10-24 23:57:45 +05:30
`bundler-audit` runs first. When merging the reports, Dependency Scanning
removes the duplicates and keeps the `bundler-audit` entries.
2019-09-30 21:07:59 +05:30
### Disabling default analyzers
2020-10-24 23:57:45 +05:30
Setting `DS_DEFAULT_ANALYZERS` to an empty string disables all the official
2019-09-30 21:07:59 +05:30
default analyzers. In `.gitlab-ci.yml` define:
```yaml
include:
template: Dependency-Scanning.gitlab-ci.yml
variables:
DS_DEFAULT_ANALYZERS: ""
```
That's needed when one totally relies on [custom analyzers ](#custom-analyzers ).
## Custom analyzers
2020-11-24 15:15:51 +05:30
You can provide your own analyzers by
2020-04-22 19:07:51 +05:30
defining CI jobs in your CI configuration. For consistency, you should suffix your custom Dependency
Scanning jobs with `-dependency_scanning` . Here's how to add a scanning job that's based on the
Docker image `my-docker-registry/analyzers/nuget` and generates a Dependency Scanning report
`gl-dependency-scanning-report.json` when `/analyzer run` is executed. Define the following in
`.gitlab-ci.yml` :
```yaml
nuget-dependency_scanning:
image:
name: "my-docker-registry/analyzers/nuget"
script:
- /analyzer run
artifacts:
reports:
dependency_scanning: gl-dependency-scanning-report.json
```
The [Security Scanner Integration ](../../../development/integrations/secure.md ) documentation explains how to integrate custom security scanners into GitLab.
2019-09-30 21:07:59 +05:30
## Analyzers data
The following table lists the data available for each official analyzer.
| Property \ Tool | Gemnasium | bundler-audit | Retire.js |
|---------------------------------------|:------------------:|:------------------:|:------------------:|
| Severity | 𐄂 | ✓ | ✓ |
| Title | ✓ | ✓ | ✓ |
| File | ✓ | ⚠ | ✓ |
| Start line | 𐄂 | 𐄂 | 𐄂 |
| End line | 𐄂 | 𐄂 | 𐄂 |
| External ID (e.g., CVE) | ✓ | ✓ | ⚠ |
| URLs | ✓ | ✓ | ✓ |
| Internal doc/explanation | ✓ | 𐄂 | 𐄂 |
| Solution | ✓ | ✓ | 𐄂 |
| Confidence | 𐄂 | 𐄂 | 𐄂 |
| Affected item (e.g. class or package) | ✓ | ✓ | ✓ |
| Source code extract | 𐄂 | 𐄂 | 𐄂 |
| Internal ID | ✓ | 𐄂 | 𐄂 |
| Date | ✓ | 𐄂 | 𐄂 |
| Credits | ✓ | 𐄂 | 𐄂 |
- ✓ => we have that data
2020-10-24 23:57:45 +05:30
- ⚠ => we have that data, but it's partially reliable, or we need to extract that data from unstructured content
- 𐄂 => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it.
2019-09-30 21:07:59 +05:30
2020-10-24 23:57:45 +05:30
The values provided by these tools are heterogeneous, so they are sometimes
2019-09-30 21:07:59 +05:30
normalized into common values (e.g., `severity` , `confidence` , etc).
