module

Documentation

Overview

Package module defines Geiger's core domain types and the Module contract.

A Module is the unit of credential coverage: it recognizes a credential (via the recognize package routing to it), optionally performs a single headless token exchange, runs read-only recon, and summarizes the result into a Note. The common bearer/basic case is built declaratively via the recipe subpackage; exotic-signing providers implement Module directly.

Index

• Variables
• func MapRule(ruleID, moduleName string)
• func Register(m Module)
• type Base
  • func (Base) Authenticate(context.Context, *recon.Client, Fields) (Token, error)
• type Candidate
• type Fields
  • func (f Fields) Get(k string) string
• type Finding
• type FlagLevel
• type Harvested
• type Harvester
• type Module
• type Note
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) All() []Module
  • func (r *Registry) ByName(name string) (Module, bool)
  • func (r *Registry) ByRule(ruleID string) (Module, bool)
  • func (r *Registry) MapRule(ruleID, moduleName string)
  • func (r *Registry) Register(m Module)
  • func (r *Registry) RuleModule(ruleID string) (string, bool)
  • func (r *Registry) Rules() map[string]string
• type SourceKind
• type Token

Variables

var Default = NewRegistry()

Default is the process-wide registry that modules self-register into.

Functions

func MapRule

func MapRule(ruleID, moduleName string)

MapRule routes a rule id in the default registry.

func Register

func Register(m Module)

Register adds a module to the default registry.

Types

type Base

type Base struct{}

Base provides a no-op Authenticate so direct-auth modules can embed it.

func (Base) Authenticate

func (Base) Authenticate(context.Context, *recon.Client, Fields) (Token, error)

Authenticate returns an empty token (no exchange).

type Candidate

type Candidate struct {
	Value  string            // the raw credential string (a token, key, JSON, etc.)
	Source SourceKind        // how it was parsed
	File   string            // origin filename/label, if any
	Vars   map[string]string // co-located key/value pairs (env, dotenv, INI section)
}

Candidate is a single recognized-or-candidate credential plus the context it was found in. Source context lets set-shaped recognizers pair co-located variables and pick up a tenant/instance/host from the same blob.

type Fields

type Fields map[string]string

Fields are the recognizer's extracted, named inputs to a module (access key, secret, tenant, instance URL, …). Endpoint-bearing fields may be filled from the blob, a default, or the --endpoint flag.

func (Fields) Get

func (f Fields) Get(k string) string

Get returns the field value or empty string.

type Finding

type Finding struct {
	Key   string // short stable key (identity, account, scopes, buckets, …)
	Value string // human-readable value (already redacted where needed)
	Flag  FlagLevel
	// Detail holds the full expansion behind a summarized Value (e.g. the
	// individual file paths behind "8 editor local-history snapshots"). The
	// terminal shows it only with -v; JSON always emits it. Optional.
	Detail []string
}

Finding is one line of a Note: a labeled value with a significance flag.

type FlagLevel

type FlagLevel int

FlagLevel classifies the significance of a finding for the note.

const (
	FlagNone             FlagLevel = iota
	FlagInfo                       // ordinary identity/inventory detail
	FlagWarn                       // notable (prod, PII, broad read)
	FlagForceMultiplier            // turns "valid key" into "incident"
	FlagCantCharacterize           // capability exists but can't be proven read-only
)

type Harvested

type Harvested struct {
	Label string // provenance, e.g. "secretsmanager:prod/db-password"
	Value string // the extracted secret value
}

Harvested is a downstream secret pulled from a secrets store, to be fed back through recognition and triaged recursively.

type Harvester

type Harvester interface {
	Harvest(ctx context.Context, c *recon.Client, t Token, f Fields) ([]Harvested, error)
}

Harvester is implemented by modules that can read a secrets store. Harvest EXTRACTS secret values (not just metadata), so the pipeline only calls it under --live --intrusive and within a bounded recursion depth/budget.

type Module

type Module interface {
	// Name is the stable module identifier (also used for dedupe).
	Name() string
	// Authenticate performs the optional single headless token exchange.
	// Modules that need no exchange return an empty Token and nil error.
	Authenticate(ctx context.Context, c *recon.Client, f Fields) (Token, error)
	// Recon runs the read-only recipe and returns findings.
	Recon(ctx context.Context, c *recon.Client, t Token, f Fields) ([]Finding, error)
	// Summarize turns findings into the printed Note.
	Summarize(title string, fs []Finding) Note
}

Module is the unit of credential coverage.

type Note

type Note struct {
	Title    string    // e.g. "GitHub PAT ghp_…JV3Q (from .env: GITHUB_TOKEN)"
	Findings []Finding // ordered lines
	Summary  string    // one-line takeaway, e.g. "org-admin bot token"
	Invalid  bool      // recon proved the credential dead/expired
	Reason   string    // why invalid, or why it could not be characterized
}

Note is a module's summary for one credential.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds the available modules and the routes into them.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) All

func (r *Registry) All() []Module

All returns modules in registration order.

func (*Registry) ByName

func (r *Registry) ByName(name string) (Module, bool)

ByName returns a module by name.

func (*Registry) ByRule

func (r *Registry) ByRule(ruleID string) (Module, bool)

ByRule returns the module a gitleaks rule routes to.

func (*Registry) MapRule

func (r *Registry) MapRule(ruleID, moduleName string)

MapRule routes a gitleaks rule id to a module name.

func (*Registry) Register

func (r *Registry) Register(m Module)

Register adds a module. It panics on a duplicate name (a programming error).

func (*Registry) RuleModule

func (r *Registry) RuleModule(ruleID string) (string, bool)

RuleModule returns the module name a rule maps to.

func (*Registry) Rules

func (r *Registry) Rules() map[string]string

Rules returns a copy of the rule→module mapping (for tests/introspection).

type SourceKind

type SourceKind string

SourceKind records how a candidate was produced.

const (
	SourceStdin    SourceKind = "stdin"
	SourceFile     SourceKind = "file"
	SourceEnv      SourceKind = "env"
	SourceDotenv   SourceKind = "dotenv"
	SourceINI      SourceKind = "ini"
	SourceJSON     SourceKind = "json"
	SourceKube     SourceKind = "kubeconfig"
	SourceRegistry SourceKind = "registry"
)

type Token

type Token struct {
	Bearer      string
	InstanceURL string            // e.g. Salesforce instance_url
	Extra       map[string]string // grant-specific extras (scope, expiry, …)
}

Token is the result of an authenticate phase (or empty when none is needed).