Run CLI Scanner in IaC Mode

Running Sysdig Command Line Interface (CLI) Scanner in Infrastructure-as-Code (IaC) mode allows scanning IaC resources in a local directories or as part of continuous integration and continuous deployment (CI/CD) cycle and report risks and compliance posture.

Prerequisites

To include sysdig-cli-scanner in your IaC pipeline, run the sysdig-cli-scanner command.

Make sure the sysdig-cli-scanner binary is available as part of worker or runner where the pipeline is executing.
Define a secret containing the API Token and make it available in the pipeline using a SECURE_API_TOKEN environment variable.
Ensure that you have the necessary Role-Based Access Control (RBAC) permissions:
- Posture -> CLI IaC Scanning: Exec
- Policies -> Posture Policies: Read

Parameters

Basic usage of the sysdig-cli-scanner:

sysdig-cli-scanner --iac [OPTIONS] <PathsToScan>

Mandatory Parameters

Option	Description
`--iac`	The first parameter of `sysdig-cli-scanner` must be `--iac` to enable the IaC scanning functionality.
`SECURE_API_TOKEN`	Provide the API token as environment variable `SECURE_API_TOKEN` . You can retrieve this from Settings > User Profile in Sysdig Secure.
`--apiurl=<endpoint>`	Sysdig Secure Endpoint. In SaaS, this value is region-dependent and is auto-completed on the Get Started page in the UI.

Usage

sysdig-cli-scanner --iac [OPTIONS] <PathsToScan>

Replace <PathsToScan> with the path to the directory containing the source code to scan. It can be an absolute or a relative path.

If is omitted, the path defaults to current directory, ./ .

For example:

SECURE_API_TOKEN=<your-api-token> ./sysdig-cli-scanner --iac -r -f H --apiurl <sysdig-api-url> /home/user/a-git-repository /home/user/another-git-repository

Additional Parameters

To display a list of all available command line parameters:

  -h, --help                    Show this help message

Example output:

Usage:
      sysdig-cli-scanner --iac [OPTIONS] <PathsToScan>

Common Options:
  -a, --apiurl string                Secure API base URL
      --console-log                  Force logs to console, mutually exclusive with --logfile
  -o, --logfile string               File destination for logs, mutually exclusive with --console-log
  -l, --loglevel string              Log level [trace|debug|info|warn|err|fatal|panic|disabled] (default "info")
      --output-json string           Output path of the scan result report in json format
  -s, --skiptlsverify                Skip TLS certificate verification

Help Options:
  -h, --help                         Show this help message

IaC Scan Options:
      --list-unsupported-resources   Toggle output of detailed list of unsupported resources
  -r, --recursive                    Scan folders for manifests recursively
  -f, --severity-threshold string    The minimum severity that will fail a scan [low|l|medium|m|high|h|never|n] (default "h")
      --version                      Show the version and exit

Exit codes:
  0: Scan evaluation "pass"
  1: Scan evaluation "fail"
  2: Invalid parameters
  3: Internal error

CLI Scanner Exit Codes

Access the container exit codes with -h

The codes are:

0 : Scan success. No findings or all findings are below the fail threshold
1 :Scan failed. One or more findings are equal or above the fail threshold.
2 : Incorrect parameters. Implies no API token is given.
3 : Other execution errors.

Sample Result in Terminal

You can view scan results in the terminal window :

$ sysdig-cli-scanner --iac -r -f H --apiurl=https://us2.app.sysdig.com /home/user/a-git-repository /home/user/another-git-repository

Summary
—------
Detected 1 modules/manifests in 1 folders
2 resources scrapped
3 unsupported resources (use –list-unsupported-resources for details)

Findings:
 🔴 13 High
 🟠 17 Medium
 🟡 18 Low

Errors
------
 - /.github/workflows/approve-test-run.yaml: Object 'Kind' is missing in '{"jobs":{"approve-test-run":{"if":"${{ github.event.issue.pull_request }}","permissions":{"pull-requests":"write"},"runs-on":"ubuntu-latest","steps":[{"name":"Slash Command Dispatch","uses":"peter-evans/slash-command-dispatch@v3","with":{"commands":"approve-test-run","issue-type":"pull-request","permission":"write","reaction-token":"${{ secrets.GITHUB_TOKEN }}","token":"${{ secrets.TOOLS_JENKINS_ADMIN_ACCESS_GITHUB_TOKEN }}"}}]}},"name":"Approve Test Run","true":{"issue_comment":{"types":["created"]}}}'.
 ...
 - <Path> - <Details>


Details
—------
Container permitting root | 🟡 Low | 2 Occurrences
+-------------------------------------------+------------+--------------------------------------------------------+--------------------------------------+
|                 RESOURCE                  |    KIND    |                   RESOURCE LOCATION                    |                SOURCE                |
+-------------------------------------------+------------+--------------------------------------------------------+--------------------------------------+
| release-name-harbor-scanner-sysdig-secure | Deployment | runAsNonRoot in container harbor-scanner-sysdig-secure | /charts/harbor-scanner-sysdig-secure |
| release-name-sysdig-stackdriver-bridge    | Deployment | runAsNonRoot in container stackdriver-webhook-bridge   | /charts/sysdig-stackdriver-bridge    |
+-------------------------------------------+------------+--------------------------------------------------------+--------------------------------------+

