TABLE OF CONTENTS

Overview

This article explains the process of integrating your code repositories with Aqua. Your repositories may be hosted on different source code management tools such as GitHub, Bitbucket, and GitLab. Once you integrate the required code repositories, Aqua will scan them and display the security findings such as vulnerabilities, sensitive data, and misconfigurations in the Code Repositories screen.


You can integrate your code repositories using one of the following methods:

  • Source Code Management: to integrate with the source code management tools directly by granting their access to Aqua. Through this method, you can also integrate code repositories hosted on on-premises platforms: Azure Server, Bitbucket Server, GitHub Server, and GitLab Server.
  • CI Integrations: by adding the Aqua Trivy Premium Scanner to your build pipeline, by following instructions on the UI. Through his method, the source code management tools connected with the pipeline will be scanned and security findings will be detected.

Once you integrate the required code repositories using either the Source Code Management or CI Integrations method, all the pipelines and dependencies associated with code repositories are discovered and displayed in the code repository detailed view.

You can connect Aqua to multiple organizations of the same provider.

You can integrate your code repositories with Aqua from the Supply Chain Security module > Integrations page.


From the Integrations page, you can also integrate with CI/CD build platforms to detect any security issues in the configurations of the platform. For more information, refer to Integration with Build Platforms.


Prerequisites

  • Network access to https://codesec.aquasec.comfor the customers who want to integrate the on-premises source code management tools: Azure Server, Bitbucket Server, GitHub Server, and GitLab Server. For the cloud-based source code management tools, this access is available by default.
  • Outbound HTTPS traffic should be allowed from your server to integrate with the on-premises source code management tools. To check Aqua's connectivity from your server, run the following commands from the connector host:
curl https://connect.codesec.aquasec.com/
curl https://scan.codesec.aquasec.com/
  • Admin-level privileges to the "Controller" in Jenkins and "Organization" in the other source code management tools, that you want to integrate with Aqua. For example, if you want to integrate a GitHub Organization with Aqua through the Automatic method, you must have "Owner" privilege in the Organization.


Code Repository Integrations page

Once you integrate with a few code repositories through the Source Code Management or CI Integrations methods, all the connections are displayed in the Integrations page as shown below:



You can see the following information in this page:

  • Provider: such as GitHub, GitLab, or GitHub Server
  • Organization Name: in the provider to which Aqua has been connected
  • Status: shows the health of the connection with Aqua: Good or Issue (not good)


You can search or filter the connections using the following options:

  • Search: with organization name to find any connection
  • Provider: to filter the connections by provider
  • Status: to filter the connections by their health: Good, Issue, or All

Add a new code repository

You can add the required code repositories available in the connected source code management tools for scanning them. When the repositories are scanned, Aqua displays scan results in the Code Repositories screen.


On the top right side of the Integrations page, click Connect and select either Source Code Management or CI Integrations as required to integrate using the respective method.


Refer to either the Source Code Management or CI Integrations section below for instructions on integrating your code repositories.



Source Code Management

To integrate your code repository in the source code management tool using this method:

  1. On the top right side of the Integrations screen, click Connect and select Source Code Management. The Source Code Management selection page will appear.
  2. Select the required source code management tool. You can click Show More Options to see more tools. The Authentication section appears.


      3. In the Authentication section, complete the authentication to the source code management tool as instructed on the UI. This is required to grant Aqua the read/write access to the source code management tool for scanning your code repositories. The authentication process and details required for each source code management tool are different, as explained below.


Source code management toolAuthentication details
Azure
  • Install App: It will navigate you to the Azure page where you can grant the read/write access to your code in the Azure application.
  • Organization name: Once access is granted, you should enter the organization name in Azure to proceed with connecting to your Azure account.
Azure ServerYou can connect to your Azure Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either the Docker or Kubernetes platform by following instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories.
BitbucketEnter the following details:
  • Username
  • App Password: Create an app password in your Bitbucket environment by granting the permissions shown below, and add the app password to the Aqua Bitbucket Integrations page. Refer to the Bitbucket document App passwords to learn how to create a Bitbucket app password. 
  • Workspace name

While creating an app password in Bitbucket:
  • Set the app password name to "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)
Bitbucket ServerYou can connect to your Bitbucket Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either the Docker or Kubernetes platform by following the instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories.
GitHubYou should have the GitHub permission as "Organization Owner" to connect Aqua with your repositories.

