Terminal
Terminal/Skill
Scans a whole developer machine for exposed credentials, such as cloud CLI configs, shell history and browser databases (needs endpoint scanning on your workspace).
By GitGuardian
Works with
npx skills add gitguardian/agent-skills --skill scan-machineggshield machine scan scans the entire home directory for secrets across local git repositories, dotfiles (~/.bashrc, ~/.zshrc, ~/.netrc), shell history (.zsh_history, .bash_history), cloud CLI configs (~/.aws/credentials, ~/.kube/config, ~/.docker/config.json, ~/.npmrc, ~/.pypirc), AI agent caches (Cursor, Claude Code, Copilot), browser profile databases, archives, and abandoned project trees. Findings are stored in a local SQLite database (~/.ggshield/ggshield_machine_scan.db) and viewable in a local web dashboard.
This is distinct from secret scan (which targets a specific path, repo, image, or package). Machine scan is for the machine itself: "what credentials are sitting across this laptop, including local repositories and personal configuration files?" GitGuardian positions it as endpoint protection — typically rolled out across a fleet via MDM (Intune, Jamf), but also runnable ad-hoc by an individual developer whose workspace has it enabled.
Two things have to be set up before ggshield machine scan runs at all:
machine_scan plugin, installed and enabled. Machine scan is not built into the base ggshield binary — it ships as a separate plugin that has to be installed via ggshield plugin install and enabled via ggshield plugin enable machine_scan. A fresh ggshield install does not include it. Until the plugin is enabled, ggshield machine scan will exit with "command not found" or a similar error.Confirm both prerequisites before walking the user through a scan. If they're on Free, redirect them to scan-secrets (which works on Free for individual repos) and mention that machine scan requires endpoint scanning to be enabled on the workspace.
Core rule: confirm with the user before running. Machine scans inspect every file in $HOME including shell history and AI agent caches; that's invasive even when legitimate. State what will happen, ask once, then proceed.
Do not skip this section.
scan-secrets (which covers individual repos on Free) and explain that machine scan requires the endpoint scanning capability.machine_scan plugin is installed and enabled. Run ggshield plugin list before the first ggshield machine scan and look for machine_scan marked as enabled. If it isn't present or isn't enabled, run the Setup → Step 3 flow below (install the plugin, then ggshield plugin enable machine_scan). Skipping this is the most common cause of ggshield machine: command not found.--mode you're about to use and why. quick (credentials-only) is the safe default; standard and full walk the entire home directory and may take many minutes.-f json with --show-findings in agent contexts. The default output is summary stats only (counts) — useless for the agent. --show-findings reveals individual findings; -f json makes them parseable.--include-protected requires macOS permission grants. On macOS, Desktop, Documents, Pictures, and other TCC-protected directories are excluded by default. Passing --include-protected triggers a Full Disk Access prompt the first time — only suggest it after explaining the prompt.ggshield --version fails or ggshield api-status errors, complete the Onboarding (first use) section in the scan-secrets skill before attempting a machine scan.Trigger a machine scan when:
.aws/credentials, .kube/config, .npmrc, .pypirc, .docker/config.json, or other CLI config files as a possible leak sourcemachine inventory)What ggshield machine covers:
secret scan usesquick (credentials-only files), standard (entire home with sensible exclusions — the default), full (entire home with minimal exclusions)--analyze, on by default) — distinguishes live from dead credentials--hmsl-check, on by default) — flags credentials already leaking in public sources~/.ggshield/ggshield_machine_scan.db)ggshield machine dashboard)ggshield machine inventory)For platform-wide topics (auth/scope recovery, instance URLs, headless setup), see references/gitguardian-platform.md.
For remediation guidance once findings are surfaced (rotation rules, removal flow), the same playbook as scan-secrets/references/remediation-doctrine.md applies — a found credential is a found credential regardless of which scanner found it.
Do not use this skill when:
scan-secrets. Machine scan targets the whole home directory and is heavier than you want for a scoped check.scan-secrets is.machine_scan plugin is not installed and enabled. The scan cannot run; confirm both prerequisites first and otherwise redirect the user to scan-secrets.check-hmsl.machine_scan plugin is enabled)ggshield plugin list | grep machine_scan # confirm plugin enabled
ggshield api-status # verify CLI is authenticated
ggshield machine scan --mode quick -f json --show-findings # safe default — credentials-only
If ggshield plugin list doesn't show machine_scan, or ggshield --version fails, jump to Onboarding (first use) below.
ggshield 1.45.0 or later — minimum version that supports the plugin system. (For agent hooks via ggshield install -t claude-code, the floor is 1.49.0, but that's a separate skill — scan-secrets.)ggshield and the plugin rolled out to managed endpoints with the auth config baked in. The skill below covers ad-hoc invocations by a developer whose workspace has endpoint scanning enabled; fleet deployment is out of scope.There are three things to set up in order: the ggshield binary, authentication, and the machine_scan plugin. Steps 1 and 2 are exactly the same as for scan-secrets. Step 3 is specific to this skill.
ggshield to 1.45.0+If ggshield --version fails or returns < 1.45.0, follow the full Onboarding → Step 1 (Check / install ggshield) section in the scan-secrets skill — detect the user's package manager, install or upgrade ggshield. Return here once ggshield --version reports 1.45.0 or later.
If ggshield api-status errors, follow the full Onboarding → Step 2 (Authenticate and verify) section in the scan-secrets skill — run ggshield auth login (or --method oob for headless, with --method token as the fallback). Return here once ggshield api-status reports OK.
machine_scan pluginMachine scan ships as a separate plugin, not as part of the base ggshield binary. It has to be installed and enabled before ggshield machine scan works.
Discover, install, enable:
ggshield plugin status # what's available for this account; prints the install command
ggshield plugin install machine_scan # follow the command surfaced by `plugin status`
ggshield plugin enable machine_scan
ggshield plugin status is the single source of truth — it queries the GitGuardian platform for the plugins available to the user's account and prints the exact ggshield plugin install command to run. Use whatever it says. If plugin status returns a 404, the user's workspace does not have the plugin system enabled — that's a workspace-level configuration issue, not a CLI fix. Have them contact their GitGuardian admin or check whether endpoint scanning is enabled for the workspace.
ggshield plugin list # confirm machine_scan shows up as enabled
ggshield machine --help # the help should now resolve — base ggshield no longer says "no such command"
Once these both succeed, the skill is ready. Proceed to Commands.
# Plugin operations — useful before/after scans
ggshield plugin status # available plugins for this account
ggshield plugin list # installed plugins + enabled state
ggshield plugin update --check # check for plugin updates
ggshield plugin disable machine_scan # disable without uninstalling
ggshield plugin uninstall machine_scan # full removal
# Default scan modes — pick by scope
ggshield machine scan --mode quick -f json --show-findings # credentials-only, fastest
ggshield machine scan --mode standard -f json --show-findings # entire home with exclusions
ggshield machine scan --mode full -f json --show-findings # entire home, minimal exclusions
# macOS: include TCC-protected directories (Desktop, Documents, Pictures)
ggshield machine scan --mode standard --include-protected -f json --show-findings
# Include build directories too (node_modules, .venv, target/)
ggshield machine scan --mode standard --thorough -f json --show-findings
# Scan a specific path on the machine instead of all of $HOME
ggshield machine scan /path/to/audit -f json --show-findings
# Force a fresh scan, ignoring the cache and any prior DB state
ggshield machine scan --rescan -f json --show-findings
# Stateless one-off (no DB writes, no cache, useful in CI)
ggshield machine scan --stateless -f json --show-findings
# Browse findings in a local web UI (default port 7890)
ggshield machine dashboard
# Generate a GitGuardian-uploadable inventory of credentials on the machine
ggshield machine inventory --output /tmp/inventory.json
Key flags:
| Flag | Effect |
|---|---|
--mode quick|standard|full | Scope. quick = credentials-only files (fastest, safest default). standard = entire home with exclusions. full = minimal exclusions |
--include-protected | macOS only — include TCC-protected directories. Triggers a Full Disk Access prompt the first time |
--thorough | Include build directories (node_modules, .venv, target/, etc.) usually excluded for noise reasons |
-f, --format json | Structured output — always pass in agent contexts |
--show-findings | Show individual findings (overrides the default --quiet summary-only mode) |
--no-analyze | Skip validation (faster, but loses live/dead classification) |
--no-hmsl-check | Skip the HasMySecretLeaked cross-check |
--rescan | Force a fresh scan, ignoring the cache |
--stateless | One-off mode — no SQLite reads or writes |
Exit codes: 0 = no secrets found, non-zero = secrets found or an error occurred.
--mode quick for the first run. It targets known credential files specifically — fast, low surprise. Escalate to standard or full only after the user has seen the quick-mode output and wants broader coverage.-f json with --show-findings in agent contexts. Without --show-findings, you only get counts.ggshield machine dashboard for triage when the scan finds more than ~10 results. The local web UI groups findings by detector, file, and validity — much easier than scrolling through JSON output.scan-secrets/references/remediation-doctrine.md applies.ggshield machine inventory uploads findings to GitGuardian. Only run it when the user wants the machine's credentials inventoried in their workspace (governance / compliance use case). For a plain audit, stick with ggshield machine scan.ggshield: command not found — see the scan-secrets skill's Onboarding section.
ggshield machine: command not found or Error: No such command 'machine' — the machine_scan plugin isn't installed or isn't enabled. Run ggshield plugin list to confirm. If it's missing, return to Onboarding → Step 3. If it's listed as disabled, run ggshield plugin enable machine_scan.
Failed to fetch plugins: 404 on ggshield plugin status — the user's GitGuardian workspace does not have the plugin system enabled. This is a workspace-level configuration, not a CLI fix. Have them contact their GitGuardian admin or check whether endpoint scanning is enabled for the workspace.
401 Unauthorized — token missing or invalid. Run ggshield api-status. For scope recovery, see references/gitguardian-platform.md.
403 Forbidden / "Endpoint scanning not available on your plan" — the user's GitGuardian workspace is on Free or otherwise does not have endpoint scanning enabled. The fix is a workspace entitlement change, not a CLI change. Direct the user to https://dashboard.gitguardian.com (Settings → Billing) or to contact their workspace administrator. There is no CLI workaround.
Permission denied on macOS protected dirs — --include-protected was passed but the terminal app has not been granted Full Disk Access. Open System Settings → Privacy & Security → Full Disk Access and add the terminal binary, then re-run.
Scan runs but reports no findings on a machine you know has credentials — quick mode only checks known credential files. Try --mode standard or add --thorough. Also confirm ~/.ggshield/ggshield_machine_scan.db was created; if not, pass --rescan.
First scan takes many minutes — expected. The plugin indexes every file in scope on first run, then caches. Subsequent scans only re-process new/modified files.
Cache returns stale findings — pass --rescan to force re-analysis.
Dashboard won't open — port 7890 is in use. Override with ggshield machine dashboard --port <other>.
Inventory upload fails with 403 Forbidden — the Personal Access Token lacks the nhi:send-inventory scope (or nhi:write-vault, which includes it). Generate a PAT with the right scope at dashboard.gitguardian.com → API → Personal Access Tokens, or run the scope-recovery flow in references/gitguardian-platform.md.
Inventory hangs forever in a headless environment (CI, SSH, no browser) — when the API key isn't on the command line, ggshield machine inventory spins up a localhost OAuth callback server and waits for a browser. Always pass --api-key "$GITGUARDIAN_API_KEY" explicitly in headless contexts; do not rely on the env var alone.
TLS / certificate errors behind a corporate proxy — set REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem (or SSL_CERT_FILE, or pass --ssl-certificate) so the plugin trusts the proxy's CA. Priority: --ssl-certificate > REQUESTS_CA_BUNDLE > SSL_CERT_FILE.
Any other or unlisted error — before improvising a fix, consult GitGuardian's AI-agent docs index at https://docs.gitguardian.com/llms.txt to locate the relevant page, then append .md to that page's URL to read it as Markdown. Search there first rather than guessing.