diff --git a/docs/docs/configuration/skipping.md b/docs/docs/configuration/skipping.md index 7e228d696fff..508d80c05bc5 100644 --- a/docs/docs/configuration/skipping.md +++ b/docs/docs/configuration/skipping.md @@ -1,6 +1,6 @@ -# Skipping Files and Directories +# Skipping Artifacts -This section details ways to specify the files and directories that Trivy should not scan. +This section details ways to specify the files, directories and resources that Trivy should not scan. ## Skip Files | Scanner | Supported | @@ -116,4 +116,8 @@ A file pattern contains the analyzer it is used for, and the pattern itself, joi The prefixes are listed [here](https://github.com/aquasecurity/trivy/tree/{{ git.commit }}/pkg/fanal/analyzer/const.go) -[^1]: Only work with the [license-full](../scanner/license.md) flag) \ No newline at end of file +[^1]: Only work with the [license-full](../scanner/license.md) flag) + +## Skip Resources + +You can skip IaC resources by providing inline comments. More details are provided [here](../scanner/misconfiguration/config/config.md#skipping-resources-by-inline-comments) \ No newline at end of file diff --git a/docs/docs/scanner/misconfiguration/config/config.md b/docs/docs/scanner/misconfiguration/config/config.md new file mode 100644 index 000000000000..7d21425996cf --- /dev/null +++ b/docs/docs/scanner/misconfiguration/config/config.md @@ -0,0 +1,259 @@ +This page describes misconfiguration-specific configuration. + +### Enabling a subset of misconfiguration scanners +It's possible to only enable certain misconfiguration scanners if you prefer. +You can do so by passing the `--misconfig-scanners` option. +This flag takes a comma-separated list of configuration scanner types. + +```bash +trivy config --misconfig-scanners=terraform,dockerfile . +``` + +Will only scan for misconfigurations that pertain to Terraform and Dockerfiles. + +### Loading custom checks +You can load check files or directories including your custom checks using the `--config-check` flag. +This can be repeated for specifying multiple files or directories. + +```bash +trivy config --config-check custom-policy/policy --config-check combine/policy --config-check policy.rego --namespaces user myapp +``` + +You can load checks bundle as OCI Image from a Container Registry using the `--checks-bundle-repository` flag. + +```bash +trivy config --checks-bundle-repository myregistry.local/mychecks --namespaces user myapp +``` + + +### Passing custom data +You can pass directories including your custom data through `--data` option. +This can be repeated for specifying multiple directories. + +```bash +cd examples/misconf/custom-data +trivy config --config-check ./my-check --data ./data --namespaces user ./configs +``` + +For more details, see [Custom Data](./custom/data.md). + +### Passing namespaces +By default, Trivy evaluates checks defined in `builtin.*`. +If you want to evaluate custom checks in other packages, you have to specify package prefixes through `--namespaces` option. +This can be repeated for specifying multiple packages. + +``` bash +trivy config --config-check ./my-check --namespaces main --namespaces user ./configs +``` + +### Private Terraform registries +Trivy can download Terraform code from private registries. +To pass credentials you must use the `TF_TOKEN_` environment variables. +You cannot use a `.terraformrc` or `terraform.rc` file, these are not supported by trivy yet. + +From the Terraform [docs](https://developer.hashicorp.com/terraform/cli/config/config-file#environment-variable-credentials): + +> Environment variable names should have the prefix TF_TOKEN_ added to the domain name, with periods encoded as underscores. +> For example, the value of a variable named `TF_TOKEN_app_terraform_io` will be used as a bearer authorization token when the CLI makes service requests to the hostname `app.terraform.io`. +> +> You must convert domain names containing non-ASCII characters to their punycode equivalent with an ACE prefix. +> For example, token credentials for `例えば.com` must be set in a variable called `TF_TOKEN_xn--r8j3dr99h_com`. +> +> Hyphens are also valid within host names but usually invalid as variable names and may be encoded as double underscores. +> For example, you can set a token for the domain name café.fr as TF_TOKEN_xn--caf-dma_fr or TF_TOKEN_xn____caf__dma_fr. + +If multiple variables evaluate to the same hostname, Trivy will choose the environment variable name where the dashes have not been encoded as double underscores. + + +### Skipping resources by inline comments + +Trivy supports ignoring misconfigured resources by inline comments for Terraform, CloudFormation and Helm configuration files only. + +In cases where Trivy can detect comments of a specific format immediately adjacent to resource definitions, it is possible to ignore findings from a single source of resource definition (in contrast to `.trivyignore`, which has a directory-wide scope on all of the files scanned). The format for these comments is `trivy:ignore:` immediately following the format-specific line-comment [token](https://developer.hashicorp.com/terraform/language/syntax/configuration#comments). + +The ignore rule must contain one of the possible check IDs that can be found in its metadata: ID, short code or alias. The `id` from the metadata is not case-sensitive, so you can specify, for example, `AVD-AWS-0089` or `avd-aws-0089`. + +For example, to ignore a misconfiguration ID `AVD-GCP-0051` in a Terraform HCL file: + +```terraform +#trivy:ignore:AVD-GCP-0051 +resource "google_container_cluster" "example" { + name = var.cluster_name + location = var.region +} +``` + +You can add multiple ignores on the same comment line: +```terraform +#trivy:ignore:AVD-GCP-0051 trivy:ignore:AVD-GCP-0053 +resource "google_container_cluster" "example" { + name = var.cluster_name + location = var.region +} +``` + +You can also specify a long ID, which is formed as follows: `--`. + +As an example, consider the following check metadata: + +```yaml +# custom: + # id: AVD-AWS-0089 + # avd_id: AVD-AWS-0089 + # provider: aws + # service: s3 + # severity: LOW + # short_code: enable-logging +``` + +Long ID would look like the following: `aws-s3-enable-logging`. + +Example for CloudFromation: +```yaml +AWSTemplateFormatVersion: "2010-09-09" +Resources: +#trivy:ignore:* + S3Bucket: + Type: 'AWS::S3::Bucket' + Properties: + BucketName: test-bucket +``` + +!!!note +Ignore rules for Helm files should be placed before the YAML object, since only it contains the location data needed for ignoring. + +Example for Helm: +```yaml + serviceAccountName: "testchart.serviceAccountName" + containers: + # trivy:ignore:KSV018 + - name: "testchart" + securityContext: + runAsUser: 1000 + runAsGroup: 3000 + image: "your-repository/your-image:your-tag" + imagePullPolicy: "Always" + + +#### Expiration Date + +You can specify the expiration date of the ignore rule in `yyyy-mm-dd` format. This is a useful feature when you want to make sure that an ignored issue is not forgotten and worth revisiting in the future. For example: +```tf +#trivy:ignore:aws-s3-enable-logging:exp:2024-03-10 +resource "aws_s3_bucket" "example" { + bucket = "test" +} +``` + +The `aws-s3-enable-logging` check will be ignored until `2024-03-10` until the ignore rule expires. + +#### Ignoring by attributes + +You can ignore a resource by its attribute value. This is useful when using the `for-each` meta-argument. For example: + +```tf +locals { + ports = ["3306", "5432"] +} + +#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306] +resource "aws_security_group_rule" "example" { + for_each = toset(local.ports) + type = "ingress" + from_port = each.key + to_port = each.key + protocol = "TCP" + cidr_blocks = ["0.0.0.0/0"] + security_group_id = aws_security_group.example.id + source_security_group_id = aws_security_group.example.id +} +``` + +The `aws-ec2-no-public-ingress-sgr` check will be ignored only for the `aws_security_group_rule` resource with port number `5432`. It is important to note that the ignore rule should not enclose the attribute value in quotes, despite the fact that the port is represented as a string. + +If you want to ignore multiple resources on different attributes, you can specify multiple ignore rules: + +```tf +#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306] +#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=5432] +``` + +You can also ignore a resource on multiple attributes in the same rule: +```tf +locals { + rules = { + first = { + port = 1000 + type = "ingress" + }, + second = { + port = 1000 + type = "egress" + } + } +} + +#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=1000,type=egress] +resource "aws_security_group_rule" "example" { + for_each = { for k, v in local.rules : k => v } + + type = each.value.type + from_port = each.value.port + to_port = each.value.port + protocol = "TCP" + cidr_blocks = ["0.0.0.0/0"] + security_group_id = aws_security_group.example.id + source_security_group_id = aws_security_group.example.id +} +``` + +Checks can also be ignored by nested attributes: + +```tf +#trivy:ignore:*[logging_config.prefix=myprefix] +resource "aws_cloudfront_distribution" "example" { + logging_config { + include_cookies = false + bucket = "mylogs.s3.amazonaws.com" + prefix = "myprefix" + } +} +``` + +#### Ignoring module issues + +Issues in third-party modules cannot be ignored using the method described above, because you may not have access to modify the module source code. In such a situation you can add ignore rules above the module block, for example: + +```tf +#trivy:ignore:aws-s3-enable-logging +module "s3_bucket" { + source = "terraform-aws-modules/s3-bucket/aws" + + bucket = "my-s3-bucket" +} +``` + +An example of ignoring checks for a specific bucket in a module: +```tf +locals { + bucket = ["test1", "test2"] +} + +#trivy:ignore:*[bucket=test1] +module "s3_bucket" { + for_each = toset(local.bucket) + source = "terraform-aws-modules/s3-bucket/aws" + bucket = each.value +} +``` + +#### Support for Wildcards + +You can use wildcards in the `ws` (workspace) and `ignore` sections of the ignore rules. + +```tf +# trivy:ignore:aws-s3-*:ws:dev-* +``` + +This example ignores all checks starting with `aws-s3-` for workspaces matching the pattern `dev-*`. + diff --git a/docs/docs/scanner/misconfiguration/custom/schema.md b/docs/docs/scanner/misconfiguration/custom/schema.md index 7b305cc10dbf..f3d2e9f24af0 100644 --- a/docs/docs/scanner/misconfiguration/custom/schema.md +++ b/docs/docs/scanner/misconfiguration/custom/schema.md @@ -1,11 +1,37 @@ # Input Schema ## Overview -Checks can be defined with custom schemas that allow inputs to be verified against them. Adding a policy schema + +Schemas are declarative documents that define the structure, data types and constraints of inputs being scanned. Trivy provides certain schemas out of the box as seen in the explorer [here](https://aquasecurity.github.io/trivy-schemas/). You can also find the source code for the schemas [here](https://github.com/aquasecurity/trivy/tree/main/pkg/iac/rego/schemas). + +It is not required to pass in schemas, in order to scan inputs by Trivy but are required if type-checking is needed. + +Checks can be defined with custom schemas that allow inputs to be verified against them. Adding an input schema enables Trivy to show more detailed error messages when an invalid input is encountered. -In Trivy we have been able to define a schema for a [Dockerfile](https://github.com/aquasecurity/trivy/tree/main/pkg/iac/rego/schemas) -Without input schemas, a policy would be as follows: +## Unified Schema + +One of the unique advantages of Trivy is to take a variety of inputs, such as IaC files (e.g. CloudFormation, Terraform etc.) and also live cloud scanning +(e.g. [Trivy AWS plugin](https://github.com/aquasecurity/trivy-aws)) and normalize them into a standard structure, as defined by the schema. + +An example of such an application would be scanning AWS resources. You can scan them prior to deployment via the Trivy misconfiguration scanner and also +scan them after they've been deployed in the cloud with Trivy AWS scanning. Both scan methods should yield the same result as resources are gathered into +a unified representation as defined by the [Cloud schema](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/cloud.json). + + +## Supported Schemas +Currently out of the box the following schemas are supported natively: + +1. [Docker](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/dockerfile.json) +2. [Kubernetes](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/kubernetes.json) +3. [Cloud](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/cloud.json) + +You can interactively view these schemas with the [Trivy Schema Explorer](https://aquasecurity.github.io/trivy-schemas/) + + +## Example +As mentioned earlier, amongst other built-in schemas, Trivy offers a built in-schema for scanning Dockerfiles. It is available [here](https://github.com/aquasecurity/trivy/tree/main/pkg/iac/rego/schemas) +Without input schemas, a check would be as follows: !!! example ``` @@ -17,10 +43,10 @@ Without input schemas, a policy would be as follows: } ``` -If this policy is run against offending Dockerfile(s), there will not be any issues as the policy will fail to evaluate. -Although the policy's failure to evaluate is legitimate, this should not result in a positive result for the scan. +If this check is run against an offending Dockerfile(s), there will not be any issues as the check will fail to evaluate. +Although the check's failure to evaluate is legitimate, this should not result in a positive result for the scan. -For instance if we have a policy that checks for misconfigurations in a `Dockerfile`, we could define the +For instance if we have a check that checks for misconfigurations in a `Dockerfile`, we could define the schema as such !!! example @@ -38,26 +64,20 @@ schema as such Here `input: schema["dockerfile"]` points to a schema that expects a valid `Dockerfile` as input. An example of this can be found [here](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/dockerfile.json). -Now if this policy is evaluated against, a more descriptive error will be available to help fix the problem. +Now if this check is evaluated against, a more descriptive error will be available to help fix the problem. ```bash -1 error occurred: testpolicy.rego:8: rego_type_error: undefined ref: input.evil +1 error occurred: testcheck.rego:8: rego_type_error: undefined ref: input.evil input.evil ^ have: "evil" want (one of): ["Stages"] ``` -Currently, out of the box the following schemas are supported natively: - -1. [Docker](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/dockerfile.json) -2. [Kubernetes](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/kubernetes.json) -3. [Cloud](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/rego/schemas/cloud.json) - ## Custom Checks with Custom Schemas -You can also bring a custom policy that defines one or more custom schema. +You can also bring a custom check that defines one or more custom schema. !!! example ``` @@ -77,16 +97,83 @@ The checks can be placed in a structure as follows !!! example ``` /Users/user/my-custom-checks - ├── my_policy.rego + ├── my_check.rego └── schemas └── fooschema.json └── barschema.json ``` -To use such a policy with Trivy, use the `--config-policy` flag that points to the policy file or to the directory where the schemas and checks are contained. +To use such a check with Trivy, use the `--config-check` flag that points to the check file or to the directory where the schemas and checks are contained. ```bash -$ trivy --config-policy=/Users/user/my-custom-checks +$ trivy --config-check=/Users/user/my-custom-checks ``` -For more details on how to define schemas within Rego checks, please see the [OPA guide](https://www.openpolicyagent.org/docs/latest/policy-language/#schema-annotations) that describes it in more detail. \ No newline at end of file +For more details on how to define schemas within Rego checks, please see the [OPA guide](https://www.openpolicyagent.org/docs/latest/policy-language/#schema-annotations) that describes it in more detail. + +### Scan arbitrary JSON and YAML configurations +By default, scanning JSON and YAML configurations is disabled, since Trivy does not contain built-in checks for these configurations. To enable it, pass the `json` or `yaml` to `--misconfig-scanners`. Trivy will pass each file as is to the checks input. + + +!!! example +```bash +$ cat iac/serverless.yaml +service: serverless-rest-api-with-pynamodb + +frameworkVersion: ">=2.24.0" + +plugins: + - serverless-python-requirements +... + +$ cat serverless.rego +# METADATA +# title: Serverless Framework service name not starting with "aws-" +# description: Ensure that Serverless Framework service names start with "aws-" +# schemas: +# - input: schema["serverless-schema"] +# custom: +# id: SF001 +# severity: LOW +package user.serverless001 + +deny[res] { + not startswith(input.service, "aws-") + res := result.new( + sprintf("Service name %q is not allowed", [input.service]), + input.service + ) +} + +$ trivy config --misconfig-scanners=json,yaml --config-check ./serverless.rego --check-namespaces user ./iac +serverless.yaml (yaml) + +Tests: 4 (SUCCESSES: 3, FAILURES: 1) +Failures: 1 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 0, CRITICAL: 0) + +LOW: Service name "serverless-rest-api-with-pynamodb" is not allowed +═════════════════════════════════════════════════════════════════════════════════════════════════════════ +Ensure that Serverless Framework service names start with "aws-" +``` + +!!! note +In the case above, the custom check specified has a metadata annotation for the input schema `input: schema["serverless-schema"]`. This allows Trivy to type check the input IaC files provided. + +Optionally, you can also pass schemas using the `config-file-schemas` flag. Trivy will use these schemas for file filtering and type checking in Rego checks. + +!!! example +```bash +$ trivy config --misconfig-scanners=json,yaml --config-check ./serverless.rego --check-namespaces user --config-file-schemas ./serverless-schema.json ./iac +``` + +If the `--config-file-schemas` flag is specified Trivy ensures that each input IaC config file being scanned is type-checked against the schema. If the input file does not match any of the passed schemas, it will be ignored. + +If the schema is specified in the check metadata and is in the directory specified in the `--config-check` argument, it will be automatically loaded as specified [here](./custom/schema.md#custom-checks-with-custom-schemas), and will only be used for type checking in Rego. + +!!! note +If a user specifies the `--config-file-schemas` flag, all input IaC config files are ensured that they pass type-checking. It is not required to pass an input schema in case type checking is not required. This is helpful for scenarios where you simply want to write a Rego check and pass in IaC input for it. Such a use case could include scanning for a new service which Trivy might not support just yet. + +!!! tip +It is also possible to specify multiple input schemas with `--config-file-schema` flag as it can accept a comma seperated list of file paths or a directory as input. In the case of multiple schemas being specified, all of them will be evaluated against all the input files. + + diff --git a/docs/docs/scanner/misconfiguration/index.md b/docs/docs/scanner/misconfiguration/index.md index 4cd175cf58c3..556d48398c49 100644 --- a/docs/docs/scanner/misconfiguration/index.md +++ b/docs/docs/scanner/misconfiguration/index.md @@ -311,334 +311,4 @@ Tests: 20 (SUCCESSES: 18, FAILURES: 2) Failures: 2 (MEDIUM: 2, HIGH: 0, CRITICAL: 0) ``` -## Configuration -This section describes misconfiguration-specific configuration. -Other common options are documented [here](../../configuration/index.md). - -### External connectivity -Trivy needs to connect to the internet to download the checks bundle. If you are running Trivy in an air-gapped environment, or an tightly controlled network, please refer to the [Advanced Network Scenarios document](../../advanced/air-gap.md). - -### Enabling a subset of misconfiguration scanners -It's possible to only enable certain misconfiguration scanners if you prefer. -You can do so by passing the `--misconfig-scanners` option. -This flag takes a comma-separated list of configuration scanner types. - -```bash -trivy config --misconfig-scanners=terraform,dockerfile . -``` - -Will only scan for misconfigurations that pertain to Terraform and Dockerfiles. - -### Loading custom checks -You can load check files or directories including your custom checks using the `--config-check` flag. -This can be repeated for specifying multiple files or directories. - -```bash -trivy config --config-check custom-policy/policy --config-check combine/policy --config-check policy.rego --namespaces user myapp -``` - -You can load checks bundle as OCI Image from a Container Registry using the `--checks-bundle-repository` flag. - -```bash -trivy config --checks-bundle-repository myregistry.local/mychecks --namespaces user myapp -``` - - -### Scan arbitrary JSON and YAML configurations -By default, scanning JSON and YAML configurations is disabled, since Trivy does not contain built-in checks for these configurations. To enable it, pass the `json` or `yaml` to `--misconfig-scanners`. See [Enabling a subset of misconfiguration scanners](#enabling-a-subset-of-misconfiguration-scanners) for more information. Trivy will pass each file as is to the checks input. - - -!!! example -```bash -$ cat iac/serverless.yaml -service: serverless-rest-api-with-pynamodb - -frameworkVersion: ">=2.24.0" - -plugins: - - serverless-python-requirements -... - -$ cat serverless.rego -# METADATA -# title: Serverless Framework service name not starting with "aws-" -# description: Ensure that Serverless Framework service names start with "aws-" -# schemas: -# - input: schema["serverless-schema"] -# custom: -# id: SF001 -# severity: LOW -package user.serverless001 - -deny[res] { - not startswith(input.service, "aws-") - res := result.new( - sprintf("Service name %q is not allowed", [input.service]), - input.service - ) -} - -$ trivy config --misconfig-scanners=json,yaml --config-check ./serverless.rego --check-namespaces user ./iac -serverless.yaml (yaml) - -Tests: 4 (SUCCESSES: 3, FAILURES: 1) -Failures: 1 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 0, CRITICAL: 0) - -LOW: Service name "serverless-rest-api-with-pynamodb" is not allowed -═════════════════════════════════════════════════════════════════════════════════════════════════════════ -Ensure that Serverless Framework service names start with "aws-" -``` - -!!! note - In the case above, the custom check specified has a metadata annotation for the input schema `input: schema["serverless-schema"]`. This allows Trivy to type check the input IaC files provided. - -Optionally, you can also pass schemas using the `config-file-schemas` flag. Trivy will use these schemas for file filtering and type checking in Rego checks. - -!!! example -```bash -$ trivy config --misconfig-scanners=json,yaml --config-check ./serverless.rego --check-namespaces user --config-file-schemas ./serverless-schema.json ./iac -``` - -If the `--config-file-schemas` flag is specified Trivy ensures that each input IaC config file being scanned is type-checked against the schema. If the input file does not match any of the passed schemas, it will be ignored. - -If the schema is specified in the check metadata and is in the directory specified in the `--config-check` argument, it will be automatically loaded as specified [here](./custom/schema.md#custom-checks-with-custom-schemas), and will only be used for type checking in Rego. - -!!! note - If a user specifies the `--config-file-schemas` flag, all input IaC config files are ensured that they pass type-checking. It is not required to pass an input schema in case type checking is not required. This is helpful for scenarios where you simply want to write a Rego check and pass in IaC input for it. Such a use case could include scanning for a new service which Trivy might not support just yet. - -!!! tip - It is also possible to specify multiple input schemas with `--config-file-schema` flag as it can accept a comma seperated list of file paths or a directory as input. In the case of multiple schemas being specified, all of them will be evaluated against all the input files. - - -### Passing custom data -You can pass directories including your custom data through `--data` option. -This can be repeated for specifying multiple directories. - -```bash -cd examples/misconf/custom-data -trivy config --config-check ./my-check --data ./data --namespaces user ./configs -``` - -For more details, see [Custom Data](./custom/data.md). - -### Passing namespaces -By default, Trivy evaluates checks defined in `builtin.*`. -If you want to evaluate custom checks in other packages, you have to specify package prefixes through `--namespaces` option. -This can be repeated for specifying multiple packages. - -``` bash -trivy config --config-check ./my-check --namespaces main --namespaces user ./configs -``` - -### Private Terraform registries -Trivy can download Terraform code from private registries. -To pass credentials you must use the `TF_TOKEN_` environment variables. -You cannot use a `.terraformrc` or `terraform.rc` file, these are not supported by trivy yet. - -From the Terraform [docs](https://developer.hashicorp.com/terraform/cli/config/config-file#environment-variable-credentials): - -> Environment variable names should have the prefix TF_TOKEN_ added to the domain name, with periods encoded as underscores. -> For example, the value of a variable named `TF_TOKEN_app_terraform_io` will be used as a bearer authorization token when the CLI makes service requests to the hostname `app.terraform.io`. -> -> You must convert domain names containing non-ASCII characters to their punycode equivalent with an ACE prefix. -> For example, token credentials for `例えば.com` must be set in a variable called `TF_TOKEN_xn--r8j3dr99h_com`. -> -> Hyphens are also valid within host names but usually invalid as variable names and may be encoded as double underscores. -> For example, you can set a token for the domain name café.fr as TF_TOKEN_xn--caf-dma_fr or TF_TOKEN_xn____caf__dma_fr. - -If multiple variables evaluate to the same hostname, Trivy will choose the environment variable name where the dashes have not been encoded as double underscores. - - -### Skipping resources by inline comments - -Trivy supports ignoring misconfigured resources by inline comments for Terraform, CloudFormation and Helm configuration files only. - -In cases where Trivy can detect comments of a specific format immediately adjacent to resource definitions, it is possible to ignore findings from a single source of resource definition (in contrast to `.trivyignore`, which has a directory-wide scope on all of the files scanned). The format for these comments is `trivy:ignore:` immediately following the format-specific line-comment [token](https://developer.hashicorp.com/terraform/language/syntax/configuration#comments). - -The ignore rule must contain one of the possible check IDs that can be found in its metadata: ID, short code or alias. The `id` from the metadata is not case-sensitive, so you can specify, for example, `AVD-AWS-0089` or `avd-aws-0089`. - -For example, to ignore a misconfiguration ID `AVD-GCP-0051` in a Terraform HCL file: - -```terraform -#trivy:ignore:AVD-GCP-0051 -resource "google_container_cluster" "example" { - name = var.cluster_name - location = var.region -} -``` - -You can add multiple ignores on the same comment line: -```terraform -#trivy:ignore:AVD-GCP-0051 trivy:ignore:AVD-GCP-0053 -resource "google_container_cluster" "example" { - name = var.cluster_name - location = var.region -} -``` - -You can also specify a long ID, which is formed as follows: `--`. - -As an example, consider the following check metadata: - -```yaml -# custom: - # id: AVD-AWS-0089 - # avd_id: AVD-AWS-0089 - # provider: aws - # service: s3 - # severity: LOW - # short_code: enable-logging -``` - -Long ID would look like the following: `aws-s3-enable-logging`. - -Example for CloudFromation: -```yaml -AWSTemplateFormatVersion: "2010-09-09" -Resources: -#trivy:ignore:* - S3Bucket: - Type: 'AWS::S3::Bucket' - Properties: - BucketName: test-bucket -``` - -!!!note - Ignore rules for Helm files should be placed before the YAML object, since only it contains the location data needed for ignoring. - -Example for Helm: -```yaml - serviceAccountName: "testchart.serviceAccountName" - containers: - # trivy:ignore:KSV018 - - name: "testchart" - securityContext: - runAsUser: 1000 - runAsGroup: 3000 - image: "your-repository/your-image:your-tag" - imagePullPolicy: "Always" -``` - -#### Expiration Date - -You can specify the expiration date of the ignore rule in `yyyy-mm-dd` format. This is a useful feature when you want to make sure that an ignored issue is not forgotten and worth revisiting in the future. For example: -```tf -#trivy:ignore:aws-s3-enable-logging:exp:2024-03-10 -resource "aws_s3_bucket" "example" { - bucket = "test" -} -``` - -The `aws-s3-enable-logging` check will be ignored until `2024-03-10` until the ignore rule expires. - -#### Ignoring by attributes - -You can ignore a resource by its attribute value. This is useful when using the `for-each` meta-argument. For example: - -```tf -locals { - ports = ["3306", "5432"] -} - -#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306] -resource "aws_security_group_rule" "example" { - for_each = toset(local.ports) - type = "ingress" - from_port = each.key - to_port = each.key - protocol = "TCP" - cidr_blocks = ["0.0.0.0/0"] - security_group_id = aws_security_group.example.id - source_security_group_id = aws_security_group.example.id -} -``` - -The `aws-ec2-no-public-ingress-sgr` check will be ignored only for the `aws_security_group_rule` resource with port number `5432`. It is important to note that the ignore rule should not enclose the attribute value in quotes, despite the fact that the port is represented as a string. - -If you want to ignore multiple resources on different attributes, you can specify multiple ignore rules: - -```tf -#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306] -#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=5432] -``` - -You can also ignore a resource on multiple attributes in the same rule: -```tf -locals { - rules = { - first = { - port = 1000 - type = "ingress" - }, - second = { - port = 1000 - type = "egress" - } - } -} - -#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=1000,type=egress] -resource "aws_security_group_rule" "example" { - for_each = { for k, v in local.rules : k => v } - - type = each.value.type - from_port = each.value.port - to_port = each.value.port - protocol = "TCP" - cidr_blocks = ["0.0.0.0/0"] - security_group_id = aws_security_group.example.id - source_security_group_id = aws_security_group.example.id -} -``` - -Checks can also be ignored by nested attributes: - -```tf -#trivy:ignore:*[logging_config.prefix=myprefix] -resource "aws_cloudfront_distribution" "example" { - logging_config { - include_cookies = false - bucket = "mylogs.s3.amazonaws.com" - prefix = "myprefix" - } -} -``` - -#### Ignoring module issues - -Issues in third-party modules cannot be ignored using the method described above, because you may not have access to modify the module source code. In such a situation you can add ignore rules above the module block, for example: - -```tf -#trivy:ignore:aws-s3-enable-logging -module "s3_bucket" { - source = "terraform-aws-modules/s3-bucket/aws" - - bucket = "my-s3-bucket" -} -``` - -An example of ignoring checks for a specific bucket in a module: -```tf -locals { - bucket = ["test1", "test2"] -} - -#trivy:ignore:*[bucket=test1] -module "s3_bucket" { - for_each = toset(local.bucket) - source = "terraform-aws-modules/s3-bucket/aws" - bucket = each.value -} -``` - -#### Support for Wildcards - -You can use wildcards in the `ws` (workspace) and `ignore` sections of the ignore rules. - -```tf -# trivy:ignore:aws-s3-*:ws:dev-* -``` - -This example ignores all checks starting with `aws-s3-` for workspaces matching the pattern `dev-*`. - [custom]: custom/index.md diff --git a/mkdocs.yml b/mkdocs.yml index 00735e3c9680..e9756cb6405a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ nav: - Vulnerability: docs/scanner/vulnerability.md - Misconfiguration: - Overview: docs/scanner/misconfiguration/index.md + - Configuration: docs/scanner/misconfiguration/config/config.md - Policy: - Built-in Checks: docs/scanner/misconfiguration/check/builtin.md - Custom Checks: