Skip to content

Commit 71da44f

Browse files
nikpivkinnikpivkin
authored
docs(terraform): improve documentation for filtering by inline comments (#6284)
1 parent 102b6df commit 71da44f

File tree

1 file changed

+127
-11
lines changed
  • docs/docs/scanner/misconfiguration

1 file changed

+127
-11
lines changed

‎docs/docs/scanner/misconfiguration/index.md

Lines changed: 127 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ In addition to built-in policies, you can write your own custom policies, as you
66

77
Simply specify a directory containing IaC files such as Terraform, CloudFormation, Azure ARM templates, Helm Charts and Dockerfile.
88

9-
``` bash
9+
```bash
1010
$ trivy config [YOUR_IaC_DIRECTORY]
1111
```
1212

@@ -365,7 +365,7 @@ Trivy can download terraform code from private registries.
365365
To pass credentials you must use the `TF_TOKEN_` environment variables.
366366
You cannot use a `.terraformrc` or `terraform.rc` file, these are not supported by trivy yet.
367367

368-
From the terraform docs:
368+
From the terraform [docs](https://developer.hashicorp.com/terraform/cli/config/config-file#environment-variable-credentials):
369369

370370
> Environment variable names should have the prefix TF_TOKEN_ added to the domain name, with periods encoded as underscores.
371371
> 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
380380

381381

382382
### Skipping resources by inline comments
383-
Some configuration file formats (e.g. Terraform) support inline comments.
384383

385-
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).
384+
Trivy supports ignoring misconfigured resources by inline comments for Terraform configuration files only.
385+
386+
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:<rule>` immediately following the format-specific line-comment [token](https://developer.hashicorp.com/terraform/language/syntax/configuration#comments).
386387

387-
The format for these comments is `trivy:ignore:<Vulnerability ID>` immediately following the format-specific line-comment token.
388-
You can add multiple ignores on the same comment line.
388+
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`.
389389

390-
For example, to filter a misconfiguration ID "AVD-GCP-0051" in a Terraform HCL file:
390+
For example, to ignore a misconfiguration ID `AVD-GCP-0051` in a Terraform HCL file:
391391

392392
```terraform
393393
#trivy:ignore:AVD-GCP-0051
394-
resource "google_container_cluster" "one_off_test" {
394+
resource "google_container_cluster" "example" {
395395
name = var.cluster_name
396396
location = var.region
397397
}
398398
```
399399

400-
For example, to filter misconfigurations "AVD-GCP-0051" and "AVD-GCP-0053" in a Terraform HCL file:
401-
400+
You can add multiple ignores on the same comment line:
402401
```terraform
403402
#trivy:ignore:AVD-GCP-0051 trivy:ignore:AVD-GCP-0053
404-
resource "google_container_cluster" "one_off_test" {
403+
resource "google_container_cluster" "example" {
405404
name = var.cluster_name
406405
location = var.region
407406
}
408407
```
409408

409+
You can also specify a long ID, which is formed as follows: `<provider>-<service>-<short-code>`.
410+
411+
As an example, consider the following check metadata:
412+
413+
```yaml
414+
# custom:
415+
# id: AVD-AWS-0089
416+
# avd_id: AVD-AWS-0089
417+
# provider: aws
418+
# service: s3
419+
# severity: LOW
420+
# short_code: enable-logging
421+
```
422+
423+
Long ID would look like the following: `aws-s3-enable-logging`.
424+
425+
#### Expiration Date
426+
427+
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:
428+
```tf
429+
#trivy:ignore:aws-s3-enable-logging:exp:2024-03-10
430+
resource "aws_s3_bucket" "example" {
431+
bucket = "test"
432+
}
433+
```
434+
435+
The `aws-s3-enable-logging` check will be ignored until `2024-03-10` until the ignore rule expires.
436+
437+
#### Ignoring by attributes
438+
439+
You can ignore a resource by its attribute value. This is useful when using the `for-each` meta-argument. For example:
440+
441+
```tf
442+
locals {
443+
ports = ["3306", "5432"]
444+
}
445+
446+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306]
447+
resource "aws_security_group_rule" "example" {
448+
for_each = toset(local.ports)
449+
type = "ingress"
450+
from_port = each.key
451+
to_port = each.key
452+
protocol = "TCP"
453+
cidr_blocks = ["0.0.0.0/0"]
454+
security_group_id = aws_security_group.example.id
455+
source_security_group_id = aws_security_group.example.id
456+
}
457+
```
458+
459+
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.
460+
461+
If you want to ignore multiple resources on different attributes, you can specify multiple ignore rules:
462+
463+
```tf
464+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306]
465+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=5432]
466+
```
467+
468+
You can also ignore a resource on multiple attributes:
469+
```tf
470+
locals {
471+
rules = {
472+
first = {
473+
port = 1000
474+
type = "ingress"
475+
},
476+
second = {
477+
port = 1000
478+
type = "egress"
479+
}
480+
}
481+
}
482+
483+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=1000,type=egress]
484+
resource "aws_security_group_rule" "example" {
485+
for_each = { for k, v in local.rules : k => v }
486+
487+
type = each.value.type
488+
from_port = each.value.port
489+
to_port = each.value.port
490+
protocol = "TCP"
491+
cidr_blocks = ["0.0.0.0/0"]
492+
security_group_id = aws_security_group.example.id
493+
source_security_group_id = aws_security_group.example.id
494+
}
495+
```
496+
497+
!!! note
498+
Currently nested attributes are not supported. For example you will not be able to reference the `each.key` attribute.
499+
500+
#### Ignoring module issues
501+
502+
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:
503+
504+
```tf
505+
#trivy:ignore:aws-s3-enable-logging
506+
module "s3_bucket" {
507+
source = "terraform-aws-modules/s3-bucket/aws"
508+
509+
bucket = "my-s3-bucket"
510+
}
511+
```
512+
513+
An example of ignoring checks for a specific bucket in a module:
514+
```tf
515+
locals {
516+
bucket = ["test1", "test2"]
517+
}
518+
519+
#trivy:ignore:*[bucket=test1]
520+
module "s3_bucket" {
521+
for_each = toset(local.bucket)
522+
source = "terraform-aws-modules/s3-bucket/aws"
523+
bucket = each.value
524+
}
525+
```
410526
[custom]: custom/index.md

0 commit comments

Comments
 (0)