---
title: "Aqua Security Connector Guide"
slug: "aquasec"
updated: 2026-07-23T06:38:55Z
published: 2026-07-23T06:38:55Z
canonical: "docs.safe.security/aquasec"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safe.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Aqua Security Connector Guide

## Overview

Aqua Security Cloud Workload Protection provides container and cloud native cybersecurity for teams using Docker, Kubernetes, serverless, and other cloud native technologies. The **Balbix integration with Aqua Security Cloud Workload Protection** ingests infrastructure cloud workloads, cloud containers, clusters, and associated vulnerabilities discovered by Aqua Security.

Balbix uses AI to aggregate, normalize and deduplicate ingested information, along with data integrated from your other IT and cybersecurity tools, to provide a unified view of your entire asset inventory, vulnerabilities, and business and operational context. This information is further analyzed by Balbix AI models to provide deployment gap analysis, risk-based vulnerability prioritization (with strict rank and score) and quantification of risk for a single asset, groups of assets and the entire enterprise.

## Integration Summary

This table provides a summary of the Balbix integration for the Aqua Security connector.

| **Integration Type** | Fetch: An inbound API integration used to fetch cloud workloads, cloud containers, clusters, and associated vulnerabilities. |
| --- | --- |
| **Types of Assets Fetched** | Host devices including servers, virtual machines, cloud containers, active images information. |
| **Types of Data Fetched** | **Virtual Machines**: Asset name, hardware information, interface information (IP address), OS information, site information, cloud account ID, cloud asset type, native asset type, image information, K8s cluster information, compliance information, software information, CVE information, tags **Clusters:** Cluster name, type, cloud account ID, cloud asset type, native asset type, status, Kubernetes version, platform version, and node list (node name, site information, roles, tags) **Kubernetes Deployments:** Name, image name, image ID, cloud account ID, cloud asset type, native asset type, registry information, cluster information, namespace information, OS information, CVE information, software information, tags. |

## Prerequisites

To configure the Balbix connector, you must first create Aqua Security API credentials with the appropriate permissions. These credentials are required for completing the configuration process. Here are the steps you need to complete:

1. **Required Role Name**: Use the specified role name.
2. **Create Permissions and Roles**: Create the necessary auth permissions, and add a role for data access.
3. **Create an API Key**: Generate an API key to authenticate the app with Balbix.

### **Required role name**

- **api_auditor**

> [!WARNING]
> **Caution:** When adding the role, you must specify the name as **api_auditor** as the Aqua API expects this value.
> 
> The Aqua API documentation alone is not sufficient for connector setup. You must configure RBAC by creating the **api_auditor** role with the required “view” permissions under Workload Protection and other relevant modules. Without these permissions, the generated API key will not provide access for Balbix ingestion.

### **Auth permissions and roles**

You must create auth permissions and assign the specified role (api_auditor) in order to generate an API key.

1. Log in to the Aqua Console.
2. Go to **Account Management > User Management > Permission Sets**.
3. Click **Add Permission Set**.
4. Click **Create New** and define the permission set name.
5. Select permissions in each category for all resources as follows, then click **Save**.

**Category: AQUA HUB**

| Permission | Access |
| --- | --- |
| Auto-Discovery | View |
| Compliance | View |
| Dashboard | View |
| Exports | Not Permitted |
| Incidents | View |
| Inventory | View |
| Issues | View |
| Response Policies | Not Permitted |

**Category: SUPPLY CHAIN SECURITY**

| Permission | Access |
| --- | --- |
| Assurance Policies | View |
| Build Pipelines | View |
| Checks | View |
| Code Repositories | View |
| Dependencies | View |
| Integrations | View |
| Release Artifacts | View |
| Risks | View |
| Scan | Edit |
| Suppression Rules | Not Permitted |

**Category: CSPM**

| Permission | Access |
| --- | --- |
| Alerts | View |
| Cloud Accounts | View |
| Compliance | View |
| Dashboard | View |
| Events | View |
| Groups | View |
| Integrations | View |
| Remediations | View |
| Scans > MTTR Reports | View |
| Scans > Plugins | View |
| Scans > Scan Reports | View |
| Scans > Suppressions | View |
| Settings > Notifications | Not Permitted |
| Tools > CloudTrail Tail | View |
| Tools > Live Run | View |
| Tools > Visualizers | View |

**Category: WORKLOAD PROTECTION**

