Cequence can test APIs for vulnerabilities early in the development cycle, giving visibility to potential security issues in time to mitigate or eliminate those issues. The Azure DevOps pipeline enables you to integrate Cequence's automated API testing directly, providing observability and threat detection throughout the development cycle.
Prerequisites
Before you start, confirm that you have access to credentials to the Cequence repository with sufficient permissions to download the most recent API Testing Docker image.
Have the details of the target of the API test at hand. The relevant details are the Base Host, Target Host and Target Server.
For example, when Cequence tests an endpoint present at https://demo.example.com, then the target details are as follows.
- Base Host: example.com
- Target Host: demo.example.com
- Target Server: https://demo.example.com
Generating a client and secret
Several Cequence components must authenticate to the Cequence UAP platform in order to transmit and receive data. Create authentication credentials in the Cequence UAP platform to enable this authentication.
- Log in to the UAP management portal UI.
The URL for the management portal is typically of the form https://ui.<your-tenant-name>.<domain>. Replace <your-tenant-name> with the name of your Cequence tenant organization. Replace <domain> with your domain name. - Select General Settings > User Management.
The User Management pane appears. - Click the Clients tab.
- Click Add New Client.
The new client dialog box appears. - Type the client name in the Client Name field.
This name is the client ID. Note the client ID for later use. - Enable the Traffic Management toggle.
- (Optional) To change the token lifespan from the default of 1800 seconds, type a whole number of seconds in Token Lifespan.
- Click Save.
A dialog box with the client secret appears. - Click the blue Copy icon to copy the secret to the clipboard, then click Close.
The client is now set up. Note the client name for future use.
The client list appears. - Note the value of the client secret for later use. This value will not be shown again later on the UI for security reasons.
Determining the Test Plan ID
- Log in to the UAP management portal.
The UAP dashboard appears. - Select API Security Testing > Test Plans.
The Test Plans pane appears. - Select a test plan and note the value in the Test Plan ID column.
Adding a Gitlab Docker repository connection to your Azure DevOps pipeline
Before you configure your Azure DevOps pipeline to integrate with Cequence, you must configure a connection to the Cequence Docker repository on Gitlab.
- Log in to Azure DevOps.
- Navigate to Azure Build Pipeline > Project Settings > Pipelines > Service Connectors.
- Click Create New Registry service connection.
The configuration dialog box for a new service connector appears. - In Registry Type, click Others.
- In Docker Registry, type the URL https://registry.gitlab.com.
- In Docker ID and Docker Password, type the credentials provided by your Cequence team.
- In Service connection name, type a name for the connection.
- Click Save.
Your Azure DevOps pipeline now has access to the Cequence Docker repository.
Configuring your Azure DevOps pipeline
You can integrate Cequence into your Azure DevOps pipeline in two different ways. You can pass the required environment variables directly to Docker at runtime, or you can write the environment values into a file and reference that file in the pipeline configuration.
Describing environment variables directly
Open the configuration file for your Azure DevOps pipeline and add the following snippet.
variables:
CQ_TEST_PLAN_ID: Yx75Go8BrcKqwQgHPRQ-
CQ_TEST_TARGET_SERVER: https://vampi.api-testing-1.eng1.int.cequence.ai/
CQ_UAP_BASE_HOST: api-testing-2.eng1.int.cequence.ai
CQ_UAP_CLIENT_ID: azure-testing
CQ_UAP_CLIENT_SECRET: J5ulKeXPItAdR8wrchHfUpaW2vX8eE7H
CQ_TEST_PLAN_BUNDLE_MODE: CEQUENCE
CQ_UAP_AUTH_URL: https://auth.common.eng1.int.cequence.ai/auth/realms/api-testing-2/protocol/openid-connect/token
BUILD_PIPELINE_URL: "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
ARTIFACT_NAME: 'myartifact'
CQ_REPORT_SAVE_DIR: '/app/results'
DOWNLOAD_PATH: '$(Build.SourcesDirectory)/artifacts'
HOST_OUTPUT_PATH: '$(System.DefaultWorkingDirectory)/cequence'
- job: cequence_security_test
displayName: 'Cequence Security Test'
# dependsOn: [Build, UnitTest]
steps:
- task: Docker@2
inputs:
command: login
containerRegistry: ''
- script: |
echo "Running Docker container with environment variables"
docker run \
-e CQ_TEST_PLAN_ID=$(CQ_TEST_PLAN_ID) \
-e CQ_TEST_TARGET_SERVER=$(CQ_TEST_TARGET_SERVER) \
-e CQ_UAP_BASE_HOST=$(CQ_UAP_BASE_HOST) \
-e CQ_UAP_CLIENT_ID=$(CQ_UAP_CLIENT_ID) \
-e CQ_UAP_CLIENT_SECRET=$(CQ_UAP_CLIENT_SECRET) \
-e CQ_TEST_PLAN_BUNDLE_MODE=$(CQ_TEST_PLAN_BUNDLE_MODE) \
-e CQ_UAP_AUTH_URL=$(CQ_UAP_AUTH_URL) \
-e CQ_TEST_RUN_CICD_LINK=$(BUILD_PIPELINE_URL) \
-e CQ_REPORT_SAVE_API_REQUESTS=true \
-e CQ_REPORT_SAVE_DIR=$(CQ_REPORT_SAVE_DIR) \
registry.gitlab.com/cequence/releases/api-testing/fury-runner:1.5.1
CONTAINER=$(docker ps -aq)
docker cp $CONTAINER:/app/results $(HOST_OUTPUT_PATH)
displayName: 'Cequence Security test'
env:
CQ_TEST_PLAN_ID: $(CQ_TEST_PLAN_ID)
CQ_TEST_TARGET_SERVER: $(CQ_TEST_TARGET_SERVER)
CQ_UAP_BASE_HOST: $(CQ_UAP_BASE_HOST)
CQ_UAP_CLIENT_ID: $(CQ_UAP_CLIENT_ID)
CQ_UAP_CLIENT_SECRET: $(CQ_UAP_CLIENT_SECRET)
CQ_TEST_PLAN_BUNDLE_MODE: $(CQ_TEST_PLAN_BUNDLE_MODE)
CQ_UAP_AUTH_URL: $(CQ_UAP_AUTH_URL)
CQ_TEST_RUN_CICD_LINK: $(BUILD_PIPELINE_URL)Replace the placeholder values in the command with the actual values.
Adding a file to the Azure DevOps pipeline
You can define the required environment variables in a separate file and update the Azure DevOps configuration file to include that file.
- Create a file named cq.env in the same path as your pipeline's configuration file.
-
Using a text editor, open the cq.env file and add the following lines.
CQ_TEST_PLAN_ID: <plan ID> CQ_TEST_TARGET_SERVER: <URL of target server> CQ_UAP_BASE_HOST: <FQDN of base host> CQ_UAP_CLIENT_ID: <client ID> CQ_UAP_CLIENT_SECRET: <client secret> CQ_TEST_PLAN_BUNDLE_MODE: CEQUENCE CQ_UAP_AUTH_URL: <Cequence UAP authentication URL> BUILD_PIPELINE_URL: $(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)" ARTIFACT_NAME: <Artifact name> CQ_REPORT_SAVE_DIR: '/app/results' DOWNLOAD_PATH: '$(Build.SourcesDirectory)/artifacts' HOST_OUTPUT_PATH: '$(System.DefaultWorkingDirectory)/cequence'Replace the placeholders in brackets (<>) with the actual information.
-
Open the configuration file for your Azure DevOps pipeline and add the following snippet.
resources: containers: - container: "registry.gitlab.com/cequence/releases/api-testing/fury-runner" image: 1.5.1 endpoint: Cequence-SC - job: cequence_security_test displayName: 'Cequence Security Test' steps: - task: DownloadSecureFile@1 inputs: secureFile: 'cq.env' - task: CopyFiles@2 inputs: SourceFolder: '$(Agent.TempDirectory)' Contents: cq.env TargetFolder: '$(System.DefaultWorkingDirectory)' - task: Docker@2 displayName: Pull the Fury runner image and run Test inputs: command: run containerRegistry: "Cequence-SC" image: registry.gitlab.com/cequence/releases/api-testing/fury-runner:1.5.1 arguments: -w /app --env-file ./cq.env registry.gitlab.com/cequence/releases/api-testing/fury-runner:1.5.1 node .
Your Azure DevOps pipeline is now integrated with Cequence API testing.
Examining API testing results
After Cequence API testing is integrated with Azure DevOps and a test run completes, report artifacts that contain information about the testing run are stored in the pipeline's Artifacts folder. The reports are JSON files named report.json and requests.json.
The report.json file is a high-level summary of the test run. The requests.json file contains a full test run dump of the API requests and responses.
To enable test results, modify the configuration file for your Azure DevOps pipeline by adding the following code.
- task: PublishBuildArtifacts@1
inputs:
pathToPublish: '$(HOST_OUTPUT_PATH)'
artifactName: $(ARTIFACT_NAME)
displayName: 'Publish Artifact'