Overview

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

The supported ecosystems are available from [SCA documentation](GitGuardian Platform perimeters](../../../../sca/monitor-your-perimeter#supported-languages)

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|MALICIOUS].

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:

Code	Meaning
0	No problem found. If the command was a scan, it ran successfully and did not find any issue to report.
1	The command ran successfully, but it found issues to report.
2	Usage error: the command did not receive the parameters it expected.
3	Authentication error: the command tried to log on a server, but the server rejected it.
128	Unexpected 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

Dependencies between the dashboard and ggshield

So you benefit from a fully integrated experience, ggshield and the GitGuardian dashboard interact with each other when it comes to monitoring and remediating your SCA incidents. Here is how:

Ignored SCA incidents

SCA incidents that are ignored on your GitGuardian dashboard will not be raised by ggshield. Note that you need to upgrade ggshield to version 1.25.0 to benefit from this integration.