| Permission | Access |
| --- | --- |
| Assurance Policies | View |
| Audit | Not Permitted |
| CIS and DISA STIG Benchmarks | View |
| Containers | View |
| Dashboard | Not Permitted |
| Enforcers | View |
| Export/Import | Not Permitted |
| File Forensic | Not Permitted |
| Firewall Policies | Not Permitted |
| Functions | View |
| Gateways | View |
| Host Images | View |
| Image Profiles | View |
| Image Registry Integrations | Not Permitted |
| Images | View |
| Incidents | View |
| Integrations | Not Permitted |
| Risk Explorer | View |
| Runtime Policies | View |
| Scanner CLI | Not Permitted |
| Secrets | View |
| Services | Not Permitted |
| Settings | Not Permitted |
| VMs | View |
| Vulnerabilities | View |
| Webhook authorization API | Not Permitted |

**To add a role:**

1. Go to **Account Management > Roles**.
2. Click **Add Role**.
3. Enter the specified role name as **api_auditor**, add a description, select the permission set you created in the previous steps, and click **Global** for the application scope.
4. Click **Save**.

### **Create an API key**

To generate an API key from Aqua Security:

1. Go to **Account Management > Settings > API Keys**.
2. Click **Generate Key** to display the generated API key and secret.
3. Copy the API key and API secret and and securely save them for later use when setting up the Aqua Security connector in Balbix.

> [!WARNING]
> **Caution:** Be sure to copy and save the API secret—it will no longer be visible after you leave the page.
4. In the Edit API Key window, disable "Global Admin Permissions" and all "Granular Permissions" with read/write access, except for `tokens:read/write`.

## Set up your Aqua Security connector

After completing the prerequisites, follow these steps to configure your Balbix connector for Aqua Security.

### 

[Embedded content](https://scribehow.com/embed/Aqua_Security_Connector_Guide__n3eDB1dCQIehpxEr7ComTw?as=scrollable)

## Field mapping

The table below shows the field mappings from the Aqua Security API to the Balbix Platform.

| From Aqua Security API | Mapped to: Balbix Field |
| --- | --- |
| **Hosts** |  |
| Hostname | Host Name |
| Address | IP Address |
| host os | OS Name |
| Type | Asset Type |
| cloud info: vm tags | Tags |
| cloud info: vm vendor name | Tags |
| applications | Application Name |
| k8s cluster id | K8s Cluster Id |
| cloud acc id | Cloud Acc Id |
| cloud asset type | Cloud Asset Type |
| native asset type | Native Asset Type |
| bench results: controls: category | Comp Control Category |
| bench results: controls: test desc | Comp Control Statement |
| bench results: controls: test info | Controls: Test Info |
| bench results: controls: test number | Comp Control ID |
| bench results: controls: severity | Controls: Severity |
| bench results: controls: status | Comp Control Exposed |
| risk, cve details, cve id | CVE ID |
| risk, cve details, cve description | CVE Description |
| risk, cve details, cve first observed at | CVE First Observed At |
| risk, cve details, cve last observed at | CVE Last Observed At |
| risk, cve details, cve details | CVE Details |
| risk, cve details, fix version | CVE Fix Version |
| risk, cve details, name | Software Product Name |
| risk, cve details, version | Software Product Version |
| risk, cve details, path | Software Install Path |
| risk, cve details, type | Software Type |
| **Clusters** |
| cluster name | Host Name |
| type | Asset Type |
| cloud acc id | Cloud Acc ID |
| cloud asset type | Cloud Asset Type |
| native asset type | Native Asset Type |
| **Containers** |
| name | Host Name |
| image name | Software Product Name |
| image id | Tags |
| type | Asset Type |
| cloud acc id | Cloud Acc Id |
| cloud asset type | Cloud Asset Type |
| native asset type | Native Asset Type |
| registry image name | Tags |
| cluster name | Tags |
| namespace name | Tags |
| host enforcer group | Tags |
| os info, os name | OS Name |
| os info, os version | OS Version |
| os info, os architecture | OS Architecture |
| risk, cve details, cve id | CVE ID |
| risk, cve details, cve description | CVE Description |
| risk, cve details, cve first observed at | CVE First Observed At |
| risk, cve details, cve last observed at | CVE Last Observed At |
| risk, cve details, cve details | CVE Details |
| risk, cve details, fix version | CVE Fix Version |
| risk, cve details, name | Software Product Name |
| risk, cve details, version | Software Product Version |
| risk, cve details, path | Software Install Path |
| risk, cve details, type | Software Type |

## API references

This section provides comprehensive references for the API, detailing endpoints and reference documentation to help you effectively integrate and utilize the API in your system.

### **API version**

| Type | API | Version |
| --- | --- | --- |
| Clusters | /infrastructure/clusters | v2 |
| Nodes | /hosts | v1 |
| Risk (controls) | /risks/bench/{node_id}/bench_results | v2 |
| Vulnerabilities | /containers/vulnerabilities | v2 |
| SW List | /containers/image/Host%20Images/{}/resources | v2 |

### **API documentation**

For more information about the Aqua Security API, see the following references:

- [Aqua Wave API](https://cloud.aquasec.com/developers/)