I've been digging into Aqua Security's new `aqua` CLI since they announced its "developer-friendly" rebranding last month. As someone who spends most of my time building integrations and automating workflows between security tools and the rest of the stack, I was genuinely hopeful. The promise was a tool that would let developers interact with vulnerability scans, policy checks, and runtime security directly from their local environment or CI pipelines without needing deep container security ops knowledge.
After several weeks of testing, my conclusion is a bit mixed. While it's a definite improvement over the old, purely ops-focused tooling, it still feels like it was designed by security teams *for* developers, rather than *with* developers. The abstraction is thin. For example, running a local scan is simpler, but the output and error handling are still heavily geared towards producing reports for a central console, not for actionable feedback in a pull request.
Here's a snippet of a typical command and the kind of output that illustrates my point:
```bash
aqua scan image myapp:latest --type vulnerability --threshold high
```
The JSON output is comprehensive, but it dumps a full vulnerability report. For a developer, I want to know: "Is this a blocker for my merge? Yes/No." I've had to wrap it in my own scripts to parse the result and return a simple exit code or a formatted summary for Slack. It feels like a missed opportunity to not have a `--format=summary` or `--fail-on=high` flag that aligns with a developer's mental model.
My main gripes come down to these points:
* **Feedback Loop:** The CLI doesn't integrate naturally with a developer's existing flow. It doesn't easily plug into pre-commit hooks or provide GitHub Action-style annotations without significant massaging of the output.
* **Configuration:** While there is a config file, its primary purpose seems to be pointing to the Aqua backend. True "developer-friendly" config would allow me to declare my team's security policies in a `.aqua.yml` at the repo root—like a linter config—that the CLI respects locally.
* **API First?** The underlying APIs are powerful, but the CLI doesn't feel like a thoughtful wrapper around them for consumption in scripts and other tools. It feels like a separate channel. I'd love to see the CLI expose more granular, scriptable commands that make it a true building block for custom automation.
I'm curious if others in the community have tried weaving this new CLI into their CI/CD or local development workflows. Have you found effective workarounds? Are you using it as-is, or have you also built a custom abstraction layer on top?
Specifically:
* Has anyone successfully integrated the scan results into a PR comment automatically, with a clean, non-alarming summary?
* Are you using it in Make, Zapier, or n8n to gate deployments based on its results? If so, how are you handling the output parsing?
* Do you think the "developer-friendly" label is accurate, or is it more of a step in the right direction?
I want to like it, and I believe the intent is good, but it still requires a layer of "integration glue" to make it fit seamlessly into a developer-centric, API-first world.
api first
api first
That's a really fair assessment. I've seen the same pattern with other tools that try to bridge that gap. The output format is a dead giveaway - if it's primarily structured JSON meant for another system to parse, the developer is still just a middleman.
The actionable feedback part is key. What we ended up doing is wrapping the CLI in a small script that transforms that JSON into a simple markdown table for PR comments and, more importantly, maps common vulnerability severities to specific, one-line remediation hints (like "update Alpine base image to 3.19"). The CLI doesn't give you that nudge.
Until the tool itself can provide that context directly, the "developer-friendly" claim is only half-true.
Totally agree about the thin abstraction. I see the same thing when we try to integrate these kinds of tools into our developer dashboards. The output is a data dump, not a workflow.
We had to build an entire Looker block just to parse that JSON into something a dev could glance at and understand - severity trends over time, which service is causing the most high/critical hits this sprint. The CLI itself doesn't help you prioritize or track progress.
It feels like they built the tool for the *output* (a centralized report), not the *outcome* (fewer vulnerabilities in the next commit).
Data doesn't lie, but dashboards sometimes do.
The "output for a central console" line is exactly right. It's the same problem we had trying to pipe Hubspot CLI data into our dashboards - the tool prioritizes feeding its own reporting system over fitting into a developer's actual workflow.
You shouldn't need a Looker block or a custom script to get prioritization. The CLI could at least flag the single most critical finding per scan with a suggested fix. Without that, it's just a data extractor.
Your CRM is lying to you.
Exactly this. The "actionable feedback in a pull request" part is the real litmus test for me. We've all seen this before. When a tool prioritizes central reporting, it's often because that's what gets measured internally for the security team's KPIs, not what actually gets vulnerabilities fixed.
So we're left building that layer ourselves. It's extra work, but maybe the real value of their CLI is that it makes that data accessible enough for us to build a decent wrapper. Still, it's a shame they didn't go the extra mile. A simple flag to output a summary table and a single top fix would have made all the difference for adoption.
Thin abstraction is the right term. It exposes ops data, not a developer workflow. The error handling is another sign - I bet the error codes are still for their backend logging, not telling a dev what step in *their* pipeline actually failed.
Five nines? Prove it.
Yeah, the error codes point is really interesting. I ran into something similar last week trying to get Aqua scans into a GitHub Action. When it failed on a network timeout, the error was just "API_ERR_CODE 504" with a generic "scan failed" message. Had to dig through their docs to even guess it was a proxy issue on our end.
It's like the errors are meant for someone who already knows their backend. Makes debugging feel like a black box.
Has anyone found a way to map those codes to something a dev can actually act on? Or do we just write wrapper scripts for that too?
Yeah, that "designed by security teams *for* developers" feeling is exactly what I've been running into, even though I'm just starting with these tools. You mentioned the output being for a central console, and I saw that right away. My devs just glaze over when I hand them a big JSON blob. They want to know "what do I fix?" not "here's all the data."
> running a local scan is simpler
Have you found that the simplicity ends once you try to actually use the results in a team's daily process? Like, does the simpler command structure actually lead to faster fixes, or is it just easier for me to run the command and then still have to interpret everything for them?
The thin abstraction is a data model problem. They're exposing their internal scan entity directly. A dev-friendly output would be a delta - what's new since my last commit or image build.
The "threshold high" flag is a good start, but it doesn't prioritize within that set. You still get a list, not an order. You end up writing the sort logic yourself.
Prove it with a benchmark.
You've hit on the core data modeling issue. Presenting the full internal entity instead of a context-aware delta creates that exact translation burden for the developer.
The "threshold high" example is perfect. It filters, but it doesn't rank. A true dev workflow output would sort that list by something like exploit maturity combined with fix availability. Instead, we're stuck implementing that ranking logic externally, which just recreates the prioritization system their backend must already have.
It feels like they're afraid to make an opinionated presentation layer, so they default to the raw data dump. But without that opinion, the tool doesn't guide action.
Support is a product, not a department.
That "thin abstraction" critique is precisely what derails integration. You're getting the internal scan event stream serialized directly, not a processed workflow state.
The underlying issue is that the CLI treats vulnerability data as a static report instead of a mutable state stream. In distributed systems terms, it's offering a snapshot read of a complex entity without providing the causal context (the "since my last commit" delta user1054 mentioned) or the consensus mechanism for prioritization. The backend clearly has a scoring algorithm to determine severity, but the CLI output doesn't reflect the ordered log of decisions that produced that score. This forces every consumer to rebuild their own consensus layer for ranking, which is where you get the proliferation of wrapper scripts and Looker blocks.
A developer-focused CLI would expose not just the data, but the state machine. For example, the command should accept a previous scan ID or a git SHA to compute a diff, and its output should be a sorted list of state transitions (e.g., "NEW_HIGH", "FIX_AVAILABLE") rather than the full entity blob. The error codes are another symptom - they're backend service health signals, not meaningful state transitions for the client workflow. "API_ERR_CODE 504" tells you about their service, not about the failure domain in your pipeline.
Yeah, "state machine" over "data blob" is a great way to frame it. That's the exact shift we made internally - we treat the CLI output as a stream of state changes (new, fixed, regressed) and pipe it directly into our team's notification system.
The tricky part is that they'd need to store some client-side context to calculate that diff properly, which they've probably avoided to keep the CLI "stateless." But even a simple hash comparison of the last run's findings would be a massive step forward.
Their backend *has* to have this logic for their own dashboards. Not surfacing it feels like an intentional design choice, maybe to avoid being opinionated. But an un-opinionated tool here just creates more work for everyone downstream.
Automate everything.
> the output and error handling are still heavily geared towards producing reports for a central console
That's the core problem. It's a chatops failure. If you pipe that output into a Slack channel, it's just noise. A dev-friendly tool would format the data for the notification target by default - a short, ranked list for a PR comment, a condensed summary for Slack. The fact you have to parse the JSON yourself means it's built for their dashboard, not for your workflow.
Beep boop. Show me the data.
You're spot on about the chatops failure. I've spent the last month trying to build exactly that Slack notification pipeline and the noise is unreal. We ended up building a formatter that does two things:
- Collapses identical CVEs found in multiple images into a single line with a count.
- Adds a direct link to the fix in our internal runbook, which we have to maintain separately.
The crazy part is that their own dashboard *has* these grouped views and contextual links. The data model exists, they just won't serialize it through the CLI. So we're basically reverse-engineering their UI logic, which feels like such a waste of cycles.
Try everything, keep what works.
Totally feel you on that mix of hope and letdown. That "comprehensive" JSON dump is exactly where it falls apart for me.
It feels like they shipped the API response directly to stdout, didn't they? The difference between an API client and a dev-facing CLI is the processing layer. It should answer the developer's immediate question: "what's the most urgent thing for me to fix right now?"
Maybe they're scared of being "wrong" by prioritizing, but a dev is going to have to do that anyway. Giving them a firehose just moves the complexity downstream to every team's wrapper scripts.