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

docs: restructure docs and add tutorials (#2883)

Browse Source 
Co-authored-by: knqyf263 <knqyf263@gmail.com>
This commit is contained in:
Anais Urlichs
2022-09-15 19:27:58 +01:00
committed by GitHub
parent 192fd78ca2
commit 20f1e5991a
32 changed files with 696 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/tutorials/additional-resources/cks.md Normal file
View File

@@ -0,0 +1,26 @@
# CKS preparation resources
The [Certified Kubernetes Security Specialist (CKS) Exam](https://training.linuxfoundation.org/certification/certified-kubernetes-security-specialist/) is offered by The Linux Foundation. It provides assurance that a CKS has the skills, knowledge, and competence on a broad range of best practices for securing container-based applications and Kubernetes platforms during build, deployment and runtime. CKA certification is required to sit for this exam.
### Community Resources
- [Trivy Video overview (short)][overview]
- [Example questions from the exam][exam]
- [More example questions][questions]
- [CKS exam study guide](study-guide)
- [Docker Image Vulnerabilities & Trivy Image Scanning Demo | K21Academy](https://youtu.be/gHz10UsEdys)
### Aqua Security Blog posts to learn more
- Supply chain security best [practices][supply-chain-best-practices]
- Supply chain [attacks][supply-chain-attacks]
If you know of interesting resources, please start a PR to add those to the list.
[overview]: https://youtu.be/2cjH6Zkieys
[exam]: https://jonathan18186.medium.com/certified-kubernetes-security-specialist-cks-preparation-part-7-supply-chain-security-9cf62c34cf6a
[questions]: https://github.com/kodekloudhub/certified-kubernetes-security-specialist-cks-course/blob/main/docs/06-Supply-Chain-Security/09-Scan-images-for-known-vulnerabilities-(Trivy).md
[study-guide]: https://devopscube.com/cks-exam-guide-tips/
[supply-chain-best-practices]: https://blog.aquasec.com/supply-chain-security-best-practices
[supply-chain-attacks]: https://blog.aquasec.com/supply-chain-threats-using-container-images

37
docs/tutorials/additional-resources/community.md Normal file
View File

@@ -0,0 +1,37 @@
# Community References
Below is a list of additional resources from the community.
## Vulnderability Scanning
- [Detecting Spring4Shell with Trivy and Grype](https://youtu.be/mOfBcpJWwSs)
## CI/CD Pipelines
- [How to use Tekton to set up a CI pipeline with OpenShift Pipelines](https://www.redhat.com/architect/cicd-pipeline-openshift-tekton)
- [Continuous Container Vulnerability Testing with Trivy](https://semaphoreci.com/blog/continuous-container-vulnerability-testing-with-trivy)
- [Getting Started With Trivy and Jenkins](https://youtu.be/MWe01VdwuMA)
- [How to use Tekton to set up a CI pipeline with OpenShift Pipelines](https://www.redhat.com/architect/cicd-pipeline-openshift-tekton)
## Misconfiguration Scanning
- [Identifying Misconfigurations in your Terraform](https://youtu.be/cps1V5fOHtE)
- [How to write custom policies for Trivy](https://blog.ediri.io/how-to-write-custom-policies-for-trivy)
## SBOM, Attestation & related
- [Attesting Image Scans With Kyverno](https://neonmirrors.net/post/2022-07/attesting-image-scans-kyverno/)
## Trivy Kubernetes
- [Using Trivy Kubernetes in OVHCloud documentation.](https://docs.ovh.com/gb/en/kubernetes/installing-trivy/)
## Comparisons
- [the vulnerability remediation lifecycle of Alpine containers](https://ariadne.space/2021/06/08/the-vulnerability-remediation-lifecycle-of-alpine-containers/)
- [Open Source CVE Scanner Round-Up: Clair vs Anchore vs Trivy](https://boxboat.com/2020/04/24/image-scanning-tech-compared/)
- [Docker Image Security: Static Analysis Tool Comparison – Anchore Engine vs Clair vs Trivy](https://www.a10o.net/devsecops/docker-image-security-static-analysis-tool-comparison-anchore-engine-vs-clair-vs-trivy/)
### Evaluations
- [Istio evaluating to use Trivy](https://github.com/istio/release-builder/pull/687#issuecomment-874938417)
- [Research Spike: evaluate Trivy for scanning running containers](https://gitlab.com/gitlab-org/gitlab/-/issues/270888)

38
docs/tutorials/additional-resources/references.md Normal file
View File

@@ -0,0 +1,38 @@
# Additional Resources and Tutorials
Below is a list of additional resources from Aqua Security.
## Announcements
- [Trivy Vulnerability Scanner Joins the Aqua Open-source Family](https://blog.aquasec.com/trivy-vulnerability-scanner-joins-aqua-family)
- [Trivy Image Vulnerability Scanner Now Under Apache 2.0 License](https://blog.aquasec.com/trivy-open-source-vulnerability-scanner-apache2.0-license)
## Vulnderability Scanning
- [Using Trivy to Discover Vulnerabilities in VS Code Projects](https://blog.aquasec.com/trivy-open-source-vulnerability-scanner-vs-code)
- [How does a vulnerability scanner identify packages?](https://youtu.be/PaMnzeHBa8M)
- [Handling Container Vulnerabilities with Open Policy Agent - Teppei Fukuda, Aqua Security](https://youtu.be/WKE2XNZ2zr4)
## CI/CD Pipelines
- [DevSecOps with Trivy and GitHub Actions](https://blog.aquasec.com/devsecops-with-trivy-github-actions)
- [Find Image Vulnerabilities Using GitHub and Aqua Security Trivy Action](https://blog.aquasec.com/github-vulnerability-scanner-trivy)
## Misconfiguration Scanning
- [Identifying Misconfigurations in your Terraform](https://youtu.be/cps1V5fOHtE)
## Client/Server
- [Using Trivy in client server mode](https://youtu.be/tNQ-VlahtYM)
## Workshops
- [Trivy Live Demo & Q&A](https://youtu.be/6Vw0QgJ-k5o)
- [First Steps to Full Lifecycle Security with Open Source Tools - Rory McCune & Anais Urlichs](https://youtu.be/nwJ0366rs6s)
## Older Resources
- [Webinar: Trivy Open Source Scanner for Container Images – Just Download and Run!](https://youtu.be/XnYxX9uueoQ)
- [Kubernetes Security through GitOps Best Practices: ArgoCD and Starboard](https://youtu.be/YvMY8to9aHI)
- [Get started with Kubernetes Security and Starboard](https://youtu.be/QgctrpTpJec)

4
docs/tutorials/integrations/aws-codepipeline.md Normal file
View File

@@ -0,0 +1,4 @@
# AWS CodePipeline
See [this blog post][blog] for an example of using Trivy within AWS CodePipeline.
[blog]: https://aws.amazon.com/blogs/containers/scanning-images-with-trivy-in-an-aws-codepipeline/

51
docs/tutorials/integrations/aws-security-hub.md Normal file
View File

@@ -0,0 +1,51 @@
# AWS Security Hub
## Upload findings to Security Hub
In the following example using the template `asff.tpl`, [ASFF](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html) file can be generated.
```
$ AWS_REGION=us-west-1 AWS_ACCOUNT_ID=123456789012 trivy image --format template --template "@contrib/asff.tpl" -o report.asff golang:1.12-alpine
```
ASFF template needs AWS_REGION and AWS_ACCOUNT_ID from environment variables.
The Product [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) field follows the pattern below to match what AWS requires for the [product resource type](https://github.com/awsdocs/aws-security-hub-user-guide/blob/master/doc_source/securityhub-partner-providers.md#aqua-security--aqua-cloud-native-security-platform-sends-findings).
{% raw %}
```
"ProductArn": "arn:aws:securityhub:{{ env "AWS_REGION" }}::product/aquasecurity/aquasecurity",
```
{% endraw %}
In order to upload results you must first run [enable-import-findings-for-product](https://docs.aws.amazon.com/cli/latest/reference/securityhub/enable-import-findings-for-product.html) like:
```
aws securityhub enable-import-findings-for-product --product-arn arn:aws:securityhub:<AWS_REGION>::product/aquasecurity/aquasecurity
```
Then, you can upload it with AWS CLI.
```
$ aws securityhub batch-import-findings --findings file://report.asff
```
### Note
The [batch-import-findings](https://docs.aws.amazon.com/cli/latest/reference/securityhub/batch-import-findings.html#options) command limits the number of findings uploaded to 100 per request. The best known workaround to this problem is using [jq](https://stedolan.github.io/jq/) to run the following command
```
jq '.[:100]' report.asff 1> short_report.asff
```
## Customize
You can customize [asff.tpl](https://github.com/aquasecurity/trivy/blob/main/contrib/asff.tpl)
```
$ export AWS_REGION=us-west-1
$ export AWS_ACCOUNT_ID=123456789012
$ trivy image --format template --template "@your-asff.tpl" -o report.asff golang:1.12-alpine
```
## Reference
https://aws.amazon.com/blogs/security/how-to-build-ci-cd-pipeline-container-vulnerability-scanning-trivy-and-aws-security-hub/

22
docs/tutorials/integrations/azure-devops.md Normal file
View File

@@ -0,0 +1,22 @@
# Azure Devops
- Here is the [Azure DevOps Pipelines Task for Trivy][action]
![trivy-azure](https://github.com/aquasecurity/trivy-azure-pipelines-task/blob/main/screenshot.png?raw=true)
### [Use ImageCleaner to clean up stale images on your Azure Kubernetes Service cluster][azure2]
It's common to use pipelines to build and deploy images on Azure Kubernetes Service (AKS) clusters. While great for image creation, this process often doesn't account for the stale images left behind and can lead to image bloat on cluster nodes. These images can present security issues as they may contain vulnerabilities. By cleaning these unreferenced images, you can remove an area of risk in your clusters. When done manually, this process can be time intensive, which ImageCleaner can mitigate via automatic image identification and removal.
Vulnerability is determined based on a trivy scan, after which images with a LOW, MEDIUM, HIGH, or CRITICAL classification are flagged. An updated ImageList will be automatically generated by ImageCleaner based on a set time interval, and can also be supplied manually.
### [Microsoft Defender for container registries and Trivy][azure]
This blog explains how to scan your Azure Container Registry-based container images with the integrated vulnerability scanner when they're built as part of your GitHub workflows.
To set up the scanner, you'll need to enable Microsoft Defender for Containers and the CI/CD integration. When your CI/CD workflows push images to your registries, you can view registry scan results and a summary of CI/CD scan results.
The findings of the CI/CD scans are an enrichment to the existing registry scan findings by Qualys. Defender for Cloud's CI/CD scanning is powered by Aqua Trivy
[action]: https://github.com/aquasecurity/trivy-azure-pipelines-task
[azure]: https://docs.microsoft.com/en-us/azure/defender-for-cloud/defender-for-containers-cicd
[azure2]: https://docs.microsoft.com/en-us/azure/aks/image-cleaner?tabs=azure-cli

5
docs/tutorials/integrations/bitbucket.md Normal file
View File

@@ -0,0 +1,5 @@
# Bitbucket Pipelines
See [trivy-pipe][trivy-pipe] for the details.
[trivy-pipe]: https://github.com/aquasecurity/trivy-pipe

34
docs/tutorials/integrations/circleci.md Normal file
View File

@@ -0,0 +1,34 @@
# CircleCI
```
$ cat .circleci/config.yml
jobs:
build:
docker:
- image: docker:stable-git
steps:
- checkout
- setup_remote_docker
- run:
name: Build image
command: docker build -t trivy-ci-test:${CIRCLE_SHA1} .
- run:
name: Install trivy
command: |
apk add --update-cache --upgrade curl
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin
- run:
name: Scan the local image with trivy
command: trivy image --exit-code 0 --no-progress trivy-ci-test:${CIRCLE_SHA1}
workflows:
version: 2
release:
jobs:
- build
```
[Example][example]
[Repository][repository]
[example]: https://circleci.com/gh/aquasecurity/trivy-ci-test
[repository]: https://github.com/aquasecurity/trivy-ci-test

9
docs/tutorials/integrations/github-actions.md Normal file
View File

@@ -0,0 +1,9 @@
# GitHub Actions
- Here is the [Trivy GitHub Action][action]
- The Microsoft Azure team have written a [container-scan action][azure] that uses Trivy and Dockle
- For full control over the options specified to Trivy, this [blog post][blog] describes adding Trivy into your own GitHub action workflows
[action]: https://github.com/aquasecurity/trivy-action
[azure]: https://github.com/Azure/container-scan
[blog]: https://blog.aquasec.com/devsecops-with-trivy-github-actions

181
docs/tutorials/integrations/gitlab-ci.md Normal file
View File

@@ -0,0 +1,181 @@
# GitLab CI
GitLab 15.0 includes [free](https://gitlab.com/groups/gitlab-org/-/epics/2233) integration with Trivy.
To [configure container scanning with Trivy in GitLab](https://docs.gitlab.com/ee/user/application_security/container_scanning/#configuration), simply include the CI template in your `.gitlab-ci.yml` file:
```yaml
include:
- template: Security/Container-Scanning.gitlab-ci.yml
```
If you're a GitLab 14.x Ultimate customer, you can use the same configuration above.
Alternatively, you can always use the example configurations below.
```yaml
stages:
- test
trivy:
stage: test
image: docker:stable
services:
- name: docker:dind
entrypoint: ["env", "-u", "DOCKER_HOST"]
command: ["dockerd-entrypoint.sh"]
variables:
DOCKER_HOST: tcp://docker:2375/
DOCKER_DRIVER: overlay2
# See https://github.com/docker-library/docker/pull/166
DOCKER_TLS_CERTDIR: ""
IMAGE: trivy-ci-test:$CI_COMMIT_SHA
TRIVY_NO_PROGRESS: "true"
TRIVY_CACHE_DIR: ".trivycache/"
before_script:
- export TRIVY_VERSION=$(wget -qO - "https://api.github.com/repos/aquasecurity/trivy/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
- echo $TRIVY_VERSION
- wget --no-verbose https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz -O - | tar -zxvf -
allow_failure: true
script:
# Build image
- docker build -t $IMAGE .
# Build report
- ./trivy image --exit-code 0 --format template --template "@contrib/gitlab.tpl" -o gl-container-scanning-report.json $IMAGE
# Print report
- ./trivy image --exit-code 0 --severity HIGH $IMAGE
# Fail on severe vulnerabilities
- ./trivy image --exit-code 1 --severity CRITICAL $IMAGE
cache:
paths:
- .trivycache/
# Enables https://docs.gitlab.com/ee/user/application_security/container_scanning/ (Container Scanning report is available on GitLab EE Ultimate or GitLab.com Gold)
artifacts:
reports:
container_scanning: gl-container-scanning-report.json
```
[Example][example]
[Repository][repository]
### GitLab CI using Trivy container
To scan a previously built image that has already been pushed into the
GitLab container registry the following CI job manifest can be used.
Note that `entrypoint` needs to be unset for the `script` section to work.
In case of a non-public GitLab project Trivy additionally needs to
authenticate to the registry to be able to pull your application image.
Finally, it is not necessary to clone the project repo as we only work
with the container image.
```yaml
container_scanning:
image:
name: docker.io/aquasec/trivy:latest
entrypoint: [""]
variables:
# No need to clone the repo, we exclusively work on artifacts. See
# https://docs.gitlab.com/ee/ci/runners/README.html#git-strategy
GIT_STRATEGY: none
TRIVY_USERNAME: "$CI_REGISTRY_USER"
TRIVY_PASSWORD: "$CI_REGISTRY_PASSWORD"
TRIVY_AUTH_URL: "$CI_REGISTRY"
TRIVY_NO_PROGRESS: "true"
TRIVY_CACHE_DIR: ".trivycache/"
FULL_IMAGE_NAME: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
script:
- trivy --version
# cache cleanup is needed when scanning images with the same tags, it does not remove the database
- time trivy image --clear-cache
# update vulnerabilities db
- time trivy image --download-db-only
# Builds report and puts it in the default workdir $CI_PROJECT_DIR, so `artifacts:` can take it from there
- time trivy image --exit-code 0 --format template --template "@/contrib/gitlab.tpl"
--output "$CI_PROJECT_DIR/gl-container-scanning-report.json" "$FULL_IMAGE_NAME"
# Prints full report
- time trivy image --exit-code 0 "$FULL_IMAGE_NAME"
# Fail on critical vulnerabilities
- time trivy image --exit-code 1 --severity CRITICAL "$FULL_IMAGE_NAME"
cache:
paths:
- .trivycache/
# Enables https://docs.gitlab.com/ee/user/application_security/container_scanning/ (Container Scanning report is available on GitLab EE Ultimate or GitLab.com Gold)
artifacts:
when: always
reports:
container_scanning: gl-container-scanning-report.json
tags:
- docker-runner
```
[example]: https://gitlab.com/aquasecurity/trivy-ci-test/pipelines
[repository]: https://github.com/aquasecurity/trivy-ci-test
### GitLab CI alternative template
Depending on the edition of gitlab you have or your desired workflow, the
container scanning template may not meet your needs. As an addition to the
above container scanning template, a template for
[code climate](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html)
has been included. The key things to update from the above examples are
the `template` and `report` type. An updated example is below.
```yaml
stages:
- test
trivy:
stage: test
image: docker:stable
services:
- name: docker:dind
entrypoint: ["env", "-u", "DOCKER_HOST"]
command: ["dockerd-entrypoint.sh"]
variables:
DOCKER_HOST: tcp://docker:2375/
DOCKER_DRIVER: overlay2
# See https://github.com/docker-library/docker/pull/166
DOCKER_TLS_CERTDIR: ""
IMAGE: trivy-ci-test:$CI_COMMIT_SHA
TRIVY_NO_PROGRESS: "true"
TRIVY_CACHE_DIR: ".trivycache/"
before_script:
- export TRIVY_VERSION=$(wget -qO - "https://api.github.com/repos/aquasecurity/trivy/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
- echo $TRIVY_VERSION
- wget --no-verbose https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz -O - | tar -zxvf -
allow_failure: true
script:
# Build image
- docker build -t $IMAGE .
# Image report
- ./trivy image --exit-code 0 --format template --template "@contrib/gitlab-codequality.tpl" -o gl-codeclimate-image.json $IMAGE
# Filesystem report
- ./trivy filesystem --security-checks config,vuln --exit-code 0 --format template --template "@contrib/gitlab-codequality.tpl" -o gl-codeclimate-fs.json .
# Combine report
- apk update && apk add jq
- jq -s 'add' gl-codeclimate-image.json gl-codeclimate-fs.json > gl-codeclimate.json
cache:
paths:
- .trivycache/
# Enables https://docs.gitlab.com/ee/user/application_security/container_scanning/ (Container Scanning report is available on GitLab EE Ultimate or GitLab.com Gold)
artifacts:
paths:
- gl-codeclimate.json
reports:
codequality: gl-codeclimate.json
```
Currently gitlab only supports a single code quality report. There is an
open [feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/9014)
to support multiple reports. Until this has been implemented, if you
already have a code quality report in your pipeline, you can use
`jq` to combine reports. Depending on how you name your artifacts, it may
be necessary to rename the artifact if you want to reuse the name. To then
combine the previous artifact with the output of trivy, the following `jq`
command can be used, `jq -s 'add' prev-codeclimate.json trivy-codeclimate.json > gl-codeclimate.json`.
### GitLab CI alternative template example report
You'll be able to see a full report in the GitLab pipeline code quality UI, where filesystem vulnerabilities and misconfigurations include links to the flagged files and image vulnerabilities report the image/os or runtime/library that the vulnerability originates from instead.
![codequality](../../imgs/gitlab-codequality.png)

2
docs/tutorials/integrations/index.md Normal file
View File

@@ -0,0 +1,2 @@
# 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`.

29
docs/tutorials/integrations/travis-ci.md Normal file
View File

@@ -0,0 +1,29 @@
# Travis CI
```
$ cat .travis.yml
services:
- docker
env:
global:
- COMMIT=${TRAVIS_COMMIT::8}
before_install:
- docker build -t trivy-ci-test:${COMMIT} .
- export VERSION=$(curl --silent "https://api.github.com/repos/aquasecurity/trivy/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
- wget https://github.com/aquasecurity/trivy/releases/download/v${VERSION}/trivy_${VERSION}_Linux-64bit.tar.gz
- tar zxvf trivy_${VERSION}_Linux-64bit.tar.gz
script:
- ./trivy image --exit-code 0 --severity HIGH --no-progress trivy-ci-test:${COMMIT}
- ./trivy image --exit-code 1 --severity CRITICAL --no-progress trivy-ci-test:${COMMIT}
cache:
directories:
- $HOME/.cache/trivy
```
[Example][example]
[Repository][repository]
[example]: https://travis-ci.org/aquasecurity/trivy-ci-test
[repository]: https://github.com/aquasecurity/trivy-ci-test

120
docs/tutorials/kubernetes/cluster-scanning.md Normal file
View File

@@ -0,0 +1,120 @@
# Kubernetes Scanning Tutorial
## Prerequisites
To test the following commands yourself, make sure that you’re connected to a Kubernetes cluster. A simple kind, a Docker-Desktop or microk8s cluster will do. In our case, we’ll use a one-node kind cluster.
Pro tip: The output of the commands will be even more interesting if you have some workloads running in your cluster.
## Cluster Scanning
Trivy K8s is great to get an overview of all the vulnerabilities and misconfiguration issues or to scan specific workloads that are running in your cluster. You would want to use the Trivy K8s command either on your own local cluster or in your CI/CD pipeline post deployments.
The Trivy K8s command is part of the Trivy CLI:
With the following command, we can scan our entire Kubernetes cluster for vulnerabilities and get a summary of the scan:
```
trivy k8s --report=summary
```
To get detailed information for all your resources, just replace ‘summary’ with ‘all’:
```
trivy k8s --report=all
```
However, we recommend displaying all information only in case you scan a specific namespace or resource since you can get overwhelmed with additional details.
Furthermore, we can specify the namespace that Trivy is supposed to scan to focus on specific resources in the scan result:
```
trivy k8s -n kube-system --report=summary
```
Again, if you’d like to receive additional details, use the ‘--report=all’ flag:
```
trivy k8s -n kube-system --report=all
```
Like with scanning for vulnerabilities, we can also filter in-cluster security issues by severity of the vulnerabilities:
```
trivy k8s --severity=CRITICAL --report=summary
```
Note that you can use any of the Trivy flags on the Trivy K8s command.
With the Trivy K8s command, you can also scan specific workloads that are running within your cluster, such as our deployment:
```
trivy k8s –n app --report=summary deployments/react-application
```
## Trivy Operator
The Trivy K8s command is an imperative model to scan resources. We wouldn’t want to manually scan each resource across different environments. The larger the cluster and the more workloads are running in it, the more error-prone this process would become. With the Trivy Operator, we can automate the scanning process after the deployment.
The Trivy Operator follows the Kubernetes Operator Model. Operators automate human actions, and the result of the task is saved as custom resource definitions (CRDs) within your cluster.
This has several benefits:
- Trivy Operator is installed CRDs in our cluster. As a result, all our resources, including our security scanner and its scan results, are Kubernetes resources. This makes it much easier to integrate the Trivy Operator directly into our existing processes, such as connecting Trivy with Prometheus, a monitoring system.
- The Trivy Operator will automatically scan your resources every six hours. You can set up automatic alerting in case new critical security issues are discovered.
- The CRDs can be both machine and human-readable depending on which applications consume the CRDs. This allows for more versatile applications of the Trivy operator.
There are several ways that you can install the Trivy Operator in your cluster. In this guide, we’re going to use the Helm installation based on the [following documentation.](../../docs/kubernetes/operator/index.md)
Make sure that you have the [Helm CLI installed.](https://helm.sh/docs/intro/install/)
Next, run the following commands.
First, we are going to add the Aqua Security Helm repository to our Helm repository list:
```
helm repo add aqua https://aquasecurity.github.io/helm-charts/
```
Then, we will update all of our Helm repositories. Even if you have just added a new repository to your existing charts, this is generally good practice to have access to the latest changes:
```
helm repo update
```
Lastly, we can install the Trivy operator Helm Chart to our cluster:
```
helm install trivy-operator aqua/trivy-operator \
--namespace trivy-system \
--create-namespace \
--set="trivy.ignoreUnfixed=true" \
--version v0.0.3
```
You can make sure that the operator is installed correctly via the following command:
```
kubectl get deployment -n trivy-system
```
Trivy will automatically start scanning your Kubernetes resources.
For instance, you can view vulnerability reports with the following command:
```
kubectl get vulnerabilityreports --all-namespaces -o wide
```
And then you can access the details of a security scan:
```
kubectl describe vulnerabilityreports <name of one of the above reports>
```
The same process can be applied to access Configauditreports:
```
kubectl get configauditreports --all-namespaces -o wide
```

125
docs/tutorials/kubernetes/gitops.md Normal file
View File

@@ -0,0 +1,125 @@
# Installing the Trivy-Operator through GitOps
This tutorial shows you how to install the Trivy Operator through GitOps platforms, namely ArgoCD and FluxCD.
## ArgoCD
Make sure to have [ArgoCD installed](https://argo-cd.readthedocs.io/en/stable/getting_started/) and running in your Kubernetes cluster.
You can either deploy the Trivy Operator through the argocd CLI or by applying a Kubernetes manifest.
ArgoCD command:
```
> kubectl create ns trivy-system
> argocd app create trivy-operator --repo https://github.com/aquasecurity/trivy-operator --path deploy/helm --dest-server https://kubernetes.default.svc --dest-namespace trivy-system
```
Note that this installation is directly related to our official Helm Chart. If you want to change any of the value, we'd suggest you to create a separate values.yaml file.
Kubernetes manifest `trivy-operator.yaml`:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: trivy-operator
namespace: argocd
spec:
project: default
source:
chart: trivy-operator
repoURL: https://aquasecurity.github.io/helm-charts/
targetRevision: 0.0.3
helm:
values: |
trivy:
ignoreUnfixed: true
destination:
server: https://kubernetes.default.svc
namespace: trivy-system
syncPolicy:
automated:
prune: true
selfHeal: true
```
The apply the Kubernetes manifest. If you have the manifest locally, you can use the following command through kubectl:
```
> kubectl apply -f trivy-operator.yaml
application.argoproj.io/trivy-operator created
```
If you have the manifest in a Git repository, you can apply it to your cluster through the following command:
```
> kubectl apply -n argocd -f https://raw.githubusercontent.com/AnaisUrlichs/argocd-starboard/main/starboard/argocd-starboard.yaml
```
The latter command would allow you to make changes to the YAML manifest that ArgoCD would register automatically.
Once deployed, you want to tell ArgoCD to sync the application from the actual state to the desired state:
```
argocd app sync trivy-operator
```
Now you can see the deployment in the ArgoCD UI. Have a look at the ArgoCD documentation to know how to access the UI.
![ArgoCD UI after deploying the Trivy Operator](../../imgs/argocd-ui.png)
Note that ArgoCD is unable to show the Trivy CRDs as synced.
## FluxCD
Make sure to have [FluxCD installed](https://fluxcd.io/docs/installation/#install-the-flux-cli) and running in your Kubernetes cluster.
You can either deploy the Trivy Operator through the Flux CLI or by applying a Kubernetes manifest.
Flux command:
```
> kubectl create ns trivy-system
> flux create source helm trivy-operator --url https://aquasecurity.github.io/helm-charts --namespace trivy-system
> flux create helmrelease trivy-operator --chart trivy-operator
--source HelmRepository/trivy-operator
--chart-version 0.0.3
--namespace trivy-system
```
Kubernetes manifest `trivy-operator.yaml`:
```
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
name: trivy-operator
namespace: flux-system
spec:
interval: 60m
url: https://aquasecurity.github.io/helm-charts/
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: trivy-operator
namespace: trivy-system
spec:
chart:
spec:
chart: trivy-operator
sourceRef:
kind: HelmRepository
name: trivy-operator
namespace: flux-system
version: 0.0.5
interval: 60m
```
You can then apply the file to your Kubernetes cluster:
```
kubectl apply -f trivy-operator.yaml
```
## After the installation
After the install, you want to check that the Trivy operator is running in the trivy-system namespace:
```
kubectl get deployment -n trivy-system
```

114
docs/tutorials/kubernetes/kyverno.md Normal file
View File

@@ -0,0 +1,114 @@
# Attesting Image Scans With Kyverno
This tutorial is based on the following blog post by Chip Zoller: [Attesting Image Scans With Kyverno](https://neonmirrors.net/post/2022-07/attesting-image-scans-kyverno/)
This tutorial details
- Verify the container image has an attestation with Kyverno
### Prerequisites
1. [Attestation of the vulnerability scan uploaded][vuln-attestation]
3. A running Kubernetes cluster that kubectl is connected to
### Kyverno Policy to check attestation
The following policy ensures that the attestation is no older than 168h:
vuln-attestation.yaml
{% raw %}
```bash
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: check-vulnerabilities
spec:
validationFailureAction: enforce
webhookTimeoutSeconds: 10
failurePolicy: Fail
rules:
- name: not-older-than-one-week
match:
any:
- resources:
kinds:
- Pod
verifyImages:
- imageReferences:
- "CONTAINER-REGISTRY/*:*"
attestations:
- predicateType: cosign.sigstore.dev/attestation/vuln/v1
conditions:
- all:
- key: "{{ time_since('','{{metadata.scanFinishedOn}}','') }}"
operator: LessThanOrEquals
value: "168h"
```
{% endraw %}
### Apply the policy to your Kubernetes cluster
Ensure that you have Kyverno already deployed and running on your cluster -- for instance throught he Kyverno Helm Chart.
Next, apply the above policy:
```
kubectl apply -f vuln-attestation.yaml
```
To ensure that the policy worked, we can deploye an example deployment file with our container image:
deployment.yaml
```
apiVersion: apps/v1
kind: Deployment
metadata:
name: cns-website
namespace: app
spec:
replicas: 2
selector:
matchLabels:
run: cns-website
template:
metadata:
labels:
run: cns-website
spec:
containers:
- name: cns-website
image: docker.io/anaisurlichs/cns-website:0.0.6
ports:
- containerPort: 80
imagePullPolicy: Always
resources:
limits:
memory: 512Mi
cpu: 200m
securityContext:
allowPrivilegeEscalation: false
```
Once we apply the deployment, it should pass since our attestation is available:
```
kubectl apply -f deployment.yaml -n app
deployment.apps/cns-website created
```
However, if we try to deploy any other container image, our deployment will fail. We can verify this by replacing the image referenced in the deployment with `docker.io/anaisurlichs/cns-website:0.0.5` and applying the deployment:
```
kubectl apply -f deployment-two.yaml
Resource: "apps/v1, Resource=deployments", GroupVersionKind: "apps/v1, Kind=Deployment"
Name: "cns-website", Namespace: "app"
for: "deployment-two.yaml": admission webhook "mutate.kyverno.svc-fail" denied the request:
resource Deployment/app/cns-website was blocked due to the following policies
check-image:
autogen-check-image: |
failed to verify signature for docker.io/anaisurlichs/cns-website:0.0.5: .attestors[0].entries[0].keys: no matching signatures:
```
[vuln-attestation]: ../signing/vuln-attestation.md

27
docs/tutorials/overview.md Normal file
View File

@@ -0,0 +1,27 @@
# Tutorials
Tutorials are a great way to learn about use cases and integrations. We highly encourage community members to share their Trivy use cases with us in the documentation.
There are two ways to contributor to the tutorials section
1. If you are creating any external content on Trivy, we would love to have it as part of our list of [external community resources][community-resources]
2. If you are creating an end-to-end tutorial on a specific Trivy use-case, we would love to feature it in our tutorial section. Read below how you can contribute tutorials to the docs.
## Process for adding new tutorials
Requirements
- The tutorial has to provide an end-to-end set of instructions
- Ideally, tutorials should focus on a specific use case
- If the tutorial is featuring other tools, those should be open source, too
- Make sure to describe the expected outcome after each instruction
**Tip:** Make sure that your tutorial is concise about a specific use case or integration.
How to add a tutorial
1. Simply create a new `.md` file in the tutorials folder of the docs
2. Add your content
3. Create a new index in the mkdocs.yaml file which is in the [root directory](https://github.com/aquasecurity/trivy) of the repository
4. Create a PR
[community-resources]: additional-resources/community.md

36
docs/tutorials/signing/vuln-attestation.md Normal file
View File

@@ -0,0 +1,36 @@
# Vulnerability Scan Record Attestation
This tutorial details
- Scan your container image for vulnerabilities
- Generate an attestation with Cosign
#### Prerequisites
1. Trivy CLI installed
2. Cosign installed
#### Scan Container Image for vulnerabilities
Scan your container image for vulnerabilities and save the scan result to a scan.json file:
```
trivy image --ignore-unfixed --format json --output scan.json anaisurlichs/cns-website:0.0.6
```
* --ignore-unfixed: Ensures that only the vulnerabilities are displayed that have a already a fix available
* --output scan.json: The scan output is scaved to a scan.json file instead of being displayed in the terminal.
Note: Replace the container image with the container image that you would like to scan.
#### Attestation of the vulnerability scan with Cosign
The following command generates an attestation for the vulnerability scan and uploads it to our container image:
```
cosign attest --replace --predicate scan.json --type vuln anaisurlichs/cns-website:0.0.6
```
Note: Replace the container image with the container image that you would like to scan.
See [here][vuln-attestation] for more details.
[vuln-attestation]: ../../docs/attestation/vuln.md