In the Authentication section, click Connect to navigate to GitHub where you can perform the following:
  1. Login with your GitHub credentials.
  2. Select either "All repositories" or only the selected repositories to grant permissions to Aqua to access these repositories.
  3. Click Install to complete the authentication process.
GitHub ServerYou can connect to your GitHub Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either Docker or Kubernetes platform by following the instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories.
GitLab
  • Group ID
  • Personal Access Token: Generate this in GitLab and copy it to the Aqua UI. Refer to the GitLab document Personal access tokens for more information.

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

GitLab ServerYou can connect to your GitLab Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either the Docker or Kubernetes platform by following the instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories.

Authentication section of the Azure integration is shown below for your reference:



       4. In the Repositories section, select the required code repositories that you want Aqua to scan and detect security findings.

       5. Click Start Scanning. The repositories will be added, and security findings will be displayed on the Code Repositories screen.


You can add any number of repositories to Aqua from an "Organization" in the source code management tool.


Once the selected code repositories are added and scanned, you can see these repositories and their security findings on the Code Repositories screen. You can also add more repositories of the connected source code management tool in the Code Repositories screen later. For more information, refer to Code Repositories List View.


By default, code repositories which have activities in the last six months are automatically selected for scanning, while integrating with its source code management tool for the first time. If required, Admins can check these code repositories and remove their selection. 


Example: Source Code Management connection with a code repository in GitHub

Watch the video below to see an example on how to connect a code repository in GitHub.



CI Integrations

You can integrate a new code repository manually by adding a code block displayed in the UI to your project in the CI build system. Different code blocks are displayed in the UI, depending on where you want to apply them: either Pull Request or Push. Select one of the following options. These options are visible when you select any repository hosting platform below except Jenkins and CircleCI.

  • Pull Request: to scan the specific code changes in a pull request. When a new pull request is triggered, Aqua scans the code changes in the pull request automatically and displays scan results in the Code Repositories page. If you select this option, the existing code repository on which the pull request is raised will not be scanned. If you want to scan the full code repository, select the Push option.
  • Push: to scan the full code repository. When a new build is triggered, Aqua scans the newly built code repository and displays scan results in the Code Repositories page.

To integrate a code repository in the source code management tool:

  1. On the top right side of the Integrations page, click Connect and select CI Integrations. The CI Integration page will appear.
  2. Select the repository hosting platform relevant to your organization, such as GitHub Actions or Bitbucket Pipelines. The Integration Instructions section will appear.


3. Integrate your code repository with the repository hosting platform as explained below. Detailed integration                   instructions are displayed in the UI for each code repository hosting platform.

 4. Copy the code block and add it to the workflow in your project or pipeline. Once the CI integration is successful, you will         see the integrated code repository on the Code Repositories screen.


The CI Integration page for GitHub Actions is shown here for your reference:



Integrate your code repository with the repository hosting platform

  1. In your pipeline settings, add Aqua Key and Aqua Secret as secrets or variables. For more information on obtaining Aqua Key and Aqua Secret, refer to Generating an API Key and Secret. These secrets are required to identify the Aqua environment to which the repository will be integrated. The secrets or variables that should be added to your pipeline settings vary depending on the selected repository hosting platform, as explained below:


CI build systemSecrets or variables required
Azure PipelinesAdd the following variables to your Azure secret variables:Refer to the Azure document, Secret variable in the UI for more information on how to add variables to the pipeline settings.
Bitbucket PipelinesAdd the following variables to your Bitbucket workspace variables:
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
  • BITBUCKET_TOKEN=The app password generated with the `pull request read` scope
  • BITBUCKET_USER=Your Bitbucket username collected from your personal settings
Refer to the Bitbucket document, Workspace variables for more information on how to add variables to the pipeline settings.
CircleCIAdd the following variables to the CircleCI project settings:
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
  • PROVIDER_TOKEN=<Provider token or personal access token>
Refer to the CircleCI document Set an environment variable in a project for more information on how to add variables to the CircleCI project settings.
JenkinsIn the Aqua UI Step 2, select either Bitbucket or GitHub depending on where you want to apply the pipeline. Add the following variables to your Jenkins Global Credentials:
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
  • If you select Bitbucket in Aqua UI step 2, add PROVIDER_CREDENTIALS=Your provider credentials (Username and password)
  • If you select GitHub in Aqua UI step 2, add GITHUB_TOKEN
