aquasecurity/trivy-action: Trivy-Scans fest in GitHub-Workflows verankern
Projektüberblick: Führt Trivy als GitHub-Aktion aus, um Ihr Docker-Container-Image auf Schwachstellen zu scannen.
Auf einen Blick
- Was ist das?
- Die GitHub Action kapselt den Trivy-Scanner für Container-Images, Dateisysteme, Git-Repos, IaC und SBOM: Inputs, trivy.yaml, Cache-Verhalten, SARIF-Anbindung, Private-Registry-Auth und dokumentierte Stolperfallen.
- Für wen ist es gedacht?
- trivy-action passt zu Teams, die Schwachstellen- und Secret-Scans direkt in GitHub-Workflows verankern wollen, ohne eigene Scanner-Installation zu pflegen, und dabei Container-Images, Dateisysteme, Git-Repos oder IaC-Konfigurationen prüfen. Weniger geeignet ist sie, wenn ein zentraler Scanner außerhalb der CI laufen soll oder wenn die Workflows die Action mehrfach aufrufen und eine ältere Version mit dem dokumentierten Eingaben-Leak im Einsatz bleibt.
- Darf ich es kommerziell nutzen?
- Ja. Apache-2.0 ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 28 Tagen.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich Shell, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 15. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Container-Images scannen mit aquasecurity/trivy-action@v0.36.0
aquasecurity/trivy-action ist eine GitHub Action, die den Trivy-Scanner des Projekts aquasecurity/trivy in Workflow-Schritte verwandelt. Der Einstieg im README ist ein Imagescan: Der Job checkt den Code mit actions/checkout@v4 aus, baut mit docker build ein Image, das mit dem Tag docker.io/my-organization/my-app:${{ github.sha }} versehen wird, und ruft dann aquasecurity/trivy-action@v0.36.0 auf.
Die Inputs in diesem Beispiel sind aufschlussreich. image-ref nennt das zu prüfende Image, format table steuert die Ausgabe, und exit-code: '1' lässt den Job scheitern, sobald Findings in den gewählten Schweregraden auftauchen. ignore-unfixed: true blendet Schwachstellen aus, für die es kein Fix-Release gibt, was Fehlalarme im Alltag deutlich reduziert.
Die Repository-Metadaten nennen Shell als Sprache und Apache-2.0 als Lizenz, bei 1.406 Sternen und 357 Forks. Die Release-Historie zeigt einen engen Rhythmus: v0.35.0 erschien am 20. März 2026, v0.36.0 am 22. April 2026. Wer die Action referenziert, sollte den Versionstag fest pinnen, denn ein Float auf master zieht Verhaltensänderungen automatisch nach.
trivy.yaml als zentrale Steuerung: scan-type, scan-ref und die Viper-Priorität
Neben dem Imagescan zeigt das README einen fs-Scan, bei dem alle Optionen in einer Datei trivy.yaml liegen, die im Repo eingecheckt ist. Der Action-Aufruf reduziert sich dann auf scan-type: 'fs', scan-ref: '.' und trivy-config: trivy.yaml. Die Beispieldatei setzt format json, exit-code 1, severity CRITICAL und verweist mit secret.config auf eine eigene Datei config/trivy/secret.yaml für die Secret-Erkennung.
Interessant ist die dokumentierte Prioritätskette, die Trivy über die Viper-Bibliothek auflöst: GitHub-Action-Flag zuerst, dann Umgebungsvariable, dann Konfigurationsdatei, dann Standardwert. Drei Inputs lassen sich laut README nicht über die Config-Datei abdecken und gehören immer in den Aufruf: scan-ref für fs- und repo-Scans, image-ref für den Imagescan und scan-type für die Wahl des Modus.
Die Standardeinstellungen der Eingabetabelle erklären manches Überraschungsmoment: format steht auf table, exit-code auf 0, severity umfasst UNKNOWN, LOW, MEDIUM, HIGH und CRITICAL. Wer einen strengen Gate will, muss also exit-code explizit auf 1 setzen, sonst protokolliert der Scan Findings nur, ohne den Build zu stoppen.
Caching der Vulnerability-DB in $GITHUB_WORKSPACE/.cache/trivy
Die Action bringt ein eingebautes Caching für die Vulnerability-DB, die Java-DB und das Checks-Bundle mit, sofern diese während des Scans heruntergeladen wurden. Der Cache liegt standardmäßig im Verzeichnis $GITHUB_WORKSPACE/.cache/trivy, wird vor dem Scan wiederhergestellt und nach dem Scan gespeichert. Unter der Haube arbeitet die Action mit actions/cache, verlangt aber weniger Konfiguration, und das Caching ist standardmäßig aktiv.
Abschalten lässt es sich mit dem Input cache: 'false', aber das README rät davon ab, um Rate-Limiting-Probleme zu vermeiden. Der Grund ist plausibel: Ohne Cache lädt jeder Job die Vulnerability-DB neu, und bei vielen Workflows summiert sich das schnell zu Drosselungen durch die Datenquellen.
Die Grenze des Cachings liegt in den Regeln von GitHub Actions selbst: Ein Workflow kann standardmäßig nur Caches aus dem aktuellen oder dem Default-Branch wiederherstellen. Für teamweite Wiederverwendung empfiehlt das README einen separaten Cron-Workflow, der täglich um Mitternacht UTC den Cache im Default-Branch aktualisiert, während der eigentliche Scan-Workflow mit den Umgebungsvariablen TRIVY_SKIP_DB_UPDATE und TRIVY_SKIP_JAVA_DB_UPDATE den Download überspringt. Das spart Zeit, koppelt aber die Scan-Frische an den Cron-Takt.
Setup-Kette über aquasecurity/setup-trivy und der Input skip-setup-trivy
Standardmäßig ruft die Action als ersten Schritt aquasecurity/setup-trivy auf, das die über den Input version gewählte Trivy-Version installiert. Wer Trivy bereits auf andere Weise installiert hat, etwa durch einen direkten Aufruf von aquasecurity/setup-trivy@v0.2.0 mit cache: true und version: v0.74.0, setzt den Input skip-setup-trivy, um die doppelte Installation zu vermeiden.
Das ist vor allem für Workflows relevant, die die Action mehrfach hintereinander aufrufen, etwa einmal für das Image und einmal für das Dateisystem. Ohne skip-setup-trivy würde jeder Aufruf die Setup-Kette erneut durchlaufen.
Ein Spezialfall betrifft GitHub Enterprise Server: Laut README ist dessen github.token für github.com ungültig, weshalb der Input token-setup-trivy existiert, um das Token zu überschreiben. Wer in einer Enterprise-Umgebung arbeitet, sollte diese Kombination vor der breiten Einführung in einem Test-Workflow durchspielen, denn genau solche Authentifizierungsdetails fallen selten in der Dokumentation des Hauptscanners auf.
SARIF-Berichte, html.tpl-Templates und der Weg in GitHub Code Scanning
Mehrere README-Beispiele verbinden die Action mit GitHub Code Scanning. Der Workflow setzt permissions mit contents: read und security-events: write, führt den Scan mit format sarif und einer Ausgabedatei aus und lädt das Ergebnis über github/codeql-action/upload-sarif hoch. Der Trick dabei: Wenn der Scan wegen exit-code 1 scheitert, lässt sich der Upload-Schritt mit if: always() trotzdem ausführen, damit die Findings im Security-Tab landen.
Alternativ unterstützt die Action Trivy-Templates über den Input template, dessen Pfad mit einem @-Zeichen präfixiert wird. Die Standard-Templates werden laut README von setup-trivy unter $HOME/.local/bin/trivy-bin/contrib installiert, das README zeigt als Beispiel das Template html.tpl aus diesem Verzeichnis.
Der praktische Unterschied: table-Ausgaben leben nur im Job-Log und verschwinden mit der Zeit, SARIF-Berichte bleiben im Security-Tab greifbar und werden über Runs hinweg vergleichbar. Wer Findings alsTickets nachverfolgen will, fährt mit SARIF besser als mit der Tabellenausgabe.
Private Registries mit TRIVY_USERNAME, AWS_SECRET_ACCESS_KEY und SBOM-Upload
Für Scans gegen private Registries dokumentiert das README die nötigen Umgebungsvariablen. Docker Hub verlangt TRIVY_USERNAME und TRIVY_PASSWORD, AWS ECR arbeitet mit AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY und AWS_DEFAULT_REGION, GCR nutzt GOOGLE_APPLICATION_CREDENTIALS, und selbst gehostete BasicAuth-Server verwenden ebenfalls TRIVY_USERNAME und TRIVY_PASSWORD, mit TRIVY_NON_SSL=true für Port 80.
Diese Zettelwirtschaft lässt sich vermeiden, wenn das Image bereits im Workflow gebaut wurde, denn ein lokaler Imagescan braucht keine Registry-Authentifizierung. Die Umgebungsvariablen fallen erst an, wenn Trivy ein Image aus einer privaten Registry ziehen soll.
Eine zweite Sparte ist die SBOM-Weitergabe: Mit format github und dem Input github-pat erzeugt die Action ein SBOM und übermittelt es an den GitHub Dependency Graph. Dafür benötigt der Workflow die Berechtigung contents: write, und das README zeigt, wie die erzeugte JSON-Datei zusätzlich als Artefakt hochgeladen wird. Damit erscheinen Abhängigkeiten im Dependency-Graph des Repos, was Lizenz- und Sicherheitsauswertungen außerhalb der CI erst ermöglicht.
IaC-Scans, Terraform-Module mit Git-Auth und ein Eingaben-Leak in alten Versionen
Der Modus scan-type: 'config' prüft Infrastruktur-as-Code-Dateien. Ein dokumentierter Haken: Verwendet die Terraform-Konfiguration private Module, muss Git für die Authentifizierung gegen das hostende Repository konfiguriert sein, etwa mit einem Personal Access Token oder SSH-Keys. Ohne diese Vorbereitung scheitert der Scan an Moduldownloads, nicht an Findings.
Das README beschreibt außerdem einen Bug älterer Action-Versionen, bei dem Inputs eines Aufrufs in nachfolgende Aufrufe übergehen konnten. Das betrifft Workflows, die die Action mehrfach aufrufen, denn dann kann der zweite Scan versehentlich die Konfiguration des ersten erben.
Als Prüfmethode nennt das README die Schrittinformationen der GitHub Action: Enthält der env-Abschnitt TRIVY_*-Variablen, die nie explizit gesetzt wurden, ist der Workflow möglicherweise betroffen und sollte auf die neueste Action-Version gehoben werden. Genau hier zeigt sich der Unterschied zwischen einem einmaligen Testlauf und dem Dauerbetrieb, denn der Leak fällt nur auf, wenn zwei Scan-Schritte mit unterschiedlichen Inputs im selben Job liegen.
Redaktionelles Fazit
trivy-action passt zu Teams, die Schwachstellen- und Secret-Scans direkt in GitHub-Workflows verankern wollen, ohne eigene Scanner-Installation zu pflegen, und dabei Container-Images, Dateisysteme, Git-Repos oder IaC-Konfigurationen prüfen. Weniger geeignet ist sie, wenn ein zentraler Scanner außerhalb der CI laufen soll oder wenn die Workflows die Action mehrfach aufrufen und eine ältere Version mit dem dokumentierten Eingaben-Leak im Einsatz bleibt. Wer sie einführt, sollte zuerst die Version v0.36.0 pinnen, die Vorgehensweise aus den README-Beispielen mit exit-code und ignore-unfixed gegen die eigene Pipeline testen und den Cache im Default-Branch per Cron-Workflow aktuell halten, bevor TRIVY_SKIP_DB_UPDATE im Scan-Workflow gesetzt wird.
Community-Notizen