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-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: Family

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 a regular expression pattern against the document content.

• AssignmentRegexMatcher: Regex pattern that matches an assignment of a variable in one or more programming languages.

• AggregateMatcher: Group multiple matchers.

Post-validators

• EntropyPostValidator: Calculates the Shannon entropy of the match string

Strategies

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