harbor-scanner-aqua - Aqua Enterprise scanner as a plug-in vulnerability

项目说明

[![GitHub release][release-img]][release]
[![GitHub Build Action][build-action-img]][actions]
[![Go Report Card][report-card-img]][report-card]
![Docker Pulls][docker-pulls]
[![License][license-img]][license]

Harbor Scanner Adapter for Aqua Enterprise

> NOTE: This adapter is only required if you want Harbor to use Aqua Enterprise for its image scanning feature.
> If your objective is to use Aqua Enterprise to provide its own analysis reports against images stored in Harbor,
> that can be achie deploying this adapter.

The Harbor Scanner Adapter for Aqua Enterprise is a service that translates the Harbor scanning API into scannercli
commands and allows Harbor to use Aqua Enterprise ad hoc scanning for pro reports on images stored
in Harbor registry as part of its scan feature.

The adapter service implements the [Pluggable Scanners API v1.0][harbor-pluggable-scanner-api] and communicates with
the Aqua API server to fulfil the contract required by Harbor scanning API. This contract is based on OS and application
, which implies that Harbor scanning API and Harbor Portal are **only capable of handling and displaying
OS and application **.

!HLD

> NOTE: To see the whole report generated by the Aqua scanner, including detected malware and sensitive data,
> you have to na from Harbor Portal to Aqua Management Console. Similarly, Harbor does not ha for
> displaying or enforcing Aqua's image assurance policies. You will need to use the Aqua Management Console to view
> and configure these policies.

TOC

Requirements

How does it work?

Deployment

- Docker
- Kubernetes
- OpenShift Container Platform
- Configuring Harbor Scanner

Configuration

Troubleshooting

- Error: Failed getting image manifest: 412 Precondition Failed
- Error: Failed scanning image: image was not found in registry
- Error: Failed scanning image: no such registry
- Scans are not displayed in the CI/CD Scans page

Contributing

Requirements

1. Harbor >= 1.10
2. This adapter service requires Aqua Enterprise >= 4.5 deployment to operate. The adapter can be deployed before the
Aqua Enterprise installation, but the Aqua Management Console URL and credentials must be known to configure the
adapter with the en .
3. The adapter service also requires the scannercli executable binary, in matching the Aqua Enterprise, to be
mounted at /usr/local/bin/scannercli. The provided Helm chart mounts the scannercli executable automatically by
pulling the registry.aquasec.com/scanner:$AQUA_ image from Aqua Registry and running it as an
[init container][k8s-init-containers]. The init container's command is configured to copy the executable from the
container's filesystem to an [emptyDir][k8s-] , which is shared with the main container. This
makes the scannercli executable a to the main container at /usr/local/bin/scannercli.

> NOTE: Make sure that you provide valid Aqua Registry credentials received from Aqua Security as Helm
> in order to create the corresponding image pull secret.

If you're not using Kubernetes to run the adapter service, you have to download the scannercli executable from the
Aqua downloads page manually and mount it at /usr/local/bin/scannercli.
See [Aqua Scanner Executable Binary][aqua-docs-scanner-binary] for more details on manual download.
4. It is highly recommended to create a new user in the Aqua Management Console with credentials dedicated to the
Harbor adapter, e.g. harbor_scanner. The adapter does not need full access to Aqua: the Scanner role is the only
permission required for the scannercli executable binary which is run by the adapter service on each scan request.
Therefore, create your harbor_scanner user and assign it only the Scanner role.

5. It is also highly recommended to create a new user in Harbor for the Aqua Enterprise scanner, with permission only to
pull images from Harbor, e.g. aqua_scanner. Please remember to add this user as a member of the project in Harbor
that you intend to scan the images from.

6. Finally, add a new Harbor registry integration in Aqua Management Console and use the credentials of the user
created in the previous step. Please note that the value of the Registry Name field corresponds to the
SCANNER_AQUA_REGISTRY configuration .


How does it work?

In essence, a scan request payload sent by Harbor to the adapter:

is translated to the following scannercli command:

Finally, the output report is transformed to Harbor's model and displayed in the Harbor interface.

