docs: restructure scanners (aquasecurity#3977)

Co-authored-by: DmitriyLewen <dmitriy.lewen@smartforce.io>
DmitriyLewen · Apr 17, 2023 · 57bb77c · 57bb77c
1 parent b19b56c
commit 57bb77c
Show file tree

Hide file tree

Showing 142 changed files with 1,743 additions and 5,298 deletions.
diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md
@@ -139,4 +139,4 @@ $ trivy conf --skip-policy-update /path/to/conf
 [allowlist]: ../references/troubleshooting.md
 [oras]: https://oras.land/cli/
 
-[^1]: This is only required to scan `jar` files. More information about `Java index db` [here](../vulnerability/languages/java.md)
+[^1]: This is only required to scan `jar` files. More information about `Java index db` [here](../scanner/vulnerability/language/java.md)
diff --git a/docs/docs/advanced/private-registries/index.md b/docs/docs/advanced/private-registries/index.md
@@ -18,7 +18,7 @@ $ TRIVY_PASSWORD=YOUR_PASSWORD trivy image --username YOUR_USERNAME YOUR_PRIVATE
     The CLI flag `--password` is available, but its use is not recommended for security reasons.
 
 You can also store your credentials in `trivy.yaml`.
-For more information, please refer to [the documentation](../../references/customization/config-file.md).
+For more information, please refer to [the documentation](../../references/configuration/config-file.md).
 
 It can handle multiple sets of credentials as well:
 

diff --git a/docs/docs/vulnerability/examples/cache.md → docs/docs/configuration/cache.md b/docs/docs/vulnerability/examples/cache.md → docs/docs/configuration/cache.md
@@ -1,5 +1,12 @@
 # Cache
-The cache directory includes [the vulnerability database][trivy-db], [the Java index database][trivy-java-db][^1], [misconfiguration policies][misconf-policies][^2] and cache of previous scans.
+The cache directory includes 
+
+- [Vulnerability Database][trivy-db][^1]
+- [Java Index Database][trivy-java-db][^2]
+- [Misconfiguration Policies][misconf-policies][^3]
+- Cache of previous scans.
+
+The cache option is common to all scanners.
 
 ## Clear Caches
 The `--clear-cache` option removes caches.
@@ -61,9 +68,10 @@ $ trivy server --cache-backend redis://localhost:6379 \
   --redis-key /path/to/key.pem
 ```
 
-[trivy-db]: ../db.md#vulnerability-database
-[trivy-java-db]: ../db.md#java-index-database
-[misconf-policies]: ../../misconfiguration/policy/builtin.md
+[trivy-db]: ./db.md#vulnerability-database
+[trivy-java-db]: ./db.md#java-index-database
+[misconf-policies]: ../scanner/misconfiguration/policy/builtin.md
 
-[^1]: The Java Index Database is downloaded for scanning `jar/war/par/ear` files.
-[^2]: Misconfiguration policies are downloaded for misconfiguration scanning.
+[^1]: Downloaded when scanning for vulnerabilities
+[^2]: Downloaded when scanning `jar/war/par/ear` files
+[^3]: Downloaded when scanning for misconfigurations
diff --git a/docs/docs/vulnerability/examples/db.md → docs/docs/configuration/db.md b/docs/docs/vulnerability/examples/db.md → docs/docs/configuration/db.md
@@ -1,6 +1,18 @@
-# Vulnerability DB
+# DB
 
-## Skip update of vulnerability DB
+|     Scanner      | Supported |
+|:----------------:|:---------:|
+|  Vulnerability   |     ✓     |
+| Misconfiguration |           |
+|      Secret      |           |
+|     License      |           |
+
+The vulnerability database and the Java index database are needed only for vulnerability scanning.
+See [here](../scanner/vulnerability/index.md) for the detail.
+
+## Vulnerability Database
+
+### Skip update of vulnerability DB
 If you want to skip downloading the vulnerability database, use the `--skip-db-update` option.
 
 ```
@@ -27,22 +39,22 @@ Total: 1 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 0, CRITICAL: 0)
 
 </details>
 
