Skip to content

Commit 56345fd

Browse files
simar7simar7
committed
docs(misconf): Reorganize misconfiguration scan pages
1 parent bbc5a85 commit 56345fd

File tree

4 files changed

+321
-315
lines changed

4 files changed

+321
-315
lines changed

‎docs/docs/scanner/misconfiguration/config/config.md

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
This page describes misconfiguration-specific configuration.
2+
Other common options are documented [here](../../configuration/index.md).
3+
4+
### External connectivity
5+
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).
6+
7+
### Enabling a subset of misconfiguration scanners
8+
It's possible to only enable certain misconfiguration scanners if you prefer.
9+
You can do so by passing the `--misconfig-scanners` option.
10+
This flag takes a comma-separated list of configuration scanner types.
11+
12+
```bash
13+
trivy config --misconfig-scanners=terraform,dockerfile .
14+
```
15+
16+
Will only scan for misconfigurations that pertain to Terraform and Dockerfiles.
17+
18+
### Loading custom checks
19+
You can load check files or directories including your custom checks using the `--config-check` flag.
20+
This can be repeated for specifying multiple files or directories.
21+
22+
```bash
23+
trivy config --config-check custom-policy/policy --config-check combine/policy --config-check policy.rego --namespaces user myapp
24+
```
25+
26+
You can load checks bundle as OCI Image from a Container Registry using the `--checks-bundle-repository` flag.
27+
28+
```bash
29+
trivy config --checks-bundle-repository myregistry.local/mychecks --namespaces user myapp
30+
```
31+
32+
33+
### Passing custom data
34+
You can pass directories including your custom data through `--data` option.
35+
This can be repeated for specifying multiple directories.
36+
37+
```bash
38+
cd examples/misconf/custom-data
39+
trivy config --config-check ./my-check --data ./data --namespaces user ./configs
40+
```
41+
42+
For more details, see [Custom Data](./custom/data.md).
43+
44+
### Passing namespaces
45+
By default, Trivy evaluates checks defined in `builtin.*`.
46+
If you want to evaluate custom checks in other packages, you have to specify package prefixes through `--namespaces` option.
47+
This can be repeated for specifying multiple packages.
48+
49+
``` bash
50+
trivy config --config-check ./my-check --namespaces main --namespaces user ./configs
51+
```
52+
53+
### Private Terraform registries
54+
Trivy can download Terraform code from private registries.
55+
To pass credentials you must use the `TF_TOKEN_` environment variables.
56+
You cannot use a `.terraformrc` or `terraform.rc` file, these are not supported by trivy yet.
57+
58+
From the Terraform [docs](https://developer.hashicorp.com/terraform/cli/config/config-file#environment-variable-credentials):
59+
60+
> Environment variable names should have the prefix TF_TOKEN_ added to the domain name, with periods encoded as underscores.
61+
> 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`.
62+
>
63+
> You must convert domain names containing non-ASCII characters to their punycode equivalent with an ACE prefix.
64+
> For example, token credentials for `例えば.com` must be set in a variable called `TF_TOKEN_xn--r8j3dr99h_com`.
65+
>
66+
> Hyphens are also valid within host names but usually invalid as variable names and may be encoded as double underscores.
67+
> 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.
68+
69+
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.
70+
71+
72+
### Skipping resources by inline comments
73+
74+
Trivy supports ignoring misconfigured resources by inline comments for Terraform and CloudFormation configuration files only.
75+
76+
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).
77+
78+
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`.
79+
80+
For example, to ignore a misconfiguration ID `AVD-GCP-0051` in a Terraform HCL file:
81+
82+
```terraform
83+
#trivy:ignore:AVD-GCP-0051
84+
resource "google_container_cluster" "example" {
85+
name = var.cluster_name
86+
location = var.region
87+
}
88+
```
89+
90+
You can add multiple ignores on the same comment line:
91+
```terraform
92+
#trivy:ignore:AVD-GCP-0051 trivy:ignore:AVD-GCP-0053
93+
resource "google_container_cluster" "example" {
94+
name = var.cluster_name
95+
location = var.region
96+
}
97+
```
98+
99+
You can also specify a long ID, which is formed as follows: `<provider>-<service>-<short-code>`.
100+
101+
As an example, consider the following check metadata:
102+
103+
```yaml
104+
# custom:
105+
# id: AVD-AWS-0089
106+
# avd_id: AVD-AWS-0089
107+
# provider: aws
108+
# service: s3
109+
# severity: LOW
110+
# short_code: enable-logging
111+
```
112+
113+
Long ID would look like the following: `aws-s3-enable-logging`.
114+
115+
Example for CloudFromation:
116+
```yaml
117+
AWSTemplateFormatVersion: "2010-09-09"
118+
Resources:
119+
#trivy:ignore:*
120+
S3Bucket:
121+
Type: 'AWS::S3::Bucket'
122+
Properties:
123+
BucketName: test-bucket
124+
```
125+
126+
#### Expiration Date
127+
128+
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:
129+
```tf
130+
#trivy:ignore:aws-s3-enable-logging:exp:2024-03-10
131+
resource "aws_s3_bucket" "example" {
132+
bucket = "test"
133+
}
134+
```
135+
136+
The `aws-s3-enable-logging` check will be ignored until `2024-03-10` until the ignore rule expires.
137+
138+
#### Ignoring by attributes
139+
140+
You can ignore a resource by its attribute value. This is useful when using the `for-each` meta-argument. For example:
141+
142+
```tf
143+
locals {
144+
ports = ["3306", "5432"]
145+
}
146+
147+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306]
148+
resource "aws_security_group_rule" "example" {
149+
for_each = toset(local.ports)
150+
type = "ingress"
151+
from_port = each.key
152+
to_port = each.key
153+
protocol = "TCP"
154+
cidr_blocks = ["0.0.0.0/0"]
155+
security_group_id = aws_security_group.example.id
156+
source_security_group_id = aws_security_group.example.id
157+
}
158+
```
159+
160+
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.
161+
162+
If you want to ignore multiple resources on different attributes, you can specify multiple ignore rules:
163+
164+
```tf
165+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=3306]
166+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=5432]
167+
```
168+
169+
You can also ignore a resource on multiple attributes in the same rule:
170+
```tf
171+
locals {
172+
rules = {
173+
first = {
174+
port = 1000
175+
type = "ingress"
176+
},
177+
second = {
178+
port = 1000
179+
type = "egress"
180+
}
181+
}
182+
}
183+
184+
#trivy:ignore:aws-ec2-no-public-ingress-sgr[from_port=1000,type=egress]
185+
resource "aws_security_group_rule" "example" {
186+
for_each = { for k, v in local.rules : k => v }
187+
188+
type = each.value.type
189+
from_port = each.value.port
190+
to_port = each.value.port
191+
protocol = "TCP"
192+
cidr_blocks = ["0.0.0.0/0"]
193+
security_group_id = aws_security_group.example.id
194+
source_security_group_id = aws_security_group.example.id
195+
}
196+
```
197+
198+
Checks can also be ignored by nested attributes:
199+
200+
```tf
201+
#trivy:ignore:*[logging_config.prefix=myprefix]
202+
resource "aws_cloudfront_distribution" "example" {
203+
logging_config {
204+
include_cookies = false
205+
bucket = "mylogs.s3.amazonaws.com"
206+
prefix = "myprefix"
207+
}
208+
}
209+
```
210+
211+
#### Ignoring module issues
212+
213+
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:
214+
215+
```tf
216+
#trivy:ignore:aws-s3-enable-logging
217+
module "s3_bucket" {
218+
source = "terraform-aws-modules/s3-bucket/aws"
219+
220+
bucket = "my-s3-bucket"
221+
}
222+
```
223+
224+
An example of ignoring checks for a specific bucket in a module:
225+
```tf
226+
locals {
227+
bucket = ["test1", "test2"]
228+
}
229+
230+
#trivy:ignore:*[bucket=test1]
231+
module "s3_bucket" {
232+
for_each = toset(local.bucket)
233+
source = "terraform-aws-modules/s3-bucket/aws"
234+
bucket = each.value
235+
}
236+
```
237+
238+
#### Support for Wildcards
239+
240+
You can use wildcards in the `ws` (workspace) and `ignore` sections of the ignore rules.
241+
242+
```tf
243+
# trivy:ignore:aws-s3-*:ws:dev-*
244+
```
245+
246+
This example ignores all checks starting with `aws-s3-` for workspaces matching the pattern `dev-*`.
247+

‎docs/docs/scanner/misconfiguration/custom/schema.md

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# Input Schema
22

33
## Overview
4+
5+
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).
6+
7+
It is not required to pass in schemas, in order to scan inputs by Trivy but are required if type-checking is needed.
8+
49
Checks can be defined with custom schemas that allow inputs to be verified against them. Adding a policy schema
510
enables Trivy to show more detailed error messages when an invalid input is encountered.
611

