Skip to content

Commit

Permalink
docs: improve filter by rego (#5402)
Browse files Browse the repository at this point in the history 
Signed-off-by: knqyf263 <knqyf263@gmail.com>
Co-authored-by: knqyf263 <knqyf263@gmail.com>
  • Loading branch information
@itaysk @knqyf263
itaysk and knqyf263 authored Jan 9, 2024
1 parent a626cdf commit 92d9b3d
Showing 1 changed file with 52 additions and 59 deletions.
111 changes: 52 additions & 59 deletions docs/docs/configuration/filtering.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -408,7 +408,7 @@ Total: 7 (UNKNOWN: 0, LOW: 1, MEDIUM: 1, HIGH: 3, CRITICAL: 2)
</details>
## By Open Policy Agent
## By Rego
| Scanner | Supported |
|:----------------:|:---------:|
Expand All @@ -420,75 +420,68 @@ Total: 7 (UNKNOWN: 0, LOW: 1, MEDIUM: 1, HIGH: 3, CRITICAL: 2)
!!! warning "EXPERIMENTAL"
This feature might change without preserving backwards compatibility.
Trivy supports Open Policy Agent (OPA) to filter vulnerabilities.
You can specify a Rego file with `--ignore-policy` option.
[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) is a policy language that allows you to express decision logic in a concise syntax.
Rego is part of the popular [Open Policy Agent (OPA)](https://www.openpolicyagent.org) CNCF project.
For advanced filtering, Trivy allows you to use Rego language to filter vulnerabilities.
The Rego package name must be `trivy` and it must include a rule called `ignore` which determines if each individual vulnerability should be excluded (ignore=true) or not (ignore=false). In the policy, each vulnerability will be available for inspection as the `input` variable. The structure of each vulnerability input is the same as for the Trivy JSON output.
There is a built-in Rego library with helper functions that you can import into your policy using: `import data.lib.trivy`. For more info about the helper functions, look at the library [here][helper]
Use the `--ignore-policy` flag which takes a path to a Rego file that defines the filtering policy.
The Rego package name must be `trivy` and it must include a "rule" named `ignore` which determines if each individual scan result should be excluded (ignore=true) or not (ignore=false).
The `input` for the evaluation is each [DetectedVulnerability](https://github.com/aquasecurity/trivy/blob/00f2059e5d7bc2ca2e3e8b1562bdfede1ed570e3/pkg/types/vulnerability.go#L9) and [DetectedMisconfiguration](https://github.com/aquasecurity/trivy/blob/00f2059e5d7bc2ca2e3e8b1562bdfede1ed570e3/pkg/types/misconfiguration.go#L6).
To get started, see the [example policy][policy].
A practical way to observe the filtering policy input in your case, is to run a scan with the `--format json` option and look at the resulting structure:
```bash
$ trivy image --ignore-policy contrib/example_policy/basic.rego centos:7
trivy image -f json centos:7
...
"Results": [
{
"Target": "centos:7 (centos 7.9.2009)",
"Class": "os-pkgs",
"Type": "centos",
"Vulnerabilities": [
{
"VulnerabilityID": "CVE-2015-5186",
"PkgID": "audit-libs@2.8.5-4.el7.x86_64",
"PkgName": "audit-libs",
"InstalledVersion": "2.8.5-4.el7",
"Layer": {
"Digest": "sha256:2d473b07cdd5f0912cd6f1a703352c82b512407db6b05b43f2553732b55df3bc",
"DiffID": "sha256:174f5685490326fc0a1c0f5570b8663732189b327007e47ff13d2ca59673db02"
},
"SeveritySource": "redhat",
"PrimaryURL": "https://avd.aquasec.com/nvd/cve-2015-5186",
"Title": "log terminal emulator escape sequences handling",
"Description": "Audit before 2.4.4 in Linux does not sanitize escape characters in filenames.",
"Severity": "MEDIUM",
"CweIDs": [
"CWE-20"
],
...
```
<details>
<summary>Result</summary>
Each individual vulnerability (under `Results.Vulnerabilities`) or Misconfiguration (under `Results.Misconfigurations`) is evaluated for exclusion or inclusion by the `ignore` rule.
The following is a Rego ignore policy that filters out every vulnerability with a specific CWE ID (as seen in the JSON example above):
```rego
package trivy
default ignore = false
ignore {
input.CweIDs[_] == "CWE-20"
}
```
```bash
centos:7 (centos 7.9.2009)
==========================
Total: 9 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 4, CRITICAL: 5)
+--------------+------------------+----------+-------------------+-------------------+-----------------------------------------+
| LIBRARY | VULNERABILITY ID | SEVERITY | INSTALLED VERSION | FIXED VERSION | TITLE |
+--------------+------------------+----------+-------------------+-------------------+-----------------------------------------+
| glib2 | CVE-2015-8385 | HIGH | 2.56.1-7.el7 | | pcre: buffer overflow caused |
| | | | | | by named forward reference |
| | | | | | to duplicate group number... |
| | | | | | -->avd.aquasec.com/nvd/cve-2015-8385 |
+ +------------------+ + +-------------------+-----------------------------------------+
| | CVE-2016-3191 | | | | pcre: workspace overflow for |
| | | | | | (*ACCEPT) with deeply nested |
| | | | | | parentheses (8.39/13, 10.22/12) |
| | | | | | -->avd.aquasec.com/nvd/cve-2016-3191 |
+ +------------------+ + +-------------------+-----------------------------------------+
| | CVE-2021-27219 | | | 2.56.1-9.el7_9 | glib: integer overflow in |
| | | | | | g_bytes_new function on |
| | | | | | 64-bit platforms due to an... |
| | | | | | -->avd.aquasec.com/nvd/cve-2021-27219 |
+--------------+------------------+----------+-------------------+-------------------+-----------------------------------------+
| glibc | CVE-2019-1010022 | CRITICAL | 2.17-317.el7 | | glibc: stack guard protection bypass |
| | | | | | -->avd.aquasec.com/nvd/cve-2019-1010022 |
+--------------+ + + +-------------------+ +
| glibc-common | | | | | |
| | | | | | |
+--------------+------------------+ +-------------------+-------------------+-----------------------------------------+
| nss | CVE-2021-43527 | | 3.53.1-3.el7_9 | 3.67.0-4.el7_9 | nss: Memory corruption in |
| | | | | | decodeECorDsaSignature with |
| | | | | | DSA signatures (and RSA-PSS) |
| | | | | | -->avd.aquasec.com/nvd/cve-2021-43527 |
+--------------+ + + + + +
| nss-sysinit | | | | | |
| | | | | | |
| | | | | | |
| | | | | | |
+--------------+ + + + + +
| nss-tools | | | | | |
| | | | | | |
| | | | | | |
| | | | | | |
+--------------+------------------+----------+-------------------+-------------------+-----------------------------------------+
| openssl-libs | CVE-2020-1971 | HIGH | 1:1.0.2k-19.el7 | 1:1.0.2k-21.el7_9 | openssl: EDIPARTYNAME |
| | | | | | NULL pointer de-reference |
| | | | | | -->avd.aquasec.com/nvd/cve-2020-1971 |
+--------------+------------------+----------+-------------------+-------------------+-----------------------------------------+
trivy image --ignore-policy contrib/example_policy/basic.rego centos:7
```
</details>
For more advanced use cases, there is a built-in Rego library with helper functions that you can import into your policy using: `import data.lib.trivy`.
More info about the helper functions are in the library [here](https://github.com/aquasecurity/trivy/tree/{{ git.tag }}/pkg/result/module.go).
[helper]: https://github.com/aquasecurity/trivy/tree/{{ git.tag }}/pkg/result/module.go
[policy]: https://github.com/aquasecurity/trivy/tree/{{ git.tag }}/contrib/example_policy
You can find more example policies [here](https://github.com/aquasecurity/trivy/tree/{{ git.tag }}/pkg/result/module.go)
## By Inline Comments
Expand Down

0 comments on commit 92d9b3d

Please sign in to comment.