-## Only download vulnerability database
+### Only download vulnerability database
 You can also ask `Trivy` to simply retrieve the vulnerability database.
 This is useful to initialize workers in Continuous Integration systems.
 
 ```
 $ trivy image --download-db-only
 ```
 
-## DB Repository
+### DB Repository
 `Trivy` could also download the vulnerability database from an external OCI registry by using `--db-repository` option.
 
 ```
 $ trivy image --db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-db
 ```
 
-## Java Vulnerability DB
+## Java Index Database
 The same options are also available for the Java index DB, which is used for scanning Java applications.
 Skipping an update can be done by using the `--skip-java-db-update` option, while `--download-java-db-only` can be used to only download the Java index DB.
 
@@ -51,3 +63,10 @@ Downloading the Java index DB from an external OCI registry can be done by using
 ```
 $ trivy image --java-db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-java-db --download-java-db-only
 ```
+
+## Remove DBs
+The `--reset` flag removes all caches and databases.
+
+```
+$ trivy image --reset
+```
diff --git a/docs/docs/vulnerability/examples/filter.md → docs/docs/configuration/filtering.md b/docs/docs/vulnerability/examples/filter.md → docs/docs/configuration/filtering.md
diff --git a/docs/docs/configuration/index.md b/docs/docs/configuration/index.md
@@ -0,0 +1,31 @@
+# Configuration
+Trivy can be configured using the following ways. Each item takes precedence over the item below it:
+
+- CLI flags
+- Environment variables
+- Configuration file
+
+## CLI Flags
+You can view the list of available flags using the `--help` option.
+For more details, please refer to [the CLI reference](../references/configuration/cli/trivy.md).
+
+## Environment Variables
+Trivy can be customized by environment variables.
+The environment variable key is the flag name converted by the following procedure.
+
+- Add `TRIVY_` prefix
+- Make it all uppercase
+- Replace `-` with `_`
+
+For example,
+
+- `--debug` => `TRIVY_DEBUG`
+- `--cache-dir` => `TRIVY_CACHE_DIR`
+
+```
+$ TRIVY_DEBUG=true TRIVY_SEVERITY=CRITICAL trivy image alpine:3.15
+```
+
+## Configuration File
+By default, Trivy reads the `trivy.yaml` file.
+For more details, please refer to [the page](../references/configuration/config-file.md).
diff --git a/docs/docs/vulnerability/examples/others.md → docs/docs/configuration/others.md b/docs/docs/vulnerability/examples/others.md → docs/docs/configuration/others.md
@@ -1,8 +1,32 @@
 # Others
 
+## Enable/Disable Scanners
+You can enable/disable scanners with the `--scanners` flag.
+
+Supported values:
+
+- vuln
+- config
+- secret
+- license
+
+For example, container image scanning enables vulnerability and secret scanners by default.
+If you don't need secret scanning, it can be disabled.
+
+``` shell
+$ trivy image --scanners vuln alpine:3.15
+```
+
 ## Skip Files