@@ -89,4 +94,71 @@ To use such a policy with Trivy, use the `--config-policy` flag that points to t
8994
$ trivy --config-policy=/Users/user/my-custom-checks <path/to/iac>
9095
```
9196

92-
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.
97+
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.
98+
99+
### Scan arbitrary JSON and YAML configurations
100+
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.
101+
102+
103+
!!! example
104+
```bash
105+
$ cat iac/serverless.yaml
106+
service: serverless-rest-api-with-pynamodb
107+
108+
frameworkVersion: ">=2.24.0"
109+
110+
plugins:
111+
- serverless-python-requirements
112+
...
113+
114+
$ cat serverless.rego
115+
# METADATA
116+
# title: Serverless Framework service name not starting with "aws-"
117+
# description: Ensure that Serverless Framework service names start with "aws-"
118+
# schemas:
119+
# - input: schema["serverless-schema"]
120+
# custom:
121+
# id: SF001
122+
# severity: LOW
123+
package user.serverless001
124+
125+
deny[res] {
126+
not startswith(input.service, "aws-")
127+
res := result.new(
128+
sprintf("Service name %q is not allowed", [input.service]),
129+
input.service
130+
)
131+
}
132+
133+
$ trivy config --misconfig-scanners=json,yaml --config-check ./serverless.rego --check-namespaces user ./iac
134+
serverless.yaml (yaml)
135+
136+
Tests: 4 (SUCCESSES: 3, FAILURES: 1)
137+
Failures: 1 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 0, CRITICAL: 0)
138+
139+
LOW: Service name "serverless-rest-api-with-pynamodb" is not allowed
140+
═════════════════════════════════════════════════════════════════════════════════════════════════════════
141+
Ensure that Serverless Framework service names start with "aws-"
142+
```
143+
144+
!!! note
145+
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.
146+
147+
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.
148+
149+
!!! example
150+
```bash
151+
$ trivy config --misconfig-scanners=json,yaml --config-check ./serverless.rego --check-namespaces user --config-file-schemas ./serverless-schema.json ./iac
152+
```
153+
154+
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.
155+
156+
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.
157+
158+
!!! note
159+
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.
160+
161+
!!! tip
162+
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.
163+
164+

0 commit comments

Comments
 (0)