TABLE OF CONTENTS

Overview

This article explains the process of deploying Aqua components for Supply Chain Security on your server which also hosts your code repositories. Once Aqua components are deployed on your server, it scans the code repositories, detects security issues, and reports them back to Aqua to display in the UI.


This integration includes the deployment of two main components on your server:

  • Connector Client: an agent that can be deployed on your server and sends information about the detection of security issues in your code repositories to Aqua in real time
  • Scanner Clientscans your code repositories hosted in your environment for security issues. It sends this information to Connector Client, which in turn sends it to Aqua to report in the UI.


You can deploy the components on either a Kubernetes cluster or a Docker environment. The following sections explain the procedures to deploy the components on Kubernetes and Docker environments. You can find deployment steps and command syntax for each Source Code Management (SCM) tool (Azure Server, Bitbucket Server, GitHub Server, and GitLab Server) in the relevant Integration page in the UI. For more information, refer to Code repository Integrations.


Prerequisites

Before you deploy these components, you should have the following details to fill them as environment variables in the commands:

  • SCM URL: e.g. https://example.your-scm-server.com
  • SCM Username
  • SCM Password: Enter access token for Azure Server, GitHub Server, and GitLab Server or app password for Bitbucket Server in this variable. Refer to the following documentation to create a personal access token or an app password with the required permissions shown in the Permissions required to create a personal access token or an app password section below.

    To create a personal access token or an app password, refer to the following documentation:
  • HTTP or HTTPS details: Optionally you can add SSL CA certificate and client certificate/key for SSL connection to the SCM/CI server. The details required are HTTP/HTTPS Proxy, HTTPS certificate, HTTPS Key, and CA certificate.
  • Local directory: which has HTTPS certificates

 For the list of all environment variables, refer to the Environment Variables section below.


Permissions required to create a personal access token or an app password


Bitbucket Server

While creating an app password in Bitbucket or Bitbucket Server:

  • Set the app password name as "Aqua Supply Chain".
  • Grant access to the following with either "Read" or "Read and Write" permissions:
    • Account (Read)
    • Pipelines (Read)
    • Projects (Read)
    • Repositories (Read)
    • Webhooks (Read and Write)


GitHub Server

While creating a personal access token in GitHub:

  • Set the name for personal access token as "Aqua Supply Chain"
  • Grant permissions to the following scopes:
    • repo (access to all scopes)
    • workflow


GitLab Server

While creating a personal access token in GitLab:

  • Set the name for personal access token as "Aqua Supply Chain"
  • Grant access to the following with the "Check" permissions:
    • read-api
    • read-repository
    • read-user

Connectivity check

Before deploying Aqua components on your environment, you can run a check to validate whether your server would support the deployment of Aqua components.


Run the following commands in the terminal of the server where you want to deploy Aqua components:


curl https://connect.codesec.aquasec.com/
curl https://scan.codesec.aquasec.com/

# To authenticate with CSPM:
curl https://api.cloudsploit.com/v2/tokens

# For Aqua URL:
curl https://api.aquasec.com/v2/build

# For Trivy artifact download:
curl https://github.com/  
curl ghcr.io 
curl pkg-containers.githubusercontent.com


If you want to deploy Aqua components in the EU region, you should pass the following environment variables with the respective values for the connectivity check:


Docker composeKubernetesValues to check connectivity
AQUA_SERVER_URL
aquaServerUrl
https://eu-1.supply-chain.cloud.aquasec.com
CSPM_SERVER_URL
cspmServerUrl
https://eu-1.api.cloudsploit.com
SCANNER_SERVER
scanServerUrl
https://scan.eu-1.codesec.aquasec.com
SERVER_URL
connectServerUrl
https://connect.eu-1.codesec.aquasec.com


You will then get a result on whether your server has passed the validation. Once validated, you can move on to the next steps of deploying Aqua components.


Deploy Aqua components in a Docker environment

On a host with Docker Compose, perform the following actions to deploy Aqua components on your server:

  1. Create a local version of docker-compose.yaml using the following syntax. The following syntax has parameters supported for deploying Aqua components on the environment which also hosts Azure Server.


