secrets

type Allowlist struct {
	// Patterns are regex patterns to match against secret values.
	Patterns []string `json:"patterns,omitempty"`
	// Hashes are SHA256 hashes of exact values to ignore.
	Hashes []string `json:"hashes,omitempty"`
	// Paths are glob patterns for files to completely skip.
	Paths []string `json:"paths,omitempty"`
	// Types are secret types to completely ignore.
	Types []string `json:"types,omitempty"`
	// Reasons maps entries to their justification.
	Reasons map[string]string `json:"reasons,omitempty"`
}

type ArchiveFinding struct {
	Finding

	// ArchivePath is the path to the archive file.
	ArchivePath string `json:"archivePath"`
	// EntryPath is the path within the archive.
	EntryPath string `json:"entryPath"`
	// Format is the archive format.
	Format ArchiveFormat `json:"format"`
	// Nested indicates if this was found in a nested archive.
	Nested bool `json:"nested,omitempty"`
	// NestingDepth is how many levels of archives deep this finding is.
	NestingDepth int `json:"nestingDepth,omitempty"`
}

type ArchiveFormat string

type ArchiveScanConfig struct {
	// MaxFileSize limits individual file scanning within archives.
	MaxFileSize int64
	// MaxTotalSize limits total bytes read from an archive.
	MaxTotalSize int64
	// MaxFiles limits the number of files scanned in an archive.
	MaxFiles int
	// MaxNestingDepth limits recursive archive scanning depth.
	MaxNestingDepth int
	// MaxCompressionRatio limits the decompression ratio to protect against zip bombs.
	// A ratio of 100 means the uncompressed size can be at most 100x the compressed size.
	// Set to 0 to disable this check (not recommended).
	MaxCompressionRatio float64
	// PathPatterns limits scanning to matching paths (nil = all text files).
	PathPatterns []string
	// ScanBinaryStrings enables string extraction from binary files.
	ScanBinaryStrings bool
	// BinaryMinStringLen is the minimum length for extracted binary strings.
	BinaryMinStringLen int
}

type ArchiveScanResult struct {
	// ArchivePath is the path to the scanned archive.
	ArchivePath string `json:"archivePath"`
	// Format is the detected archive format.
	Format ArchiveFormat `json:"format"`
	// EntriesScanned is the number of entries analyzed.
	EntriesScanned int `json:"entriesScanned"`
	// BytesScanned is the total bytes scanned.
	BytesScanned int64 `json:"bytesScanned"`
	// Findings contains all discovered secrets.
	Findings []ArchiveFinding `json:"findings"`
	// Errors contains any non-fatal errors encountered.
	Errors []string `json:"errors,omitempty"`
	// Truncated indicates if scanning was stopped early due to limits.
	Truncated bool `json:"truncated,omitempty"`
	// TruncationReason explains why scanning was truncated.
	TruncationReason string `json:"truncationReason,omitempty"`
}

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

type AuditResult struct {
	File   string
	Entry  BaselineEntry
	Status AuditStatus
}

type AuditStatus string

type Baseline struct {
	// Version of the baseline format.
	Version string `json:"version"`

	// GeneratedAt is when the baseline was last updated.
	GeneratedAt time.Time `json:"generated_at"`

	// Plugins lists which detectors were enabled when generating this baseline.
	// Used for compatibility checking.
	Plugins []string `json:"plugins,omitempty"`

	// Filters lists active filter configurations.
	Filters *BaselineFilters `json:"filters,omitempty"`

	// Results maps file paths to their known findings.
	Results map[string][]BaselineEntry `json:"results"`

	// Custom is for user-defined metadata.
	Custom map[string]any `json:"custom,omitempty"`
}

type BaselineComment struct {
	// Pattern to match the comment
	Pattern string
	// Reason extracted from the comment
	Reason string
}

type BaselineEntry struct {
	// Type of secret detected.
	Type string `json:"type"`
	// Line number (1-indexed).
	Line int `json:"line"`
	// Column position (1-indexed).
	Column int `json:"column,omitempty"`
	// Hash is a content-based hash for matching (avoids storing actual secret).
	Hash string `json:"hash"`
	// Reason explains why this is in the baseline (false positive, test data, etc.).
	Reason string `json:"reason,omitempty"`
	// IsVerified indicates if the hash was verified against the file.
	IsVerified bool `json:"is_verified,omitempty"`
	// AddedAt is when this entry was added to the baseline.
	AddedAt time.Time `json:"added_at,omitempty"`
}

