Skip to content

Commit 5a0bf9e

Browse files
owenrumneyknqyf263itaysksimar7
authored
feat(cli): Add available version checking (#8553)
Signed-off-by: Owen Rumney <owen.rumney@aquasec.com> Co-authored-by: Teppei Fukuda <knqyf263@gmail.com> Co-authored-by: Itay <itay@itaysk.com> Co-authored-by: simar7 <1254783+simar7@users.noreply.github.com>
1 parent 7ca656d commit 5a0bf9e

20 files changed

+703
-10
lines changed

‎docs/docs/advanced/air-gap.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,8 @@ Trivy might attempt to connect (over HTTPS) to the following URLs:
7575
### Offline mode
7676

7777
There's no way to leverage Maven Central in a network-restricted environment, but you can prevent Trivy from trying to connect to it by using the `--offline-scan` flag.
78+
79+
## Check updates service
80+
81+
Trivy [checks for updates](../configuration/others.md#check-for-updates) and [collects usage telemetry](../advanced/telemetry.md) by connecting to the following domain: `https://check.trivy.dev`.
82+
Connectivity with this domain is entirely optional and is not necessary for the normal operation of Trivy.

‎docs/docs/advanced/telemetry.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Usage Telemetry
2+
3+
Trivy collect anonymous usage data in order to help us improve the product. This document explains what is collected and how you can control it.
4+
5+
## Data collected
6+
7+
The following information could be collected:
8+
9+
- Environmental information
10+
- Installation identifier
11+
- Trivy version
12+
- Operating system
13+
- Scan
14+
- Non-revealing scan options
15+
16+
## Privacy
17+
18+
No personal information, scan results, or sensitive data is specifically collected. We take the following measures to ensure that:
19+
20+
- Installation identifier: one-way hash of machine fingerprint, resulting in opaque string.
21+
- Scaner: any option that is user controlled is omitted (never collected). For example, file paths, image names, etc are never collected.
22+
23+
Trivy is an Aqua Security product and adheres to the company's privacy policy: <https://aquasec.com/privacy>.
24+
25+
## Disabling telemetry
26+
27+
You can disable telemetry altogether using the `--disable-telemetry` flag. Like other Trivy flags, this can be set on the command line, YAML configuration file, or environment variable. For more details see [here](../configuration/index.md).
28+
29+
For example:
30+
31+
```bash
32+
trivy image --disable-metrics alpine
33+
```

‎docs/docs/configuration/others.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,3 +160,14 @@ When we want to get the image `alpine` with the settings above. The logic will b
160160
1. Try to get the image from `mirror.with.bad.auth/library/alpine`, but we get an error because there are no credentials for this registry.
161161
2. Try to get the image from `mirror.without.image/library/alpine`, but we get an error because this registry doesn't have this image (but most likely it will be an error about authorization).
162162
3. Get the image from `index.docker.io` (the original registry).
163+
164+
## Check for updates
165+
166+
Trivy periodically checks for updates and notices, and displays a message to the user with recommendations.
167+
Updates checking is non-blocking and has no impact on scanning time, performance, results, or any user experience aspect besides displaying the message.
168+
You can disable updates checking by specifying the `--skip-version-check` flag.
169+
170+
## Telemetry
171+
172+
Trivy collected usage data for product improvement. More details in the [Telemetry document](../advanced/telemetry.md).
173+
You can disable telemetry collection using the `--disable-telemetry` flag.

‎docs/docs/references/configuration/cli/trivy_filesystem.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ trivy filesystem [flags] PATH
3535
- "precise": Prioritizes precise by minimizing false positives.
3636
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
3737
(allowed values: precise,comprehensive) (default "precise")
38+
--disable-telemetry disable sending anonymous usage data to Aqua
3839
--distro string [EXPERIMENTAL] specify a distribution, <family>/<version>
3940
--download-db-only download/update vulnerability database but don't run a scan
4041
--download-java-db-only download/update Java index database but don't run a scan
@@ -126,6 +127,7 @@ trivy filesystem [flags] PATH
126127
--skip-dirs strings specify the directories or glob patterns to skip
127128
--skip-files strings specify the files or glob patterns to skip
128129
--skip-java-db-update skip updating Java index database
130+
--skip-version-check suppress notices about version updates and Trivy announcements
129131
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
130132
--table-mode strings [EXPERIMENTAL] tables that will be displayed in 'table' format (allowed values: summary,detailed) (default [summary,detailed])
131133
-t, --template string output template

‎docs/docs/references/configuration/cli/trivy_image.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ trivy image [flags] IMAGE_NAME
4949
- "precise": Prioritizes precise by minimizing false positives.
5050
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
5151
(allowed values: precise,comprehensive) (default "precise")
52+
--disable-telemetry disable sending anonymous usage data to Aqua
5253
--distro string [EXPERIMENTAL] specify a distribution, <family>/<version>
5354
--docker-host string unix domain socket path to use for docker scanning
5455
--download-db-only download/update vulnerability database but don't run a scan
@@ -148,6 +149,7 @@ trivy image [flags] IMAGE_NAME
148149
--skip-dirs strings specify the directories or glob patterns to skip
149150
--skip-files strings specify the files or glob patterns to skip
150151
--skip-java-db-update skip updating Java index database
152+
--skip-version-check suppress notices about version updates and Trivy announcements
151153
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
152154
--table-mode strings [EXPERIMENTAL] tables that will be displayed in 'table' format (allowed values: summary,detailed) (default [summary,detailed])
153155
-t, --template string output template

‎docs/docs/references/configuration/cli/trivy_kubernetes.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ trivy kubernetes [flags] [CONTEXT]
5252
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
5353
(allowed values: precise,comprehensive) (default "precise")
5454
--disable-node-collector When the flag is activated, the node-collector job will not be executed, thus skipping misconfiguration findings on the node.
55+
--disable-telemetry disable sending anonymous usage data to Aqua
5556
--distro string [EXPERIMENTAL] specify a distribution, <family>/<version>
5657
--download-db-only download/update vulnerability database but don't run a scan
5758
--download-java-db-only download/update Java index database but don't run a scan
@@ -138,6 +139,7 @@ trivy kubernetes [flags] [CONTEXT]
138139
--skip-files strings specify the files or glob patterns to skip
139140
--skip-images skip the downloading and scanning of images (vulnerabilities and secrets) in the cluster resources
140141
--skip-java-db-update skip updating Java index database
142+
--skip-version-check suppress notices about version updates and Trivy announcements
141143
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
142144
-t, --template string output template
143145
--tf-exclude-downloaded-modules exclude misconfigurations for downloaded terraform modules

‎docs/docs/references/configuration/cli/trivy_repository.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
3535
- "precise": Prioritizes precise by minimizing false positives.
3636
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
3737
(allowed values: precise,comprehensive) (default "precise")
38+
--disable-telemetry disable sending anonymous usage data to Aqua
3839
--download-db-only download/update vulnerability database but don't run a scan
3940
--download-java-db-only download/update Java index database but don't run a scan
4041
--enable-modules strings [EXPERIMENTAL] module names to enable
@@ -124,6 +125,7 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
124125
--skip-dirs strings specify the directories or glob patterns to skip
125126
--skip-files strings specify the files or glob patterns to skip
126127
--skip-java-db-update skip updating Java index database
128+
--skip-version-check suppress notices about version updates and Trivy announcements
127129
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
128130
--table-mode strings [EXPERIMENTAL] tables that will be displayed in 'table' format (allowed values: summary,detailed) (default [summary,detailed])
129131
--tag string pass the tag name to be scanned

‎docs/docs/references/configuration/cli/trivy_rootfs.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ trivy rootfs [flags] ROOTDIR
3737
- "precise": Prioritizes precise by minimizing false positives.
3838
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
3939
(allowed values: precise,comprehensive) (default "precise")
40+
--disable-telemetry disable sending anonymous usage data to Aqua
4041
--distro string [EXPERIMENTAL] specify a distribution, <family>/<version>
4142
--download-db-only download/update vulnerability database but don't run a scan
4243
--download-java-db-only download/update Java index database but don't run a scan
@@ -127,6 +128,7 @@ trivy rootfs [flags] ROOTDIR
127128
--skip-dirs strings specify the directories or glob patterns to skip
128129
--skip-files strings specify the files or glob patterns to skip
129130
--skip-java-db-update skip updating Java index database
131+
--skip-version-check suppress notices about version updates and Trivy announcements
130132
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
131133
--table-mode strings [EXPERIMENTAL] tables that will be displayed in 'table' format (allowed values: summary,detailed) (default [summary,detailed])
132134
-t, --template string output template

‎docs/docs/references/configuration/cli/trivy_sbom.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ trivy sbom [flags] SBOM_PATH
2929
- "precise": Prioritizes precise by minimizing false positives.
3030
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
3131
(allowed values: precise,comprehensive) (default "precise")
32+
--disable-telemetry disable sending anonymous usage data to Aqua
3233
--distro string [EXPERIMENTAL] specify a distribution, <family>/<version>
3334
--download-db-only download/update vulnerability database but don't run a scan
3435
--download-java-db-only download/update Java index database but don't run a scan
@@ -99,6 +100,7 @@ trivy sbom [flags] SBOM_PATH
99100
--show-suppressed [EXPERIMENTAL] show suppressed vulnerabilities
100101
--skip-db-update skip updating vulnerability database
101102
--skip-java-db-update skip updating Java index database
103+
--skip-version-check suppress notices about version updates and Trivy announcements
102104
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
103105
--table-mode strings [EXPERIMENTAL] tables that will be displayed in 'table' format (allowed values: summary,detailed) (default [summary,detailed])
104106
-t, --template string output template

‎docs/docs/references/configuration/cli/trivy_vm.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ trivy vm [flags] VM_IMAGE
3333
- "precise": Prioritizes precise by minimizing false positives.
3434
- "comprehensive": Aims to detect more security findings at the cost of potential false positives.
3535
(allowed values: precise,comprehensive) (default "precise")
36+
--disable-telemetry disable sending anonymous usage data to Aqua
3637
--distro string [EXPERIMENTAL] specify a distribution, <family>/<version>
3738
--download-db-only download/update vulnerability database but don't run a scan
3839
--download-java-db-only download/update Java index database but don't run a scan
@@ -115,6 +116,7 @@ trivy vm [flags] VM_IMAGE
115116
--skip-dirs strings specify the directories or glob patterns to skip
116117
--skip-files strings specify the files or glob patterns to skip
117118
--skip-java-db-update skip updating Java index database
119+
--skip-version-check suppress notices about version updates and Trivy announcements
118120
--skip-vex-repo-update [EXPERIMENTAL] Skip VEX Repository update
119121
--table-mode strings [EXPERIMENTAL] tables that will be displayed in 'table' format (allowed values: summary,detailed) (default [summary,detailed])
120122
-t, --template string output template

‎docs/docs/references/configuration/config-file.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -586,6 +586,9 @@ scan:
586586
# Same as '--detection-priority'
587587
detection-priority: "precise"
588588

589+
# Same as '--disable-telemetry'
590+
disable-telemetry: false
591+
589592
# Same as '--distro'
590593
distro: ""
591594

@@ -615,6 +618,9 @@ scan:
615618
# Same as '--skip-files'
616619
skip-files: []
617620

621+
# Same as '--skip-version-check'
622+
skip-version-check: false
623+
618624
```
619625
## Secret options
620626

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ nav:
158158
- GCR (Google Container Registry): docs/advanced/private-registries/gcr.md
159159
- ACR (Azure Container Registry): docs/advanced/private-registries/acr.md
160160
- Self-Hosted: docs/advanced/private-registries/self.md
161+
- Usage Telemetry: docs/advanced/telemetry.md
161162
- References:
162163
- Configuration:
163164
- CLI:

‎pkg/commands/artifact/run.go

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import (
2626
"github.com/aquasecurity/trivy/pkg/log"
2727
"github.com/aquasecurity/trivy/pkg/misconf"
2828
"github.com/aquasecurity/trivy/pkg/module"
29+
"github.com/aquasecurity/trivy/pkg/notification"
2930
"github.com/aquasecurity/trivy/pkg/policy"
3031
pkgReport "github.com/aquasecurity/trivy/pkg/report"
3132
"github.com/aquasecurity/trivy/pkg/result"
@@ -92,6 +93,7 @@ type Runner interface {
9293

9394
type runner struct {
9495
initializeScanService InitializeScanService
96+
versionChecker *notification.VersionChecker
9597
dbOpen bool
9698

9799
// WASM modules
@@ -116,6 +118,13 @@ func NewRunner(ctx context.Context, cliOptions flag.Options, opts ...RunnerOptio
116118
opt(r)
117119
}
118120

121+
// If the user has not disabled notices or is running in quiet mode
122+
r.versionChecker = notification.NewVersionChecker(
123+
notification.WithSkipVersionCheck(cliOptions.SkipVersionCheck),
124+
notification.WithQuietMode(cliOptions.Quiet),
125+
notification.WithTelemetryDisabled(cliOptions.DisableTelemetry),
126+
)
127+
119128
// Update the vulnerability database if needed.
120129
if err := r.initDB(ctx, cliOptions); err != nil {
121130
return nil, xerrors.Errorf("DB error: %w", err)
@@ -137,6 +146,13 @@ func NewRunner(ctx context.Context, cliOptions flag.Options, opts ...RunnerOptio
137146
m.Register()
138147
r.module = m
139148

149+
// Make a silent attempt to check for updates in the background
150+
// only do this if the user has not disabled notices or is running
151+
// in quiet mode
152+
if r.versionChecker != nil {
153+
r.versionChecker.RunUpdateCheck(ctx, os.Args[1:])
154+
}
155+
140156
return r, nil
141157
}
142158

@@ -152,6 +168,12 @@ func (r *runner) Close(ctx context.Context) error {
152168
if err := r.module.Close(ctx); err != nil {
153169
errs = multierror.Append(errs, err)
154170
}
171+
172+
// silently check if there is notifications
173+
if r.versionChecker != nil {
174+
r.versionChecker.PrintNotices(os.Stderr)
175+
}
176+
155177
return errs
156178
}
157179

‎pkg/flag/scan_flags.go

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,16 @@ var (
118118
ConfigName: "scan.distro",
119119
Usage: "[EXPERIMENTAL] specify a distribution, <family>/<version>",
120120
}
121+
SkipVersionCheckFlag = Flag[bool]{
122+
Name: "skip-version-check",
123+
ConfigName: "scan.skip-version-check",
124+
Usage: "suppress notices about version updates and Trivy announcements",
125+
}
126+
DisableTelemetryFlag = Flag[bool]{
127+
Name: "disable-telemetry",
128+
ConfigName: "scan.disable-telemetry",
129+
Usage: "disable sending anonymous usage data to Aqua",
130+
}
121131
)
122132

123133
type ScanFlagGroup struct {
@@ -132,6 +142,8 @@ type ScanFlagGroup struct {
132142
RekorURL *Flag[string]
133143
DetectionPriority *Flag[string]
134144
DistroFlag *Flag[string]
145+
SkipVersionCheck *Flag[bool]
146+
DisableTelemetry *Flag[bool]
135147
}
136148

137149
type ScanOptions struct {
@@ -146,6 +158,8 @@ type ScanOptions struct {
146158
RekorURL string
147159
DetectionPriority ftypes.DetectionPriority
148160
Distro ftypes.OS
161+
SkipVersionCheck bool
162+
DisableTelemetry bool
149163
}
150164

151165
func NewScanFlagGroup() *ScanFlagGroup {
@@ -161,6 +175,8 @@ func NewScanFlagGroup() *ScanFlagGroup {
161175
Slow: SlowFlag.Clone(),
162176
DetectionPriority: DetectionPriority.Clone(),
163177
DistroFlag: DistroFlag.Clone(),
178+
SkipVersionCheck: SkipVersionCheckFlag.Clone(),
179+
DisableTelemetry: DisableTelemetryFlag.Clone(),
164180
}
165181
}
166182

@@ -181,6 +197,8 @@ func (f *ScanFlagGroup) Flags() []Flagger {
181197
f.RekorURL,
182198
f.DetectionPriority,
183199
f.DistroFlag,
200+
f.SkipVersionCheck,
201+
f.DisableTelemetry,
184202
}
185203
}
186204

@@ -220,6 +238,8 @@ func (f *ScanFlagGroup) ToOptions(opts *Options) error {
220238
RekorURL: f.RekorURL.Value(),
221239
DetectionPriority: ftypes.DetectionPriority(f.DetectionPriority.Value()),
222240
Distro: distro,
241+
SkipVersionCheck: f.SkipVersionCheck.Value(),
242+
DisableTelemetry: f.DisableTelemetry.Value(),
223243
}
224244
return nil
225245
}

‎pkg/flag/scan_flags_test.go

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@ import (
1414

1515
func TestScanFlagGroup_ToOptions(t *testing.T) {
1616
type fields struct {
17-
skipDirs []string
18-
skipFiles []string
19-
offlineScan bool
20-
scanners string
21-
distro string
17+
skipDirs []string
18+
skipFiles []string
19+
offlineScan bool
20+
scanners string
21+
distro string
22+
skipVersionCheck bool
2223
}
2324
tests := []struct {
2425
name string
@@ -127,6 +128,16 @@ func TestScanFlagGroup_ToOptions(t *testing.T) {
127128
},
128129
assertion: require.Error,
129130
},
131+
{
132+
name: "skip version check flag",
133+
fields: fields{
134+
skipVersionCheck: true,
135+
},
136+
want: flag.ScanOptions{
137+
SkipVersionCheck: true,
138+
},
139+
assertion: require.NoError,
140+
},
130141
}
131142

132143
for _, tt := range tests {
@@ -137,14 +148,16 @@ func TestScanFlagGroup_ToOptions(t *testing.T) {
137148
setValue(flag.OfflineScanFlag.ConfigName, tt.fields.offlineScan)
138149
setValue(flag.ScannersFlag.ConfigName, tt.fields.scanners)
139150
setValue(flag.DistroFlag.ConfigName, tt.fields.distro)
151+
setValue(flag.SkipVersionCheckFlag.ConfigName, tt.fields.skipVersionCheck)
140152

141153
// Assert options
142154
f := &flag.ScanFlagGroup{
143-
SkipDirs: flag.SkipDirsFlag.Clone(),
144-
SkipFiles: flag.SkipFilesFlag.Clone(),
145-
OfflineScan: flag.OfflineScanFlag.Clone(),
146-
Scanners: flag.ScannersFlag.Clone(),
147-
DistroFlag: flag.DistroFlag.Clone(),
155+
SkipDirs: flag.SkipDirsFlag.Clone(),
156+
SkipFiles: flag.SkipFilesFlag.Clone(),
157+
OfflineScan: flag.OfflineScanFlag.Clone(),
158+
Scanners: flag.ScannersFlag.Clone(),
159+
DistroFlag: flag.DistroFlag.Clone(),
160+
SkipVersionCheck: flag.SkipVersionCheckFlag.Clone(),
148161
}
149162

150163
flags := flag.Flags{f}

0 commit comments

Comments
 (0)