version: '3.9'
services:
  aqua-connector:
    restart: unless-stopped
    image: docker.io/aquasec/codesec-connector:minified
    environment:
      SOURCE: 'azure_server'
      SCM_URL: ${SCM_URL}
      USERNAME: ${SCM_USERNAME}
      PASSWORD: ${SCM_PASSWORD}
      AQUA_KEY: ${AQUA_KEY}
      AQUA_SECRET: ${AQUA_SECRET}
      
      # Uncomment if you have a proxy
      # HTTP_PROXY: ${HTTP_PROXY}

      # Uncomment this section if you are using a custom certificate
      # CA_CERT: ${CA_CERT} # .pem file path
      # HTTPS_CERT: ${HTTPS_CERT} # certificate file path
      # HTTPS_KEY: ${HTTPS_KEY} # certificate private key path
    # volumes:
    #   - ${LOCAL_CERT_DIR}:/home/private

  aqua-scanner:
    restart: unless-stopped
    image: docker.io/aquasec/codesec-scanner:latest
    environment:
      SOURCE: 'azure_server'
      USERNAME: ${SCM_USERNAME}
      PASSWORD: ${SCM_PASSWORD}
      AQUA_KEY: ${AQUA_KEY}
      AQUA_SECRET: ${AQUA_SECRET} 
      
      # Uncomment if you have a proxy
      # HTTP_PROXY: ${HTTP_PROXY}

      # Uncomment this section if you are using a custom certificate
      # CA_CERT: ${CA_CERT} # .pem file path
      # HTTPS_CERT: ${HTTPS_CERT} # certificate file path
      # HTTPS_KEY: ${HTTPS_KEY} # certificate private key path
    # volumes:
    #   - ${LOCAL_CERT_DIR}:/home/private

    # Uncomment if you want more than one scanner running
    # deploy:
    #   replicas: 3


        2. Run the following command after adding the required variables. 


export AQUA_KEY=<aqua key>
export AQUA_SECRET=<aqua secret>
export SCM_URL=<scm endpoint>
export SCM_PASSWORD=<access-token or password>
export SCM_USERNAME=<token-name or account-name/empty>
docker-compose up -d

You can find syntax for each SCM tool in the relevant Integration page in the UI.


Deploy Aqua components in a Kubernetes environment

To deploy Aqua components on your Kubernetes cluster, run the following commands:

  1.  Run the following command to add and update "Aqua codesec" Helm chart repository:


helm repo add aqua-helm https://helm.aquasec.com
  helm repo update

        2. Run one of the following commands after adding the required variables. The following commands have parameters
            supported for deploying Aqua components on the environment which also hosts Azure Server.

  • Command with basic configuration:

helm upgrade -i aqua-codesec aqua-helm/codesec-agent --namespace aqua-codesec \
--create-namespace \
--set integration.source=azure_server \
--set credentials.aqua_key=<aqua key> \
--set credentials.aqua_secret=<aqua secret> \
--set integration.url=<scm endpoint> \
--set integration.username=<token-name or account-name/empty> \
--set integration.password=<access-token or password>
  • Command with advanced configuration:

credentials:
  # Aqua key and secret generated from the platform
  aqua_key: <AQUA_KEY>
  aqua_secret: <AQUA_SECRET>

integration:
  source: azure_server

  # Your SCM url
  url: <SCM_URL>

  # Access Token/Api Key/Account information
  username: <SCM_USERNAME>
  password: <SCM_PASSWORD>

You can get AQUA_KEY and AQUA_SECRET from the Aqua CSPM Module > Settings > API Keys page. For more information, refer to Creating Aqua CSPM API Keys.


        3. (Optional) Run the following command to upgrade release name to the latest chart version. This command is required
            to upgrade the already deployed Helm chart version.


helm upgrade -i aqua-codesec aqua-helm/codesec-agent --namespace aqua-codesec \
--create-namespace -f env-values.yaml

You can find syntax for each SCM tool in the relevant Integration page in the UI.


Environment Variables

You can pass values to the following environment variables in either a Docker or Kubernetes environment, while deploying Aqua components on your server. The following list describes these variables and their functions:


Docker ComposeKubernetesDescription
AQUA_KEYcredentials.aqua_keyAqua Key (from CSPM module > Settings > API Keys). This value is already populated in the snippets that you copy from the UI. 
AQUA_SECRETcredentials.aqua_secretAqua Secret (from CSPM module > Settings > API Keys)). This value is already populated in the snippets that you copy from the UI.
CA_CERTssl.caCA Certificate
HTTP_PROXYproxy.urlHTTP Proxy
HTTPS_CERTssl.certSSL Certificate
HTTPS_KEYssl.keySSL Certificate key
HTTPS_PROXYproxy.urlHTTPS Proxy
LOCAL_CERT_DIR
Certificates directory
PASSWORDintegration.passwordPassword or Access Token value for provider authentication

<RELEASE_NAME>Release name to update the already deployed Helm chart version
SCM_URLintegration.urlBase URL of the provider
SOURCEintegration.sourceProvider identifier (Hardcoded)
USERNAMEintegration.usernameUser or Access Token name for provider authentication