Workload container default RunAsGroup root | 🟠 Medium | 2 Occurrences
+-------------------------------------------+------------+----------------------------------------------------+--------------------------------------+
|                 RESOURCE                  |    KIND    |                 RESOURCE LOCATION                  |                SOURCE                |
+-------------------------------------------+------------+----------------------------------------------------+--------------------------------------+
| release-name-harbor-scanner-sysdig-secure | Deployment | `runAsGroup` in workload                           | /charts/harbor-scanner-sysdig-secure |
| release-name-sysdig-stackdriver-bridge    | Deployment | `runAsGroup` in workload                           | /charts/sysdig-stackdriver-bridge    |
+-------------------------------------------+------------+----------------------------------------------------+--------------------------------------+

Workload without ServiceAccount | 🔴 High | 1 Occurrences
+----------------------------------------+------------+----------------------------------------------------+-----------------------------------+
|                RESOURCE                |    KIND    |                 RESOURCE LOCATION                  |              SOURCE               |
+----------------------------------------+------------+----------------------------------------------------+-----------------------------------+
| release-name-sysdig-stackdriver-bridge | Deployment | `serviceAccountName` in workload                   | /charts/sysdig-stackdriver-bridge |
+----------------------------------------+------------+----------------------------------------------------+-----------------------------------+

...

IaC Scan SUCCESS at 2024-01-04 13:19:37.702567 -0500 EST m=+0.100174543
OK: scan complete

Scan errors

Errors that are not critical are the errors that are collected during the scan and are present in our existing scan summary model, defined per resource. They shouldn’t fail the scan execution or alter the Exit Code. Therefore, Exit Code will remain 0 or 1 in the presence of non-critical errors.

The non-critical errors are displayed in the output and as part of the JSON.

Integrations

Vulnerability Policies

Policies allow you to define a set of rules that will evaluate each scan result. After the evaluation, each policy will pass or fail. A policy failure or non-compliance happens if the scan result doesn’t meet all the rules in a policy.

You can configure the CI/CD policies as Always apply. If a policy has the Always apply flag, it will be evaluated on every scanned image even if you don’t specify it explicitly.

Specifying Policies

For CI/CD and manual image scans, you can instruct the sysdig-cli-scanner tool to evaluate specific policies by using the --policies=policy-name-1,policy-name-2 flag or the short version, -p policy-name-1,policy-name-2. This flag accepts a comma-separated list of policy IDs, allowing you to specify one or more policies for evaluation. This flexibility is useful when policy names are lengthy or contain special characters.

If a specified policy does not exist, the Policy service will display the following error and halt execution.

ERROR: Policy "policy-name-6" does not exist. Please check and try again.

Configuration File Options

You can specify a configuration file with -c config-file-name or --config-file=config-file-name. This defaults to $HOME/.sysdig/cli_config.yaml.

Grouping Options

The CLI scanner supports grouping results by policy or resource.

Policy grouping: --group-by=policy or -g policy
Resource grouping (default): --group-by=resource or -g resource

Guidelines

All keys in the cli_config.yaml file are case-insensitive, as determined by the underlying libraries.
Values set in cli_config.yaml have the lowest priority; if the same setting is specified via an environment variable or CLI flag, those will override the configuration file.
You can configure all CLI flags and environment variables for IaC mode within this file. Fields like help are included for completeness, even though they may not be commonly used here.
The secureapitoken can now be added directly in cli_config.yaml; previously, it was only configurable as an environment variable.

Sample YAML File

iac:
  apiurl: https://secure-site.sysdig.com
  console-log: true
  help: false
  list-unsupported-resources: true
  logfile: ""
  loglevel: debug
  output-json: ""
  policy:
    - All Posture Findings
  recursive: true
  secureapitoken: ***
  severity-threshold: l
  skiptlsverify: false
  version: false

If you save this file as sample-configuration.yaml file, you can enter the following command:

sysdig-cli-scanner --iac -p "All Posture Findings" --group-by resource sample-configuration.yaml

For information on using Posture Policies, see Create Custom Controls with Terraform.

Jenkins

You can integrate the Sysdig CLI Scanner as a Jenkins step. Once imported from the URL, you can add it to your project.

Create the Project or use an existing one:
Chose Sysdig Secure Code Scan as the build step:

Configure the operation:

Option	Description
`Sysdig Secure Engine URL`	The Sysdig Secure endpoint. In SaaS, this value is region-dependent and is auto-completed on the Get Started page in the UI.
`SECURE_API_TOKEN`	Provide your API token. You can retrieve this from Settings > User Profile in Sysdig Secure.
`Path`	The path to the directory containing the source code to scan. It can be an absolute or a relative path.

Configure the Advanced parameters:

Option	Description
`List Unsupported Resources`	Toggle output of detailed list of unsupported resources.
`Recursive`	Scan folders for manifests recursively.
`Choose Severity Threshold`	The minimum severity that will fail a scan: Low \| Medium \| High \| Never. The default is High.
`Version`	The CLI Scanner version to use. The default is `latest`.

Run your Project:

Once you run the Project, the generated output will be identical to the output produced when running the CLI Scanner as a standalone application.