Detector YAML Syntax Reference

Introduction

GitGuardian detectors are defined as YAML files. These pages document the syntax of these YAML files.

Note: the word "pattern" in these pages refers to a Python regular expression.

Detector

Top-level object defining how to capture a secret for a given service.

name (required)

Type: string

Pattern: ^[a-zA-Z0-9_]+$

Machine name for the detector.

For historical reasons this field accepts upper-case letters but the convention is to use only lower-case letters and _.

display_name (required)

Type: string

Human-friendly name for the detector.

family (required)

Type: enum

One of:

• certificate
• credentials
• cryptographic_key
• identifiers
• oauth_token
• other
• token
• webhook_url

matchers (required)

Type: list[Matcher]

Extract secrets from documents.

pre_validators

Type: list[PreValidator]

Fast filters to quickly eliminate documents.

post_validators

Type: list[PostValidator]

Eliminate false-positives.

Objects inside a detector

Pre-validators

• ContentWhitelistPreValidator: Accept documents if either the filename or content contain ANY of the given patterns.

• FilenameBanlistPreValidator: Ban documents based on their filename or extension.

Matchers

• RegexMatcher: Matches values captured by a pattern.

• AssignmentRegexMatcher: Capture assignments (KEY=VALUE, KEY:VALUE, ...).

• AggregateMatcher: Group multiple matchers.

Post-validators

• EntropyPostValidator: Ensures the Shannon entropy of matches is greater than a given threshold.

Strategies

• DistanceStrategy: Use the distance between matches to group them.