type BaselineFilters struct {
	// ExcludedPatterns are file glob patterns to skip.
	ExcludedPatterns []string `json:"excluded_patterns,omitempty"`
	// ExcludedTypes are secret types to skip.
	ExcludedTypes []string `json:"excluded_types,omitempty"`
	// MinConfidence is the minimum confidence threshold.
	MinConfidence float64 `json:"min_confidence,omitempty"`
}

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

type BatchResult struct {
	// ID is the identifier for the scanned item (e.g., filename, path).
	ID string `json:"id"`
	// Findings are the secrets found in this item.
	Findings []Finding `json:"findings"`
	// Error is any error encountered during scanning (nil if successful).
	Error error `json:"error,omitempty"`
}

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

type BatchScannerOption func(*BatchScanner)

type BinarySection struct {
	Name   string
	Offset uint64
	Size   uint64
	Data   []byte
}

type CommitInfo struct {
	Hash      string    `json:"hash"`
	ShortHash string    `json:"shortHash"`
	Author    string    `json:"author"`
	Email     string    `json:"email"`
	Message   string    `json:"message"`
	Date      time.Time `json:"date"`
}

type ContainerFinding struct {
	Finding

	// LayerIndex is the layer number (0 = base layer).
	LayerIndex int `json:"layerIndex"`
	// LayerDigest is the layer's digest.
	LayerDigest string `json:"layerDigest,omitempty"`
	// LayerCommand is the Dockerfile command that created this layer.
	LayerCommand string `json:"layerCommand,omitempty"`
	// InBaseImage indicates if this layer is from the base image.
	InBaseImage bool `json:"inBaseImage"`
	// Source indicates where the secret was found.
	Source ContainerSecretSource `json:"source"`
}

type ContainerScanConfig struct {
	// ScanLayers enables deep layer content scanning.
	ScanLayers bool
	// ScanEnvVars enables environment variable scanning.
	ScanEnvVars bool
	// ScanHistory enables build history scanning.
	ScanHistory bool
	// ScanLabels enables label scanning.
	ScanLabels bool
	// MaxLayerSize limits layer scanning to files under this size (bytes).
	MaxLayerSize int64
	// PathPatterns limits file scanning to matching paths.
	PathPatterns []string
	// BaseImageLayers is the number of layers from the base image.
	BaseImageLayers int
}

type ContainerScanOptions struct {
	Deep     bool
	Platform string
}

type ContainerScanResult struct {
	// Image is the image reference that was scanned.
	Image string `json:"image"`
	// Digest is the image digest.
	Digest string `json:"digest,omitempty"`
	// LayersScanned is how many layers were analyzed.
	LayersScanned int `json:"layersScanned"`
	// Findings contains all discovered secrets.
	Findings []ContainerFinding `json:"findings"`
	// Stats provides aggregate statistics.
	Stats ContainerScanStats `json:"stats"`
}

type ContainerScanStats struct {
	// TotalSecrets is the total secrets found.
	TotalSecrets int `json:"totalSecrets"`
	// BySource breaks down by source location.
	BySource map[ContainerSecretSource]int `json:"bySource"`
	// ByLayer breaks down by layer index.
	ByLayer map[int]int `json:"byLayer"`
	// InBaseImage counts secrets from base image layers.
	InBaseImage int `json:"inBaseImage"`
	// InAppLayers counts secrets from application layers.
	InAppLayers int `json:"inAppLayers"`
}

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

type ContainerSecretSource string

type DiffResult struct {
	// Added are secrets introduced in the target ref.
	Added []Finding
	// Removed are secrets present in base ref but not target ref.
	Removed []Finding
}

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

type EngineConfig struct {
	// EnableEntropy enables entropy-based detection for unknown secret formats.
	EnableEntropy bool
	// EntropyThreshold is the minimum Shannon entropy to flag (0-8 for bytes).
	// Default is 4.5, which catches most random strings while avoiding false positives.
	EntropyThreshold float64
	// EntropyMinLength is the minimum string length for entropy detection.
	EntropyMinLength int
	// DisabledPatterns allows disabling specific pattern detectors.
	DisabledPatterns map[SecretType]bool
	// CustomPatterns allows adding custom pattern detectors.
	CustomPatterns []PatternDetector
}

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

type FilteringScannerOption func(*FilteringScanner)

type Finding struct {
	// Type identifies what kind of secret was found.
	Type SecretType `json:"type"`

	// Description provides human-readable context.
	Description string `json:"description"`

	// File is the source file where the secret was found (if applicable).
	File string `json:"file,omitempty"`

	// Line number where the secret was found (1-indexed, 0 if unknown).
	Line int `json:"line,omitempty"`

	// Column where the secret starts (1-indexed, 0 if unknown).
	Column int `json:"column,omitempty"`

	// Value is the actual secret value (for masking purposes).
	// This should NOT be logged or exposed in reports.
	Value string `json:"-"`

	// Redacted is a safe representation for display.
	Redacted string `json:"redacted"`

	// Confidence indicates detection certainty (0.0-1.0).
	Confidence float64 `json:"confidence"`

	// Validated indicates if the secret was verified as active.
	Validated bool `json:"validated,omitempty"`
}

