docs(terraform): improve documentation for filtering by inline commen…

…ts (aquasecurity#6284)

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:<rule>` 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:<Vulnerability ID>` 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: `<provider>-<service>-<short-code>`.
+
+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