Scan Machine

ggshield — Scan Machine

Overview

ggshield 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:

1. Endpoint scanning enabled on the GitGuardian workspace. Endpoint scanning is gated server-side; on Free, the plugin install will fail.
2. The 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.

Start Here — Read This Before Doing Anything

Do not skip this section.

• Confirm endpoint scanning is enabled first. Machine scan is gated server-side and will not work on Free. If the user can't confirm endpoint scanning is enabled on their workspace, do not run the scan; redirect to scan-secrets (which covers individual repos on Free) and explain that machine scan requires the endpoint scanning capability.
• Confirm the 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.
• Confirm the scope with the user before launching. Tell them which --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.
• Do not run machine scans silently in the background. They are long-running, produce large output, and may surface very personal credentials (browser saves, SSH keys). The user should be in front of the keyboard when this runs.
• Always pair -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.
• Treat findings with the same care as production secrets. Live credentials surfaced by a machine scan must be rotated immediately; dead credentials should still be removed. Never log raw secret values; report by file, line, type, and validity.
• Run Onboarding first if the CLI isn't set up. If ggshield --version fails or ggshield api-status errors, complete the Onboarding (first use) section in the scan-secrets skill before attempting a machine scan.

When to Use

Trigger a machine scan when:

• The user is about to wipe, sell, hand off, or return a laptop and wants to know what credentials it holds
• The user has onboarded a new machine and wants to audit what credentials migrated over
• The user is auditing dev-machine hygiene before a compliance review, SOC 2 audit, or security questionnaire
• The user mentions .aws/credentials, .kube/config, .npmrc, .pypirc, .docker/config.json, or other CLI config files as a possible leak source
• The user suspects a former employee, contractor, or compromised account left credentials on a shared machine
• The user wants a credential inventory for the machine fed into GitGuardian for governance (machine inventory)
• The user explicitly asks to scan the machine, the laptop, the home folder, or everything on the system

What ggshield machine covers:

• Scan the home directory for 700+ secret types — same Rust detection engine secret scan uses
• Three scan depths: quick (credentials-only files), standard (entire home with sensible exclusions — the default), full (entire home with minimal exclusions)
• Validate secrets (--analyze, on by default) — distinguishes live from dead credentials
• Cross-check findings against HasMySecretLeaked (--hmsl-check, on by default) — flags credentials already leaking in public sources
• Store findings in a local SQLite database for triage (~/.ggshield/ggshield_machine_scan.db)
• Browse findings in a local web dashboard (ggshield machine dashboard)
• Generate a JSON inventory and upload to GitGuardian for governance (ggshield machine inventory)

For platform-wide topics (auth/scope recovery, instance URLs, headless setup), see [references/gitguardian-platform.md](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.

When Not to Use

Do not use this skill when:

• You only need to scan a single repository, directory, path, commit, Docker image, or package — use scan-secrets. Machine scan targets the whole home directory and is heavier than you want for a scoped check.
• You need a CI gate. Machine scan is an interactive endpoint-hygiene tool that writes to a local SQLite database and dashboard; it is not a pipeline pass/fail check — scan-secrets is.
• The workspace is on Free or does not have endpoint scanning enabled, or the machine_scan plugin is not installed and enabled. The scan cannot run; confirm both prerequisites first and otherwise redirect the user to scan-secrets.
• The goal is to check a known credential against the public-leak corpus — use check-hmsl.

Quick Start (if ggshield is already installed, authorized, and the 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.

Onboarding (first use)

Prerequisites

• GitGuardian workspace with endpoint scanning enabled. Endpoint scanning is gated server-side. On the Free plan the plugin install (and the scan command) will fail. Confirm before proceeding.
• 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.)
• For fleet rollouts (security teams managing endpoints across an org), deployment is typically handled via MDM (Intune, Jamf) — 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.

Setup

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.

Step 1 — Install or upgrade ggshield to 1.45.0+

If ggshield --version fails or returns `.

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](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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GitGuardian
• Source: GitGuardian/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.