type GitHistoryOptions struct {
	MaxCommits     int
	Since          string
	Until          string
	Branch         string
	IncludeRemoved bool
}

type HistoricalFinding struct {
	Finding

	// IntroducedIn is the commit that first introduced this secret.
	IntroducedIn *CommitInfo `json:"introducedIn,omitempty"`
	// RemovedIn is the commit that removed this secret (nil if still present).
	RemovedIn *CommitInfo `json:"removedIn,omitempty"`
	// StillPresent indicates if the secret exists in the current HEAD.
	StillPresent bool `json:"stillPresent"`
	// CommitCount is how many commits contained this secret.
	CommitCount int `json:"commitCount"`
	// Authors is the list of commit authors who touched this secret.
	Authors []string `json:"authors,omitempty"`
	// Age is how long the secret has existed (from introduction to now or removal).
	Age time.Duration `json:"age,omitempty"`
}

type HistoryFinding struct {
	Finding

	// CommitHash where the secret was introduced.
	CommitHash string
	// Author of the commit.
	Author string
	// AuthorEmail of the commit author.
	AuthorEmail string
	// CommitDate when the secret was introduced.
	CommitDate string
	// CommitMessage summary.
	CommitMessage string
	// RemovedIn is the commit where the secret was removed (empty if still present).
	RemovedIn string
	// StillPresent indicates if the secret exists in HEAD.
	StillPresent bool
}

type HistoryScanConfig struct {
	// MaxCommits limits how many commits to scan (0 = all).
	MaxCommits int
	// Since only scans commits after this time.
	Since *time.Time
	// Until only scans commits before this time.
	Until *time.Time
	// Branch specifies which branch to scan (default: HEAD).
	Branch string
	// IncludeRemoved includes secrets that were later removed.
	IncludeRemoved bool
	// PathFilter limits scanning to specific paths.
	PathFilter []string
}

type HistoryScanResult struct {
	// Repository is the path to the scanned repository.
	Repository string `json:"repository"`
	// Branch is the branch that was scanned.
	Branch string `json:"branch"`
	// CommitsScanned is the total number of commits analyzed.
	CommitsScanned int `json:"commitsScanned"`
	// Findings contains all historical secret findings.
	Findings []HistoricalFinding `json:"findings"`
	// Stats provides aggregate statistics.
	Stats HistoryStats `json:"stats"`
	// ScannedAt is when the scan was performed.
	ScannedAt time.Time `json:"scannedAt"`
}

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

type HistoryStats struct {
	// TotalSecrets is the total unique secrets found across all commits.
	TotalSecrets int `json:"totalSecrets"`
	// ActiveSecrets is secrets still present in HEAD.
	ActiveSecrets int `json:"activeSecrets"`
	// RemovedSecrets is secrets that were later removed.
	RemovedSecrets int `json:"removedSecrets"`
	// ByType breaks down secrets by type.
	ByType map[SecretType]int `json:"byType"`
	// OldestSecret is the age of the oldest secret.
	OldestSecret time.Duration `json:"oldestSecret,omitempty"`
	// AuthorsWithSecrets lists authors who committed secrets.
	AuthorsWithSecrets []string `json:"authorsWithSecrets,omitempty"`
}

type HookConfig struct {
	// HookType is the type of hook to generate.
	HookType HookType

	// FailOnSecrets determines whether the hook should fail if secrets are found.
	// If false, it will only warn.
	FailOnSecrets bool

	// VerifySecrets enables verification of detected secrets.
	VerifySecrets bool

	// Format is the output format for the hook (text, json, sarif).
	Format string

	// ExcludePatterns are file patterns to exclude from scanning.
	ExcludePatterns []string

	// IncludePatterns are file patterns to include (if empty, scans all).
	IncludePatterns []string

	// DeputyPath is the path to the deputy binary.
	// If empty, assumes "deputy" is in PATH.
	DeputyPath string

	// AllowList is a path to an allowlist/baseline file.
	AllowList string

	// ScanStaged only scans staged files (for pre-commit).
	ScanStaged bool

	// Diff mode for pre-push (compare branches).
	DiffMode bool
}

type HookStatus struct {
	Type      HookType
	Installed bool
	IsDeputy  bool // True if it's a deputy-generated hook
	HasBackup bool // True if there's a backup of previous hook
}

type HookType string

