Overview

Beta program

Please note that IaC Prevention features are currently in beta.

Description

The iac scan command helps you detect Infrastructure as Code vulnerabilities using ggshield. They can be run in your local environment or in a CI environment. These subcommands use our public API to scan your files.

ggshield iac scan [OPTIONS] <SUBCOMMAND> [ARGS]...

List of available policies can be found in the documentation.

Options

It supports a few options that can be used to adapt the output behavior.

• --json: output results in JSON [default:false]
• --exit-zero: always return a 0 (non-error) status code, even if incidents are found. The env var GITGUARDIAN_EXIT_ZERO can also be used to set this option [default:false].
• --ignore-path <PATH>, --ipa <PATH>: do not scan the specified file patterns.
• --ignore-policy <POLICY-ID>, --ipo <POLICY-ID>: ignore IaC vulnerabilities associated with the specified policy ID. You can ignore multiple policies by calling this option several times.
• --minimum-severity [LOW|MEDIUM|HIGH|CRITICAL]: ignore all IaC vulnerabilities with a severity stricty lower than this value [default:LOW].
• -v, --verbose: verbose display mode [default:false].

Subcommands

The command can be used with several subcommands depending on the data that needs to be scanned.

• ggshield iac scan all
• ggshield iac scan diff
• ggshield iac scan ci
• ggshield iac scan pre-commit
• ggshield iac scan pre-push
• ggshield iac scan pre-receive
• [DEPRECATED] ggshield iac scan: refer to ggshield iac scan all instead

How to

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.

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 by adding the minimum severity in iac/minimum-severity:

  iac:
    minimum_severity: CRITICAL

• Using the CLI with the option --minimum-severity:

  ggshield iac scan <SUBCOMMAND> --minimum-severity CRITICAL iac_repo

Ignore a specific IaC vulnerability

This will prevent the IaC vulnerability to be shown in the reports.

Within the targeted resource of your IaC file, you can add an inline comment using 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
 }

Ignore a directory or a file

This will prevent the file from being scanned. You can either provide a filename, or a folder.

• Using the .gitguardian.yaml file by adding a list of paths in iac/ignored-paths:

  iac:
    ignored_paths:
      - 'iac_repo/general/'

  You can also ignore a path temporarily, and/or add a comment:

  iac:
    ignored_paths:
      - path: 'iac_repo/general/'
        comment: 'Ignore these files for now'
        until: '2030-01-01'

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

  ggshield iac scan <SUBCOMMAND> --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 by adding a list of policies IDs in iac/ignored-policies:

  iac:
    ignored_policies:
      - GG_IAC_0001

  You can also ignore a policy temporarily, and/or add a comment:

  iac:
    ignored_policies:
      - policy: 'GG_IAC_0001'
        comment: 'Ignore these files for now'
        until: '2030-01-01T00:00:01Z'

• Using the CLI with the option --ignore-policy:

  ggshield iac scan <SUBCOMMAND> --ignore-policy GG_IAC_0001

Sample configuration

version: 2
iac:
  # Exclude files and paths by globbing
  ignored_paths:
    - '**/README.md'
    - 'doc/*'
    - 'LICENSE'
    - path: 'tests/*'
      comment: 'Ignore vulnerabilities in tests'
    - path: 'dev/*'
      comment: 'Ignore vulnerabilities in dev sandbox'
      until: '2030-01-01T00:00:01Z'

  # IaC vulnerabilities to ignore
  ignored_policies:
    - GG_IAC_0000
    - GG_IAC_0005
    - policy: 'GG_IAC_0003'
      until: '2030-01-01T00:00:01Z'
    - policy: 'GG_IAC_0012'
      comment: 'We will handle this later'
      until: '2030-01-01'

  # Minimum severity of the policies
  minimum_severity: HIGH

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 IaC incidents. Here is how:

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

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 IaC vulnerability will include a policy ID, a description, an assessment of the criticality and some remediation guidelines.

API quotas

IaC scan uses the same permissions as secret scan. Each IaC scan will decrease your available quota by one. See the dedicated page for more information.

Limitations

Currently, ggshield exhaustively scan High+ IaC vulnerabilities written using Terraform or AWS CloudFormation, and targeting AWS services.

• Even though ggshield also scans High+ IaC vulnerabilities written using Kubernetes YAML and/or targeting GCP and Kubernetes as providers, fewer IaC vulnerabilities might be detected.
• All other IaC vulnerabilities with a lower severity, written using another languages or targeting other providers aren't scanned yet.

Was this page helpful?