Commands
Endpoint Protection repose sur les commandes regroupées 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 de nouveau. | Oui |
ggshield machine dashboard | Ouvre le dashboard local pour parcourir les résultats du dernier scan. | Non |
ggshield machine redact | Expurge sur le disque les secrets divulgués trouvés par le dernier scan. | Non |
ggshield machine setup | Configure les protections de la machine : AI Hook, git hooks et 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 envoie 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 plus réduit. - Évaluation sur votre propre machine :
ggshield machine scan --dashboardpour scanner et examiner localement, puisggshield machine submitlorsque vous souhaitez transmettre les résultats dans GitGuardian. - En local uniquement, rien d'envoyé :
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 : le périmètre et le mode ont été décidés lors de l'exécution de machine scan. L'horodatage d'envoi correspond à l'heure du scan, et non à l'heure de l'envoi, de sorte que le renvoi d'un ancien scan ne fait pas apparaî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 toutes les commandes utilisent 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'un des deux :
- 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 lus par report, submit, setup et doctor. Consultez la configuration de ggshield.
Options de scan
ggshield machine scan scanne toujours toute la machine et ne prend aucun argument de chemin. Pour le restreindre à des répertoires précis, définissez scan.scan_only dans le fichier de configuration du scan de 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 | Inclut les répertoires protégés par TCC sur macOS (Desktop, Documents, Downloads). Peut déclencher des demandes d'autorisation macOS. |
--include-remote-fs | Inclut les montages distants et de stockage cloud (OneDrive, Google Drive, Dropbox, iCloud Drive, Box, NFS, SMB). Les fichiers uniquement dans le cloud sont téléchargés lors de leur lecture. Plugin 0.64.0 ou ultérieur. |
--background | S'exécute comme une charge de travail à basse priorité avec un budget de ressources plus réduit. Plugin 0.65.0 ou ultérieur. |
-x, --scan-archives / --no-scan-archives | Scanne à l'intérieur des archives. Par défaut : activé. |
-a, --analyze / --no-analyze | Valide les secrets et extrait leurs métadonnées. Par défaut : activé. |
--rescan | Ignore le cache : rescanne chaque fichier et ré-analyse chaque secret. |
--show-findings | Liste les résultats individuels, et pas seulement les statistiques de synthèse. |
-f, --format [text|json] | Format de sortie. Par défaut : text. |
-o, --output PATH | Écrit la sortie dans un fichier au lieu de stdout. |
--dashboard | Ouvre le dashboard local à la fin du scan. |
--config FILE | Chemin d'un fichier de configuration du scan de machine (machine_scan.yaml). |
Options de report et de submit
| Option | Description |
|---|---|
--no-upload | Construit l'inventaire sans l'envoyer. Combinez-la avec -o pour le conserver. |
-o, --output PATH | Écrit aussi le JSON de l'inventaire dans ce fichier. |
--api-key KEY | Clé API utilisée pour l'envoi. Par défaut, la variable d'environnement GITGUARDIAN_API_KEY, puis le token stocké par ggshield auth login. |
--config FILE | Chemin d'un fichier de configuration du scan de machine (machine_scan.yaml). |
report accepte aussi --mode, --include-protected, --include-remote-fs et --background, avec la même signification que sur scan.
Options du dashboard
| Option | Description |
|---|---|
-p, --port PORT | Port du serveur local. Par défaut : 7890. |
--no-browser | Démarre le serveur sans ouvrir de navigateur. |
-d, --daemon | Exécute le dashboard en arrière-plan. |
--db PATH | Chemin de la base de données de résultats. Par défaut : ~/.ggshield/ggshield_machine_scan.db, ou la base de données système lorsque la commande s'exécute 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 ne remplaçant que le secret lui-même. Elle 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, elle sélectionne tous les secrets pouvant être expurgés : les copies locales jetables, telles que les logs, l'historique du shell et les transcriptions des agents IA. Les copies à l'intérieur de projets, de stockages gérés par des applications et de sources distantes sont signalées comme ignorées, car elles nécessitent une remédiation manuelle. Il s'agit de la même sélection que le filtre Auto-fixable du dashboard local.
| Option | Description |
|---|---|
--dry-run | Affiche ce qui serait expurgé, sans rien écrire. |
-y, --yes | Expurge sans demander de confirmation. Obligatoire lorsque la commande ne s'exécute pas dans un terminal interactif. |
--finding ID | Expurge 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 | Expurge uniquement les secrets trouvés par ce détecteur. Répétable. |
--path DIR | Expurge uniquement les occurrences situées sous ce répertoire. Il doit exister ; ~ est développé. |
--exclude-path PATTERNS | Ignore les occurrences dont le chemin correspond à ces motifs séparés par des virgules. * et ? sont des jokers, 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 d'un fichier de configuration du scan de machine (machine_scan.yaml). |
--db PATH | Chemin de 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.
L'expurgation est irréversible et ne supprime que les copies locales. Effectuez d'abord la rotation ou la révocation du secret auprès de son fournisseur.
Options de setup et de 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 git hooks pre-commit et pre-push, et plante un honeytoken. Elle est idempotente, elle fait donc aussi office de tâche de réparation.
| Option | Description |
|---|---|
--no-ai-hooks | Ne configure pas l'AI Hook. |
--no-git-hooks | N'installe pas les git hooks. |
--no-honeytokens | Ne plante pas de honeytoken. |
--agent NAME | Configure l'AI Hook uniquement pour cet assistant. Répétable. |
--exclude-agent NAME | Ne configure pas l'AI Hook pour cet assistant. Répétable. |
--system | Installe les git hooks à l'échelle de la machine, pour tous les utilisateurs. Implicite lorsque la commande s'exécute en tant que root. |
Git n'est nécessaire que pour les git hooks : 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 dispose des scopes dont elles ont besoin. Elle ne prend aucune option, ne modifie rien et retourne un code non nul si une vérification échoue, ce qui lui permet de fonctionner directement comme 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
# Scan and send in one step, at low priority (scheduled MDM job)
ggshield machine report --background
# Scan locally, review in the local dashboard, send later
ggshield machine scan --dashboard
ggshield machine submit
# Build the payload locally without sending anything
ggshield machine report --no-upload -o inventory.json
# EU or self-hosted instance
GITGUARDIAN_INSTANCE=https://gitguardian.example.com ggshield machine report
# Preview, then redact the secrets leaked in your 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é API dans la variable d'environnement GITGUARDIAN_API_KEY. Consultez Déployer à grande échelle avec un token de compte de service pour les déploiements sans surveillance.
