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

feat(vex): VEX Repository support (#7206)

Browse Source 
Signed-off-by: knqyf263 <knqyf263@gmail.com>
Co-authored-by: DmitriyLewen <91113035+DmitriyLewen@users.noreply.github.com>
This commit is contained in:
Teppei Fukuda
2024-07-25 16:18:37 +04:00
committed by GitHub
parent 174b1e3515
commit 88ba46047c
77 changed files with 3505 additions and 651 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/docs/configuration/cache.md
View File

@@ -1,10 +1,11 @@
# Cache
The cache directory includes
- Cache of previous scans (Scan cache).
- [Vulnerability Database][trivy-db][^1]
- [Java Index Database][trivy-java-db][^2]
- [Misconfiguration Checks][misconf-checks][^3]
- Cache of previous scans.
- [VEX Repositories](../supply-chain/vex/repo.md)
The cache option is common to all scanners.

2
docs/docs/configuration/filtering.md
View File

@@ -493,7 +493,7 @@ You can find more example checks [here](https://github.com/aquasecurity/trivy/tr
| Secret | |
| License | |
Please refer to the [VEX documentation](../supply-chain/vex.md) for the details.
Please refer to the [VEX documentation](../supply-chain/vex/index.md) for the details.
[^1]: license name is used as id for `.trivyignore.yaml` files.

1
docs/docs/references/configuration/cli/trivy.md
View File

@@ -56,5 +56,6 @@ trivy [global flags] command [flags] target
* [trivy sbom](trivy_sbom.md) - Scan SBOM for vulnerabilities and licenses
* [trivy server](trivy_server.md) - Server mode
* [trivy version](trivy_version.md) - Print the version
* [trivy vex](trivy_vex.md) - [EXPERIMENTAL] VEX utilities
* [trivy vm](trivy_vm.md) - [EXPERIMENTAL] Scan a virtual machine image

1
docs/docs/references/configuration/cli/trivy_clean.md
View File

@@ -28,6 +28,7 @@ trivy clean [flags]
-h, --help help for clean
--java-db remove Java database
--scan-cache remove scan cache (container and VM image analysis results)
--vex-repo remove VEX repositories
--vuln-db remove vulnerability database
```

3
docs/docs/references/configuration/cli/trivy_filesystem.md
View File

@@ -82,6 +82,7 @@ trivy filesystem [flags] PATH
--skip-dirs strings specify the directories or glob patterns to skip
--skip-files strings specify the files or glob patterns to skip
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
-t, --template string output template
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules
--tf-vars strings specify paths to override the Terraform tfvars files
@@ -89,7 +90,7 @@ trivy filesystem [flags] PATH
--token-header string specify a header name for token in client/server mode (default "Trivy-Token")
--trace enable more verbose trace output for custom queries
--username strings username. Comma-separated usernames allowed.
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

3
docs/docs/references/configuration/cli/trivy_image.md
View File

@@ -103,13 +103,14 @@ trivy image [flags] IMAGE_NAME
--skip-dirs strings specify the directories or glob patterns to skip
--skip-files strings specify the files or glob patterns to skip
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
-t, --template string output template
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules
--token string for authentication in client/server mode
--token-header string specify a header name for token in client/server mode (default "Trivy-Token")
--trace enable more verbose trace output for custom queries
--username strings username. Comma-separated usernames allowed.
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

3
docs/docs/references/configuration/cli/trivy_kubernetes.md
View File

@@ -98,12 +98,13 @@ trivy kubernetes [flags] [CONTEXT]
--skip-files strings specify the files or glob patterns to skip
--skip-images skip the downloading and scanning of images (vulnerabilities and secrets) in the cluster resources
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
-t, --template string output template
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules
--tolerations strings specify node-collector job tolerations (example: key1=value1:NoExecute,key2=value2:NoSchedule)
--trace enable more verbose trace output for custom queries
--username strings username. Comma-separated usernames allowed.
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

3
docs/docs/references/configuration/cli/trivy_repository.md
View File

@@ -81,6 +81,7 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
--skip-dirs strings specify the directories or glob patterns to skip
--skip-files strings specify the files or glob patterns to skip
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
--tag string pass the tag name to be scanned
-t, --template string output template
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules
@@ -89,7 +90,7 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
--token-header string specify a header name for token in client/server mode (default "Trivy-Token")
--trace enable more verbose trace output for custom queries
--username strings username. Comma-separated usernames allowed.
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

3
docs/docs/references/configuration/cli/trivy_rootfs.md
View File

@@ -83,6 +83,7 @@ trivy rootfs [flags] ROOTDIR
--skip-dirs strings specify the directories or glob patterns to skip
--skip-files strings specify the files or glob patterns to skip
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
-t, --template string output template
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules
--tf-vars strings specify paths to override the Terraform tfvars files
@@ -90,7 +91,7 @@ trivy rootfs [flags] ROOTDIR
--token-header string specify a header name for token in client/server mode (default "Trivy-Token")
--trace enable more verbose trace output for custom queries
--username strings username. Comma-separated usernames allowed.
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

3
docs/docs/references/configuration/cli/trivy_sbom.md
View File

@@ -58,10 +58,11 @@ trivy sbom [flags] SBOM_PATH
--skip-dirs strings specify the directories or glob patterns to skip
--skip-files strings specify the files or glob patterns to skip
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
-t, --template string output template
--token string for authentication in client/server mode
--token-header string specify a header name for token in client/server mode (default "Trivy-Token")
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

28
docs/docs/references/configuration/cli/trivy_vex.md Normal file
View File

@@ -0,0 +1,28 @@
## trivy vex
[EXPERIMENTAL] VEX utilities
### Options
```
-h, --help help for vex
```
### Options inherited from parent commands
```
--cache-dir string cache directory (default "/path/to/cache")
-c, --config string config path (default "trivy.yaml")
-d, --debug debug mode
--generate-default-config write the default config to trivy-default.yaml
--insecure allow insecure server connections
-q, --quiet suppress progress bar and log output
--timeout duration timeout (default 5m0s)
-v, --version show version
```
### SEE ALSO
* [trivy](trivy.md) - Unified security scanner
* [trivy vex repo](trivy_vex_repo.md) - Manage VEX repositories

44
docs/docs/references/configuration/cli/trivy_vex_repo.md Normal file
View File

@@ -0,0 +1,44 @@
## trivy vex repo
Manage VEX repositories
### Examples
```
# Initialize the configuration file
$ trivy vex repo init
# List VEX repositories
$ trivy vex repo list
# Download the VEX repositories
$ trivy vex repo download
```
### Options
```
-h, --help help for repo
```
### Options inherited from parent commands
```
--cache-dir string cache directory (default "/path/to/cache")
-c, --config string config path (default "trivy.yaml")
-d, --debug debug mode
--generate-default-config write the default config to trivy-default.yaml
--insecure allow insecure server connections
-q, --quiet suppress progress bar and log output
--timeout duration timeout (default 5m0s)
-v, --version show version
```
### SEE ALSO
* [trivy vex](trivy_vex.md) - [EXPERIMENTAL] VEX utilities
* [trivy vex repo download](trivy_vex_repo_download.md) - Download the VEX repositories
* [trivy vex repo init](trivy_vex_repo_init.md) - Initialize a configuration file
* [trivy vex repo list](trivy_vex_repo_list.md) - List VEX repositories

35
docs/docs/references/configuration/cli/trivy_vex_repo_download.md Normal file
View File

@@ -0,0 +1,35 @@
## trivy vex repo download
Download the VEX repositories
### Synopsis
Downloads enabled VEX repositories. If specific repository names are provided as arguments, only those repositories will be downloaded. Otherwise, all enabled repositories are downloaded.
```
trivy vex repo download [REPO_NAMES] [flags]
```
### Options
```
-h, --help help for download
```
### Options inherited from parent commands
```
--cache-dir string cache directory (default "/path/to/cache")
-c, --config string config path (default "trivy.yaml")
-d, --debug debug mode
--generate-default-config write the default config to trivy-default.yaml
--insecure allow insecure server connections
-q, --quiet suppress progress bar and log output
--timeout duration timeout (default 5m0s)
-v, --version show version
```
### SEE ALSO
* [trivy vex repo](trivy_vex_repo.md) - Manage VEX repositories

31
docs/docs/references/configuration/cli/trivy_vex_repo_init.md Normal file
View File

@@ -0,0 +1,31 @@
## trivy vex repo init
Initialize a configuration file
```
trivy vex repo init [flags]
```
### Options
```
-h, --help help for init
```
### Options inherited from parent commands
```
--cache-dir string cache directory (default "/path/to/cache")
-c, --config string config path (default "trivy.yaml")
-d, --debug debug mode
--generate-default-config write the default config to trivy-default.yaml
--insecure allow insecure server connections
-q, --quiet suppress progress bar and log output
--timeout duration timeout (default 5m0s)
-v, --version show version
```
### SEE ALSO
* [trivy vex repo](trivy_vex_repo.md) - Manage VEX repositories

31
docs/docs/references/configuration/cli/trivy_vex_repo_list.md Normal file
View File

@@ -0,0 +1,31 @@
## trivy vex repo list
List VEX repositories
```
trivy vex repo list [flags]
```
### Options
```
-h, --help help for list
```
### Options inherited from parent commands
```
--cache-dir string cache directory (default "/path/to/cache")
-c, --config string config path (default "trivy.yaml")
-d, --debug debug mode
--generate-default-config write the default config to trivy-default.yaml
--insecure allow insecure server connections
-q, --quiet suppress progress bar and log output
--timeout duration timeout (default 5m0s)
-v, --version show version
```
### SEE ALSO
* [trivy vex repo](trivy_vex_repo.md) - Manage VEX repositories

3
docs/docs/references/configuration/cli/trivy_vm.md
View File

@@ -72,11 +72,12 @@ trivy vm [flags] VM_IMAGE
--skip-dirs strings specify the directories or glob patterns to skip
--skip-files strings specify the files or glob patterns to skip
--skip-java-db-update skip updating Java index database
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
-t, --template string output template
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules
--token string for authentication in client/server mode
--token-header string specify a header name for token in client/server mode (default "Trivy-Token")
--vex string [EXPERIMENTAL] file path to VEX
--vex strings [EXPERIMENTAL] VEX sources ("repo" or file path)
```
### Options inherited from parent commands

8
docs/docs/supply-chain/vex.md → docs/docs/supply-chain/vex/file.md
View File

@@ -1,11 +1,11 @@
# Vulnerability Exploitability Exchange (VEX)
# Local VEX Files
!!! warning "EXPERIMENTAL"
This feature might change without preserving backwards compatibility.
Trivy supports filtering detected vulnerabilities using [the Vulnerability Exploitability Exchange (VEX)](https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf), a standardized format for sharing and exchanging information about vulnerabilities.
By providing VEX during scanning, it is possible to filter vulnerabilities based on their status.
Currently, Trivy supports the following three formats:
In addition to [VEX repositories](./repo.md), Trivy also supports the use of local VEX files for vulnerability filtering.
This method is useful when you have specific VEX documents that you want to apply to your scans.
Currently, Trivy supports the following formats:
- [CycloneDX](https://cyclonedx.org/capabilities/vex/)
- [OpenVEX](https://github.com/openvex/spec)

33
docs/docs/supply-chain/vex/index.md Normal file
View File

@@ -0,0 +1,33 @@
# Vulnerability Exploitability Exchange (VEX)
!!! warning "EXPERIMENTAL"
This feature might change without preserving backwards compatibility.
Trivy supports filtering detected vulnerabilities using the [Vulnerability Exploitability eXchange (VEX)](https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf), a standardized format for sharing and exchanging information about vulnerabilities.
By providing VEX during scanning, it is possible to filter vulnerabilities based on their status.
## VEX Usage Methods
Trivy currently supports two methods for utilizing VEX:
1. [VEX Repository](./repo.md)
2. [Local VEX Files](./file.md)
### Enabling VEX
To enable VEX, use the `--vex` option.
You can specify the method to use:
- To enable the VEX Repository: `--vex repo`
- To use a local VEX file: `--vex /path/to/vex-document.json`
```bash
$ trivy image ghcr.io/aquasecurity/trivy:0.52.0 --vex repo
```
You can enable both methods simultaneously.
The order of specification determines the priority:
- `--vex repo --vex /path/to/vex-document.json`: VEX Repository has priority
- `--vex /path/to/vex-document.json --vex repo`: Local file has priority
For detailed information on each method, please refer to each page.

210
docs/docs/supply-chain/vex/repo.md Normal file
View File

@@ -0,0 +1,210 @@
# VEX Repository
!!! warning "EXPERIMENTAL"
This feature might change without preserving backwards compatibility.
## Using VEX Repository
Trivy can download and utilize VEX documents from repositories that comply with [the VEX Repository Specification][vex-repo].
While it's planned to be enabled by default in the future, currently it can be activated by explicitly specifying `--vex repo`.
```
$ trivy image ghcr.io/aquasecurity/trivy:0.52.0 --vex repo
2024-07-20T11:22:58+04:00 INFO [vex] The default repository config has been created
file_path="/Users/teppei/.trivy/vex/repository.yaml"
2024-07-20T11:23:23+04:00 INFO [vex] Updating repository... repo="default" url="https://github.com/aquasecurity/vexhub"
```
During scanning, Trivy generates PURLs for discovered packages and searches for matching PURLs in the VEX Repository.
If a match is found, the corresponding VEX is utilized.
### Configuration File
#### Default Configuration
When `--vex repo` is specified for the first time, a default configuration file is created at `$HOME/.trivy/vex/repository.yaml`.
The home directory can be configured through environment variable `$XDG_DATA_HOME`.
You can also create the configuration file in advance using the `trivy vex repo init` command and edit it.
The default configuration file looks like this:
```yaml
repositories:
- name: default
url: https://github.com/aquasecurity/vexhub
enabled: true
username: ""
password: ""
token: ""
```
By default, [VEX Hub][vexhub] managed by Aqua Security is used.
VEX Hub primarily trusts VEX documents published by the package maintainers.
#### Show Configuration
You can see the config file path and the configured repositories with `trivy vex repo list`:
```bash
$ trivy vex repo list
VEX Repositories (config: /home/username/.trivy/vex/repository.yaml)
- Name: default
URL: https://github.com/aquasecurity/vexhub
Status: Enabled
```
#### Custom Repositories
If you want to trust VEX documents published by other organizations or use your own VEX repository, you can specify a custom repository that complies with [the VEX Repository Specification][vex-repo].
You can add a custom repository as below:
```yaml
- name: custom
url: https://example.com/custom-repo
enabled: true
```
#### Authentication
For private repositories:
- `username`/`password` can be used for Basic authentication
- `token` can be used for Bearer authentication
```yaml
- name: custom
url: https://example.com/custom-repo
enabled: true
token: "my-token"
```
#### Repository Priority
The priority of VEX repositories is determined by their order in the configuration file.
You can add repositories with higher priority than the default or even remove the default VEX Hub.
```yaml
- name: repo1
url: https://example.com/repo1
- name: repo2
url: https://example.com/repo2
```
In this configuration, when Trivy detects a vulnerability in a package, it generates a PURL for that package and searches for matching VEX documents in the configured repositories.
The search process follows this order:
1. Trivy first looks for a VEX document matching the package's PURL in `repo1`.
2. If no matching VEX document is found in `repo1`, Trivy then searches in `repo2`.
3. This process continues through all configured repositories until a match is found.
If a matching VEX document is found in any repository (e.g., `repo1`), the search stops, and Trivy uses that VEX document.
Subsequent repositories (e.g., `repo2`) are not checked for that specific vulnerability and package combination.
It's important to note that the first matching VEX document found determines the final status of the vulnerability.
For example, if `repo1` states that a package is "Affected" by a vulnerability, this status will be used even if `repo2` states that the same package is "Not Affected" for the same vulnerability.
The "Affected" status from the higher-priority repository (`repo1`) takes precedence, and Trivy will consider the package as affected by the vulnerability.
### Repository Updates
VEX repositories are automatically updated during scanning.
Updates are performed based on the update frequency specified by the repository.
To disable auto-update, pass `--skip-vex-repo-update`.
```shell
$ trivy image ghcr.io/aquasecurity/trivy:0.50.0 --vex repo --skip-vex-repo-update
```
To download VEX repositories in advance without scanning, use `trivy vex repo download`.
The cache can be cleared with `trivy clean --vex-repo`.
### Displaying Filtered Vulnerabilities
To see which vulnerabilities were filtered and why, use the `--show-suppressed` option:
```shell
$ trivy image ghcr.io/aquasecurity/trivy:0.50.0 --vex repo --show-suppressed
...
Suppressed Vulnerabilities (Total: 4)
=====================================
┌───────────────┬────────────────┬──────────┬──────────────┬───────────────────────────────────────────────────┬──────────────────────────────────────────┐
│ Library │ Vulnerability │ Severity │ Status │ Statement │ Source │
├───────────────┼────────────────┼──────────┼──────────────┼───────────────────────────────────────────────────┼──────────────────────────────────────────┤
│ busybox │ CVE-2023-42364 │ MEDIUM │ not_affected │ vulnerable_code_cannot_be_controlled_by_adversary │ VEX Repository: default │
│ │ │ │ │ │ (https://github.com/aquasecurity/vexhub) │
│ ├────────────────┤ │ │ │ │
│ │ CVE-2023-42365 │ │ │ │ │
│ │ │ │ │ │ │
├───────────────┼────────────────┤ │ │ │ │
│ busybox-binsh │ CVE-2023-42364 │ │ │ │ │
│ │ │ │ │ │ │
│ ├────────────────┤ │ │ │ │
│ │ CVE-2023-42365 │ │ │ │ │
│ │ │ │ │ │ │
└───────────────┴────────────────┴──────────┴──────────────┴───────────────────────────────────────────────────┴──────────────────────────────────────────┘
```
## Publishing VEX Documents
### For OSS Projects
As an OSS developer or maintainer, you may encounter vulnerabilities in the packages your project depends on.
These vulnerabilities might be discovered through your own scans or reported by third parties using your OSS project.
While Trivy strives to minimize false positives, it doesn't perform code graph analysis, which means it can't evaluate exploitability at the code level.
Consequently, Trivy may report vulnerabilities even in cases where:
1. The vulnerable function in a dependency is never called in your project.
2. The vulnerable code cannot be controlled by an attacker in the context of your project.
If you're confident that a reported vulnerability in a dependency doesn't affect your OSS project or container image, you can publish a VEX document to reduce noise in Trivy scans.
To assess exploitability, you have several options:
1. Manual assessment: As a maintainer, you can read the source code and determine if the vulnerability is exploitable in your project's context.
2. Automated assessment: You can use SAST (Static Application Security Testing) tools or similar tools to analyze the code and determine exploitability.
By publishing VEX documents in the source repository, Trivy can automatically utilize them through VEX Hub.
The main steps are:
1. Generate a VEX document
2. Commit the VEX document to the `.vex/` directory in the source repository (e.g., [Trivy's VEX][trivy-vex])
3. Register your project's [PURL][purl] in VEX Hub
Step 3 is only necessary once.
After that, updating the VEX file in your repository will automatically be fetched by VEX Hub and utilized by Trivy.
See the [VEX Hub repository][vexhub] for more information.
If you want to issue a VEX for an OSS project that you don't maintain, consider first proposing the VEX publication to the original repository.
Many OSS maintainers are open to contributions that improve the security posture of their projects.
However, if your proposal is not accepted, or if you want to issue a VEX with statements that differ from the maintainer's judgment, you may want to consider creating a [custom repository](#hosting-custom-repositories).
### For Private Projects
If you're working on private software or personal projects, you have several options:
1. [Local VEX files](./file.md): You can create local VEX files and have Trivy read them during scans. This is suitable for individual use or small teams.
2. [.trivyignore](../../configuration/filtering.md#trivyignore): For simpler cases, using a .trivyignore file might be sufficient to suppress specific vulnerabilities.
3. [Custom repositories](#hosting-custom-repositories): For large organizations wanting to share VEX information for internally used software across different departments, setting up a custom VEX repository might be the best approach.
## Hosting Custom Repositories
While the principle is to store VEX documents for OSS packages in the source repository, it's possible to create a custom repository if that's difficult.
There are various use cases for providing custom repositories:
- A Pull Request to add a VEX document upstream was not merged
- Consolidating VEX documents output by SAST tools
- Publishing vendor-specific VEX documents that differ from OSS maintainer statements
- Creating a private VEX repository to publish common VEX for your company
In these cases, you can create a repository that complies with [the VEX Repository Specification][vex-repo] to make it available for use with Trivy.
[vex-repo]: https://github.com/aquasecurity/vex-repo-spec
[vexhub]: https://github.com/aquasecurity/vexhub
[trivy-vex]: https://github.com/aquasecurity/trivy/blob/b76a7250912cfc028cfef743f0f98cd81b39f8aa/.vex/trivy.openvex.json
[purl]: https://github.com/package-url/purl-spec