Repository navigation
Native Vulnerability & Misconfiguration Scanning (Trivy Integration) #97
Description
Summary
I propose integrating Trivy by Aqua Security natively into Compose Manager Plus. Trivy is a lightweight, open-source scanner that requires no cloud authentication and can scan both container images (for CVEs) and Compose files (for IaC misconfigurations).
Detailed description
As Unraid homelabs grow, security observability becomes a major blind spot. Users often run dozens of Docker Compose stacks without knowing if they are running outdated images with critical CVEs, or if their docker-compose.yml files contain severe misconfigurations (e.g., unnecessary privileged: true, exposed sensitive ports, or root user definitions). Currently, discovering this requires setting up complex third-party tools or running manual CLI commands.
Describe the solution you'd like:
I propose integrating Trivy by Aqua Security natively into Compose Manager Plus. Trivy is a lightweight, open-source scanner that requires no cloud authentication and scans both container images (for CVEs) and Compose files (for IaC misconfigurations).
By integrating this, Compose Manager Plus could become an all-in-one DevSecOps tool tailored for the Unraid community.
🖥️ Proposed Interface & UX Concept
The integration could add a "Security" dimension to the plugin, visualized in the following ways:
- At-A-Glance Badges: Add a small shield icon (🟢 Green, 🟡 Yellow, 🔴 Red) next to the stack names on the main Compose Manager page so users immediately know their security posture.
- Global Security Dashboard (The "Leaderboard"): A new tab featuring graphs (using Unraid's native styling or Chart.js) showing the total breakdown of vulnerabilities across all stacks. Include a "Hall of Shame" table that ranks stacks/images by their vulnerability score, allowing users to prioritize updates.
- Stack-Level Security Report: Inside individual project views, add a "Security" tab. Users can expand specific "Critical" vulnerabilities to see the exact package, CVE description, and crucially, the Fixed Version (so they know if pulling a new image will actually solve the problem).
- Unraid Native Notifications (Community Value-Add): Allow users to schedule weekly scans. If a new Critical vulnerability is detected in a public-facing container (like Nginx Proxy Manager or Nextcloud), trigger an Unraid system notification (which routes to the Unraid app/Discord/Telegram).
⚙️ High-Level Deployment Strategy (How to build it elegantly)
While users could run Trivy as a separate Docker container, that approach is clunky, requires manual socket mounts, and fractures the UI. Native plugin integration is much cleaner:
- Installation via
.plg: During plugin installation/update, the.plgscript simply downloads the latest standalone Linuxtrivybinary into/usr/local/bin/. No daemon or dependencies are required. - Flash Drive Protection (Crucial for Unraid): Trivy downloads a vulnerability DB. To prevent wearing out the Unraid USB flash drive, the plugin must configure Trivy to cache this DB in RAM (
/tmp/trivy-db) or allow the user to specify a path on their cache drive (e.g.,/mnt/user/appdata/compose.manager/trivy). - Execution (Backend): When a user triggers a scan, PHP runs:
trivy image -f json <image_name>(for container CVEs)trivy config -f json /path/to/stack/(for Compose misconfigurations)
- Parsing (Frontend): Because Trivy outputs clean JSON, the PHP backend can simply use
json_decode()and pass the arrays directly to the frontend to render the graphs and tables.
Alternatives considered
- Docker Scout: Focuses mostly on images, requires a Docker Hub account/authentication, and adds friction for privacy-conscious homelab users.
- Separate Trivy Container: Forces the user to configure Docker socket mounts manually and jump between different web UIs, ruining the unified experience Compose Manager Plus provides.
Additional context:
Making security actionable and visible right inside the Unraid UI would make this plugin an absolute must-have for the community. Having a visual graph of CVEs and alerting users to misconfigurations would elevate the security standard of Unraid homelabs everywhere. I'd love to hear your thoughts on this!
Activity
lordraiden commentedon Apr 15, 2026
Proposal: Native Trivy-Based Security Scanning in Compose Manager Plus
Summary
Compose Manager Plus should add native security scanning for stack images using Trivy.
This is not feature creep. It is a direct extension of what the plugin already does well: it is the control plane for Docker Compose stacks on Unraid. It already knows what stacks exist, what images they use, what containers are running, and what the operational state is. The next logical step is to expose the security state of those same stacks.
Right now, Compose Manager Plus answers:
It should also answer:
That would move the plugin from being a convenience layer to being the default operational dashboard for Compose-based homelabs on Unraid.
Problem
As Unraid homelabs scale, users accumulate large numbers of Compose stacks and usually lose visibility into the security posture of the images those stacks depend on.
At that point, security becomes reactive and fragmented:
This is exactly the kind of operational gap Compose Manager Plus is in a unique position to close.
Why this belongs in Compose Manager Plus
Compose Manager Plus already owns the correct abstraction layer: the stack.
That matters because users do not think in terms of isolated images. They think in terms of:
If security is exposed anywhere, it should be exposed at that same level.
A separate Trivy container or external dashboard is possible, but it is the wrong user experience:
If this ships natively, users will actually use it.
Scope
This proposal is intentionally opinionated:
v1 should focus on image security scanning grouped by stack.
Not Compose linting.
Not full IaC policy evaluation.
Not external dashboards.
Just:
That is enough to deliver immediate value without overcomplicating the architecture.
Why Trivy
Trivy is the right fit because it is:
That makes it suitable for native plugin integration rather than forcing a secondary containerized workflow.
Product outcome
If implemented correctly, Compose Manager Plus becomes the place where an Unraid user can answer all of the following in one interface:
That is a major jump in practical value.
Implementation plan
1. Core design decision
The scanner should operate on resolved stack images, not just currently running containers.
That is the correct design because it allows:
The stack remains the primary UI grouping, but the scan unit becomes the unique image.
That gives the plugin the best of both worlds:
2. Proposed file additions
Extend existing files:
3. Settings
Add the following to
default.cfg:Storage strategy
/boot/config/plugins/.../mnt/user/appdata/...or/tmp/...This is not optional. Writing the Trivy cache/DB to flash would be the wrong default for Unraid.
4. Stack image resolution
The plugin should resolve images directly from the Compose stack context.
Example approach:
This should be the canonical source of image membership for a stack.
Do not rely only on running containers. That would miss stopped stacks and make the feature feel inconsistent.
5. Unique-image scan planning
Once images are resolved per stack, the plugin should build a global unique scan plan.
This matters because shared images are common across homelabs:
Scanning each unique image once is the obvious architecture.
6. Trivy execution layer
The backend should wrap Trivy as a local binary and normalize its output.
The plugin should treat Trivy as an engine, not as a UI source of truth. All frontend-facing data should be normalized first.
7. Normalized result model
The raw Trivy JSON should be transformed into a plugin-specific schema.
This is the correct place to flatten, sort, and trim the Trivy output so the frontend does not need to understand Trivy internals.
8. Persisted status model
Security should be persisted the same way update-state is persisted: lightweight, file-backed, and easy to hydrate into the UI.
Suggested shape:
{ "generatedAt": 1776218400, "stacks": { "nextcloud": { "badge": "red", "score": 92, "summary": { "critical": 3, "high": 11, "medium": 28, "low": 14 }, "images": { "nextcloud:29-apache": { "critical": 2, "high": 7, "medium": 18, "low": 9, "lastScanned": 1776218400 }, "redis:7-alpine": { "critical": 1, "high": 4, "medium": 10, "low": 5, "lastScanned": 1776218400 } } } }, "images": { "nextcloud:29-apache": { "counts": { "CRITICAL": 2, "HIGH": 7, "MEDIUM": 18, "LOW": 9, "UNKNOWN": 0 }, "vulnerabilities": [] } } }This gives the plugin:
9. AJAX actions
This should be wired into
exec.phpusing the same pattern as other plugin actions.This is the right integration point because it preserves the plugin’s current request/response model.
10. Badge model
Do not over-engineer this. Users need immediate clarity.
Badge semantics
That is enough.
11. Main stack list integration
Security should be visible on the main page immediately.
Example addition in
compose_list.php:CSS:
If the feature ships but users have to click three levels deep to see it, adoption will be weaker. The main stack list is the correct place for the first signal.
12. Frontend hydration
The saved security state should hydrate into the UI the same way update status already does.
This should be automatic on page load. Not a secondary action.
13. Stack-level Security tab
Each stack should get a dedicated Security tab with three sections.
Summary
Images
Findings
Example findings table:
The key operational field here is fixed version. Without that, the UI is informative but not actionable.
14. Global dashboard
The plugin should also expose a global security dashboard built entirely from the persisted status JSON.
Suggested widgets:
Simple server-side shape:
This can start as plain tables and counters. Fancy charts can wait.
15. Scheduled scans
A scheduled security workflow is necessary, but it must be disciplined.
The job should:
security-status.jsonExample:
Overlapping scans should not happen.
16. Notifications
Notifications should be diff-based, not state-based.
Users do not need a weekly reminder that the same known issue still exists. They need to know when:
Example diff logic:
That keeps notifications useful instead of turning them into background noise.
17. Plugin installation flow
The
.plgshould install Trivy as a standalone binary.This is the correct operational model:
Rollout recommendation
Phase 1
.plgPhase 2
Phase 3
This sequence delivers value early and avoids blocking on secondary features.
Alternatives considered
Separate Trivy container
Rejected as the primary solution.
It works technically, but it is the wrong UX:
Docker Scout
Useful in general, but not the best default for this use case:
Final position
This should not be treated as a “nice to have.”
For the kind of users Compose Manager Plus targets, this is a natural and high-value capability:
Adding native Trivy-based image scanning would make Compose Manager Plus not just a Compose UI, but the central operational and security console for Docker Compose on Unraid.
That is a meaningful product upgrade, not just another checkbox feature.
mstrhakr commentedon Apr 15, 2026
I see a thumbs down on this but I'm curious. This may be better suited to a new plugin that handles docker and compose in one plugin. I do like the idea of some kind of security scan/warnings for common issues in compose files though. This will likely not be implemented right away though.