docs: improve documentation for scanning raw IaC configurations (aquasecurity#9571)

nikpivkin · web-flow · commit 36712514ce16 · 2025-10-07T04:52:26.000Z
Signed-off-by: nikpivkin &lt;nikita.pivkin@smartforce.io&gt;
diff --git a/docs/docs/scanner/misconfiguration/custom/index.md b/docs/docs/scanner/misconfiguration/custom/index.md
@@ -121,18 +121,18 @@ Trivy supports extra fields in the `custom` section as described below.
 If you are creating checks for your Trivy misconfiguration scans, some fields are optional as referenced in the table below. The `schemas` field should be used to enable policy validation using a built-in schema. It is recommended to use this to ensure your checks are 
 correct and do not reference incorrect properties/values.
 
-| Field name                   | Allowed values                                                      |        Default value         | In table | In JSON |
-|------------------------------|---------------------------------------------------------------------|:----------------------------:|:--------:|:-------:|
-| title                        | Any characters                                                      |             N/A              |    ✅     |    ✅    |
-| description                  | Any characters                                                      |                              |    -     |    ✅    |
-| schemas.input                | `schema["kubernetes"]`, `schema["dockerfile"]`, `schema["cloud"]`   | (applied to all input types) |    -     |    -    |
-| custom.id                    | Any characters                                                      |             N/A              |    ✅     |    ✅    |
-| custom.severity              | `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`                                 |           UNKNOWN            |    ✅     |    ✅    |
-| custom.recommended_actions   | Any characters                                                      |                              |    -     |    ✅    |
-| custom.deprecated            | `true`, `false`                                                     |           `false`            |    -     |    ✅    |
-| custom.input.selector.type   | Any item(s) in [this list][source-types]                            |                              |    -     |    ✅    |
-| custom.minimum_trivy_version | The minimum version of Trivy that's required to evaluate this check |                              |    -     |    ✅    |
-| url                          | Any characters                                                      |                              |    -     |    ✅    |
+| Field name                   | Allowed values                                                                               |        Default value         | In table | In JSON |
+|------------------------------|----------------------------------------------------------------------------------------------|:----------------------------:|:--------:|:-------:|
+| title                        | Any characters                                                                               |             N/A              |    ✅     |    ✅    |
+| description                  | Any characters                                                                               |                              |    -     |    ✅    |
+| schemas.input                | `schema["kubernetes"]`, `schema["dockerfile"]`, `schema["cloud"]`, `schema["terraform-raw"]` | (applied to all input types) |    -     |    -    |
+| custom.id                    | Any characters                                                                               |             N/A              |    ✅     |    ✅    |
+| custom.severity              | `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`                                                          |           UNKNOWN            |    ✅     |    ✅    |
+| custom.recommended_actions   | Any characters                                                                               |                              |    -     |    ✅    |
+| custom.deprecated            | `true`, `false`                                                                              |           `false`            |    -     |    ✅    |
+| custom.input.selector.type   | Any item(s) in [this list][source-types]                                                     |                              |    -     |    ✅    |
+| custom.minimum_trivy_version | The minimum version of Trivy that's required to evaluate this check                          |                              |    -     |    ✅    |
+| url                          | Any characters                                                                               |                              |    -     |    ✅    |
 
 #### custom.avd_id and custom.id
 
@@ -224,4 +224,4 @@ See [here](schema.md) for the detail.
 
 [rego]: https://www.openpolicyagent.org/docs/latest/policy-language/
 [package]: https://www.openpolicyagent.org/docs/latest/policy-language/#packages
-[source-types]: https://github.com/aquasecurity/trivy/blob/9361cdb7e28fd304d6fd2a1091feac64a6786672/pkg/iac/types/sources.go#L4
+[source-types]: https://github.com/aquasecurity/trivy/blob/e4af279b29ed5b77ed1d62e31b232b1f9b92ef4f/pkg/iac/types/sources.go#L5-L17
diff --git a/docs/docs/scanner/misconfiguration/index.md b/docs/docs/scanner/misconfiguration/index.md
@@ -311,6 +311,100 @@ Tests: 20 (SUCCESSES: 18, FAILURES: 2)
 Failures: 2 (MEDIUM: 2, HIGH: 0, CRITICAL: 0)
 ```
 
+## Scan raw configurations
+IaC configurations from cloud providers such as Terraform, CloudFormation, and ARM are converted into a unified structure that is exported to Rego. Checks are developed only for the unified structure, not for each configuration type with its own structure. This avoids duplication and simplifies maintenance. Using the unified structure has a limitation: it is not possible to create checks for resources or attributes that are not exported.
+
+The `--raw-config-scanners` flag allows scanning the raw configuration — that is, evaluated but not converted into the unified structure. Currently, only `terraform` is supported.
+
+!!! note
+    The raw configuration scanner does not work on its own. To use `--raw-config-scanners`, you must also specify the corresponding `--misconfig-scanners`. The report will include results from both scanners.
+
+For more information on custom checks and exported data schemas, see [here](../misconfiguration/custom/index.md).
+
+Example check:
+```rego
+# METADATA
+# title: AWS required resource tags
+# description: Ensure required tags are set on AWS resources
+# scope: package
+# schemas:
+#   - input: schema["terraform-raw"]
+# custom:
+#   id:  USR-TFRAW-0001
+#   severity: CRITICAL
+#   short_code: required-aws-resource-tags
+#   recommended_actions: Add the required tags to AWS resources.
+#   input:
+#     selector:
+#     - type: terraform-raw
+package user.terraform.required_aws_tags
+
+import rego.v1
+
+resource_types_to_check := {"aws_s3_bucket"}
+
+resources_to_check := {block |
+	some module in input.modules
+	some block in module.blocks
+	block.kind == "resource"
+	block.type in resource_types_to_check
+}
+
+required_tags := {"Access", "Owner"}
+
+deny contains res if {
+	some block in resources_to_check
+	not block.attributes.tags
+	res := result.new(
+		sprintf("The resource %q does not contain the following required tags: %v", [block.type, required_tags]),
+		block,
+	)
+}
+
+deny contains res if {
+	some block in resources_to_check
+	tags_attr := block.attributes.tags
+	tags := object.keys(tags_attr.value)
+	missing_tags := required_tags - tags
+	count(missing_tags) > 0
+	res := result.new(
+		sprintf("The resource %q does not contain the following required tags: %v", [block.type, missing_tags]),
+		tags_attr,
+	)
+}
+```
+
+Running Trivy:
+```bash
+trivy conf main.tf \
+  --check-namespaces user \
+  --config-check examples/terraform-raw/required-aws-tags.rego \
+  --misconfig-scanners terraform --raw-config-scanners terraform
+```
+
+Example output:
+```bash
+main.tf (terraform)
+
+Tests: 10 (SUCCESSES: 0, FAILURES: 10)
+Failures: 10 (UNKNOWN: 0, LOW: 2, MEDIUM: 1, HIGH: 6, CRITICAL: 1)
+
+ (CRITICAL): The resource "aws_s3_bucket" does not contain the following required tags: {"Access"}
+═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+Ensure required tags are set on AWS resources
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ main.tf:3-5
+   via main.tf:1-6 (aws_s3_bucket.this)
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+   1   resource "aws_s3_bucket" "this" {
+   2     bucket = "test"
+   3 ┌   tags = {
+   4 │     Owner: "user"
+   5 └   }
+   6   }
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+```
+
 ## 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).
 
