ggshield secret scan ai-hook

Description

Scan AI coding tool hook events for secrets. This command is called automatically by AI coding tools (Cursor, Claude Code, VS Code with GitHub Copilot) when ggshield is installed as a hook.

ggshield secret scan ai-hook [OPTIONS]

The command reads a JSON hook event from stdin, scans its content for secrets, and returns a JSON response. The response format is adapted automatically based on the calling tool.

This command is not intended to be called manually. It is invoked by the AI coding tool's hook system. To set up the hooks, use ggshield install with the -t flag.

Options

• --source-uuid TEXT: Identifier of the custom source in GitGuardian. If used, incidents will be created and visible on the dashboard. Requires the 'scan:create-incidents' scope.
• --all-secrets: Do not ignore any secret. Possible ignore-reason is shown as well.
• --instance URL: URL of the instance to use.
• --with-incident-details: Display full details about the dashboard incident if one is found (JSON and SARIF formats only). Requires the 'incidents:read' scope.
• -b, --banlist-detector DETECTOR: Exclude results from a detector.
• --ignore-known-secrets: Ignore secrets already known by GitGuardian dashboard.
• --exclude PATTERNS: Do not scan paths that match the specified glob-like patterns.
• --exit-zero: Return a 0 (non-error) status code, even if incidents are found. An error status code will still be returned for other errors, such as connection errors. This option can also be set with the GITGUARDIAN_EXIT_ZERO environment variable.
• --show-secrets: Show secrets in plaintext instead of hiding them.
• -o, --output PATH: Redirect ggshield output to PATH.
• --format [text|json|sarif]: Format to use for the output.
• --json: Shorthand for --format json.

This command supports all ggshield global options.

Exit codes

In normal operation, this command always returns exit code 0. The block or allow decision is communicated through a JSON payload in stdout, which the AI coding tool uses to display feedback in its UI.

If ggshield cannot identify the calling AI coding tool, it falls back to standard exit codes:

• 0: No secrets found.
• 1: An error occurred during scanning.
• 2: Secrets were found.

See also

• Secret scanning for AI coding tools: Installation guide and usage details.