Commandes
Endpoint Protection est piloté par les commandes sous ggshield machine.
| Commande | Ce qu'elle fait | Envoie des données à GitGuardian |
|---|---|---|
ggshield machine scan | Scanne la machine et stocke les résultats localement. | Non |
ggshield machine report | Scanne la machine, puis envoie les résultats. | Oui |
ggshield machine submit | Envoie les résultats du dernier scan local, sans scanner à nouveau. | Oui |
ggshield machine dashboard | Ouvre le dashboard local pour parcourir les résultats du dernier scan. | Non |
ggshield machine redact | Caviarde les secrets fuités trouvés par le dernier scan, directement sur le disque. | Non |
ggshield machine setup | Configure les protections de la machine : AI Hook, hooks git et un honeytoken. | Non |
ggshield machine doctor | Vérifie que ces protections sont en place. | Non |
Quelle commande de scan dois-je utiliser ?
- Déploiement de flotte (MDM, tâche planifiée, CI) :
ggshield machine report. Une seule invocation « fire-and-forget » qui scanne à neuf et téléverse le résultat. C'est la commande à placer dans votre tâche quotidienne. Ajoutez--backgroundpour que le scan s'exécute en basse priorité avec un budget CPU et mémoire réduit. - Évaluation sur votre propre machine :
ggshield machine scan --dashboardpour scanner et examiner localement, puisggshield machine submitlorsque vous voulez les résultats dans GitGuardian. - Local uniquement, rien de téléversé :
ggshield machine scan. Les résultats restent dans la base de données de résultats locale et ne quittent jamais la machine.
submit envoie le dernier scan terminé et ne prend aucune option de scan : la portée et le mode ont été décidés lors de l'exécution de machine scan. L'horodatage du téléversement est l'heure du scan, pas l'heure de l'envoi, de sorte que renvoyer un ancien scan ne fait pas paraître l'endpoint comme fraîchement scanné.
Un scan exécuté avec sudo stocke ses résultats dans la base de données système. Exécutez également submit, dashboard et redact avec sudo, afin que chaque commande utilise la même base de données.
Options communes
scan, report et submit acceptent :
| Option | Description |
|---|---|
--insecure | Ignore la vérification des certificats. À utiliser uniquement sur des réseaux de confiance. |
--debug | Active la journalisation de débogage. |
Passez les options après la sous-commande : ggshield machine report --insecure, et non ggshield machine --insecure report. Les options placées entre machine et la sous-commande appartiennent à ggshield lui-même et ne sont pas transmises au scanner.
Les commandes ggshield machine n'ont pas d'option --instance. Pour une instance EU ou Self-Hosted, définissez l'instance avant de les exécuter, avec l'une des options suivantes :
- la variable d'environnement
GITGUARDIAN_INSTANCE, pour une seule exécution ou un script de déploiement ; ggshield config set instance <URL>, pour en faire la valeur par défaut sur la machine.
Les deux sont lues par report, submit, setup et doctor. Voir Configuration de ggshield.
Options de scan
ggshield machine scan scanne toujours l'ensemble de la machine et ne prend aucun argument de chemin. Pour le restreindre à des répertoires spécifiques, définissez scan.scan_only dans le fichier de configuration de scan de la machine ou la variable d'environnement GGSHIELD_MACHINE_SCAN_ONLY. La variable d'environnement est ignorée lorsque le scan s'exécute avec sudo.
| Option | Description |
|---|---|
--mode [quick|standard|full] | Couverture du scan. Par défaut : standard. Voir Ce qui est scanné. |
--include-protected | Inclure les répertoires macOS protégés par TCC (Desktop, Documents, Downloads). Peut déclencher des invites d'autorisation macOS. |
--include-remote-fs | Inclure les montages distants et de stockage cloud (OneDrive, Google Drive, Dropbox, iCloud Drive, Box, NFS, SMB). Les fichiers uniquement sur le cloud sont téléchargés lors de la lecture. Plugin 0.64.0 ou ultérieur. |
--background | Exécuter comme une charge de travail en basse priorité avec un budget de ressources réduit. Plugin 0.65.0 ou ultérieur. |
-x, --scan-archives / --no-scan-archives | Scanner à l'intérieur des archives. Par défaut : activé. |
-a, --analyze / --no-analyze | Valider les secrets et extraire leurs métadonnées. Par défaut : activé. |
--rescan | Ignorer le cache : rescanner chaque fichier et réanalyser chaque secret. |
--show-findings | Lister les résultats individuels, pas seulement les statistiques récapitulatives. |
-f, --format [text|json] | Format de sortie. Par défaut : text. |
-o, --output PATH | Écrire la sortie dans un fichier au lieu de stdout. |
--dashboard | Ouvrir le dashboard local lorsque le scan se termine. |
--config FILE | Chemin vers un fichier de configuration de scan de la machine (machine_scan.yaml). |
Options de report et submit
| Option | Description |
|---|---|
--no-upload | Construire l'inventaire sans l'envoyer. Combinez avec -o pour le conserver. |
-o, --output PATH | Écrire également le JSON de l'inventaire dans ce fichier. |
--api-key KEY | Clé d'API à utiliser pour l'envoi. Par défaut, la variable d'environnement GITGUARDIAN_API_KEY, puis le token stocké par ggshield auth login. |
--config FILE | Chemin vers un fichier de configuration de scan de la machine (machine_scan.yaml). |
report accepte également --mode, --include-protected, --include-remote-fs et --background, avec la même signification que pour scan.
Options du dashboard
| Option | Description |
|---|---|
-p, --port PORT | Port du serveur local. Par défaut : 7890. |
--no-browser | Démarrer le serveur sans ouvrir de navigateur. |
-d, --daemon | Exécuter le dashboard en arrière-plan. |
--db PATH | Chemin vers la base de données de résultats. Par défaut : ~/.ggshield/ggshield_machine_scan.db, ou la base de données système lorsqu'il est exécuté en tant que root. |
Options de redact
ggshield machine redact réécrit les fichiers qui contiennent les secrets trouvés par le dernier scan, en remplaçant uniquement le secret lui-même. Il ne scanne pas : exécutez d'abord machine scan ou machine report. Disponible à partir de la version 0.63.0 du plugin machine_scan.
Par défaut, il sélectionne chaque secret caviardable : copies locales et jetables comme les logs, l'historique du shell et les transcriptions d'agents IA. Les copies à l'intérieur des projets, des stores gérés par les applications et des sources distantes sont signalées comme ignorées, car elles nécessitent une remédiation manuelle. C'est la même sélection que le filtre Auto-fixable du dashboard local.
| Option | Description |
|---|---|
--dry-run | Montrer ce qui serait caviardé, sans rien écrire. |
-y, --yes | Caviarder sans demander de confirmation. Requis lorsque la commande ne s'exécute pas dans un terminal interactif. |
--finding ID | Caviarder uniquement ce résultat. Répétable. L'ID est la dernière partie de l'URL du résultat dans le dashboard local. |
--detector NAME | Caviarder uniquement les secrets trouvés par ce détecteur. Répétable. |
--path DIR | Caviarder uniquement les occurrences sous ce répertoire. Il doit exister ; ~ est développé. |
--exclude-path PATTERNS | Ignorer les occurrences dont le chemin correspond à ces motifs séparés par des virgules. * et ? sont des caractères génériques, la correspondance est insensible à la casse, et un motif qui n'est pas un chemin absolu correspond n'importe où dans le chemin. |
--style [fixed|named|asterisk|partial] | Style de remplacement. Par défaut, remediation.scrub_redact_style dans la configuration, fixed si non défini. |
--replacement TEXT | Texte de remplacement pour le style fixed. Par défaut, remediation.scrub_redact_string, [REDACTED] si non défini. |
--format [pretty|json] | Format de sortie. Par défaut : pretty. |
--config FILE | Chemin vers un fichier de configuration de scan de la machine (machine_scan.yaml). |
--db PATH | Chemin vers la base de données de résultats. |
--debug | Active la journalisation de débogage. |
Les styles de remplacement transforment ghp_abc123 en :
| Style | Résultat |
|---|---|
fixed | [REDACTED], ou votre texte --replacement |
named | [GITHUB_PAT_REDACTED] |
asterisk | ********** |
partial | ghp_****** |
La commande se termine avec le code 1 lorsqu'un fichier n'a pas pu être écrit. Les résultats ignorés ne modifient pas le code de sortie.
Le caviardage ne peut pas être annulé, et ne supprime que les copies locales. Faites d'abord tourner ou révoquez le secret chez son fournisseur.
Options de setup et doctor
setup et doctor sont disponibles à partir de ggshield 1.53.0.
ggshield machine setup configure l'AI Hook pour chaque assistant de codage IA détecté, installe les hooks git pre-commit et pre-push, et plante un honeytoken. Il est idempotent, il fait donc aussi office de tâche de réparation.
| Option | Description |
|---|---|
--no-ai-hooks | Ne pas configurer l'AI Hook. |
--no-git-hooks | Ne pas installer les hooks git. |
--no-honeytokens | Ne pas planter de honeytoken. |
--agent NAME | Configurer l'AI Hook uniquement pour cet assistant. Répétable. |
--exclude-agent NAME | Ne pas configurer l'AI Hook pour cet assistant. Répétable. |
--system | Installer les hooks git à l'échelle de la machine, pour chaque utilisateur. Implicite lorsqu'il est exécuté en tant que root. |
Git n'est nécessaire que pour les hooks git : sans lui, setup ignore cette étape avec un avertissement et doctor la signale comme ignorée sans échouer.
ggshield machine doctor indique si ces protections sont en place et si le token porte les scopes dont elles ont besoin. Il ne prend aucune option, ne change rien, et se termine avec un code non nul si une vérification échoue, de sorte qu'il fonctionne directement comme un script d'audit MDM. Voir Déployer et vérifier.
ggshield machine inventory est déprécié
ggshield machine inventory fonctionne toujours comme un alias de report (scan, puis envoi) afin que les tâches existantes continuent de s'exécuter, et il affiche un avis de dépréciation. Mettez à jour vos scripts MDM et vos tâches planifiées vers ggshield machine report.
Exemples
# Scanner et envoyer en une seule étape, en basse priorité (tâche MDM planifiée)
ggshield machine report --background
# Scanner localement, examiner dans le dashboard local, envoyer plus tard
ggshield machine scan --dashboard
ggshield machine submit
# Construire la charge utile localement sans rien envoyer
ggshield machine report --no-upload -o inventory.json
# Instance EU ou Self-Hosted
GITGUARDIAN_INSTANCE=https://gitguardian.example.com ggshield machine report
# Prévisualiser, puis caviarder les secrets fuités dans vos logs
ggshield machine redact --path ~/logs --dry-run
ggshield machine redact --path ~/logs
L'envoi nécessite des identifiants GitGuardian : le token stocké par ggshield auth login, ou une clé d'API dans la variable d'environnement GITGUARDIAN_API_KEY. Voir Déployer à grande échelle avec un token de compte de service pour les déploiements sans intervention.
