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 (SCM) 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 page.


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

  • Automatic (SCM): with the SCM tools by granting their access to Aqua. Through this method, you can also integrate code repositories hosted on the On-premises platforms such as Azure Server, Bitbucket Server, GitHub Server, and GitLab Server.
  • Manual (CI): by adding Aqua Trivy Premium Scanner to your build pipeline, by following instructions on UI.

(Enterprise plan only) If you want to integrate cloud accounts, image registries, or serverless applications from the Aqua Hub page, click See Integrations at the bottom of the page.


Prerequisites

  • Network access to https://codesec.aquasec.comfor the customers who want to integrate the on-premises SCM tools Azure server, Bitbucket server, GitHub server, and GitLab server. For the cloud based SCM tools, this access is available by default.
  • Outbound HTTPS traffic should be allowed from your server to integrate the on-premises SCM 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 SCM tools, that you want to integrate with Aqua.


Add a new code repository

You can add the required code repositories available in the connected SCM tools for scanning them. When the repositories are scanned, Aqua displays scan results in the Code Repositories page. To add a new code repository:

  1. From the mega menu, access the Supply Chain Security module.
  2. From the left menu, navigate to Integrations.
  3. Click either Automatic or Manual as required to integrate through the respective method.
Refer to either Automatic or Manual section below for the respective instructions to integrate your code repositories.



Automatic - integrate a code repository

To integrate your code repository in the SCM tool through the Automatic method:

  1. In the Integrations page, click the Automatic option. The Automatic Connection page appears.
  2. Select the required SCM tool. You can click Show More Options to see more SCM tools. Authentication section appears.


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


SCM toolAuthentication details
Azure
  • Install App: It will navigate you to the Azure page where you can grant read and 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 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 Docker or Kubernetes platform by following instructions on 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 and add the same in the Aqua Bitbucket Integrations page. refer to the Bitbucket document App passwords to learn how to create Bitbucket app password. 
  • Workspace name
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 Docker or Kubernetes platform by following instructions on UI. For more information, refer to Integration with On-Premises Code Repositories.
GitHubYou should have GitHub permission Organization Owner to connect Aqua with your repositories.

Select either All repositories or only selected repositories to connect with respective repositories and then 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 instructions on 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 Aqua UI. Refer to GitLab document, Personal access tokens for more information.
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 Docker or Kubernetes platform by following instructions on UI. For more information, refer to Integration with On-Premises Code Repositories.


You can integrate Aqua with only one "Organization" in each SCM tool.


       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 in the Code Repositories page.


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



Once the selected code repositories are added and scanned, you can see these repositories and their security findings in the Code Repositories page. You can also add more repositories of the connected SCM tool in the Code Repositories page later. For more information, refer to Code Repositories and Checks.


By default, code repositories having activities from the last six months are automatically selected for scanning, while integrating with it SCM tool for the first time. If required, Admins can check these code repositories and remove their selection. 


Example: Automatic connection with a code repository in GitHub

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



Manual - integrate a code repository

You can integrate a new code repository manually by adding a code block displayed in the UI to your project in the code repository. Different code blocks are displayed in the UI, depending on where you want to apply them, as explained below:

  • Pull Request: to scan the specific code changes in a pull request. When there is a new pull request 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 into which pull request is raised will not be scanned and security findings will not be detected. If you want to scan the full code repository, select the Push option.
  • Push: to scan the full code repository. When there is a new build triggered, Aqua scans the newly built code repository and displays scan results in the Code Repositories page.

To integrate a code repository in an SCM tool:

  1. In the Integrations page, click the Manual option. Manual Connection page appears.
  2. Select the required SCM tool. Integration Instructions section appears.
  3. Perform the following actions to integrate your code repository in the selected SCM tool. Detailed integration instructions are displayed in the UI for each SCM.
    1. In your code repository settings, add Aqua Key and Aqua Secret as secrets or variables. You can get these details from the CSPM module > Settings > API Keys. These secrets are required to identify the Aqua environment to which the repository will be integrated and report security finding to the respective Aqua environment. The secrets or variables that should be added to a repository vary depending on its SCM tool, as explained below:


SCM toolSecrets or variables required
Azure
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
Refer to the Azure document, Define variables for more information on how to add variables to the pipeline settings.
Bitbucket
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
Refer to the Bitbucket document, Variables and secrets for more information on how to add variables to the repository settings.
Jenkins
  • TRIVY_RUN_AS_PLUGIN=aqua
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
Refer to the Jenkins document, Using environment variables for more information on how to export variables to the Jenkins pipeline.
GitHub
  • AQUA_KEY=<Aqua Key>
  • AQUA_SECRET=<Aqua Secret>
Refer to the GitHub document, Encrypted secrets for more information on how to add the secrets to the repository settings.
GitLab
  • TRIVY_RUN_AS_PLUGIN=aqua

  • AQUA_KEY=<Aqua Key>

  • AQUA_SECRET=<Aqua Secret>

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


                      b. Select either Pull request or Push depending on where you want to apply code block to scan code repositories.

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