Refer to the Jenkins document, Adding new global credentials for more information on how to add the variables to your Jenkins Global Credentials.

Note: Aqua supports integrating with Jenkins pipelines of both the types: Multibranch Pipeline and Single branch Pipeline.
GitHub ActionsAdd the following variables to your Organization Encrypted Secrets:
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
Refer to the GitHub document, Organization Encrypted secrets for more information on how to add the variables as encrypted secrets to your GitHub Organization.
GitLab CI/CD

Add the following variables to your CI/CD variables:

Refer to the GitLab document, Add a CI/CD variable to a group for more information on how to add a variable to your GitLab group.

Note: Make sure your CI/CD variables are not marked as protected, otherwise you will not be able to use them.


        2. Follow the instructions displayed on the UI for each CI build system to establish a connection with the pipeline.

        3. Select either Pull request or Push, depending on whether you want to scan the specific code changes in a pull request or full code repository. These options are visible only when you select any repository hosting platform except Jenkins and CircleCI.

       4. Copy the code block and add it to the workflow in your project or pipeline. Once the CI integration is successful, you will see the integrated code repository on the Code Repositories page.


Usage of the code block

As an example, a code block is shown below which should be added to the workflow in your Azure pipeline. Description to the important parameters is added below.


Code block:


name: Aqua
on: pull_request
jobs:
  aqua:
    name: Aqua scanner
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Run Aqua scanner
        uses: docker://aquasec/aqua-scanner
        with:
          args: trivy fs --scanners config,vuln,secret .
          # To customize which severities to scan for, add the following flag: --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL
          # To enable SAST scanning, add: --sast
          # To enable reachability scanning, add: --reachability
          # To enable npm/dotnet non-lock file scanning, add: --package-json / --dotnet-proj
        env:
          AQUA_KEY: ${{ secrets.AQUA_KEY }}
          AQUA_SECRET: ${{ secrets.AQUA_SECRET }}
          GITHUB_TOKEN: ${{ github.token }}
          AQUA_URL: https://api.eu-1.supply-chain.cloud.aquasec.com
          CSPM_URL: https://eu-1.api.cloudsploit.com
          TRIVY_RUN_AS_PLUGIN: 'aqua'
          # For http/https proxy configuration add env vars: HTTP_PROXY/HTTPS_PROXY

Aqua's Container image: As specified in the code block, you will get the "aqua-scanner" image from the docker hub aquasec repository.


Usage of the mandatory environment variables in the code block:


Environment variableExplanation
AQUA_KEYAdd Aqua key generated from Account Management > Settings > API Keys. For more information, refer to the Integrate your code repository with the repository hosting platform section above.
AQUA_SECRETAdd Aqua secret generated from Account Management > Settings > API Keys. For more information, refer to the Integrate your code repository with the repository hosting platform section above.
AQUA_URLIf the code repositories are connected to the Aqua environment deployed outside the US region, you should set the Aqua URL using this variable. Add one of the following Aqua URLs as required:

CSPM_URLIf the Aqua key and Aqua secret are generated in the Aqua environment deployed outside the US region, you should set the CSPM URL using this variable. Add one of the following CSPM URLs as required:
Token from any repository hosting platform (e.g., GITHUB_TOKEN)The token will automatically be pulled from the respective repository hosting platform once the code block is added to the pipeline settings. For more information on token from each platform, refer to the Integrate your code repository with the repository hosting platform section above.
TRIVY_RUN_AS_PLUGINValue for this variable is always "aqua". Do not change it.


Usage of the optional arguments and the corresponding environment variables in the code block:


