gitguardian/ggshieldErkenne und validiere über 500 Arten von hartkodierten Geheimnissen mit erweiterten Prüfungen. Nutze es als Pre-Commit-Hook, GitHub Action oder CLI zur proaktiven Geheimniserkennung und Sicherheit.
# [ggshield](https://github.com/GitGuardian/ggshield): Schützen Sie Ihren Code mit GitGuardian
[](https://pypi.org/project/ggshield/)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
[](https://github.com/GitGuardian/ggshield/stargazers)
[](https://github.com/GitGuardian/ggshield/actions)
[](https://codecov.io/gh/GitGuardian/ggshield/)
> [!IMPORTANT]
> **macOS: Das Upgrade auf 1.54.0 löst eine Keychain-Abfrage für `ggshield-py` aus**, eine zweite Binärdatei, die nun im Rahmen unserer Leistungsverbesserungen Ihr gespeichertes Token liest. Klicken Sie auf **Immer erlauben**; es wird nicht erneut gefragt.
`ggshield` ist eine CLI-Anwendung, die in Ihrer lokalen Umgebung oder in einer CI-Umgebung ausgeführt wird, um Ihnen zu helfen, mehr als 500+ Arten von Secrets zu erkennen.
`ggshield` verwendet unsere [öffentliche API](https://api.gitguardian.com/docs) über [py-gitguardian](https://github.com/GitGuardian/py-gitguardian), um Dateien und andere Textinhalte auf potenzielle Schwachstellen zu scannen und zu erkennen.
Bei Scans mit `ggshield` werden nur Metadaten wie Aufrufzeit, Anfragegröße und Scanmodus gespeichert, daher werden Secrets nicht in Ihrem Dashboard angezeigt und **Ihre Dateien und Secrets werden nicht gespeichert**.
# Inhaltsverzeichnis
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Installation](#installation)
- [Installationsskript (Empfohlen)](#installationsskript-empfohlen)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Eigenständiges .pkg-Paket](#eigenständiges-pkg-paket)
- [Linux](#linux)
- [Deb- und RPM-Pakete](#deb-und-rpm-pakete)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [MSI-Installer](#msi-installer)
- [Eigenständiges .zip-Archiv](#eigenständiges-zip-archiv)
- [Alle Betriebssysteme](#alle-betriebssysteme)
- [Verwendung von pipx](#verwendung-von-pipx)
- [Verwendung von pip](#verwendung-von-pip)
- [Ersteinrichtung](#ersteinrichtung)
- [Verwendung von `ggshield auth login`](#verwendung-von-ggshield-auth-login)
- [Manuelle Einrichtung](#manuelle-einrichtung)
- [Erste Schritte](#erste-schritte)
- [Secrets](#secrets)
- [Migration einer Legacy-Konfigurationsdatei](#migration-einer-legacy-konfigurationsdatei)
- [Integrationen](#integrationen)
- [KI-Codierungsassistenten](#ki-codierungsassistenten)
- [Mehr erfahren](#mehr-erfahren)
- [Ausgabe](#ausgabe)
- [Verwandte Open-Source-Projekte](#verwandte-open-source-projekte)
- [Lizenz](#lizenz)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Installation
<!--
Any change made in this section must be replicated in the "Step 1: Install
ggshield" section of the "Getting started" page of ggshield public
documentation.
-->
## Installationsskript (Empfohlen)
Der schnellste Weg, `ggshield` zu installieren.
Linux / macOS:
```shell
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
```
Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
```
Oder, wenn Sie `curl` bevorzugen (in Windows 10+ enthalten):
```powershell
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
```
Das Skript akzeptiert Optionen wie `--instance` und `--plugin` (Installation eines
Plugins). Für den EU-Workspace oder eine selbst gehostete Instanz setzen Sie die
Umgebungsvariable `GITGUARDIAN_INSTANCE` (oder übergeben Sie `--instance <URL>`)
vor der Ausführung.
Siehe [`scripts/install/README.md`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md) für die vollständige Liste
der Optionen, die anderen Installationsmethoden und wie Sie deinstallieren können.
Die folgenden Methoden installieren die CLI stattdessen manuell.
## macOS
### Homebrew
Sie können `ggshield` mit Homebrew installieren:
```shell
brew install ggshield
```
Das Upgrade wird von Homebrew übernommen.
### Eigenständiges .pkg-Paket
Alternativ können Sie ein eigenständiges .pkg-Paket von der [`ggshield`-Release-Seite](https://github.com/GitGuardian/ggshield/releases) herunterladen und installieren.
Dieses Paket erfordert _nicht_ die Installation von Python, aber Sie müssen neue Versionen manuell herunterladen.
## Linux
### Deb- und RPM-Pakete
Deb- und RPM-Pakete sind auf [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/) verfügbar.
Einrichtungsanweisungen:
- [Deb-Pakete](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [RPM-Pakete](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
Das Upgrade wird vom Paketmanager übernommen.
## Windows
### Chocolatey
`ggshield` ist über den [Chocolatey-Paketmanager](https://chocolatey.org/packages/ggshield) verfügbar:
```shell
choco install ggshield
```
### MSI-Installer
Laden Sie den MSI-Installer von der [`ggshield`-Release-Seite](https://github.com/GitGuardian/ggshield/releases) herunter und installieren Sie ihn:
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### Eigenständiges .zip-Archiv
Wir stellen ein eigenständiges .zip-Archiv auf der [`ggshield`-Release-Seite](https://github.com/GitGuardian/ggshield/releases) bereit.
Entpacken Sie das Archiv auf Ihrer Festplatte und fügen Sie dann das Verzeichnis, das die Datei `ggshield.exe` enthält, zu `%PATH%` hinzu.
Dieses Archiv erfordert _nicht_ die Installation von Python, aber Sie müssen neue Versionen manuell herunterladen.
## Alle Betriebssysteme
`ggshield` kann auf allen unterstützten Betriebssystemen über sein [PyPI-Paket](https://pypi.org/project/ggshield) installiert werden.
Es erfordert **eine unterstützte Version von Python (nicht EOL)** (außer bei eigenständigen Paketen) und git.
Wenn Sie nicht unsere paketierten Versionen von `ggshield` verwenden, beachten Sie bitte, dass wir dem [Python-Release-Zyklus](https://devguide.python.org/versions/) folgen und Versionen, die EOL erreicht haben, nicht unterstützen.
### Verwendung von pipx
Der empfohlene Weg, `ggshield` von PyPI zu installieren, ist die Verwendung von [pipx](https://pypa.github.io/pipx/), das es in einer isolierten Umgebung installiert:
```shell
pipx install ggshield
```
Um Ihre Installation zu aktualisieren, führen Sie aus:
```shell
pipx upgrade ggshield
```
### Verwendung von pip
Sie können `ggshield` auch von PyPI mit pip installieren, aber dies wird nicht empfohlen, da die Installation nicht isoliert ist, sodass andere Anwendungen oder auf diese Weise installierte Pakete Ihre `ggshield`-Installation beeinträchtigen können. Diese Methode funktioniert auch nicht, wenn Ihre Python-Installation als extern verwaltet deklariert ist (zum Beispiel bei Verwendung des System-Python auf Betriebssystemen wie Debian 12):
```shell
pip install --user ggshield
```
Um Ihre Installation zu aktualisieren, führen Sie aus:
```shell
pip install --user --upgrade ggshield
```
# Ersteinrichtung
## Verwendung von `ggshield auth login`
Um `ggshield` zu verwenden, müssen Sie sich bei den GitGuardian-Servern authentifizieren. Verwenden Sie dazu den Befehl `ggshield auth login`. Dieser Befehl automatisiert die Bereitstellung eines persönlichen Zugriffstokens und dessen Konfiguration auf der lokalen Workstation.
Weitere Informationen finden Sie in der [Dokumentation zu `ggshield auth login`](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).
Führen Sie nach der Authentifizierung `ggshield machine setup` aus, um KI- und Git-Hooks zu konfigurieren, Honeytokens zu platzieren und die Maschine auf der Endpoints-Seite vor ihrem ersten Scan zu registrieren. Die Registrierung umfasst den aktuellen Benutzer oder alle Honeytoken-Zielbenutzer, wenn sie als root ausgeführt wird. Sie erfolgt nach bestem Bemühen, dauert höchstens fünf Sekunden und hat keinen Einfluss auf den Exit-Code des Befehls.
Die Scans von `ggshield secret scan pre-commit`, `pre-push` und `ai-hook` senden auch den Hostnamen der Maschine, von dem aus GitGuardian die Benutzer dieser Hooks registriert. Andere Scan-Befehle senden ihn nicht, ebenso wenig wie der native KI-Hook, den eigenständige und plattformspezifische `pip`-Installationen ausführen.
In CI registriert ggshield weder die Maschine noch sendet es den Hostnamen. Um beides anderswo zu deaktivieren, setzen Sie `endpoint_registration: false` in `.gitguardian.yaml` oder setzen Sie `GGSHIELD_NO_ENDPOINT_REGISTRATION` auf einen nicht leeren Wert.
## Manuelle Einrichtung
Sie können Ihr persönliches Zugriffstoken auch manuell erstellen und in der Umgebungsvariable `GITGUARDIAN_API_KEY` speichern, um die Einrichtung abzuschließen.
# Erste Schritte
## Secrets
Sie können `ggshield` jetzt verwenden, um nach Secrets zu suchen:
- in Dateien: `ggshield secret scan path -r .`
- in Repositories: `ggshield secret scan repo .`
- in Docker-Images (der Befehl `docker` muss verfügbar sein): `ggshield secret scan docker ubuntu:22.04`
- in Pypi-Paketen (der Befehl `pip` muss verfügbar sein): `ggshield secret scan pypi flask`
- und mehr, schauen Sie sich die Ausgabe von `ggshield secret scan --help` für Details an.
## Migration einer Legacy-Konfigurationsdatei
Wenn `ggshield` meldet, dass Ihre Konfigurationsdatei `.gitguardian.yaml` (oder `.gitguardian.yml`) ein veraltetes Format verwendet, migrieren Sie sie mit folgendem Befehl auf die neueste Version:
```shell
ggshield config migrate
```
Standardmäßig sucht dieser Befehl im aktuellen Verzeichnis nach der Konfigurationsdatei, führen Sie ihn also aus dem Verzeichnis aus, das die Datei enthält. Um ihn von überall aus auszuführen, verweisen Sie `ggshield` explizit auf die Datei:
```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```
Die vorherige Version der Datei wird als `.old`-Backup daneben aufbewahrt.
# Integrationen
Sie können `ggshield` in Ihren [CI/CD-Workflow](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow) integrieren.
Um Fehler früher zu erkennen, verwenden Sie `ggshield` als [pre-commit-, pre-push- oder pre-receive-Git-Hook](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
## KI-Codierungsassistenten
`ggshield` kann [Interaktionen](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) zwischen Ihnen und Ihrem KI-Codierungsassistenten in Echtzeit scannen und Aktionen blockieren, die Secrets enthalten, bevor sie ausgeführt werden.
Sie können die Hooks mit dem Befehl `ggshield install` installieren.
Unterstützte Tools: **Cursor**, **Claude Code**, **Copilot Chat**, **Codex** und
**Mistral Vibe 2.21+**.
# Mehr erfahren
Weitere Informationen finden Sie in [der Dokumentation](https://docs.gitguardian.com/ggshield-docs/getting-started)
# Ausgabe
Wenn keine Secrets gefunden wurden, ist der Exit-Code 0:
```bash
ggshield secret scan pre-commit
```
Wenn ein Secret in Ihrem bereitgestellten Code oder in Ihrer CI gefunden wird, erhalten Sie eine Warnung mit dem Dateinamen, in dem das Secret gefunden wurde, und einen Patch, der Ihnen die Position des Secrets in der Datei angibt:
```shell
ggshield secret scan pre-commit
```
```
2 incidents have been found in file production.rb
11 | config.paperclip_defaults = {
12 | :s3_credentials => {
13 | :bucket => "XXX",
14 | :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
|_____AWS Keys_____|
15 | :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|_______________AWS Keys_______________|
16 | }
17 | }
```
Zu lange Zeilen werden auf die Größe des Terminals gekürzt, es sei denn, der ausführliche Modus wird verwendet (`-v` oder `--verbose`).
# Verwandte Open-Source-Projekte
- [truffleHog](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
# Lizenz
`ggshield` ist unter der MIT-Lizenz lizenziert.