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
• PyPI
• RubyGems

Subcommands

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

• ggshield sca scan ci
• ggshield sca scan all
• ggshield sca scan diff
• ggshield sca scan pre-push
• ggshield sca scan pre-commit
• ggshield sca scan pre-receive

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:

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.

Was this page helpful?