SDK reference

NAME

snyk-iac-rules - SDK to write, debug, test, and bundle custom rules for Snyk IaC

SYNOPSIS

snyk-iac-rules [COMMAND] [PATH] [OPTIONS]

DESCRIPTION

The SDK helps you write, debug, test, bundle, and distribute custom rules written in Rego, which can then be used by the Snyk IaC CLI to find vulnerabilities in IaC configuration files.

For more information on Snyk, see the Snyk website.

Not sure where to start?

  1. Start writing a new rule with $ snyk-iac-rules template

  2. To start writing Rego, parse fixtures into JSON with $ snyk-iac-rules parse

  3. Test your rule with $ snyk-iac-rules test

  4. Bundle your rules with $ snyk-iac-rules build

  5. Distribute your rules with $ snyk-iac-rules push

COMMANDS

To see command-specific flags and usage, run the help command, for example, snyk-iac-rules --help.

The following top-level SDK commands are available

template Generate the scaffolding for writing new rules. See snyk-iac-rules template --help for full instructions.

parse Return the JSON format of the provided fixture file. Rego requires JSON input, so use this to build your Rego rules. Runsnyk-iac-rules parse --help for full instructions.

test Execute all test cases discovered in matching files. Runsnyk-iac-rules test --help for full instructions.

build Package OPA policy and data files into a bundle. Run snyk-iac-rules build --help for full instructions.

push Distribute the bundle generated by the build command to one of the supported container registries. Runsnyk-iac-rules push --help for full instructions.

PATH

All the commands in the SDK can take an optional path to a folder, which dictates where the rules would be located. The parse and push commands are the only commands where this path is strictly required.

Any path can be provided - relative or absolute.

OPTIONS

To see command-specific flags and usage, run the help command, for example,snyk-iac-rules template --help.

Template options

--rule=RULE

The mandatory name of the rule you want to define. This generates a rules/ folder at the top level, which contains a folder named after the rule and a Rego rule and Rego test file. At the same time, it generates a lib/ folder containing utility functions that can be accessed from data.lib for writing rules and extending the testing library, or data.lib.testing for the tests.

The scaffolded folder structure looks like this:

rules └── RULE ├── fixtures ├── allowed.<extension> └── denied.<extension> ├── main.rego └── main_test.rego lib └── testing └── main.rego └── tfplan.rego └── main.rego

Note: the rule name cannot contain any whitespace or start with SNYK-.

--format=hcl2|json|yaml|tf-plan

The mandatory configuration format you want to define your rule for. This generates two fixture files under the rules/<RULE>/fixtures folder, which are then used by the tests to verify the behavior of the Rego rule.

--severity=low|medium|high|critical

The severity of the rule, which will show up when running the Snyk Infrastructure as Code CLI.

Default: low

--title=TITLE

The title of the rule, which will show up when running the Snyk Infrastructure as Code CLI.

Parse options

--format=hcl2|yaml|tf-plan

The format of the fixture. The format dictates what parser Snyk uses to generate JSON from the fixture.

Default: hcl2

Test options

--verbose

Output tracing logs.

--explain=full|notes|fails

Filter tracing logs.

Default: fails

--timeout=TIMEOUT

The amount of time in nanoseconds to wait for the tests to run. If it takes longer than TIMEOUT, the tests fail.

Default: 5000000 (5 seconds).

--ignore

Accepts a regular expression that can be used to ignore files and folders and prevent them from being loaded for testing.

Default: ".*" (hidden files), "fixtures"

--run

Accepts a regular expression that can be used for running a subset of the tests.

Build options

--output

The name and location of the resulting bundle.

Default: bundle.tar.gz

--entrypoint

By default, the Template command places the Rego for the rules under a ./rules/<rule> folder. The Rego belongs to the rules package, and the entry function is called deny, returning JSON representing a vulnerability if a misconfiguration was found. This structure works with the rules/deny entrypoint, but a custom entrypoint can be provided if the generated file and package structure needs to be modified.

Default: "rules/deny"

--ignore

Accepts a regular expression that can be used to ignore files and folders and prevent them from being loaded for bundling.

Default: ".*”"(hidden files), "fixtures", "testing", "*_test.rego"

--target=rego|wasm

What format to use for the bundle. Snyk does not support Rego bundles for now in the Snyk IaC CLI.

Default: wasm

Push options

--registry

The registry location you want the bundle to be pushed to, for example, docker.io/example/bundle.tar.gz

Flags available across all commands

[COMMAND] --help, --help [COMMAND], -h

Prints a help text. You may specify a COMMAND to get more details.

SDK examples

Generate a new rule with the name CUSTOM_RULE:

$ snyk-iac-rules template --rule CUSTOM_RULE

Test the rule:

$ snyk-iac-rules test --run CUSTOM_RULE

Generate the custom rules bundle:

$ snyk-iac-rules build --output bundle-v1.0.0.tar.gz

SDK exit codes

Possible exit codes and their meaning:

0: success

1: failure, the custom rule might be invalid

Last updated

More information

Snyk privacy policy

© 2024 Snyk Limited | All product and company names and logos are trademarks of their respective owners.