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.

Hostname is obtained via:

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

System ID is a platform-specific unique identifier:

• 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 UUID from wmic csproduct get uuid, with a PowerShell fallback

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.