Commands

Endpoint Protection is driven by the commands under ggshield machine. Scanning is handled by three of them.

Command	What it does	Sends data to GitGuardian
ggshield machine scan	Scans the machine and stores the results locally.	No
ggshield machine report	Scans the machine, then sends the results.	Yes
ggshield machine submit	Sends the results of the latest local scan, without scanning again.	Yes

ggshield machine dashboard opens the local dashboard to browse the findings of the latest scan on the machine itself.

Set up and check a machine

Two more commands, available from ggshield 1.53.0, manage the protections that live on the machine rather than the scan itself.

Command	What it does
ggshield machine setup	Configures the AI Hook for every detected AI coding assistant, installs the git pre-commit and pre-push hooks, and plants a honeytoken. Idempotent, so it doubles as a repair job.
ggshield machine doctor	Reports whether those protections are in place and whether the token carries the scopes they need. Read-only, and exits non-zero if any check fails.

Drop any part of the setup with --no-ai-hooks, --no-git-hooks, or --no-honeytokens, and narrow which assistants get the hook with --agent or --exclude-agent. Run machine setup as root, or pass --system, to install the git hooks machine-wide for every user.

Because machine doctor exits non-zero on failure, it works directly as an MDM audit script. See Roll out and verify.

Which scan command should I use?

• Fleet deployment (MDM, scheduled job, CI): ggshield machine report. One fire-and-forget invocation that scans fresh and uploads the result. This is the command to put in your daily job.
• Evaluating on your own machine: ggshield machine scan --dashboard to scan and review locally, then ggshield machine submit when you want the results in GitGuardian.
• Local only, nothing uploaded: ggshield machine scan. Results stay in the local results database and never leave the machine.

submit sends the latest completed scan and takes no scan options: the scope and mode were decided when machine scan ran. The upload timestamp is the scan time, not the send time, so re-sending an old scan does not make the endpoint look freshly scanned.

note

A scan run with sudo stores its results in the system database. Run submit with sudo too, so both commands use the same database.

ggshield machine inventory is deprecated

ggshield machine inventory still works as an alias of report (scan, then send) so existing jobs keep running, and it prints a deprecation notice. Update your MDM scripts and scheduled jobs to ggshield machine report.

Examples

# Scan and send in one step (MDM / automation)
ggshield machine report

# 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

# Self-hosted instance
ggshield machine --instance https://gitguardian.example.com report

Sending requires GitGuardian credentials: the token stored by ggshield auth login, or an API key in the GITGUARDIAN_API_KEY environment variable. See Deploy at scale with a service account token for unattended deployments.