From 71da44f7e14705678ceaecc6f651e3a867dd6811 Mon Sep 17 00:00:00 2001 From: Nikita Pivkin Date: Tue, 12 Mar 2024 17:49:07 +0300 Subject: [PATCH] docs(terraform): improve documentation for filtering by inline comments (#6284) --- docs/docs/scanner/misconfiguration/index.md | 138 ++++++++++++++++++-- 1 file changed, 127 insertions(+), 11 deletions(-) diff --git a/docs/docs/scanner/misconfiguration/index.md b/docs/docs/scanner/misconfiguration/index.md index 49cb97ef3636..b1107a530718 100644 --- a/docs/docs/scanner/misconfiguration/index.md +++ b/docs/docs/scanner/misconfiguration/index.md @@ -6,7 +6,7 @@ In addition to built-in policies, you can write your own custom policies, as you Simply specify a directory containing IaC files such as Terraform, CloudFormation, Azure ARM templates, Helm Charts and Dockerfile. -``` bash +```bash $ trivy config [YOUR_IaC_DIRECTORY] ``` @@ -365,7 +365,7 @@ 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: +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`. @@ -380,31 +380,147 @@ If multiple variables evaluate to the same hostname, Trivy will choose the envir ### Skipping resources by inline comments -Some configuration file formats (e.g. Terraform) support inline comments. -In cases where trivy can detect comments of a specific format immediately adjacent to resource definitions, it is possible to filter/ignore findings from a single point of resource definition (in contrast to `.trivyignore`, which has a directory-wide scope on all of the files scanned). +Trivy supports ignoring misconfigured resources by inline comments for Terraform 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 format for these comments is `trivy:ignore:` immediately following the format-specific line-comment token. -You can add multiple ignores on the same comment line. +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 filter a misconfiguration ID "AVD-GCP-0051" in a Terraform HCL file: +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" "one_off_test" { +resource "google_container_cluster" "example" { name = var.cluster_name location = var.region } ``` -For example, to filter misconfigurations "AVD-GCP-0051" and "AVD-GCP-0053" in a Terraform HCL file: - +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" "one_off_test" { +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`. + +#### 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: +```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 +} +``` + +!!! note + Currently nested attributes are not supported. For example you will not be able to reference the `each.key` attribute. + +#### 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 +} +``` [custom]: custom/index.md \ No newline at end of file