CLI
Anleitungen
Scanverra CLI
Scannen Sie jede Codebasis von Ihrem Terminal oder Ihrer CI-Pipeline aus mit @scanverra/cli. Der Scan läuft auf Ihrem eigenen Rechner, an Scanverra werden nur die Ergebnisse gesendet.
Schnellstart
Nichts global installieren, oder npm i -g @scanverra/cli für einen dauerhaften scanverra-Befehl ausführen.
npx @scanverra/cli login # paste an API key from Dashboard > API keys npx @scanverra/cli scan .
So funktioniert es
Immer aktuell
Sie führen immer die neuesten Prüfungen aus, keine separate CLI-Version, die Sie manuell verfolgen oder aktualisieren müssen.
Dieselbe Engine wie das Dashboard
Die Ergebnisse entsprechen einem Scan, der in Scanverra gestartet wurde, unabhängig davon, wo Sie ihn ausführen.
Scannt lokal
Ihre Quelldateien werden auf Ihrem eigenen Rechner gelesen. Standardmäßig werden nur die Funde an Scanverra gesendet, nicht der Dateiinhalt oder die betroffenen Codezeilen.
Erscheint in Ihrem Dashboard
Jeder Scan erhält eine KI-geschriebene Zusammenfassung und einen Link, dieselbe Ergebnisseite wie ein im Dashboard gestarteter Scan.
Befehle
| Befehl | Beschreibung |
|---|---|
scanverra login | API-Schlüssel prüfen und speichern |
scanverra logout | Gespeicherten Schlüssel entfernen |
scanverra whoami | Konto und Plan hinter dem Schlüssel anzeigen |
scanverra scan [path] | Einen Ordner scannen (Standard: aktueller Ordner), Ergebnisse anzeigen und hochladen |
scanverra audit <url> | Geschwindigkeit einer Live-Website prüfen; mit --budget scheitern, wenn ein gespeichertes Budget verletzt wird |
Wichtige Optionen
| Option | Beschreibung |
|---|---|
--json / --sarif | Maschinenlesbare Ausgabe. SARIF funktioniert mit GitHub Code Scanning und dem Sonar-Import |
--fail-on <severity> | Mit Fehler beenden, wenn ein Fund dieser Schwere oder höher existiert (Standard: high) |
--fail-on-new, --baseline-branch <name>, --baseline-commit <sha> | Nur fehlschlagen, wenn dieser Scan im Vergleich zum zuletzt hochgeladenen Scan ein kritisches oder hohes Problem hinzufügt (das New-Code-Gate, für Pull Requests). Mit --baseline-branch main wird mit dem Zielbranch verglichen. Wurde dieser Branch noch nie gescannt, zählt jedes kritische oder hohe Problem als neu. Wenn bekannt, wird der Scan des Commits verwendet, von dem dein Branch abgezweigt wurde (per git merge-base oder --baseline-commit <sha>), damit spätere Fixes im Zielbranch nicht gegen dich zählen. Ersetzt --fail-on; erfordert einen Upload |
--category <list> | Nur security-, dependency-, iac- oder quality-Funde einschließen |
--exclude <glob> | Passende Pfade überspringen. Eine .scanverraignore-Datei wirkt genauso |
--no-upload | Nur scannen, keine Ergebnisse an Scanverra senden |
--include-code | Auch die betroffene Codezeile jedes Funds hochladen (standardmäßig aus) |
--offline | Zwischengespeicherte Regeln ohne Netzwerkzugriff verwenden |
--api-key, --api-url | Zugangsdaten oder Server überschreiben, nützlich in CI |
--save-budget <file> | Audit: Budget aus diesem Lauf speichern (Grenzwerte mit Spielraum + erlaubte Drittanbieter) |
--budget <file> | Audit: gegen ein gespeichertes Budget prüfen; Exit 1 bei jeder Verletzung |
Was hochgeladen wird
Dateipfade, Zeilennummern, Regel-IDs, Titel, Beschreibungen, Fix-Vorschläge, Schweregrade, Namen und Versionen von Abhängigkeiten sowie Projektname, Branch, Commit und PR-Nummer.
Dateiinhalte und die betroffene Codezeile jedes Funds. Secret-Funde enthalten nie den Secret-Wert selbst. Mit --include-code können betroffene Zeilen im Dashboard angezeigt werden.
Wie Dateien ausgewählt werden
- Innerhalb eines Git-Repositorys werden verfolgte und nicht verfolgte Dateien verwendet, .gitignore wird respektiert. Außerhalb von Git werden übliche Build- und Abhängigkeitsordner übersprungen.
- Eine .scanverraignore-Datei (ein Glob-Muster pro Zeile) und wiederholbare --exclude-Flags fügen weitere Ausschlüsse hinzu.
- Einen einzelnen Fund mit einem scanverra-ignore- oder nosec-Kommentar in der Zeile darüber unterdrücken.
Exit-Codes
| 0 | Erfolgreich, und kein Fund hat den --fail-on-Schwellenwert erreicht |
| 1 | Ein Fund hat den Schwellenwert erreicht, das Quality Gate ist mit --fail-on-gate fehlgeschlagen, oder der Scan hat mit --fail-on-new ein kritisches oder hohes Problem hinzugefügt |
| 2 | Benutzungsfehler, der Server hat den Schlüssel oder Plan abgelehnt, oder eine Schwachstellendatenbank war nicht erreichbar, sodass das Ergebnis nicht geprüft werden konnte (erneut ausführen) |
Einsatz in CI
Speichern Sie den API-Schlüssel als Secret, genau wie bei jeder anderen Scanverra-CI-Integration, und cachen Sie den Regelordner, damit ein neuer Runner sie nicht bei jedem Lauf erneut herunterlädt.
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with: { node-version: 24 }
- run: npx @scanverra/cli scan . --fail-on high
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}Regeln zwischen Läufen cachen
- uses: actions/cache@v4
with:
path: ~/.cache/scanverra
key: scanverra-rules-${{ github.run_id }}
restore-keys: scanverra-rules-Performance-Budget für Ihre Website
Committen Sie ein Budget aus einem guten Deployment. Jeder spätere Lauf lässt den Build scheitern, wenn die Seite langsamer oder schwerer wird oder ein neuer Drittanbieter auftaucht.
# once, from a good deploy:
scanverra audit https://staging.example.com --save-budget perf-budget.json
# in CI, after deploying a preview:
- run: npx scanverra audit "$PREVIEW_URL" --budget perf-budget.json
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}Fehlerbehebung
| Meldung | Was zu tun ist |
|---|---|
Not logged in | scanverra login ausführen oder SCANVERRA_API_KEY setzen |
API key was rejected | Der Schlüssel ist falsch oder wurde widerrufen. Einen neuen unter API-Schlüssel erstellen |
You have reached your free scan limit | Die kostenlosen Repo-Scanner-Scans dieses Monats sind aufgebraucht. Scannen Sie mit --no-upload, warten Sie bis zum nächsten Monat oder upgraden Sie. |
Daily limit for downloading the scanner rules reached | Regelordner in CI cachen, siehe oben |
No scannable files found | Pfad sowie .gitignore und .scanverraignore prüfen |
Bereit, vom Terminal aus zu scannen?
Erstellen Sie einen API-Schlüssel und führen Sie Ihren ersten Scan in weniger als einer Minute aus.