ArgumentEnvironment variableExplanationExample Usage
--debugDEBUGSet this to "true" to obtain logs for the code repository scanning which can be used for debugging purpose.--debug / DEBUG=true
--dotnet-projDOTNET_PROJSet this to "true" to enable scanning the dotnet files without lock files.--dotnet-proj / DOTNET_PROJ=true
--package-jsonPACKAGE_JSONSet this to "true" to enable scanning the package.json (npm) files without lock files.--package-json / PACKAGE_JSON=true
--reachabilityREACHABILITYSet this to "true" to enable detecting the reachability of the vulnerabilities in the code repositories.--reachability / REACHABILITY=true
--sastSASTSet this to "true" to enable performing Static Application Security Testing (SAST) checks on your application code in the code repositories.--sast / SAST=true
--severitiesTRIVY_SEVERITYSet this to "true" to add severities of all the risks that should be detected and displayed on the UI.--severities CRITICAL,HIGH,UNKNOWN / TRIVY_SEVERITY= CRITICAL,HIGH,UNKNOWN
--skip-pipelinesSKIP_PIPELINESSet this to "true" to skip scanning pipelines associated with the code repositories.--skip-pipelines / SKIP_PIPELINES=true
--skip-policiesTRIVY_SKIP_POLICIESSet this to "true" to skip applying assurance policies on the code repositories; the default setting is "false".--skip-policies / TRIVY_SKIP_POLICIES=true
--skip-policy-exit-codeTRIVY_SKIP_POLICY_EXIT_CODESet this to "true" to ensure the pipeline runs successfully even when any controls in a policy fail; the default setting is "false".--skip-policy-exit-code / TRIVY_SKIP_POLICY_EXIT_CODE=true
--skip-result-uploadTRIVY_SKIP_RESULT_UPLOADSet this to "true" to disable uploading the code repository scan results to the Aqua platform; the default setting is "false".--skip-result-upload / TRIVY_SKIP_RESULT_UPLOAD=true


Usage of other optional environment variables in the code block:


Environment variableExplanation
AQUA_ASSURANCE_EXPORTSpecify a path to export results of the applied Assurance Policies in a JSON file.
FALLBACK_BRANCHSpecify the branch name for discovering and scanning code repositories as a fallback when neither the branch specified through the OVERRIDE_BRANCH variable nor the branch of the pipeline connected code repository is found. It is particularly useful in specific use cases, such as when your pipeline runs on a local system and your code repositories are locally hosted. If the branch is not found via the OVERRIDE_BRANCH and FALLBACK_BRANCH variables, the associated code repositories will not be shown in the Code Repositories screen.
FALLBACK_REPOSITORYSpecify the code repository name for scanning as a fallback when neither the code repository specified through the OVERRIDE_REPOSITORY variable nor the pipeline connected code repository is found. It is particularly useful in specific use cases, such as when your pipeline runs on a local system and your code repositories are locally hosted. If the code repository is not found via the OVERRIDE_REPOSITORY commit to the repository. It is particularly useful in specific cases, such as when your pipeline runs on a local system and your code repositories are locally hosted.
HTTP_PROXY (or) HTTPS_PROXYAdd values for the http or https proxy configuration.
IGNORE_PANICSet this to "true" to prevent the pipeline from failing if scanning the connected code repositories encounters internal panic errors; the default setting is "false".
OVERRIDE_AUTHORSpecify author's name of the code repository that triggered the commit, which automatically initiates scanning of the code repository. It can be used when integrating with specific code repository hosting platforms which do not share author's name with Aqua through integration. It is particularly useful in specific use cases, such as scanning local code repositories, or when your code repositories are connected to the hosting platform not supported for integration with Aqua.
OVERRIDE_BRANCHSpecify the branch name for discovering and scanning code repositories in it, overriding the one detected through the pipeline. If the specified branch is not found, Aqua will identify the branch discovered from the pipeline connected code repository. It is particularly useful in specific use cases, such as when your pipeline runs on a local system and your code repositories are locally hosted.
OVERRIDE_BUILD_IDSpecify job or build ID of the pipeline to discover and scan the associated code repositories. If the specified build ID is not found, it defaults to source code management build ID.
OVERRIDE_BUILDSYSTEMAssign the build system (e.g., Jenkins, GitHub Actions) to the pipeline. If the specified build system is not found, Aqua will identify the build system discovered from the integrated pipeline. If the build system is not found via the OVERRIDE_BUILDSYSTEM variable and pipeline connected code repository, it is shown as "Other" for the pipeline connected code repositories in the Code Repositories screen.
OVERRIDE_REPOSITORYSpecify the code repository name for scanning, overriding the one detected through the pipeline. If the specified code repository is not found, Aqua will use the pipeline connected code repository for scanning. It is particularly useful in specific use cases, such as when your pipeline runs on a local system and your code repositories are locally hosted.
OVERRIDE_REPOSITORY_SOURCEAssign the code repository source (e.g., GitLab, GitHub). If the specified repository source is not connected, Aqua will identify the source discovered from the pipeline connected code repository. The repository source can be either a cloud or an on-premises system where your code repositories are hosted. It is particularly useful in specific use cases, such as when your pipeline runs on a local system and your code repositories are locally hosted.
OVERRIDE_REPOSITORY_URLTo specify the URL for code repository scanning, overriding the one identified through the pipeline. This URL can point to code repositories hosted in cloud or on-premises. It is particularly useful in specific use cases, such as when your pipeline runs on a local system and your code repositories are locally hosted.
OVERRIDE_RUN_IDSpecify Run ID of the pipeline to discover and scan the associated code repositories. If the specified Run ID is not found, it defaults to source code management run build number.
SAST_LOGSSet this to "true" to obtain logs for scanning code repositories, specifically for SAST results, in a separate log file; the default setting is "false". The SAST logs can be used for debugging. The SAST logs file name is "${REPOSITORY_NAME}-sast-logs.txt" stored under the directory specified through the variable SAST_LOGS_DIR.
SAST_LOGS_DIRSpecify the directory for storing the SAST log file. The default directory is /tmp/.trivy/plugins/aqua.
TRIVY_FETCH_DEPTHSpecify a number to determine the count of historical commits in a pull request for fetching the code repository changes for scanning. The default value is 100. You can pass 0 for repositories with a large commit history data.
TRIVY_QUIETSet this to "true" to disable reporting scan results in the logs; the default setting is "false".
XDG_CACHE_HOMESpecify the cache directory for storing temporary data used by the Aqua scanner and other dependent artifacts such as NPM. The default cache directory is /tmp/.cache.
XDG_DATA_HOMESpecify the directory for storing the plugins (modules) downloaded by the Aqua scanner for the scan jobs in future. The default directory is /tmp.


