ggshield iac scan

caution

This feature is experimental.

Purpose#

ggshield iac is a command that runs in your local environment or in a CI environment to help you detect Infrastructure as Code vulnerabilities. This command uses our public API to scan your files.

Only metadata such as call time, request size and scan mode is stored server-side from scans using ggshield iac. Scanning a repository with this command will not trigger any incident on your dashboard. Neither the files scanned nor the potential secrets they contain will be stored.

List of available policies can be found in the documentation.

Command overview#

The only subcommand available for now is scan. It only supports v2 of the configuration file.

$ ggshield iac scan --helpUsage: ggshield iac scan [OPTIONS] DIRECTORY
  Scan a directory for IaC vulnerabilities.
Options:  --exit-zero                     Always return 0 (non-error) status code.  --minimum-severity [LOW|MEDIUM|HIGH|CRITICAL]                                  Minimum severity of the policies  -v, --verbose                   Verbose display mode.  --ignore-policy, --ipo TEXT     Policies to exclude from the results.  --ignore-path, --ipa PATH       Do not scan the specified paths.  --json                          JSON output.  -h, --help                      Show this message and exit.

How to#

Scan a repo or directory#

ggshield iac scan path_to_main_iac_folder

Create a token#

You can use the ggshield auth command as described in the README or create a personal access token with the scan permission in your dashboard.

Ignore a directory or a file#

This will prevent the file from being scanned.

Using the .gitguardian.yaml file (v2): a list of paths can be added in iac/ignored-paths:
```
iac:  ignored-paths:    - iac_repo/general/
```

Using the CLI with the option --ignore-path:

ggshield iac scan --ignore-path my_file.tf iac_repo

Ignore a policy by ID#

This will prevent the policy ID from being used in scans.

Using the .gitguardian.yaml file (v2): a list of policies IDs can be added in iac/ignored-policies:
```
iac:  ignored-policies:    - GG_IAC_0001
```
Using the CLI with the option --ignore-policy:

ggshield iac scan --ignore-policy GG_IAC_0001

Set minimum severity#

Severity is an assessment per policy made by GitGuardian. Currently available values are LOW (default), MEDIUM, HIGH and CRITICAL. Setting the minimum severity will ignore policies with strictly lower severity levels.

Using the .gitguardian.yaml file (v2): the minimum severity can be added in iac/minimum-severity:
```
iac:  minimum-severity: CRITICAL
```
Using the CLI with the option --minimum-severity:

ggshield iac scan --minimum-severity CRITICAL iac_repo

Ignore a vulnerability#

If you ignore a vulnerability, it will not be shown in the reports.

A vulnerability can be ignored by adding an inline comment to the corresponding resource.

After any of the vulnerable lines, add a comment with the following format ggignore-iac: <ids to ignore> (ids should be separated by a comma).

Example:

resource "aws_alb_listener" "inline_ignore" {    protocol = "HTTP"  # ggignore-iac: GG_IAC_0001,GG_IAC_0002 }

Sample configuration#

The iac command only supports the v2 of the configuration file.

version: 2iac:  ignored-policies:    - GG_IAC_0001    - GG_IAC_0003  ignored-paths:    - folder/general/    - sample/file.tf  minimum-severity: CRITICAL

Return results as JSON#

Results are returned in the shell output, either as text summarizing vulnerabilities (default), or as JSON for further investigations in the pipeline. In order to display results as JSON, use the --json flag.

ggshield iac scan --json iac_repo

Internals#

Files selection#

ggshield select IaC files based on path, filenames and extensions as well as content. It will not select any file ignored by git. You can also provide a custom banlist which will be added on top.

Scanning#

Files are scanned simultaneously and results are returned grouped by file. Each vulnerability will include a policy ID, a description, an assessment of the criticality and a remediation guide.

API quotas#

IaC scans uses the same permissions as secret scan. Each IaC scan will decrease your available quota by one.

Limitations#

Currently, we support terraform files with AWS as a provider. While scanning alternative providers and languages is supported by GitGuardian, fewer vulnerabilities might be detected.