Having recently orchestrated a large-scale container platform migration with a significant shift-left security requirement, I found integrating Aqua Security into the CI/CD pipeline to be one of the more nuanced aspects of the project. The documentation is comprehensive but can be overwhelming for those new to the Aqua ecosystem. For those embarking on this within Azure DevOps, the process hinges on understanding three core components: the scanner, the enforcer concept translated to pipeline gates, and the correct configuration of the Aqua CLI.
The primary vehicle is the Aqua Security Scanner for Azure DevOps extension, available in the marketplace. Installation is straightforward, but the critical work lies in the service connection and pipeline task configuration. You must first establish a service principal or API key in your Aqua CSPM console (SaaS) or your self-hosted Aqua server. This credential is used to create an Azure DevOps service connection of type `AquaSecurity`.
Here is a minimal, yet functional, example of a `azure-pipelines.yml` stage that incorporates scanning:
```yaml
- stage: Security_Scan
displayName: 'Container Image Scan'
jobs:
- job: Scan
displayName: 'Scan with Aqua'
pool:
vmImage: 'ubuntu-latest'
steps:
- task: AquaSecurity@1
inputs:
aquaServiceConnection: 'your-aqua-service-connection-name'
image: '$(registry)/$(imageName):$(tag)'
command: 'scan'
failBuild: true
criticalThreshold: '1'
highThreshold: '10'
```
The `failBuild` and threshold parameters are crucial for policy enforcement; they move security from a passive report to an active gate. You will also need to consider the scan timing. Scanning after the `docker build` but before the `docker push` to your production registry is typical, but you may also want a faster, less sensitive scan on PR builds and a full, deep scan on merges to your main branch.
Beyond the simple scan, you must also integrate Trivy for vulnerability scanning and the `aqua` CLI for richer compliance checks if your policies require it. This often involves a multi-step job:
* **Step 1:** Build the Docker image.
* **Step 2:** Scan the image with the Azure DevOps Aqua task (which leverages the scanner behind the scenes).
* **Step 3:** Use a script task to run the `aqua` CLI for specific compliance checks (e.g., ensuring no packages from a denylist are present).
* **Step 4:** Push the image only if all previous steps succeed.
A common pitfall is misconfiguring the service connection URL; for SaaS, it is typically ` https://csp.aquasec.com`, while for on-premises it's your server URL. Another frequent issue is not accounting for the scanner's pull of the latest vulnerability database, which can add time to the pipeline run. I recommend using a dedicated, persistent VM agent pool with the Aqua scanner pre-installed if scan performance becomes a bottleneck.
Ultimately, the goal is to translate your Aqua runtime policies (like prohibited binaries, CVSS score thresholds, malware presence) into pipeline failures. Start by implementing a single, critical policy (e.g., critical vulnerabilities > 0) in a non-production pipeline, observe the output, and then iteratively add policy complexity. This approach provides immediate value while building the operational knowledge necessary for more sophisticated governance later in your cloud-native journey.
That service connection is the main blocker. People miss the permission scope needed on the Aqua side.
> minimal, yet functional example
Your yaml snippet got cut off, but the key flag everyone forgets is `--show-all`. Without it, the pipeline task might pass even with findings if they're below the threshold, which isn't useful for a gate.
Also, run it as an early stage, not post-build. If you scan the image after pushing to a registry, you're already too late. Use the dockerfile scan task on the source before you even build.
Benchmarks or bust.
Great point about the service connection being the main blocker. I'd add that the permissions issue often bites teams because the Aqua API key needs the "Scanner" role at minimum, but for pipeline gates to work properly, it also needs read access to the specific policies you're trying to enforce. A key with just global scanner rights might connect but then fail to pull policy details.
Also, totally second running it early. We actually run the scanner in two spots: a lightweight dockerfile scan right after checkout, then the full image scan after the build but before we push to any staging registry. Catching issues before the build saves a ton of pipeline runtime.
Automate the boring stuff.
> You must first establish a service principal or API key in your Aqua CSPM console (SaaS) or your self-hosted Aqua server.
Is the service connection process the same for both SaaS and self-hosted? I've only used the SaaS version and the docs imply the steps are identical, but the endpoint URL must be different for an on-prem server. Could a wrong URL here cause the vague permissions errors the others mentioned?
Yes, a wrong endpoint absolutely causes those vague permissions errors. The API call fails at the network layer before it even tries authentication.
For SaaS, it's always ` https://.aquasec.com`. For self-hosted, it's your server's base URL, like ` https://aqua.mycompany.internal`. The Azure DevOps service connection task won't validate the URL format for you. It just passes it to the CLI.
Double-check the console URL you use to log in. That's your endpoint.
Data over opinions