As per your selection of repository hosting platform, you will see the similar code block. You can add flags and environment variables as required.


Scanning local code repositories (without source code management tool)


If your code repositories are on your local machine or a system shared by multiple users, you can scan them using the Aqua scanner image. You can scan these local repositories on a Linux machine using either Docker or Podman container engines. Execute the following Docker or Podman command after adding the necessary flags and environment variables as listed above.


Docker command

AQUA_KEY=${AQUA_KEY} AQUA_SECRET=${AQUA_SECRET} TRIVY_RUN_AS_PLUGIN=aqua 
docker run -it -e AQUA_KEY -e AQUA_SECRET -e TRIVY_RUN_AS_PLUGIN -e INPUT_WORKING_DIRECTORY=/scanning -v "${YOUR_WORKSPACE}":"/scanning" aquasec/aqua-scanner trivy fs --scanners config,vuln,secret .

Podman command

podman run --rm \
                -e AQUA_KEY=${AQUA_KEY} \
                -e AQUA_SECRET=${AQUA_SECRET} \
                -e TRIVY_RUN_AS_PLUGIN='aqua' \
                -e SAST='true' \
                -e INPUT_WORKING_DIRECTORY='/scanning' \
                -v ${WORKSPACE}:/scanning \
                docker.io/aquasec/aqua-scanner \
                git config --global --add safe.directory /scanning && trivy fs --scanners='config,vuln,secret' .


Integration with On-premises code repositories

Refer to Integration with On-Premises Code Repositories for the integration of code repositories hosted in the on-premises source code management tools.


Delete an existing integration

To delete any existing integration:

  1. In the Actions column > options menu of the specific integration, click the Delete button. The Delete Integration dialog appears.



      2. (Optional) Select the checkbox: Delete existing saved scan reports, policies and suppressions to delete the configurations and data associated with the integration. If this is not selected, the integration will only be deleted but not the associated configurations and data.
      3. Click Delete.



Edit an existing integration


You can edit an existing integration to change the following authentication details. To edit an integration:


  1. In the Actions column > options menu of one of the following integrations, click the Edit button. The Authentication section of the integration appears.
  2. Change the following authentication details as required for these integrations:


  • Code repositories:
    • Bitbucket: username and app password
    • GitLab: access token
  • Artifact registry:
    • JFrog: access token