Commands

Endpoint Protection is driven by the commands under ggshield machine.

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.	No
ggshield machine redact	Redacts leaked secrets found by the latest scan, in place on disk.	No
ggshield machine setup	Sets up the machine's protections: AI Hook, git hooks, and a honeytoken.	No
ggshield machine doctor	Checks that those protections are in place.	No

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. Add --background so the scan runs at low priority with a smaller CPU and memory budget.
• 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, dashboard, and redact with sudo too, so every command uses the same database.

Common options

scan, report, and submit accept:

Option	Description
--insecure	Skip certificate verification. Use only on networks you trust.
--debug	Enable debug logging.

Pass options after the subcommand: ggshield machine report --insecure, not ggshield machine --insecure report. Options placed between machine and the subcommand belong to ggshield itself and are not forwarded to the scanner.

ggshield machine commands have no --instance option. For an EU or self-hosted instance, set the instance before running them, with either:

• the GITGUARDIAN_INSTANCE environment variable, for a single run or a deployment script;
• ggshield config set instance <URL>, to make it the default on the machine.

Both are read by report, submit, setup, and doctor. See ggshield configuration.

Scan options

ggshield machine scan always scans the whole machine and takes no path argument. To restrict it to specific directories, set scan.scan_only in the machine scan configuration file or the GGSHIELD_MACHINE_SCAN_ONLY environment variable. The environment variable is ignored when the scan runs with sudo.

Option	Description
--mode [quick|standard|full]	Scan coverage. Default: standard. See What is scanned.
--include-protected	Include macOS TCC-protected directories (Desktop, Documents, Downloads). May trigger macOS permission prompts.
--include-remote-fs	Include remote and cloud-storage mounts (OneDrive, Google Drive, Dropbox, iCloud Drive, Box, NFS, SMB). Cloud-only files are downloaded when read. Plugin 0.64.0 or later.
--background	Run as a low-priority workload with a smaller resource budget. Plugin 0.65.0 or later.
-x, --scan-archives / --no-scan-archives	Scan inside archives. Default: enabled.
-a, --analyze / --no-analyze	Validate secrets and extract their metadata. Default: enabled.
--rescan	Ignore the cache: rescan every file and re-analyze every secret.
--show-findings	List individual findings, not just summary stats.
-f, --format [text|json]	Output format. Default: text.
-o, --output PATH	Write the output to a file instead of stdout.
--dashboard	Open the local dashboard when the scan finishes.
--config FILE	Path to a machine scan configuration file (machine_scan.yaml).

Report and submit options

Option	Description
--no-upload	Build the inventory without sending it. Combine with -o to keep it.
-o, --output PATH	Also write the inventory JSON to this file.
--api-key KEY	API key to send with. Defaults to the GITGUARDIAN_API_KEY environment variable, then to the token stored by ggshield auth login.
--config FILE	Path to a machine scan configuration file (machine_scan.yaml).

report also accepts --mode, --include-protected, --include-remote-fs, and --background, with the same meaning as on scan.

Dashboard options

Option	Description
-p, --port PORT	Port of the local server. Default: 7890.
--no-browser	Start the server without opening a browser.
-d, --daemon	Run the dashboard in the background.
--db PATH	Path to the results database. Default: ~/.ggshield/ggshield_machine_scan.db, or the system database when run as root.

Redact options

ggshield machine redact rewrites the files that hold the secrets found by the latest scan, replacing only the secret itself. It does not scan: run machine scan or machine report first. Available from version 0.63.0 of the machine_scan plugin.

By default, it selects every redactable secret: local, disposable copies such as logs, shell history, and AI agent transcripts. Copies inside projects, app-managed stores, and remote sources are reported as skipped, because they need manual remediation. This is the same selection as the Auto-fixable filter of the local dashboard.

Option	Description
--dry-run	Show what would be redacted, and write nothing.
-y, --yes	Redact without asking for confirmation. Required when the command does not run in an interactive terminal.
--finding ID	Redact only this finding. Repeatable. The ID is the last part of the finding's URL in the local dashboard.
--detector NAME	Redact only secrets found by this detector. Repeatable.
--path DIR	Redact only occurrences under this directory. It must exist; ~ is expanded.
--exclude-path PATTERNS	Skip occurrences whose path matches these comma-separated patterns. * and ? are wildcards, matching is case-insensitive, and a pattern that is not an absolute path matches anywhere in the path.
--style [fixed|named|asterisk|partial]	Replacement style. Defaults to remediation.scrub_redact_style in the configuration, fixed if unset.
--replacement TEXT	Replacement text for the fixed style. Defaults to remediation.scrub_redact_string, [REDACTED] if unset.
--format [pretty|json]	Output format. Default: pretty.
--config FILE	Path to a machine scan configuration file (machine_scan.yaml).
--db PATH	Path to the results database.
--debug	Enable debug logging.

The replacement styles turn ghp_abc123 into:

Style	Result
fixed	[REDACTED], or your --replacement text
named	[GITHUB_PAT_REDACTED]
asterisk	**********
partial	ghp_******

The command exits with code 1 when a file could not be written. Skipped findings don't change the exit code.

warning

Redaction cannot be undone, and only removes local copies. Rotate or revoke the secret at its provider first.

Setup and doctor options

setup and doctor are available from ggshield 1.53.0.

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. It is idempotent, so it doubles as a repair job.

Option	Description
--no-ai-hooks	Don't configure the AI Hook.
--no-git-hooks	Don't install the git hooks.
--no-honeytokens	Don't plant a honeytoken.
--agent NAME	Configure the AI Hook only for this assistant. Repeatable.
--exclude-agent NAME	Don't configure the AI Hook for this assistant. Repeatable.
--system	Install the git hooks machine-wide, for every user. Implied when run as root.

Git is only needed for the git hooks: without it, setup skips that step with a warning and doctor reports it as skipped without failing.

ggshield machine doctor reports whether those protections are in place and whether the token carries the scopes they need. It takes no options, changes nothing, and exits non-zero if any check fails, so it works directly as an MDM audit script. See Roll out and verify.

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, 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

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.