Skip to main content

Overview

caution

This feature is experimental, and only available from GGShield version 1.18.0.

Purpose

The ggshield sca scan commands help you detect vulnerabilities in your code dependencies through Software Composition Analysis. They can be run in your local environment or in a CI environment. These commands use our public API to scan the files provided in the required directory or git repository.

They analyze the open-source dependencies of your project, and return the list of vulnerabilities associated with those open-source dependencies.

Supported ecosystems

For now, we support the following ecosystems:

  • Go
  • Maven
  • NPM
  • NuGet
  • PyPI
  • RubyGems

Subcommands

The command has to be used with one of the following subcommands, depending on the data that needs to be scanned.

Configuration file

All the ggshield SCA subcommands support the .gitguardian.yaml (v2) config file. The SCA configuration should be of the following form:

version: 2
sca:
minimum-severity: CRITICAL
ignored-paths:
- folder/general/
- sample/file.lock
ignored_vulnerabilities:
- identifier: GHSA-abcd-efgh-1234
path: Pipfile.lock
comment: 'Vulnerability does not concern this repository.'
until: '2024-01-01T00:00:01Z'

Minimum severity

The minimum severity allows to ignore every vulnerability with a severity strictly lower than the given one. Its value should be in [LOW(default)|MEDIUM|HIGH|CRITICAL].

Ignored paths

The ignored-paths parameter allows to ignore some files or directories from the scan.

Ignored vulnerabilities

The configuration file also allows to ignore some vulnerabilities. An ignored vulnerability is specified with the following parameters:

  • identifier: the identifier provided by GGShield when finding the vulnerability
  • path: the path to the file in which the vulnerability was found
  • comment (Optional): a comment on the reason why the vulnerability can be ignored
  • until (Optional): a datetime until when the vulnerability should be ignored. If not specified, the vulnerability will be ignored as long as the entry exists in the .gitguardian.yaml configuration file.

Exit codes

Depending on the outcome of the command, ggshield exit code will be one of these:

CodeMeaning
0No problem found. If the command was a scan, it ran successfully and did not find any issue to report.
1The command ran successfully, but it found issues to report.
2Usage error: the command did not receive the parameters it expected.
3Authentication error: the command tried to log on a server, but the server rejected it.
128Unexpected error.
tip

If you need this command to exit with a code 0 when vulnerabilities are found in a scan, you can pass the option --exit-zero