docs: add misconfiguration (aquasecurity#1101)

Co-authored-by: Itay Shakury <[email protected]>

.github/workflows/mkdocs-dev.yaml

@@ -4,8 +4,8 @@ on:
     paths:
       - 'docs/**'
       - mkdocs.yml
-    branches:
-      - main
+        #    branches:
+        #      - main
 jobs:
   deploy:
     name: Deploy the dev documentation

.github/workflows/test.yaml

@@ -1,5 +1,14 @@
 name: Test
-on: pull_request
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '*.md'
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'LICENSE'
+  pull_request:
 env:
   GO_VERSION: "1.16"
 jobs:

README.md

@@ -1,88 +1,45 @@
-<img src="docs/imgs/logo.png" width="150">
+<p align="center">
+  <img src="docs/imgs/logo.png" width="200">
+</p>
 
+<p align="center">
+  <a href="https://aquasecurity.github.io/trivy/">Documentation</a> 
+</p>
+
+<p align="center">
+Scanner for vulnerabilities in container images, file systems, and Git repositories, as well as for configuration issues
+</p>
 
 [![GitHub Release][release-img]][release]
-[![Go Report Card](https://goreportcard.com/badge/github.com/aquasecurity/trivy)](https://goreportcard.com/report/github.com/aquasecurity/trivy)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)][license]
+[![Test][test-img]][test]
+[![Go Report Card][go-report-img]][go-report]
+[![License: Apache-2.0][license-img]][license]
 [![GitHub All Releases][github-all-releases-img]][release]
 ![Docker Pulls][docker-pulls]
 
-[release]: https://github.com/aquasecurity/trivy/releases
-[release-img]: https://img.shields.io/github/release/aquasecurity/trivy.svg?logo=github
-[github-all-releases-img]: https://img.shields.io/github/downloads/aquasecurity/trivy/total?logo=github
-[docker-pulls]: https://img.shields.io/docker/pulls/aquasec/trivy?logo=docker&label=docker%20pulls%20%2F%20trivy
-[license]: https://github.com/aquasecurity/trivy/blob/main/LICENSE
-
-
-A Simple and Comprehensive Vulnerability Scanner for Containers and other Artifacts, Suitable for CI.
 
 # Abstract
-`Trivy` (`tri` pronounced like **tri**gger, `vy` pronounced like en**vy**) is a simple and comprehensive vulnerability scanner for containers and other artifacts.
-A software vulnerability is a glitch, flaw, or weakness present in the software or in an Operating System.
-`Trivy` detects vulnerabilities of OS packages (Alpine, RHEL, CentOS, etc.) and application dependencies (Bundler, Composer, npm, yarn, etc.).
-`Trivy` is easy to use. Just install the binary and you're ready to scan. All you need to do for scanning is to specify a target such as an image name of the container.
-
-<img src="docs/imgs/overview.png" width="700">
-
-Trivy can be run in two different modes:
-
-- [Standalone](https://aquasecurity.github.io/trivy/latest/modes/standalone/)
-- [Client/Server](https://aquasecurity.github.io/trivy/latest/modes/client-server/)
-
-Trivy can scan three different artifacts:
-
-- [Container Images](https://aquasecurity.github.io/trivy/latest/scanning/image/)
-- [Filesystem](https://aquasecurity.github.io/trivy/latest/scanning/filesystem/)
-- [Git Repositories](https://aquasecurity.github.io/trivy/latest/scanning/git-repository/)
-
-<img src="docs/imgs/usage.gif" width="700">
-<img src="docs/imgs/usage1.png" width="600">
-<img src="docs/imgs/usage2.png" width="600">
-
-It is considered to be used in CI. Before pushing to a container registry or deploying your application, you can scan your local container image and other artifacts easily.
-See [here](https://aquasecurity.github.io/trivy/latest/integrations/) for details.
-
-# Features
-
-- Detect comprehensive vulnerabilities
-  - OS packages (Alpine, **Red Hat Universal Base Image**, Red Hat Enterprise Linux, CentOS, Oracle Linux, Debian, Ubuntu, Amazon Linux, openSUSE Leap, SUSE Enterprise Linux, Photon OS and Distroless)
-  - **Application dependencies** (Bundler, Composer, Pipenv, Poetry, npm, yarn, Cargo, NuGet, Maven, and Go)
-- Simple
-  - Specify only an image name or artifact name
-  - See [Quick Start](#quick-start) and [Examples](#examples)
-- Fast
-  - The first scan will finish within 10 seconds (depending on your network). Consequent scans will finish in single seconds.
-  - Unlike other scanners that take long to fetch vulnerability information (~10 minutes) on the first run, and encourage you to maintain a durable vulnerability database, Trivy is stateless and requires no maintenance or preparation.
-- Easy installation
-  - `apt-get install`, `yum install` and `brew install` is possible (See [Installation](#installation))
-  - **No pre-requisites** such as installation of DB, libraries, etc.
-- High accuracy
-  - **Especially Alpine Linux and RHEL/CentOS**
-  - Other OSes are also high
-- DevSecOps
-  - **Suitable for CI** such as Travis CI, CircleCI, Jenkins, GitLab CI, etc.
-  - See [CI Example](#continuous-integration-ci)
-- Support multiple formats
-  - container image
-    - A local image in Docker Engine which is running as a daemon
-    - A local image in Podman (>=2.0) which is exposing a socket
-    - A remote image in Docker Registry such as Docker Hub, ECR, GCR and ACR
-    - A tar archive stored in the `docker save` / `podman save` formatted file
-    - An image directory compliant with [OCI Image Format](https://github.com/opencontainers/image-spec)
-  - local filesystem
-  - remote git repository
-
-Please see [LICENSE][license] for Trivy licensing information. Note that Trivy uses vulnerability information from a variety of sources, some of which are licensed for non-commercial use only.
+`Trivy` (`tri` pronounced like **tri**gger, `vy` pronounced like en**vy**) is a simple and comprehensive scanner for vulnerabilities in container images, file systems, and Git repositories, as well as for configuration issues.
+`Trivy` detects vulnerabilities of OS packages (Alpine, RHEL, CentOS, etc.) and language-specific packages (Bundler, Composer, npm, yarn, etc.).
+In addition, `Trivy` scans Infrastructure as Code (IaC) files such as Terraform, Dockerfile and Kubernetes, to detect potential configuration issues that expose your deployments to the risk of attack.
+`Trivy` is easy to use. Just install the binary and you're ready to scan.
 
-# Documentation
-The official documentation, which provides detailed installation, configuration, and quick start guides, is available at https://aquasecurity.github.io/trivy/.
+<p align="center">
+  <img src="docs/imgs/overview.png" width="800" alt="Trivy Overview">
+</p>
 
-# Installation
-See [here](https://aquasecurity.github.io/trivy/latest/installation/)
+### Demo: Vulnerability Detection (Container Image)
+<p align="center">
+  <img src="docs/imgs/vuln-demo.gif" width="1000" alt="Vulnerability Detection">
+</p>
 
+### Demo: Misconfiguration Detection (IaC Files)
+<p align="center">
+  <img src="docs/imgs/misconf-demo.gif" width="1000" alt="Misconfiguration Detection">
+</p>
 
 # Quick Start
-
+## Scan Image for Vulnerabilities
 Simply specify an image name (and a tag).
 
 ```
@@ -113,21 +70,140 @@ Total: 1 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 0, CRITICAL: 0)
 |         |                  |          |                   |               | with long nonces               |
 +---------+------------------+----------+-------------------+---------------+--------------------------------+
 ```
+</details>
+
+## Scan Filesystem for Vulnerabilities and Misconfigurations
+Simply specify a directory to scan.
+
+```bash
+$ trivy fs --security-checks vuln,config [YOUR_PROJECT_DIR]
+```
+
+For example:
+
+```bash
+$ trivy fs --security-checks vuln,config myproject/
+```
+
+<details>
+<summary>Result</summary>
+
+```bash
+2021-07-09T12:03:27.564+0300    INFO    Number of language-specific files: 1
+2021-07-09T12:03:27.564+0300    INFO    Detecting pipenv vulnerabilities...
+2021-07-09T12:03:27.566+0300    INFO    Detected config files: 1
+
+Pipfile.lock (pipenv)
+=====================
+Total: 1 (HIGH: 1, CRITICAL: 0)
+
++----------+------------------+----------+-------------------+---------------+---------------------------------------+
+| LIBRARY  | VULNERABILITY ID | SEVERITY | INSTALLED VERSION | FIXED VERSION |                 TITLE                 |
++----------+------------------+----------+-------------------+---------------+---------------------------------------+
+| httplib2 | CVE-2021-21240   | HIGH     | 0.12.1            | 0.19.0        | python-httplib2: Regular              |
+|          |                  |          |                   |               | expression denial of                  |
+|          |                  |          |                   |               | service via malicious header          |
+|          |                  |          |                   |               | -->avd.aquasec.com/nvd/cve-2021-21240 |
++----------+------------------+----------+-------------------+---------------+---------------------------------------+
+
+Dockerfile (dockerfile)
+=======================
+Tests: 23 (SUCCESSES: 22, FAILURES: 1, EXCEPTIONS: 0)
+Failures: 1 (HIGH: 1, CRITICAL: 0)
+
++---------------------------+------------+----------------------+----------+------------------------------------------+
+|           TYPE            | MISCONF ID |        CHECK         | SEVERITY |                 MESSAGE                  |
++---------------------------+------------+----------------------+----------+------------------------------------------+
+| Dockerfile Security Check |   DS002    | Image user is 'root' |   HIGH   | Last USER command in                     |
+|                           |            |                      |          | Dockerfile should not be 'root'          |
+|                           |            |                      |          | -->avd.aquasec.com/appshield/ds002       |
++---------------------------+------------+----------------------+----------+------------------------------------------+
+```
+</details>
+
+## Scan Directory for Misconfigurations
+
+Simply specify a directory containing IaC files such as Terraform and Dockerfile.
+
+```
+$ trivy config [YOUR_IAC_DIR]
+```
+
+For example:
+
+```
+$ ls build/
+Dockerfile
+$ trivy config ./build
+```
+
+<details>
+<summary>Result</summary>
+
+```
+2021-07-09T10:06:29.188+0300    INFO    Need to update the built-in policies
+2021-07-09T10:06:29.188+0300    INFO    Downloading the built-in policies...
+2021-07-09T10:06:30.520+0300    INFO    Detected config files: 1
+
+Dockerfile (dockerfile)
+=======================
+Tests: 23 (SUCCESSES: 22, FAILURES: 1, EXCEPTIONS: 0)
+Failures: 1 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 1, CRITICAL: 0)
+
++---------------------------+------------+----------------------+----------+------------------------------------------+
+|           TYPE            | MISCONF ID |        CHECK         | SEVERITY |                 MESSAGE                  |
++---------------------------+------------+----------------------+----------+------------------------------------------+
+| Dockerfile Security Check |   DS002    | Image user is 'root' |   HIGH   | Last USER command in                     |
+|                           |            |                      |          | Dockerfile should not be 'root'          |
+|                           |            |                      |          | -->avd.aquasec.com/appshield/ds002       |
++---------------------------+------------+----------------------+----------+------------------------------------------+
+```
 
 </details>
 
-# Examples
-See [here](https://aquasecurity.github.io/trivy/latest/examples/filter/)
 
-# Continuous Integration (CI)
-See [here](https://aquasecurity.github.io/trivy/latest/integrations/)
+# Features
 
-# Vulnerability Detection
-See [here](https://aquasecurity.github.io/trivy/latest/vuln-detection/)
+- Comprehensive vulnerability detection
+  - OS packages (Alpine Linux, Red Hat Universal Base Image, Red Hat Enterprise Linux, CentOS, Oracle Linux, Debian, Ubuntu, Amazon Linux, openSUSE Leap, SUSE Enterprise Linux, Photon OS and Distroless)
+  - **Language-specific packages** (Bundler, Composer, Pipenv, Poetry, npm, yarn, Cargo, NuGet, Maven, and Go)
+- Misconfiguration detection (IaC scanning) 
+  - A wide variety of built-in policies are provided **out of the box**
+    - Kubernetes, Docker, Terraform, and more coming soon
+  - Support custom policies
+- Simple
+  - Specify only an image name, a path to config files, or an artifact name
+- Fast
+  - The first scan will finish within 10 seconds (depending on your network). Consequent scans will finish in single seconds.
+- Easy installation
+  - `apt-get install`, `yum install` and `brew install` are possible.
+  - **No pre-requisites** such as installation of DB, libraries, etc.
+- High accuracy
+  - **Especially [Alpine Linux][alpine] and RHEL/CentOS**
+  - Other OSes are also high
+- DevSecOps
+  - **Suitable for CI** such as GitHub Actions, Jenkins, GitLab CI, etc.
+- Support multiple targets
+  - container image, local filesystem and remote git repository
 
-# Usage
-See [here](https://aquasecurity.github.io/trivy/latest/usage/)
+# Integrations
+- [GitHub Actions][action]
+- [Visual Studio Code][vscode]
 
-# Author
+# Documentation
+The official documentation, which provides detailed installation, configuration, and quick start guides, is available at https://aquasecurity.github.io/trivy/.
+
+[test]: https://github.com/aquasecurity/trivy/actions/workflows/test.yaml
+[test-img]: https://github.com/aquasecurity/trivy/actions/workflows/test.yaml/badge.svg
+[go-report]: https://goreportcard.com/report/github.com/aquasecurity/trivy
+[go-report-img]: https://goreportcard.com/badge/github.com/aquasecurity/trivy
+[release]: https://github.com/aquasecurity/trivy/releases
+[release-img]: https://img.shields.io/github/release/aquasecurity/trivy.svg?logo=github
+[github-all-releases-img]: https://img.shields.io/github/downloads/aquasecurity/trivy/total?logo=github
+[docker-pulls]: https://img.shields.io/docker/pulls/aquasec/trivy?logo=docker&label=docker%20pulls%20%2F%20trivy
+[license]: https://github.com/aquasecurity/trivy/blob/main/LICENSE
+[license-img]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
 
-[Teppei Fukuda](https://github.com/knqyf263) (knqyf263)
+[alpine]: https://ariadne.space/2021/06/08/the-vulnerability-remediation-lifecycle-of-alpine-containers/
+[action]: https://github.com/aquasecurity/trivy-action
+[vscode]: https://github.com/aquasecurity/trivy-vscode-extension

docs/scanning/advanced/oci.md → docs/advanced/container/oci.md

@@ -1,6 +1,6 @@
-# OCI
+# OCI Image Layout
 
-An image directory compliant with "Open Container Image Layout Specification".
+An image directory compliant with [Open Container Image Layout Specification](https://github.com/opencontainers/image-spec/blob/master/spec.md).
 
 Buildah:
 

docs/scanning/advanced/podman.md → docs/advanced/container/podman.md

@@ -1,10 +1,12 @@
 # Podman
 
-[EXPERIMENTAL] This feature might change without preserving backwards compatibility.
+!!! warning "EXPERIMENTAL"
+    This feature might change without preserving backwards compatibility.
 
 Scan your image in Podman (>=2.0) running locally. The remote Podman is not supported.
 Before performing Trivy commands, you must enable the podman.sock systemd service on your machine.
-For more details, see [here][sock]
+For more details, see [here][sock].
+
 
 ```bash
 $ systemctl --user enable --now podman.socket

docs/contrib/triage.md → docs/advanced/contrib/triage.md

@@ -185,7 +185,7 @@ We use two labels [help wanted](https://github.com/aquasecurity/trivy/issues?q=i
 and [good first issue](https://github.com/aquasecurity/trivy/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
 to identify issues that have been specially groomed for new contributors.
 
-We have specific [guidelines](/docs/contrib/help-wanted.md)
+We have specific [guidelines](/docs/advanced/contribd/contrib/help-wanted.md)
 for how to use these labels. If you see an issue that satisfies these
 guidelines, you can add the `help wanted` label and the `good first issue` label.
 Please note that adding the `good first issue` label must also 

docs/advanced/index.md

@@ -0,0 +1,2 @@
+# Advanced
+This section describes advanced features, integrations, etc.

docs/integrations/index.md → docs/advanced/integrations/index.md

@@ -1,3 +1,4 @@
+# Integrations
 Scan your image automatically as part of your CI workflow, failing the workflow if a vulnerability is found. When you don't want to fail the test, specify `--exit-code 0`.
 
 Since in automated scenarios such as CI/CD you are only interested in the end result, and not the full report, use the `--light` flag to optimize for this scenario and get fast results.

docs/modes/client-server.md → docs/advanced/modes/client-server.md

@@ -55,5 +55,5 @@ $ trivy client --remote http://localhost:8080 --token dummy alpine:3.10
 
 ## Architecture
 
-![architecture](../imgs/client-server.png)
+![architecture](../../imgs/client-server.png)
 

docs/modes/standalone.md → docs/advanced/modes/standalone.md

@@ -4,13 +4,13 @@
 
 ## Image
 
-![standalone](../imgs/image.png)
+![standalone](../../imgs/image.png)
 
 ## Filesystem
 
-![fs](../imgs/fs.png)
+![fs](../../imgs/fs.png)
 
 ## Git Repository
 
-![repo](../imgs/repo.png)
+![repo](../../imgs/repo.png)