fuzzfinder

package
v2026.0.159 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 31, 2026 License: MPL-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package fuzzfinder finds Go-generated fuzz corpus and crasher artifacts in one rooted directory with bounded memory and explicit partial accounting.

Classification is declared by the caller and carried, not inferred. The Go toolchain writes cache corpus entries and testdata crashers under the same generated-name format, so the containing directory is the only discriminator and every observation reports the artifact class its request named.

It does not run fuzz tests, mutate files, retain payload custody, or define a consumer's evidence schema.

Index

Constants

View Source 
const (
	// MaximumRetainedEntries is the product-neutral safety ceiling for one
	// bounded observation.
	MaximumRetainedEntries uint16 = 128
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ArtifactKind 

type ArtifactKind uint8

ArtifactKind is the closed wire identity of a corpus or crasher artifact. 

const (
	ArtifactUnknown ArtifactKind = iota
	ArtifactCorpus
	ArtifactCrasher
)

func ParseArtifactKind 

func ParseArtifactKind(token string) (ArtifactKind, error)

ParseArtifactKind parses one exact wire token.

func (ArtifactKind) IsValid 

func (k ArtifactKind) IsValid() bool

IsValid reports membership in the corpus/crasher domain.

func (ArtifactKind) MarshalJSON 

func (k ArtifactKind) MarshalJSON() ([]byte, error)

MarshalJSON emits the exact artifact-kind token.

func (ArtifactKind) String 

func (k ArtifactKind) String() string

String returns the exact wire token or a diagnostic unknown token.

func (*ArtifactKind) UnmarshalJSON 

func (k *ArtifactKind) UnmarshalJSON(data []byte) error

UnmarshalJSON admits one bounded artifact-kind string and preserves the receiver on rejection.

func (ArtifactKind) Validate 

func (k ArtifactKind) Validate() error

Validate rejects values outside the corpus/crasher domain.

type CacheFormat 

type CacheFormat uint8

CacheFormat identifies one exact Go-generated fuzz-artifact filename format. 

const (
	CacheFormatUnknown CacheFormat = iota
	// CacheFormatGo1_27 is the generated cache/crasher filename format written
	// by Go 1.27's internal fuzz engine.
	CacheFormatGo1_27
)

func (CacheFormat) GeneratedName added in v2026.0.148 

func (f CacheFormat) GeneratedName(kind ArtifactKind, digest core.SHA256Digest) (GeneratedName, error)

GeneratedName derives the exact Go-generated filename for one content digest under f. Go's corpus writer names persisted entries from the leading digest bytes; the selected cache format owns the exact width.

func (CacheFormat) GeneratedNameBytes 

func (f CacheFormat) GeneratedNameBytes(kind ArtifactKind) (core.ByteCount, error)

GeneratedNameBytes returns the exact persisted filename width for kind under f. Go 1.27 writes both cache corpus and durable crashers through writeToCorpus.

func (CacheFormat) IsValid 

func (f CacheFormat) IsValid() bool

IsValid reports whether f is a supported cache format.

func (CacheFormat) OffWireEnum 

func (CacheFormat) OffWireEnum()

OffWireEnum declares CacheFormat as execution policy rather than wire data.

func (CacheFormat) String 

func (f CacheFormat) String() string

String returns the compiler-owned diagnostic label for f.

func (CacheFormat) Validate 

func (f CacheFormat) Validate() error

Validate rejects unsupported cache formats.

type EntryCount 

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

EntryCount is a saturating count of observed directory entries.

func (EntryCount) Uint64 

func (c EntryCount) Uint64() uint64

Uint64 returns the exact or saturated count.

type FindRequest 

type FindRequest struct {
	Location  filestore.Location
	Retention RetentionLimit
	Kind      ArtifactKind
	Format    CacheFormat
}

FindRequest binds one rooted directory, one declared artifact class, the exact Go format, and a retention limit to one observation.

Kind is declared rather than observed. Go 1.27 persists cache corpus and testdata crashers through the same filename projection, so the name alone cannot identify its class. Binding Kind into the request and retained name prevents corpus and crasher facts from being merged.

func (FindRequest) Validate 

func (r FindRequest) Validate() error

Validate rejects every unset or unsupported request boundary.

type GeneratedName 

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

GeneratedName is one exact Go-generated fuzz cache or crasher filename.

func ParseGeneratedName 

func ParseGeneratedName(format CacheFormat, kind ArtifactKind, value string) (GeneratedName, error)

ParseGeneratedName parses one filename under the declared Go cache format.

func (GeneratedName) Format added in v2026.0.148 

func (n GeneratedName) Format() CacheFormat

Format returns the exact Go toolchain format that produced n.

func (GeneratedName) Kind added in v2026.0.148 

func (n GeneratedName) Kind() ArtifactKind

Kind returns the artifact class whose Go-generated naming rule produced n.

func (GeneratedName) String 

func (n GeneratedName) String() string

String returns the exact generated filename.

func (GeneratedName) Validate 

func (n GeneratedName) Validate() error

Validate rejects unset, cross-kind, cross-format, or malformed names.

type Observation 

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

Observation is the bounded, canonical result of finding generated artifacts in one directory. Names are observations only; they do not prove payload identity or custody.

func Find 

func Find(ctx context.Context, request FindRequest) (Observation, error)

Find streams one real rooted directory through Filestore. It retains only a bounded canonical prefix and preserves Filestore's external-door identity beneath the stable Fuzzfinder observation identity.

func (Observation) Format added in v2026.0.148 

func (o Observation) Format() CacheFormat

Format returns the exact Go naming contract applied to this observation.

func (Observation) IgnoredDirectories 

func (o Observation) IgnoredDirectories() EntryCount

IgnoredDirectories returns the number of child directories not descended.

func (Observation) Kind 

func (o Observation) Kind() ArtifactKind

Kind returns the artifact class the request declared for this directory. It is present on every observation, including a failed one, because the class is a property of the directory the caller named rather than of what was read.

func (Observation) Names 

func (o Observation) Names() []GeneratedName

Names returns a defensive copy of the canonical retained prefix.

func (Observation) NonRegular 

func (o Observation) NonRegular() EntryCount

NonRegular returns the number of non-directory, non-regular entries.

func (Observation) OverLimitObservations 

func (o Observation) OverLimitObservations() EntryCount

OverLimitObservations returns the number of otherwise valid observations omitted or displaced after the retention limit was full. The unit is an observation, so a non-native reader that repeats an omitted name repeats the count; real directories cannot contain duplicate names.

func (Observation) Retained 

func (o Observation) Retained() EntryCount

Retained returns the number of returned names.

func (Observation) State 

func (o Observation) State() ObservationState

State returns the observation completeness state.

func (Observation) UnsupportedRegular 

func (o Observation) UnsupportedRegular() EntryCount

UnsupportedRegular returns regular files outside the declared Go format.

func (Observation) Validate 

func (o Observation) Validate() error

Validate rejects contradictory observation states and noncanonical names.

type ObservationState 

type ObservationState uint8

ObservationState describes how completely one directory was observed. 

const (
	ObservationUnknown ObservationState = iota
	ObservationComplete
	ObservationUnsupportedFormat
	ObservationPartial
	ObservationFailed
)

func (ObservationState) IsValid 

func (s ObservationState) IsValid() bool

IsValid reports membership in the closed observation domain.

func (ObservationState) OffWireEnum 

func (ObservationState) OffWireEnum()

OffWireEnum declares ObservationState as a runtime result, not wire data.

func (ObservationState) String 

func (s ObservationState) String() string

String returns the compiler-owned diagnostic label for s.

func (ObservationState) Validate 

func (s ObservationState) Validate() error

Validate rejects values outside the closed observation domain.

type RetentionLimit 

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

RetentionLimit is the caller-selected bounded number of canonical names to retain from one observation.

func NewRetentionLimit 

func NewRetentionLimit(value uint16) (RetentionLimit, error)

NewRetentionLimit constructs a nonzero limit at or below the shared ceiling.

func (RetentionLimit) Uint16 

func (l RetentionLimit) Uint16() uint16

Uint16 returns the exact retained-name ceiling.

func (RetentionLimit) Validate 

func (l RetentionLimit) Validate() error

Validate rejects zero or above-ceiling limits.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.