> NOTE: The SCANNER_AQUA_USE_IMAGE_TAG en whether the image tag (library/mongo:3.4-xenial)
> or digest (library/mongo:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b) is used as
> the image identifier passed to the scannercli command.

> NOTE: Harbor >= 2.0 && < 2.3 no longer set the tag property in the scan request.
> Thus, the SCANNER_AQUA_USE_IMAGE_TAG env must be set to false.

Deployment

Harbor can be [installed as a Docker service][harbor-docs-installer] or deployed with [high a via Helm][harbor-docs-helm].
This section describes how to perform a new installation of the adapter service in both cases.

It's also possible to deploy Harbor on Docker (outside the Kubernetes en) to work with Aqua Enterprise on
Kubernetes, and you should be able to figure it out based on the following instructions.

Docker

This section shows how to install the adapter service by extending the Docker Compose file
created by the Harbor >= 1.10 installer in the $HARBOR_HOME directory. We assume that the internal
[TLS communication between Harbor components][harbor-docs-internal-tls] is enabled and internal certificate files are
stored in the $HARBOR_PKI_DIR directory. The default Harbor data path is referred to as $HARBOR_DATA. We also
assume that you installed Aqua Enterprise >= 4.5, and the Aqua Management Console is accessible at
and you ha credentials with permission to scan container images.

1. Export en that are used throughout the installation scripts.

Review and adapt the to reflect your installation paths and credentials.

2. Create the config and data directories for the adapter service.

3. Download the scannercli executable binary.
1. You can download the binary from the [docs][download-scannercli] page and save it to
$HARBOR_HOME/common/config/aqua-adapter/scannercli.
2. Alternatively you can use the registry.aquasec.com/scanner:$AQUA_ image to copy the scannercli binary
from the container's file system.

4. Generate certificate files.
> NOTE: Self signed certificates without SAN were deprecated in Go, therefore you must add the SAN
> extension to your certificate files. The DNS name in SAN extension should be the same as CN field.
1. Generate a private key.

2. Generate a certificate signing request (CSR).

Adapt the in the -subj option to reflect your organization.

3. Generate an x509 v3 extension file.

You must create this file so that you can generate a certificate for adapter service host that complies with the
Subject Alternative Name (SAN) and x509 v3 extension requirements.

4. Use the aqua_adapter_v3.ext file to generate a certificate for adapter service host.
> NOTE: The certificate must be signed by the internal Harbor CA.

5. Create the env file to configure the adapter service:

6. Create docker-compose.o.yml file in the $HARBOR_HOME directory to install the adapter service:

7. For some Docker drivers you must explicitly set ownership of config files and data directories to user and
group which runs the adapter process, i.e. 1000:1000:

8. Start the adapter service:

The adapter service will be accessible at from within the harbor Docker network.
9. Connect Harbor to Aqua scanner.

Kubernetes

> I assume that you installed Aqua Enterprise >= 4.5 with [Aqua Security Helm charts][aqua-helm-chart] in the aqua
> namespace, and the Aqua Management Console is accessible at from within the cluster.

1. Export en that are used throughout the installation scripts.

Review and adapt the to reflect your installation paths and credentials.

2. Install the harbor-scanner-aqua chart:

The scanner service should be accessible at from within the cluster.
3. Connect Harbor to Aqua scanner.

OpenShift Container Platform

Similar to the way that RBAC resources control user access, administrators can use Security Context Constraints (SCCs)
to control permissions for pods. These permissions include actions that a pod can perform and what resources it can
access. You can use SCCs to define a set of conditions that a pod must run with in order to be accepted into the system.

In particular, SCCs allow an administrator to control:
* The container user ID
* The allocation of an fsGroup that owns the pod's

The harbor-scanner-aqua’s Helm chart deployment template:
* Runs the underlying pod with a dedicated service account (named after a Helm release)
* Requires that the pod's containers run as user with ID 1000
* Requires that fsGroup that owns the pod's has ID 1000

