# 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](https://snyk.io).

## 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. Run`snyk-iac-rules parse --help` for full instructions.

`test` Execute all test cases discovered in matching files. Run`snyk-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. Run`snyk-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