gitea-mirror/trivy
1
0
Fork 0
mirror of https://github.com/aquasecurity/trivy.git synced 2025-12-20 22:33:53 -08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update custom rego policy docs to reflect latest defsec/fanal changes (#2267)

Browse Source 
Signed-off-by: Liam Galvin <liam.galvin@aquasec.com>
This commit is contained in:
Liam Galvin
2022-06-06 10:51:23 +01:00
committed by GitHub
parent a17c3eec2a
commit 3912768470
1 changed files with 47 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/docs/misconfiguration/custom/index.md
View File

@@ -14,26 +14,23 @@ As for `--namespaces` option, the detail is described as below.
If a file name matches the following file patterns, Trivy will parse the file and pass it as input to your Rego policy. If a file name matches the following file patterns, Trivy will parse the file and pass it as input to your Rego policy.
| File format | File pattern | | File format | File pattern |
| ------------- | --------------------------------------------------------- | |---------------|-----------------------------------------------------------|
| JSON | `*.json` | | JSON | `*.json` |
| YAML | `*.yaml` | | YAML | `*.yaml` and `*.yml` |
| TOML | `*.toml` |
| HCL | `*.hcl`, `*.hcl1`, and `*.hcl2` |
| Dockerfile | `Dockerfile`, `Dockerfile.*`, and `*.Dockerfile` | | Dockerfile | `Dockerfile`, `Dockerfile.*`, and `*.Dockerfile` |
| Containerfile | `Containerfile`, `Containerfile.*`, and `*.Containerfile` | | Containerfile | `Containerfile`, `Containerfile.*`, and `*.Containerfile` |
| Terraform | `*.tf` and `*.tf.json` |
### Configuration languages ### Configuration languages
In the above general file formats, Trivy automatically identifies the following types of configuration files: In the above general file formats, Trivy automatically identifies the following types of configuration files:
- Ansible (YAML)
- CloudFormation (JSON/YAML) - CloudFormation (JSON/YAML)
- Kubernetes (JSON/YAML) - Kubernetes (JSON/YAML)
- Helm (YAML)
- Terraform Plan (JSON)
This is useful for filtering inputs, as described below. This is useful for filtering inputs, as described below.
!!! warning
Custom policies do not support Terraform at the moment.
## Rego format ## Rego format
A single package must contain only one policy. A single package must contain only one policy.
@@ -41,11 +38,12 @@ A single package must contain only one policy.
``` rego ``` rego
package user.kubernetes.ID001 package user.kubernetes.ID001
import lib.result
__rego_metadata__ := { __rego_metadata__ := {
"id": "ID001", "id": "ID001",
"title": "Deployment not allowed", "title": "Deployment not allowed",
"severity": "LOW", "severity": "LOW",
"type": "Custom Kubernetes Check",
"description": "Deployments are not allowed because of some reasons.", "description": "Deployments are not allowed because of some reasons.",
} }
@@ -55,9 +53,10 @@ A single package must contain only one policy.
], ],
} }
deny[msg] { deny[res] {
input.kind == "Deployment" input.kind == "Deployment"
msg = sprintf("Found deployment '%s' but deployments are not allowed", [input.metadata.name]) msg := sprintf("Found deployment '%s' but deployments are not allowed", [input.metadata.name])
res := result.new(msg, input)
} }
``` ```
@@ -73,6 +72,9 @@ If you add a new custom policy, it must be defined under a new package like `use
- MAY include the group name such as `kubernetes` for clarity - MAY include the group name such as `kubernetes` for clarity
- Group name has no effect on policy evaluation - Group name has no effect on policy evaluation
`import data.lib.result` (optional)
: - MAY be defined if you would like to embellish your result(s) with line numbers and code highlighting
`__rego_metadata__` (optional) `__rego_metadata__` (optional)
: - SHOULD be defined for clarity since these values will be displayed in the scan results : - SHOULD be defined for clarity since these values will be displayed in the scan results
@@ -82,9 +84,11 @@ If you add a new custom policy, it must be defined under a new package like `use
`deny` (required) `deny` (required)
: - SHOULD be `deny` or start with `deny_` : - SHOULD be `deny` or start with `deny_`
- Although `warn`, `warn_*`, `violation`, `violation_` also work for compatibility, `deny` is recommended as severity can be defined in `__rego_metadata__`. - Although `warn`, `warn_*`, `violation`, `violation_` also work for compatibility, `deny` is recommended as severity can be defined in `__rego_metadata__`.
- SHOULD return `string` - SHOULD return ONE OF:
- Although `object` with `msg` field is accepted, other fields are dropped and `string` is recommended. - The result of a call to `result.new(msg, cause)`. The `msg` is a `string` describing the issue occurrence, and the `cause` is the property/object where the issue occurred. Providing this allows Trivy to ascertain line numbers and highlight code in the output.
- e.g. `{"msg": "deny message", "details": "something"}` - A `string` denoting the detected issue
- Although `object` with `msg` field is accepted, other fields are dropped and `string` is recommended if `result.new()` is not utilised.
- e.g. `{"msg": "deny message", "details": "something"}`
### Package ### Package
@@ -114,7 +118,6 @@ Metadata helps enrich Trivy's scan results with useful information.
"id": "ID001", "id": "ID001",
"title": "Deployment not allowed", "title": "Deployment not allowed",
"severity": "LOW", "severity": "LOW",
"type": "Custom Kubernetes Check",
"description": "Deployments are not allowed because of some reasons.", "description": "Deployments are not allowed because of some reasons.",
"recommended_actions": "Remove Deployment", "recommended_actions": "Remove Deployment",
"url": "https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-resource-requests-and-limits", "url": "https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-resource-requests-and-limits",
@@ -123,30 +126,33 @@ Metadata helps enrich Trivy's scan results with useful information.
All fields under `__rego_metadata__` are optional. All fields under `__rego_metadata__` are optional.
| Field name | Allowed values | Default value | In table | In JSON | | Field name | Allowed values | Default value | In table | In JSON |
| ------------------ | ------------------------------------| :-----------: | :----------------: |:---------------: | |---------------------|-------------------------------------|:-------------:|:----------------:|:----------------:|
| id | Any characters | N/A | :material-check: | :material-check: | | id | Any characters | N/A | :material-check: | :material-check: |
| title | Any characters | N/A | :material-check: | :material-check: | | title | Any characters | N/A | :material-check: | :material-check: |
| severity | `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` | UNKNOWN | :material-check: | :material-check: | | severity | `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` | UNKNOWN | :material-check: | :material-check: |
| type | Any characters | N/A | :material-check: | :material-check: | | description | Any characters | | :material-close: | :material-check: |
| description | Any characters | | :material-close: | :material-check: | | recommended_actions | Any characters | | :material-close: | :material-check: |
| recommended_actions| Any characters | | :material-close: | :material-check: | | url | Any characters | | :material-close: | :material-check: |
| url | Any characters | | :material-close: | :material-check: |
Some fields are displayed in scan results. Some fields are displayed in scan results.
``` bash ``` bash
deployment.yaml (kubernetes) k.yaml (kubernetes)
============================ ───────────────────
Tests: 28 (SUCCESSES: 14, FAILURES: 14, EXCEPTIONS: 0)
Failures: 14 (HIGH: 1)
+---------------------------+------------+-------------------------------------+----------+------------------------------------------+ Tests: 32 (SUCCESSES: 31, FAILURES: 1, EXCEPTIONS: 0)
| TYPE | MISCONF ID | CHECK | SEVERITY | MESSAGE | Failures: 1 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 0, CRITICAL: 0)
+---------------------------+------------+-------------------------------------+----------+------------------------------------------+
| Custom Kubernetes Check | ID001 | Deployment not allowed | LOW | Found deployment 'test' but deployments | LOW: Found deployment 'my-deployment' but deployments are not allowed
| | | | | are not allowed | ════════════════════════════════════════════════════════════════════════
+---------------------------+------------+-------------------------------------+----------+------------------------------------------+ Deployments are not allowed because of some reasons.
────────────────────────────────────────────────────────────────────────
k.yaml:1-2
────────────────────────────────────────────────────────────────────────
1 ┌ apiVersion: v1
2 └ kind: Deployment
────────────────────────────────────────────────────────────────────────
``` ```
### Input ### Input
@@ -164,21 +170,21 @@ All fields under `__rego_input` are optional.
``` ```
`combine` (boolean) `combine` (boolean)
: The details is [here](combine.md). : The details are [here](combine.md).
`selector` (array) `selector` (array)
: This option filters the input by file formats or configuration languages. : This option filters the input by file format or configuration language.
In the above example, Trivy passes only Kubernetes files to this policy. In the above example, Trivy passes only Kubernetes files to this policy.
Even if Dockerfile exists in the specified directory, it will not be passed to the policy as input. Even if a Dockerfile exists in the specified directory, it will not be passed to the policy as input.
When configuration language such as Kubernetes is not identified, file format such as JSON will be used as `type`. When configuration languages such as Kubernetes are not identified, file formats such as JSON will be used as `type`.
When configuration language is identified, it will overwrite `type`. When a configuration language is identified, it will overwrite `type`.
!!! example !!! example
`pod.yaml` including Kubernetes Pod will be handled as `kubernetes`, not `yaml`. `pod.yaml` including Kubernetes Pod will be handled as `kubernetes`, not `yaml`.
`type` is overwritten by `kubernetes` from `yaml`. `type` is overwritten by `kubernetes` from `yaml`.
`type` accepts `kubernetes`, `dockerfile`, `ansible`, `cloudformation`, `json`, `yaml`, `toml`, or `hcl`. `type` accepts `kubernetes`, `dockerfile`, `cloudformation`, `terraform`, `terraformplan`, `json`, or `yaml`.
[rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ [rego]: https://www.openpolicyagent.org/docs/latest/policy-language/
[package]: https://www.openpolicyagent.org/docs/latest/policy-language/#packages [package]: https://www.openpolicyagent.org/docs/latest/policy-language/#packages