-Trivy traversals directories and looks for all lock files by default.
-If your image contains lock files which are not maintained by you, you can skip the file.
+|     Scanner      | Supported |
+|:----------------:|:---------:|
+|  Vulnerability   |     ✓     |
+| Misconfiguration |     ✓     |
+|      Secret      |     ✓     |
+|     License      |     ✓     |
+
+By default, Trivy traverses directories and searches for all necessary files for scanning.
+You can skip files that you don't maintain using the `--skip-files` flag.
 
 ```
 $ trivy image --skip-files "/Gemfile.lock" --skip-files "/var/lib/gems/2.5.0/gems/http_parser.rb-0.6.0/Gemfile.lock" quay.io/fluentd_elasticsearch/fluentd:v2.9.0
@@ -17,8 +41,15 @@ $ trivy image --skip-files "./testdata/*/bar" .
 Will skip any file named `bar` in the subdirectories of testdata.
 
 ## Skip Directories
-Trivy traversals directories and look for all lock files by default.
-If your image contains lock files which are not maintained by you, you can skip traversal in the specific directory.
+|     Scanner      | Supported |
+|:----------------:|:---------:|
+|  Vulnerability   |     ✓     |
+| Misconfiguration |     ✓     |
+|      Secret      |     ✓     |
+|     License      |     ✓     |
+
+By default, Trivy traverses directories and searches for all necessary files for scanning.
+You can skip directories that you don't maintain using the `--skip-dirs` flag.
 
 ```
 $ trivy image --skip-dirs /var/lib/gems/2.5.0/gems/fluent-plugin-detect-exceptions-0.0.13 --skip-dirs "/var/lib/gems/2.5.0/gems/http_parser.rb-0.6.0" quay.io/fluentd_elasticsearch/fluentd:v2.9.0
@@ -46,8 +77,15 @@ $ trivy image --skip-files "**/foo"``` image:tag
 Will skip the file `foo` that happens to be nested under any parent(s). 
 
 ## File patterns
+|     Scanner      | Supported |
+|:----------------:|:---------:|
+|  Vulnerability   |     ✓     |
+| Misconfiguration |     ✓     |
+|      Secret      |           |
+|     License      |           |
+
 When a directory is given as an input, Trivy will recursively look for and test all files based on file patterns.
-The default file patterns are [here](../../misconfiguration/custom/index.md).
+The default file patterns are [here](../scanner/misconfiguration/custom/index.md).
 
 In addition to the default file patterns, the `--file-patterns` option takes regexp patterns to look for your files.
 For example, it may be useful when your file name of Dockerfile doesn't match the default patterns.
@@ -59,10 +97,17 @@ A file pattern contains the analyzer it is used for, and the pattern itself, joi
 --file-patterns "dockerfile:.*.docker" --file-patterns "yaml:deployment" --file-patterns "pip:requirements-.*\.txt"
 ```
 
-For more details, see [an example](https://github.com/aquasecurity/trivy/tree/{{ git.commit }}/examples/misconf/file-patterns)
+The prefixes are listed [here](https://github.com/aquasecurity/trivy/tree/{{ git.commit }}/pkg/fanal/analyzer/const.go)
 
 ## Exit Code
-By default, `Trivy` exits with code 0 even when vulnerabilities are detected.
+|     Scanner      | Supported |
+|:----------------:|:---------:|
+|  Vulnerability   |     ✓     |
+| Misconfiguration |     ✓     |
+|      Secret      |     ✓     |
+|     License      |     ✓     |
+
+By default, `Trivy` exits with code 0 even when security issues are detected.
 Use the `--exit-code` option if you want to exit with a non-zero exit code.
 
 ```
@@ -98,6 +143,13 @@ $ trivy image --exit-code 1 --severity CRITICAL ruby:2.4.0
 ```
 
 ## Exit on EOL
+|     Scanner      | Supported |
+|:----------------:|:---------:|
+|  Vulnerability   |     ✓     |
+| Misconfiguration |           |
+|      Secret      |           |
+|     License      |           |
+
 Sometimes you may surprisingly get 0 vulnerabilities in an old image:
 
 - Enabling `--ignore-unfixed` option while all packages have no fixed versions.
@@ -147,20 +199,3 @@ The following example will fail when a critical vulnerability is found or the OS
 ```
 $ trivy image --exit-code 1 --exit-on-eol 1 --severity CRITICAL alpine:3.16.3
 ```
-
-## Reset
-The `--reset` option removes all caches and database.
-After this, it takes a long time as the vulnerability database needs to be rebuilt locally.
-
-```
-$ trivy image --reset
-```
-
-<details>
-<summary>Result</summary>
-
-```
-2019-05-16T13:05:31.935+0900    INFO    Resetting...
-```
-
-</details>