Therefore, the harbor-scanner-aqua deployment will be accepted by OpenShift Container Platform only when a service
account is granted access to a SCC that:
* Allows container user with ID 1000
* Allows fsGroup with ID 1000

For example, if the scanner adapter installed as the Helm release called harbor-scanner-aqua in the harbor namespace,
the following command has to be run by the administrator to accept the pods:

where <scc name> is one of the predefined SCCs or a custom SCC created by the administrator.

Configuring Harbor Scanner

1. Log in to the Harbor interface with an account that has Harbor system administrator pri.
2. Expand Administration, and select Interrogation Services.
!Scanners config
3. Click the NEW SCANNER button.
4. Enter the information to identify the scanner.
1. A unique name for this scanner instance to display in the Harbor interface, e.g. Aqua Enterprise 6.5.
2. The API endpoint URL of the adapter service.

> NOTE: For the adapter deployed on Kubernetes the default URL is
> whereas for Docker, it's

!Add scanner
5. Click TEST CONNECTION to make sure that Harbor can connect successfully to the adapter service.

> NOTE: When you click the TEST CONNECTION button Harbor only pings the adapter service. It does not
> connection to the Aqua Management Console, which is configured with SCANNER_AQUA_USERNAME, SCANNER_AQUA_PASSWORD,
> and SCANNER_AQUA_HOST en . If the connection to the Aqua Management Console is misconfigured
> you will see an error message in the scan logs accessible from the Harbor interface.
6. If e is fine click ADD to save the configuration and connect Harbor to the adapter service.
7. If you configured multiple scanners, you can designate the Aqua Enterprise scanner as the default one by selecting it
and clicking SET AS DEFAULT.
!Set default scanner
Make sure the Default label is displayed next to the Aqua scanner's name.

Configuration

Configuration of the adapter is done at startup.

| Name | Default | Description |
|---------------------------------------------|------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SCANNER_LOG_LEVEL | info | The log level of trace, debug, info, warn, warning, error, fatal or panic. The standard logger logs entries with that level or anything above it. |
| SCANNER_API_ADDR | :8080 | Binding address for the API HTTP server |
| SCANNER_API_TLS_CERTIFICATE | | The absolute path to the x509 certificate file |
| SCANNER_API_TLS_KEY | | The absolute path to the x509 private key file |
| SCANNER_API_READ_TIMEOUT | 15s | The maximum duration for reading the entire request, including the body |
| SCANNER_API_WRITE_TIMEOUT | 15s | The maximum duration before timing out writes of the response |
| SCANNER_API_IDLE_TIMEOUT | 60s | The maximum amount of time to wait for the next request when keep-alives are enabled |
| SCANNER_AQUA_USERNAME | N/A | Aqua management console username (required) |
| SCANNER_AQUA_PASSWORD | N/A | Aqua management console password (required) |
| SCANNER_AQUA_HOST | | Aqua management console address |
| SCANNER_AQUA_REGISTRY | Harbor | The name of the Harbor registry configured in Aqua management console |
| SCANNER_AQUA_REPORTS_DIR | /var/lib/scanner/reports | Directory to sa scan reports |
| SCANNER_AQUA_USE_IMAGE_TAG | false | The flag to determine whether the image tag or digest is used in the image reference passed to scannercli |
| SCANNER_CLI_NO_ | false | The flag passed to scannercli to skip TLS certificates |
| SCANNER_CLI_SHOW_NEGLIGIBLE | true | The flag passed to scannercli to show negligible/unknown se |
| SCANNER_CLI_OIALS | false | The flag to enable passing --robot-username and --robot-password flags to the scannercli executable binary |
| SCANNER_CLI_DIRECT_CC | false | The flag passed to scannercli to contact CyberCenter directly (rather than through the Aqua server) |
| SCANNER_CLI_REGISTER_IMAGES | Never | The flag to determine whether images are registered in Aqua management console: Never - skips registration; Compliant - registers only compliant images; Always - registers compliant and non-compliant images. |
| SCANNER_STORE_REDIS_NAMESPACE | harbor.scanner.aqua:store | The namespace for keys in the Redis store |
| SCANNER_STORE_REDIS_SCAN_JOB_TTL | 1h | The time to live for persisting scan jobs and associated scan reports |
| SCANNER_REDIS_URL | redis://harbor-harbor-redis:6379 | The Redis server URI. The URI supports schemas to connect to a standalone Redis server, i.e. redis://:password:port/db-number and Redis Sentinel deployment, i.e. redis+sentinel://:password:port1,sentinel_host2:port2/monitor-name/db-number. |
| SCANNER_REDIS_POOL_MAX_ACTIVE | 5 | The max number of connections allocated by the pool for the Redis store |
| SCANNER_REDIS_POOL_MAX_IDLE | 5 | The max number of idle connections in the pool for the Redis store |
| SCANNER_REDIS_POOL_IDLE_TIMEOUT | 5m | The duration after which idle connections to the Redis server are closed. If the value is zero, then idle connections are not closed. |
| SCANNER_REDIS_POOL_CONNECTION_TIMEOUT | 1s | The timeout for connecting to the Redis server |
| SCANNER_REDIS_POOL_READ_TIMEOUT | 1s | The timeout for reading a single Redis command reply |
| SCANNER_REDIS_POOL_WRITE_TIMEOUT | 1s | The timeout for writing a single Redis command |

