Documentation
¶
Overview ¶
Package finding defines the Leakwatch finding model. This package is public and can be consumed by external tools such as CI plugins.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Finding ¶
type Finding struct {
// ID is an opaque, deterministic identifier: a truncated SHA-256 rendered
// as a lowercase hex string (32 hex characters, no dashes). It is NOT a
// UUID; consumers must not validate it against a UUID format.
ID string `json:"id"`
DetectorID string `json:"detector_id"`
Severity Severity `json:"severity"`
Raw string `json:"-"`
Redacted string `json:"redacted"`
// SourceMetadata describes where the finding originated. Its custom
// MarshalJSON omits a zero Date so non-git sources do not serialize a
// bogus "0001-01-01T00:00:00Z".
SourceMetadata SourceMetadata `json:"source"`
Verification VerificationResult `json:"verification"`
Remediation *Remediation `json:"remediation,omitempty"`
DetectedAt time.Time `json:"detected_at"`
// Entropy is the Shannon entropy of the raw match, populated only when
// entropy analysis is enabled. It is omitted (via omitempty) when it holds
// the Go zero value, so a serialized finding cannot distinguish "not
// computed" from "computed as exactly 0.0"; consumers should treat an
// absent entropy as "not computed" rather than zero.
Entropy float64 `json:"entropy,omitempty"`
// ExtraData carries non-secret contextual metadata. It is json:"-" as a
// defense-in-depth measure (see the type doc); it must never hold secret
// material.
ExtraData map[string]string `json:"-"`
}
Finding represents a fully enriched secret finding.
The Raw field holds the unredacted secret. It carries a json:"-" tag so that the standard library NEVER serializes it: any external consumer that marshals a Finding cannot accidentally leak the secret. Output formatters that support an explicit opt-in (e.g. --show-raw) re-add the value via a dedicated wire type rather than relying on this struct's tags.
ExtraData is treated with the same defense-in-depth as Raw: it also carries a json:"-" tag so a detector that mistakenly stashes secret material there can never leak it into the default (non --show-raw) output path. Formatters that support --show-raw re-add it through their own opt-in wire type.
type Remediation ¶
type Remediation struct {
Title string `json:"title"`
Steps []string `json:"steps"`
DocURL string `json:"doc_url,omitempty"`
ConsoleURL string `json:"console_url,omitempty"`
Urgency string `json:"urgency"`
Checklist []string `json:"checklist,omitempty"`
}
Remediation provides actionable guidance for rotating or revoking a detected secret.
type Severity ¶
type Severity int
Severity represents the finding severity level.
func ParseSeverity ¶ added in v1.7.0
ParseSeverity converts a severity name to its Severity value. Matching is case-sensitive against the four canonical names ("low", "medium", "high", "critical"). The boolean is false when s is not one of them, so callers can decide their own fallback or reject the value explicitly instead of silently downgrading an unrecognized string. It is the single source of truth shared by the CLI (--min-severity) and custom-rule severity parsing.
func (Severity) MarshalJSON ¶
MarshalJSON serializes Severity as a JSON string.
func (*Severity) UnmarshalJSON ¶
UnmarshalJSON parses a Severity value from a JSON string.
type SourceMetadata ¶
type SourceMetadata struct {
SourceType string `json:"source_type"`
// Git-specific fields
Repository string `json:"repository,omitempty"`
Commit string `json:"commit,omitempty"`
Author string `json:"author,omitempty"`
Email string `json:"email,omitempty"`
Date time.Time `json:"date,omitempty"`
Branch string `json:"branch,omitempty"`
// File-specific fields
FilePath string `json:"file_path,omitempty"`
Line int `json:"line,omitempty"`
// Container-specific fields
Image string `json:"image,omitempty"`
Layer string `json:"layer,omitempty"`
LayerIdx int `json:"layer_idx,omitempty"`
// Slack-specific fields
Channel string `json:"channel,omitempty"`
ChannelName string `json:"channel_name,omitempty"`
MessageUser string `json:"message_user,omitempty"`
MessageTS string `json:"message_ts,omitempty"`
ThreadTS string `json:"thread_ts,omitempty"`
}
SourceMetadata describes the origin of a finding.
func (SourceMetadata) MarshalJSON ¶ added in v1.7.0
func (m SourceMetadata) MarshalJSON() ([]byte, error)
MarshalJSON serializes SourceMetadata, omitting Date when it holds the zero time. encoding/json's omitempty is a no-op on a time.Time struct value, so a non-git finding (which never sets Date) would otherwise serialize a bogus "date":"0001-01-01T00:00:00Z". A pointer shadow field lets omitempty apply.
type VerificationResult ¶
type VerificationResult struct {
Status VerificationStatus `json:"status"`
Message string `json:"message,omitempty"`
ExtraData map[string]string `json:"extra_data,omitempty"`
}
VerificationResult represents the outcome of a verification attempt.
type VerificationStatus ¶
type VerificationStatus int
VerificationStatus represents the verification state.
const ( StatusUnverified VerificationStatus = iota // Not verified StatusVerifiedActive // Verified: secret is active StatusVerifiedInactive // Verified: secret is inactive StatusVerifyError // Verification error )
func (VerificationStatus) MarshalJSON ¶
func (v VerificationStatus) MarshalJSON() ([]byte, error)
MarshalJSON serializes VerificationStatus as a JSON string.
func (VerificationStatus) String ¶
func (v VerificationStatus) String() string
String returns the human-readable representation of VerificationStatus.
func (*VerificationStatus) UnmarshalJSON ¶
func (v *VerificationStatus) UnmarshalJSON(data []byte) error
UnmarshalJSON parses a VerificationStatus value from a JSON string.
Source Files