type ImageConfig struct {
	Env        []string            `json:"Env"`
	Entrypoint []string            `json:"Entrypoint"`
	Cmd        []string            `json:"Cmd"`
	Labels     map[string]string   `json:"Labels"`
	History    []ImageHistoryEntry `json:"History"`
}

type ImageHistoryEntry struct {
	CreatedBy  string `json:"created_by"`
	EmptyLayer bool   `json:"empty_layer"`
}

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

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

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

type PatternDetector struct {
	Type        SecretType
	Pattern     *regexp.Regexp
	Description string
	Confidence  float64
}

type PolicyFinding struct {
	// Type is the secret type (e.g., "github_token", "aws_access_key").
	Type string `json:"type"`
	// Description provides context about the finding.
	Description string `json:"description"`
	// File is the path where the secret was found.
	File string `json:"file"`
	// Line is the line number (1-indexed).
	Line int `json:"line"`
	// Column is the column number (1-indexed).
	Column int `json:"column"`
	// Confidence is the detection confidence (0.0-1.0).
	Confidence float64 `json:"confidence"`
	// Validated indicates if the secret was verified as active.
	Validated bool `json:"validated"`
	// Redacted is the safe redacted representation.
	Redacted string `json:"redacted"`
	// Source identifies where the secret was found (for container scans).
	Source string `json:"source,omitempty"`
	// InBaseImage indicates if found in base image layer (for containers).
	InBaseImage bool `json:"inBaseImage,omitempty"`
	// LayerIndex is the layer where the secret was found (for containers).
	LayerIndex int `json:"layerIndex,omitempty"`
}

type PolicyReport struct {
	// Target is what was scanned (directory, image, archive).
	Target string `json:"target"`
	// FilesScanned is the number of files analyzed.
	FilesScanned int `json:"filesScanned"`
	// SecretsFound is the total number of secrets detected.
	SecretsFound int `json:"secretsFound"`
	// HighConfidenceCount is findings with >= 90% confidence.
	HighConfidenceCount int `json:"highConfidenceCount"`
	// ValidatedCount is the number of verified active secrets.
	ValidatedCount int `json:"validatedCount"`
	// Stats provides aggregate counts by secret type.
	Stats map[string]int `json:"stats"`
}

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

type SARIFReportOptions struct {
	// ToolVersion is the version of the tool.
	ToolVersion string
	// BaseURI is the base URI for relative file paths.
	BaseURI string
	// Repo is the repository URL or path that was scanned.
	Repo string
	// Ref is the git reference (branch/tag) that was scanned.
	Ref string
	// Commit is the git commit hash.
	Commit string
	// Category is a unique identifier for this analysis run.
	Category string
	// WorkingDirectory is the base path for artifact URIs.
	WorkingDirectory string
	// StartTime is when the scan started.
	StartTime time.Time
	// EndTime is when the scan completed.
	EndTime time.Time
}

type Scanner interface {
	// Scan analyzes content and returns any detected secrets.
	Scan(ctx context.Context, content []byte) ([]Finding, error)

	// ScanFile analyzes file content with filename context.
	ScanFile(ctx context.Context, filename string, content []byte) ([]Finding, error)
}

type SecretType string

type VerificationConfig struct {
	// Timeout for individual verification requests.
	Timeout time.Duration
	// MaxConcurrent limits parallel verification requests.
	MaxConcurrent int
	// SkipTLSVerify disables TLS certificate validation (for testing).
	SkipTLSVerify bool
	// RateLimit is max verifications per second (0 = unlimited).
	RateLimit int
}

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

type VerificationResult struct {
	// Status is the verification outcome.
	Status VerificationStatus `json:"status"`
	// Message provides additional context about the verification.
	Message string `json:"message,omitempty"`
	// Service identifies the service the secret belongs to.
	Service string `json:"service,omitempty"`
	// Identity is the authenticated identity (e.g., username, service account).
	Identity string `json:"identity,omitempty"`
	// Scopes lists the permissions/scopes the secret has.
	Scopes []string `json:"scopes,omitempty"`
	// ExpiresAt is when the secret expires (if applicable).
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
	// VerifiedAt is when verification was performed.
	VerifiedAt time.Time `json:"verifiedAt"`
	// Error contains error details if verification failed.
	Error string `json:"error,omitempty"`
}

type VerificationStatus string

type Verifier interface {
	// CanVerify returns true if this verifier handles the given secret type.
	CanVerify(secretType SecretType) bool
	// Verify checks if a secret is valid/active.
	Verify(ctx context.Context, secret string, secretType SecretType) VerificationResult
	// Name returns the verifier name for logging.
	Name() string
}

type VerifyOptions struct {
	RateLimit int
	Timeout   time.Duration
}