findings

Documentation

Index

• Constants
• Variables
• func NewID() string
• type Bus
  • func NewBus() *Bus
  • func (b *Bus) Emit(f Finding)
  • func (b *Bus) Subscribe(ctx context.Context) <-chan Finding
• type Finding
  • func FromProto(pluginID string, incoming *pb.Finding) (Finding, error)
  • func (f Finding) Clone() Finding
  • func (f Finding) Timestamp() time.Time
  • func (f Finding) Validate() error
• type Severity
  • func (s Severity) MarshalJSON() ([]byte, error)
  • func (s *Severity) UnmarshalJSON(data []byte) error
• type Timestamp
  • func NewTimestamp(t time.Time) Timestamp
  • func (t Timestamp) Equal(other time.Time) bool
  • func (t Timestamp) IsZero() bool
  • func (t Timestamp) MarshalJSON() ([]byte, error)
  • func (t Timestamp) Time() time.Time
  • func (t *Timestamp) UnmarshalJSON(data []byte) error
• type Writer
  • func NewWriter(path string, opts ...WriterOption) *Writer
  • func (w *Writer) Close() error
  • func (w *Writer) Path() string
  • func (w *Writer) Write(f Finding) error
• type WriterOption
  • func WithBufferSize(size int) WriterOption
  • func WithMaxBytes(limit int64) WriterOption
  • func WithMaxRotations(count int) WriterOption

Constants

const SchemaVersion = "0.2"

SchemaVersion captures the canonical findings schema version persisted to disk.

Variables

var DefaultFindingsPath = filepath.Join(defaultOutputDir, defaultFilename)

DefaultFindingsPath is the canonical location for persisted findings.

Functions

func NewID

func NewID() string

NewID generates a new ULID suitable for persisting as a finding identifier.

Types

type Bus

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

Bus provides an in-process pub/sub system for findings. Multiple subscribers can listen for emitted findings concurrently.

func NewBus

func NewBus() *Bus

NewBus returns a new, empty findings bus.

func (*Bus) Emit

func (b *Bus) Emit(f Finding)

Emit publishes a finding to all registered subscribers. If no subscribers are present the call is a no-op.

func (*Bus) Subscribe

func (b *Bus) Subscribe(ctx context.Context) <-chan Finding

Subscribe registers a new subscriber that will receive emitted findings. The returned channel is closed when the provided context is cancelled.

type Finding

type Finding struct {
	Version    string            `json:"version"`
	ID         string            `json:"id"`
	Plugin     string            `json:"plugin"`
	Type       string            `json:"type"`
	Message    string            `json:"message"`
	Target     string            `json:"target,omitempty"`
	Evidence   string            `json:"evidence,omitempty"`
	Severity   Severity          `json:"severity"`
	DetectedAt Timestamp         `json:"ts"`
	Metadata   map[string]string `json:"meta,omitempty"`
}

Finding represents a single issue reported by a plugin.

func FromProto

func FromProto(pluginID string, incoming *pb.Finding) (Finding, error)

FromProto converts a protobuf Finding emitted by a plugin into the internal representation persisted by 0xgend.

func (Finding) Clone

func (f Finding) Clone() Finding

Clone returns a deep copy of the finding to avoid accidental mutation when broadcasting to subscribers.

func (Finding) Timestamp

func (f Finding) Timestamp() time.Time

Timestamp returns the detection timestamp in UTC to simplify reporting code.

func (Finding) Validate

func (f Finding) Validate() error

Validate performs sanity checks ensuring the struct complies with the contract codified in specs/finding.md.

type Severity

type Severity string

Severity captures the allowed severity values for findings persisted by the host. The values are normalised to lowercase short codes for stable JSON encoding.

const (
	SeverityInfo     Severity = "info"
	SeverityLow      Severity = "low"
	SeverityMedium   Severity = "med"
	SeverityHigh     Severity = "high"
	SeverityCritical Severity = "crit"
)

func (Severity) MarshalJSON

func (s Severity) MarshalJSON() ([]byte, error)

MarshalJSON ensures severities are always emitted as quoted strings.

func (*Severity) UnmarshalJSON

func (s *Severity) UnmarshalJSON(data []byte) error

UnmarshalJSON performs strict validation so we catch typos during testing and when loading persisted findings.

type Timestamp

type Timestamp time.Time

Timestamp enforces RFC3339 timestamps when encoding findings to disk.

func NewTimestamp

func NewTimestamp(t time.Time) Timestamp

NewTimestamp normalises the input time before persisting it.

func (Timestamp) Equal

func (t Timestamp) Equal(other time.Time) bool

Equal compares the timestamp to the provided time value.

func (Timestamp) IsZero

func (t Timestamp) IsZero() bool

IsZero reports whether the timestamp has been initialised.

func (Timestamp) MarshalJSON

func (t Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON renders the timestamp using time.RFC3339. Zero values encode as an empty string so Validate can flag missing timestamps explicitly.

func (Timestamp) Time

func (t Timestamp) Time() time.Time

Time exposes the underlying time value.

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON enforces RFC3339 timestamps when reading persisted findings.

type Writer

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

Writer persists findings to a JSON Lines file with size based rotation.

func NewWriter

func NewWriter(path string, opts ...WriterOption) *Writer

NewWriter constructs a writer targeting the provided path.

func (*Writer) Close

func (w *Writer) Close() error

Close flushes and closes the underlying file handle.

func (*Writer) Path

func (w *Writer) Path() string

Path returns the file path currently used by the writer.

func (*Writer) Write

func (w *Writer) Write(f Finding) error

Write validates and appends the finding to disk.

type WriterOption

type WriterOption func(*Writer)

WriterOption configures the writer behaviour.

func WithBufferSize

func WithBufferSize(size int) WriterOption

WithBufferSize overrides the buffered writer size.

func WithMaxBytes

func WithMaxBytes(limit int64) WriterOption

WithMaxBytes overrides the rotation threshold. Values <= 0 disable rotation.

func WithMaxRotations

func WithMaxRotations(count int) WriterOption

WithMaxRotations sets how many rotated files are retained. Values < 1 keep a single log file without rotation history.