ggshield iac scan diff

Beta program

Please note that IaC Prevention features are currently in beta.

info

This command was implemented in version 1.17.0

Description

Scan a Git repository for changes in IaC vulnerabilities between two states.

ggshield iac scan diff [OPTIONS] [DIRECTORY]

The scan is successful if no new IaC vulnerability was found.

By default, the output will show:

The number of known IaC vulnerabilities resolved by the changes
The number of known IaC vulnerabilities left untouched
The number and the list of new IaC vulnerabilities introduced by the changes

Options

--json: Use JSON output.
--ignore-path, --ipa PATTERN: Do not scan paths that match the specified glob-like patterns.
--ignore-policy, --ipo TEXT: Policies to exclude from the results.
--minimum-severity [LOW|MEDIUM|HIGH|CRITICAL]: Minimum severity of the policies.
--exit-zero: Always return a 0 (non-error) status code, even if incidents are found. This option can also be set with the GITGUARDIAN_EXIT_ZERO environment variable.
--ref GIT_REF: A Git reference, such as a commit ID, a reference relative to HEAD or a remote. [required]
--staged: Include staged changes in the scan.

This command supports all ggshield global options.

How to

Scan since a specific commit

You can pass a commit ID as a reference for the command. The ID can be found:

On your Git host (Github, Gitlab, Bitbucket etc.): in the commits list, find the relevant commit and copy its ID (often referred to as a "commit SHA")
Using Git: The git log command displays the commit history for the repository.

$ git log
commit de3ba5b489060170e03b884885193bc90c6bc881
Author: John Doe <john.doe@email.com>
Date:   Sun Jan 8 16:50:36 2023 +0200

This is a commit message

Then pass the ID to the iac scan diff command:

ggshield iac scan diff --ref my_commit_id path_to_iac_folder

Scan the last 3 commits

The --ref argument can also be a reference relative to the current state. For instance, you can scan for the IaC vulnerabilities in the last 3 commits with the following command:

ggshield iac scan diff --ref HEAD~3 path_to_iac_folder

Scan in a Git hook

Some options are provided to simplify the use of the command in a Git hook environment. They replace the --ref and --staged options. For instructions on Git hooks usage, please refer to Git Hooks documentation