Merge pull request #76 from AnaisUrlichs/docs-template

Docs template

.github/DISCUSSION_TEMPLATE/documentation.yml

@@ -0,0 +1,28 @@
+labels: ["kind/documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        #### Note
+        Feel free to create a docs report if something doesn't work as expected or is unclear in the documentation.
+        Please ensure that you're not creating a duplicate report by searching the [issues](https://github.com/aquasecurity/trivy/issues)/[discussions](https://github.com/aquasecurity/trivy/discussions) beforehand.
+        
+        Please also check [our contribution guidelines](https://aquasecurity.github.io/trivy/latest/community/contribute/discussion/).
+  - type: textarea
+    attributes:
+      label: Description
+      description: Briefly describe the what has been unclear in the existing documentation
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Link
+      description: Please provide a link to the current documentation or where you thought to find the information you were looking for
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Suggestions
+      description: What would you like to have added or changed in the documentation?
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -6,6 +6,9 @@ contact_links:
   - name: Report a bug
     url: https://github.com/aquasecurity/trivy/discussions/new?category=bugs
     about: Report bugs
+  - name: Enhance documentation
+    url: https://github.com/aquasecurity/trivy/discussions/new?category=documentation
+    about: Make suggestions to the documentation
   - name: Request a feature enhancement
     url: https://github.com/aquasecurity/trivy/discussions/new?category=ideas
     about: Share ideas for new features

README.md

@@ -103,11 +103,14 @@ trivy k8s --report summary cluster
 
 `tri` is pronounced like **tri**gger, `vy` is pronounced like en**vy**.
 
----
+## Community
 
 Trivy is an [Aqua Security][aquasec] open source project.  
 Learn about our open source work and portfolio [here][oss].  
 Contact us about any matter by opening a GitHub Discussion [here][discussions]
+Join our [Slack community][slack] to stay up to date with community efforts.
+
+Please ensure to abide by our [Code of Conduct][code-of-conduct] during all interactions.
 
 [test]: https://github.com/aquasecurity/trivy/actions/workflows/test.yaml
 [test-img]: https://github.com/aquasecurity/trivy/actions/workflows/test.yaml/badge.svg
@@ -122,6 +125,8 @@ Contact us about any matter by opening a GitHub Discussion [here][discussions]
 [homepage]: https://trivy.dev
 [docs]: https://aquasecurity.github.io/trivy
 [pronunciation]: #how-to-pronounce-the-name-trivy
+[slack]: https://slack.aquasec.com
+[code-of-conduct]: https://github.com/aquasecurity/community/blob/main/CODE_OF_CONDUCT.md
 
 [Installation]:https://aquasecurity.github.io/trivy/latest/getting-started/installation/
 [Ecosystem]: https://aquasecurity.github.io/trivy/latest/ecosystem/

docs/docs/configuration/reporting.md

@@ -1,5 +1,6 @@
 # Reporting
 
+## Supported Formats
 Trivy supports the following formats:
 
 - Table
@@ -8,7 +9,7 @@ Trivy supports the following formats:
 - Template
 - SBOM
 
-## Table (Default)
+### Table (Default)
 
 |     Scanner      | Supported |
 |:----------------:|:---------:|
@@ -21,7 +22,7 @@ Trivy supports the following formats:
 $ trivy image -f table golang:1.12-alpine
 ```
 
-### Show origins of vulnerable dependencies
+#### Show origins of vulnerable dependencies
 
 |     Scanner      | Supported |
 |:----------------:|:---------:|
@@ -105,7 +106,7 @@ Also, **glob-parent@3.1.0** with some vulnerabilities is included through chain
 
 Then, you can try to update **axios@0.21.4** and **cra-append-sw@2.7.0** to resolve vulnerabilities in **follow-redirects@1.14.6** and **glob-parent@3.1.0**.
 
-## JSON
+### JSON
 
 |     Scanner      | Supported |
 |:----------------:|:---------:|
@@ -239,7 +240,7 @@ $ trivy image -f json -o results.json golang:1.12-alpine
 
 `VulnerabilityID`, `PkgName`, `InstalledVersion`, and `Severity` in `Vulnerabilities` are always filled with values, but other fields might be empty.
 
-## SARIF
+### SARIF
 |     Scanner      | Supported |
 |:----------------:|:---------:|
 |  Vulnerability   |     ✓     |
@@ -255,7 +256,7 @@ $ trivy image --format sarif -o report.sarif  golang:1.12-alpine
 
 This SARIF file can be uploaded to GitHub code scanning results, and there is a [Trivy GitHub Action][action] for automating this process.
 
-## Template
+### Template
 
 |     Scanner      | Supported |
 |:----------------:|:---------:|
@@ -264,7 +265,7 @@ This SARIF file can be uploaded to GitHub code scanning results, and there is a
 |      Secret      |     ✓     |
 |     License      |     ✓     |
 
-### Custom Template
+#### Custom Template
 
 {% raw %}
 ```
@@ -301,18 +302,18 @@ Critical: 0, High: 2
 
 For other features of sprig, see the official [sprig][sprig] documentation.
 
-### Load templates from a file
+#### Load templates from a file
 You can load templates from a file prefixing the template path with an @.
 
 ```
 $ trivy image --format template --template "@/path/to/template" golang:1.12-alpine
 ```
 
-### Default Templates
+#### Default Templates
 
 If Trivy is installed using rpm then default templates can be found at `/usr/local/share/trivy/templates`.
 
-#### JUnit
+##### JUnit
 |     Scanner      | Supported |
 |:----------------:|:---------:|
 |  Vulnerability   |     ✓     |
@@ -325,7 +326,7 @@ In the following example using the template `junit.tpl` XML can be generated.
 $ trivy image --format template --template "@contrib/junit.tpl" -o junit-report.xml  golang:1.12-alpine
 ```
 
-#### ASFF
+##### ASFF
 |     Scanner      | Supported |
 |:----------------:|:---------:|
 |  Vulnerability   |     ✓     |
@@ -335,7 +336,7 @@ $ trivy image --format template --template "@contrib/junit.tpl" -o junit-report.
 
 Trivy also supports an [ASFF template for reporting findings to AWS Security Hub][asff]
 
-#### HTML
+##### HTML
 |     Scanner      | Supported |
 |:----------------:|:---------:|
 |  Vulnerability   |     ✓     |
@@ -353,9 +354,34 @@ The following example shows use of default HTML template when Trivy is installed
 $ trivy image --format template --template "@/usr/local/share/trivy/templates/html.tpl" -o report.html golang:1.12-alpine
 ```
 
-## SBOM
+### SBOM
 See [here](../supply-chain/sbom.md) for details.
 
+## Converting
+To generate multiple reports, you can generate the JSON report first and convert it to other formats with the `convert` subcommand.
+
+```shell
+$ trivy image --format json -o result.json --list-all-pkgs debian:11
+$ trivy convert --format cyclonedx --output result.cdx result.json
+```
+
+!!! note
+    Please note that if you want to convert to a format that requires a list of packages, 
+    such as SBOM, you need to add the `--list-all-pkgs` flag when outputting in JSON.
+
+[Filtering options](./filtering.md) such as `--severity` are also available with `convert`.
+
+```shell
+# Output all severities in JSON
+$ trivy image --format json -o result.json --list-all-pkgs debian:11
+
+# Output only critical issues in table format
+$ trivy convert --format table --severity CRITICAL result.json
+```
+
+!!! note
+    JSON reports from "trivy aws" and "trivy k8s" are not yet supported.
+
 [cargo-auditable]: https://github.com/rust-secure-code/cargo-auditable/
 [action]: https://github.com/aquasecurity/trivy-action
 [asff]: ../../tutorials/integrations/aws-security-hub.md

docs/docs/references/configuration/cli/trivy.md

@@ -45,6 +45,7 @@ trivy [global flags] command [flags] target
 
 * [trivy aws](trivy_aws.md)	 - [EXPERIMENTAL] Scan AWS account
 * [trivy config](trivy_config.md)	 - Scan config files for misconfigurations
+* [trivy convert](trivy_convert.md)	 - Convert Trivy JSON report into a different format
 * [trivy filesystem](trivy_filesystem.md)	 - Scan local filesystem
 * [trivy image](trivy_image.md)	 - Scan a container image
 * [trivy kubernetes](trivy_kubernetes.md)	 - [EXPERIMENTAL] Scan kubernetes cluster

docs/docs/references/configuration/cli/trivy_convert.md

@@ -0,0 +1,52 @@
+## trivy convert
+
+Convert Trivy JSON report into a different format
+
+```
+trivy convert [flags] RESULT_JSON
+```
+
+### Examples
+
+```
+  # report conversion
+  $ trivy image --format json --output result.json --list-all-pkgs debian:11
+  $ trivy convert --format cyclonedx --output result.cdx result.json
+
+```
+
+### Options
+
+```
+      --compliance string      compliance report to generate
+      --dependency-tree        [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --exit-code int          specify exit code when any security issues are found
+      --exit-on-eol int        exit with the specified code when the OS reaches end of service/life
+  -f, --format string          format (table, json, template, sarif, cyclonedx, spdx, spdx-json, github, cosign-vuln) (default "table")
+  -h, --help                   help for convert
+      --ignore-policy string   specify the Rego file path to evaluate each vulnerability
+      --ignorefile string      specify .trivyignore file (default ".trivyignore")
+      --list-all-pkgs          enabling the option will output all packages regardless of vulnerability
+  -o, --output string          output file name
+      --report string          specify a report format for the output. (all,summary) (default "all")
+  -s, --severity string        severities of security issues to be displayed (comma separated) (default "UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL")
+  -t, --template string        output template
+```
+
+### 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
+

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

@@ -40,6 +40,7 @@ trivy kubernetes [flags] { cluster | all | specific resources like kubectl. eg:
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan
+      --exclude-nodes strings             indicate the node labels that the node-collector job should exclude from scanning (example: kubernetes.io/arch:arm64,team:dev)
       --exit-code int                     specify exit code when any security issues are found
       --file-patterns strings             specify config file patterns
   -f, --format string                     format (table, json, template, sarif, cyclonedx, spdx, spdx-json, github, cosign-vuln) (default "table")

docs/docs/scanner/secret.md

@@ -95,6 +95,9 @@ Trivy tries to load `trivy-secret.yaml` in the current directory by default.
 If the file doesn't exist, only built-in rules are used.
 You can customize the config file path via the `--secret-config` flag.
 
+!!! warning
+    Trivy uses [Golang regexp package](https://pkg.go.dev/regexp/syntax#hdr-Syntax). To use `^` and `$` as simbols of begin and end of line use multi-line mode -`(?m)`.
+
 ### Custom Rules
 Trivy allows defining custom rules.
 

docs/docs/scanner/vulnerability/language/index.md

@@ -64,7 +64,7 @@ Example: [Dockerfile](https://github.com/aquasecurity/trivy-ci-test/blob/main/Do
 |          | [GitHub Advisory Database (npm)][nodejs-ghsa]       |       ✅        |     -     |
 | Java     | [GitLab Advisories Community][gitlab]               |       ✅        |  1 month  |
 |          | [GitHub Advisory Database (Maven)][java-ghsa]       |       ✅        |     -     |
-| Go       | [GitLab Advisories Community][gitlab]               |       ✅        |  1 month  |
+| Go       | [GitHub Advisory Database (Go)][go-ghsa]            |       ✅        |     -     |
 |          | [The Go Vulnerability Database][go]                 |       ✅        |     -     |
 | Rust     | [Open Source Vulnerabilities (crates.io)][rust-osv] |       ✅        |     -     |
 | .NET     | [GitHub Advisory Database (NuGet)][dotnet-ghsa]     |       ✅        |     -     |
@@ -82,6 +82,7 @@ Example: [Dockerfile](https://github.com/aquasecurity/trivy-ci-test/blob/main/Do
 [dotnet-ghsa]: https://github.com/advisories?query=ecosystem%3Anuget
 [pub-ghsa]: https://github.com/advisories?query=ecosystem%3Apub
 [erlang-ghsa]: https://github.com/advisories?query=ecosystem%3Aerlang
+[go-ghsa]: https://github.com/advisories?query=ecosystem%3Ago
 
 [php]: https://github.com/FriendsOfPHP/security-advisories
 [ruby]: https://github.com/rubysec/ruby-advisory-db

docs/docs/target/kubernetes.md

@@ -283,6 +283,12 @@ Or, to filter for all other checks besides the infra checks, you can:
 $ trivy k8s cluster --report summary --components=workload --scanners=config # scan all components besides infra
 ```
 
+If you wish to exclude nodes from being scanned, you can use the flag `--exclude-nodes` with the node labels
+
+```
+trivy k8s cluster --report summary --exclude-nodes kubernetes.io/arch:arm6
+```
+
 ### Compliance
 This section describes Kubernetes specific compliance reports.
 For an overview of Trivy's Compliance feature, including working with custom compliance, check out the [Compliance documentation](../compliance/compliance.md).

docs/getting-started/faq.md

@@ -3,3 +3,9 @@
 ### How to pronounce the name "Trivy"?
 
 `tri` is pronounced like **tri**gger, `vy` is pronounced like en**vy**.
+
+### How to generate multiple reports?
+See [here](../docs/configuration/reporting.md#converting).
+
+### How to run Trivy under air-gapped environment?
+See [here](../docs/advanced/air-gap.md).