Configuration reference

Excluding paths from scans

You can exclude specific files or directories from being scanned by ggshield using a global configuration file. This is useful for ignoring test fixtures, generated files, or other paths that are known to be safe.

ggshield looks for a .gitguardian.yaml configuration file in two locations, evaluated in order:

1. Global config in the user's home directory:
   • ~/.gitguardian.yaml on Linux or macOS
   • %USERPROFILE%\.gitguardian.yaml on Windows
2. Local config at ./.gitguardian.yaml in the directory being scanned.

Both files follow the same format as the ggshield configuration file. Settings from the local config take precedence over the global one. Use the ignored_paths key under secret to specify glob patterns for paths to exclude:

secret:
  ignored_paths:
    - 'LICENSE'           # exact file at the root
    - '*.log'             # all .log files in the root directory
    - 'doc/*'             # all files directly inside doc/
    - 'tests/**/*'        # all files anywhere inside tests/
    - '**/*.generated.ts' # all .generated.ts files in any directory
    - '**/README.md'      # all README.md files in any directory

Scheduling scans across timezones

Scan scheduling is configured at deployment time. There are two approaches:

• MDM-native scheduling: configure the execution frequency directly in your MDM for the custom script (e.g. Jamf's policy execution frequency).
• OS-level scheduling: deploy a scheduled task via the MDM and let the OS scheduler handle recurrence: a launchd agent on macOS, a Task Scheduler job on Windows, or a systemd timer or cron entry on Linux. A wall-clock trigger such as "18:00 daily" fires at 6 pm in each device's local timezone automatically.

Machine identifier

GitGuardian uses a source identifier to represent each machine in your inventory. It has the format <hostname>/<system_id> and is used to deduplicate results across successive scans from the same machine. The ggshield CLI and the machine_scan plugin derive it identically, so all activity from one machine maps to a single inventory entry.

Hostname is obtained via:

• gethostname() syscall on Linux and macOS
• The COMPUTERNAME environment variable on Windows

System ID is a platform-specific unique identifier, re-derived at every scan:

• macOS: the IOPlatformUUID from ioreg -rd1 -c IOPlatformExpertDevice
• Linux: the first non-empty value from /etc/machine-id, /sys/class/dmi/id/product_uuid, or /var/lib/dbus/machine-id
• Windows: the SMBIOS UUID, normalized to its lowercase canonical form. It is read with wmic csproduct get uuid, or through PowerShell on systems where wmic is not available.

Placeholder firmware UUIDs (all zeros, all Fs, or known BIOS vendor placeholders) are not accepted as identity. Machines whose firmware reports one, typically cloned VM images or boards with an unconfigured BIOS, use the fallback below instead of colliding on a single inventory entry.

Fallback: if no platform-specific ID can be determined, a random UUID v4 is generated and cached at ~/.ggshield/machine_id so it persists across scans. A warning is logged in this case: if that file is deleted, a new ID is generated and the machine may appear as a duplicate in your inventory. The file is writable only by its owner. A cache file that other users can write to, that belongs to an unrelated account, or that is a symbolic link is ignored and replaced with a fresh one.