/
scanning.html.md.erb
executable file
·153 lines (103 loc) · 9.56 KB
/
scanning.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
---
title: Enable App Scanning
owner: Partners
---
## <a id="image-scanning"></a> Image Scanning
This section describes Aqua scanning of images for vulnerabilities, sensitive data, and malware.
Aqua provides security analysis for VMware Tanzu applications at build time, Docker images at build time, and Docker images in various storage repositories. The platform then assigns access control policies on these images when used in your environments.
Aqua scans images for common vulnerabilities and exposures (CVEs) listed on the NVD website, a U.S. government repository of standards-based vulnerability management data as well as data from other industry sources which is curated by Aqua Security research staff.
It is crucial to scan images and repositories for known vulnerabilities that could impact the system information assurance and security leading to security risks. Scanning an image for vulnerabilities reduces these incidents and makes you more aware of the known and defined vulnerable images in the system.
Each image is scanned for vulnerabilities when both its OS packages and development language files are supported as listed in the Support matrix below.
The image scanning process is initiated by:
* Performing a `cf push`
* A build pipeline tool like Concourse or Jenkins
* Integrating the Aqua Management Console with either a public image registry like Docker Hub, or with a private image registry and then adding images from a repository in that registry.
* Scheduling a container scan after adding a Registry
During this process, Aqua scans selected images from the registry and issues alerts when detecting vulnerabilities. You can view the scan results by clicking on a repository to view vulnerability scan details of its images, as described in the [View Scan Results](#view-results) section below.
## <a id="view-results"></a> View Scan Results
After the scan is completed, you can view the scan results. Do the following:
1. In the **Aqua Management Console**, select **Images** to display the **Images** screen.
1. Click on a repository to view vulnerability scan details of its images.
1. Click on an image to view a summary of the image's Image Assurance status. Click on any of the summary boxes to view details.
**Risk**: This tab displays a pie chart of the distribution of vulnerabilities detailed in the Vulnerabilities tab, as well as general information about the image.
**Vulnerabilities**: The scan status displays the vulnerability name, severity, package, and installed version. Click on a CVE to view the vulnerability details. You can further click on the Reference link to the National Vulnerability Database (NVD) entry for that specific vulnerability, where you can view additional information for the selected entry.
**Resources**: This tab displays a list of the packages in the image.
**Sensitive Data**: To view the sensitive data in the image, you must first enable sensitive data scan. To do this, go to **Settings > Scan Options** and select **Scan sensitive data in images**.
**Malware**: This tab displays a list of files that match known malware.
**Information**: This tab displays the information about scan times, env variables, etcetera.
**Audit**: The audit tab is a quicklink to a filtered view of the system audit log where your logs operations are displayed.
## <a id="decorator"></a>Aqua Decorator Buildpack
Build-time vulnerabilty scanning of VMware Tanzu apps is achieved through the `aquasec-decorator` buildpack, which is installed by an errand upon tile installation.
The decorator will be triggered if the `AQUA_SERVER_URL` envrionment variable is set for an app during staging.
To function properly, the Aqua microscanner invoked by the the decorator will require you to set an `AQUA_USERNAME` and `AQUA_PASSWORD`.
Aqua recommends implementing a `staging-environment-variable-group` variable so as to not impact developers current environment settings.
In the case of a `cf push` that fails to pass the assurance policy, the JSON output of the scanner will be sent to `stdout`, giving the developer or CI a direct feedback loop. This empowers developers directly.
### <a id="registry-naming"></a> Blobstore (Registry) Naming Conventions
There are two ways of mapping a VMware Tanzu application to an Aqua registry entry:
* Specifying the registry name using the `AQUA_REGISTRY` environment variable.
* Dynamically generating the registry name based on the VMware Tanzu space name and first eight characters of the space guid.
### <a id="image-naming"></a> Image Naming Convention
VMware Tanzu application scan results are registered within a registry using the app name and the first eight characters of the application version.
## <a id="registry-creation"></a>Aqua Registry Creation
In order to to register the scan results, an Aqua Registry listing needs to exist.
The decorator is able to create these registries on demand, if the Aqua username used for scanning has admin permissions. If you are not scanning with an admin user account, the registry or registries need to be created beforehand either through REST API or manually.
| registry | static | dynamic pre-seeded | dynamic on the fly |
|---|---|---|---|
| admin user | X | X | X |
| scanner user | X | X* | - |
<p class='note'><strong>Note:</strong> Ensure that spaces and registries stay in sync by rerunning seed steps every time a space is created.</p>
### <a id="creating-static-registry"></a>Creating a Registry with a Script
You can create a registry of the Cloud Foundry Registry type through the Aqua API by running the commands below. Make sure you have [jq](https://stedolan.github.io/jq/download/) and [curl](https://curl.haxx.se/docs/install.html) installed.
<pre class="terminal">
$ export AQUA_USERNAME=pcf-scanner
$ export AQUA_PASSWORD=password set in console
$ export AQUA_SERVER_URL=http://aquasec.[system_domain]
$ export AQUA_REGISTRY=example
$ data=$(jq -n -c --arg registry "${AQUA_REGISTRY}" '{name: $registry, type: "API"}')
$ curl -s -k -X POST -d "${data}" -H "Content-Type: application/json" -u "${AQUA_USERNAME}:${AQUA_PASSWORD}" \
${AQUA_SERVER_URL%/}/api/v1/registries
</pre>
### <a id="seed-registry"></a>Pre-Seed Registries
You can create a registry of the Cloud Foundry Registry type for each VMware Tanzu space through the Aqua API by running the commands below. Make sure you have [jq](https://stedolan.github.io/jq/download/), [curl](https://curl.haxx.se/docs/install.html), and [cf CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) installed. You must log in as a VMware Tanzu admin with `cf login`.
<pre class="terminal">
$ export AQUA_USERNAME=administrator
$ export AQUA_PASSWORD=# password from credentials tab in opsmanager
$ export AQUA_SERVER_URL=http://aquasec.[system_domain]
$ for registry in $(cf curl /v2/spaces | jq -c '.resources[] | {name: "\(.entity.name)-\(.metadata.guid | split("-") | .[0])", type: "API"}'); do
curl -s -k -X POST -d "${registry}" -H "Content-Type: application/json" -u "${AQUA_USERNAME}:${AQUA_PASSWORD}" ${AQUA_SERVER_URL%/}/api/v1/registries
done
</pre>
<p class='note'><strong>Note:</strong> If spaces in your environment change often, it is recommended to run the above snippet on a schedule through an automation tool like Concourse or Jenkins.</p>
## <a id="staging-environment-variable-group"></a> Enable Aqua Decorator for All Apps
set-staging-environment-variable-groupset-staging-environment-variable-group
You can enable security scanning globally by using the staging environment variable group.
All apps will use the same Aqua username and password. Environment variables set through a staging envrionment variable group will be visible to all app developers through `cf env {APP-NAME}`.
Set the `AQUA_USERNAME`, `AQUA_PASSWORD`, and `AQUA_SERVER_URL` environment variables for all VMware Tanzu apps during staging by running the commands below. Additionally, if the environment uses self-signed certificates for the Aqua Server, you must set `AQUA_VERIFY_CERTS="0"`. The scanning buildpack has an option to display the scan result URL in the console. Use `AQUA_SHOW_URL="1"` to enable this feature. You must be logged in as a VMware Tanzu admin with `cf login` to set these variables globally.
<pre class="terminal">
$ cf set-staging-environment-variable-group '{"AQUA_REGISTRY":"PIE23","AQUA_USERNAME":"pcf-scanner","AQUA_PASSWORD":"abc12345","AQUA_SERVER_URL":"http://2.3.4.5:8080"}'
</pre>
You can also do this with a script:
<pre class="terminal">
$ export AQUA_USERNAME=pcf-scanner
$ export AQUA_PASSWORD=# password from Aqua console
$ export AQUA_SERVER_URL=http://aquasec.[system_domain]
$ cf set-staging-environment-variable-group \
$(cf curl /v2/config/environment_variable_groups/stagPng | \
jq -c --arg user "$AQUA_USERNAME" --arg pass "$AQUA_PASSWORD" --arg url "$AQUA_SERVER_URL" \
'.AQUA_USERNAME = $user | .AQUA_PASSWORD = $pass | .AQUA_SERVER_URL = $url')
</pre>
To verify that the setting was assigned properly, run the following command:
<pre class="terminal">
$ cf staging-environment-variable-group
</pre>
## <a id="app-env"></a> Enable Aqua Decorator for a Single App
Set the `AQUA_USERNAME`, `AQUA_PASSWORD`, and `AQUA_SERVER_URL` environment variables for a single VMware Tanzu app by running the commands below. Afterward, the app will be restaged. You must log in as a developer with `cf login`.
<pre class="terminal">
$ cf set-env {APP_NAME} AQUA_USERNAME administrator
$ cf set-env {APP_NAME} AQUA_PASSWORD {AQUA_PASSWORD}
$ cf set-env {APP_NAME} AQUA_SERVER_URL http://aquasec.[system_domain]
$ cf set-env {APP_NAME} AQUA_REGISTRY example # optional
$ cf restage {APP_NAME}
</pre>