Troubleshooting

Error: Failed getting image manifest: 412 Precondition Failed

Currently, there's a limitation of scannercli in Aqua Enterprise < 4.6.20181 (4.6 update 16) which do not
accept Harbor robot account credentials passed by a Harbor scan job to the adapter service. This effectively means that
the Aqua Enterprise scanner is using the credentials provided in Aqua Management Console under the
Integrations / Image Registries section. However, these credentials do not ha permissions to bypass the
deployment security checker when it's enabled in the Harbor project configuration. In other words, the deployment
security checker prevents the Aqua Enterprise scanner from pulling an image, which it needs to be able to do in order
to scan it.


The a solution depends on the of your Aqua Enterprise deployment. In scannercli >= 4.6.20181 (4.6 update 16)
we' new --robot-username and --robot-password flags to respect credentials provided by Harbor.

For Aqua Enterprise < 4.6.20181 (4.6 update 16) you can only disable deployment security checks in the Harbor

interface under the project configuration.

For Aqua Enterprise >= 4.6.20181 (4.6 update 16) set the value of the SCANNER_CLI_OIALS

env to true.

Error: Failed scanning image: image was not found in registry

For Harbor >= 2.0 && < 2.3, which do not set the tag property in a scan request anymore, the value of the
SCANNER_AQUA_USE_IMAGE_TAG env must be set to false. This informs the adapter service to use digest rather than tag
as the image identifier.

Error: Failed scanning image: no such registry

Make sure the value of the SCANNER_AQUA_REGISTRY env is the same as the Registry Name entered in Aqua Management
Console.

Scans are not displayed in the CI/CD Scans page

Normally, scans performed via the scannercli scan command (not through the daemon mode) are only saved if the images
are also registered in Aqua Enterprise. To store and display all scannercli scans in the CI/CD Scans page,
accessible from within the Images page, enable the Save CI/CD scans option in the Aqua Management Console.


Now, even if the images stored in Harbor were not registered in Aqua Enterprise, you'd see them in the CI/CD Scans page.


Contributing

Please read CONTRIBUTING.md for information about setting up your de en, and the
contribution workflow that we expect.

[release-img]:
[release]:
[build-action-img]:
[actions]:
[report-card-img]:
[report-card]:
[docker-pulls]:
[license-img]:
[license]:
[harbor-url]:
[harbor-helm-chart]:
[harbor-docs-installer]:
[harbor-docs-internal-tls]:
[harbor-docs-helm]:
[harbor-pluggable-scanner-api]:
[k8s-init-containers]:
[k8s-]:
[aqua-docs-scanner-binary]:
[aqua-helm-chart]:
[download-scannercli]:

项目信息

开发语言：Go

Star 数：36

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Aqua Enterprise scanner as a plug-in vulnerability scanner in the Harbor registry展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。