README.md 6.26 KB
Newer Older
Olivier Gonzalez's avatar
Olivier Gonzalez committed
1 2
# GitLab Dependency Scanning

3 4
[![pipeline status](https://gitlab.com/gitlab-org/security-products/dependency-scanning/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/security-products/dependency-scanning/commits/master)
[![coverage report](https://gitlab.com/gitlab-org/security-products/dependency-scanning/badges/master/coverage.svg)](https://gitlab.com/gitlab-org/security-products/dependency-scanning/commits/master)
Olivier Gonzalez's avatar
Olivier Gonzalez committed
5

6 7 8 9
GitLab tool for running Dependency Security Scanning on given project.
It's written in Go using
the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common)
shared by SAST, Dependency Scanning and their analyzers.
Olivier Gonzalez's avatar
Olivier Gonzalez committed
10 11 12 13 14 15 16 17 18 19 20 21 22

## How to use

1. `cd` into the directory of the application you want to scan
1. Run the Docker image:

    ```sh
    docker run \
      --interactive --tty --rm \
      --volume "$PWD":/code \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      registry.gitlab.com/gitlab-org/security-products/dependency-scanning:${VERSION:-latest} /code
    ```
23 24

    `VERSION` can be replaced with the latest available release matching your GitLab version. See [Versioning](#versioning-and-release-process) for more details.
Olivier Gonzalez's avatar
Olivier Gonzalez committed
25 26 27 28 29 30 31

1. The results will be displayed and also stored in `gl-dependency-scanning-report.json`

**Why mounting the Docker socket?**

Some tools require to be able to launch Docker containers to scan your application. You can skip this but you won't benefit from all scanners.

32 33 34 35 36 37 38 39 40 41 42 43
## 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. |
Olivier Gonzalez's avatar
Olivier Gonzalez committed
44

45 46 47
Read more about [customizing analyzers](./docs/analyzers.md#custom-analyzers).

### Remote checks
Olivier Gonzalez's avatar
Olivier Gonzalez committed
48 49 50

| Name                           | Function                                                                           |
|--------------------------------|------------------------------------------------------------------------------------|
51
| DEP_SCAN_DISABLE_REMOTE_CHECKS | Do not send any data to GitLab (Used in the dependency version checker, see below) |
Olivier Gonzalez's avatar
Olivier Gonzalez committed
52

53
### Timeouts
Olivier Gonzalez's avatar
Olivier Gonzalez committed
54

55 56 57 58 59
| Environment variable                 | Function |
|--------------------------------------|----------|
| DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT | Time limit for Docker client negotation |
| DS_PULL_ANALYZER_IMAGE_TIMEOUT       | Time limit when pulling the image of an analyzer |
| DS_RUN_ANALYZER_TIMEOUT              | Time limit when running an analyzer |
Olivier Gonzalez's avatar
Olivier Gonzalez committed
60

61 62 63
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".
Olivier Gonzalez's avatar
Olivier Gonzalez committed
64

65
## Development
Olivier Gonzalez's avatar
Olivier Gonzalez committed
66

67
### Build project
Olivier Gonzalez's avatar
Olivier Gonzalez committed
68

69
Go 1.11 or higher is required to build Dependency Scanning. Go modules must be enabled.
Olivier Gonzalez's avatar
Olivier Gonzalez committed
70 71

```sh
72
GO111MODULE=on go build
Olivier Gonzalez's avatar
Olivier Gonzalez committed
73 74
```

75 76 77
### Run locally

To run the command locally and perform the scan on `/tmp/code`:
Olivier Gonzalez's avatar
Olivier Gonzalez committed
78 79

```sh
80
CI_PROJECT_DIR=/tmp/code ./dependency-scanning
Olivier Gonzalez's avatar
Olivier Gonzalez committed
81 82
```

83 84 85
### Integration tests

To run the integration tests:
Olivier Gonzalez's avatar
Olivier Gonzalez committed
86 87

```sh
88
./test.sh
Olivier Gonzalez's avatar
Olivier Gonzalez committed
89 90
```

91

Olivier Gonzalez's avatar
Olivier Gonzalez committed
92 93 94 95
## Supported languages and package managers

The following table shows which languages and package managers are supported and which tools are used.

96 97 98 99 100 101 102
| 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 |
Olivier Gonzalez's avatar
Olivier Gonzalez committed
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120

## Remote checks

While some tools pull a local database to check vulnerabilities, some others require to send data to GitLab central servers to analyze them.
You can disable these tools by using the `DEP_SCAN_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 the 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

121
Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).
Olivier Gonzalez's avatar
Olivier Gonzalez committed
122 123 124 125 126

# Contributing

If you want to help and extend the list of supported scanners, read the
[contribution guidelines](CONTRIBUTING.md).