Skip to main content

Getting started

info

This is the single-machine path: it uses an interactive browser login and needs no service account token. To roll out across a fleet, manage installation and credentials through your MDM with a service account token instead (see Deploy at scale with a service account token).

Prerequisites​

  • A GitGuardian business account with Endpoint Protection enabled.

Step 1: Install ggshield and enable machine scanning​

curl -sSfL \
  https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh |
  bash -s -- --plugin machine_scan
note

By default the script targets the US workspace. For the EU workspace or a self-hosted instance, export your instance URL before running the command. It then applies to the install and to every command below (same shell):

export GITGUARDIAN_INSTANCE=https://dashboard.eu1.gitguardian.com   # or your self-hosted instance URL

Step 2: Run your first scan​

ggshield machine scan --dashboard

Step 3: Send your results to GitGuardian​

ggshield machine submit

submit sends the scan you just ran. To scan and send in one step, the shape you want for a scheduled job, use ggshield machine report. See Commands.

Your machine then shows up under Endpoint protection → Endpoints in the GitGuardian dashboard. See Core concepts for what each view shows.

Step 4: Turn on the endpoint protections​

The scan tells you which credentials are already on the machine. This step stops new ones from leaking and catches anything that comes looking for them.

The install script authenticated you with the default scopes (scan, honeytokens:check, endpoints:send, and ai-discover:send). That covers the scan, AI Hooks, and git hooks. Planting a honeytoken also needs honeytokens:write, so log in again with that extra scope before setup:

ggshield auth logout
ggshield auth login --scopes honeytokens:write
ggshield machine setup

honeytokens:write requires a workspace Manager role. If your account does not have it, the login fails and you can either ask a Manager to plant the honeytoken, or skip it with --no-honeytokens below. Across a fleet, planting stays an admin job: see Deploy at scale with a service account token.

One idempotent run configures all three protections:

  • AI Hooks for every AI coding agent it finds, so secrets are blocked before they reach a model.
  • Git hooks, pre-commit and pre-push, in your global git configuration.
  • A honeytoken, a decoy AWS credential profile that alerts GitGuardian if anything reads it.

If you skip the honeytoken, keep the install-script token and run ggshield machine setup --no-honeytokens. Drop AI Hooks or git hooks the same way with --no-ai-hooks or --no-git-hooks. Requires ggshield 1.53.0 or later.

Verify your setup​

Confirm the install and the plugin at any time:

ggshield --version
ggshield plugin list   # machine_scan should be listed and enabled

For the protections from Step 4, run the read-only check:

ggshield machine doctor

It reports, for each AI agent it finds, whether the hook is installed, whether the git hooks are in place, and whether your token reaches GitGuardian with the scopes those protections need. Requires ggshield 1.53.0 or later.

Notes​

The script installs the standalone build per user (no admin or sudo required), and each downloaded release artifact is checksum-verified against the digest GitHub publishes for that release. That verification covers the binaries, not the installer script itself, which is fetched from main. For stricter supply-chain control, pin the script to a reviewed commit or serve it from an internal/MDM-hosted package (see Deploy at scale with a service account token).

Remove ggshield​

To uninstall later, follow Uninstall in the install scripts' README.

Next steps​

Last updated on

Something we didn’t cover?

See our Roadmap
Subscribe on GitHub
Submit a request
API status