core

Documentation

Overview

Package core defines the records a run produces. It performs no I/O and imports nothing else from this project, so every other package can depend on it without creating a cycle.

Index

• Constants
• func NormalizeHostname(s string) string
• func ValidHostname(s string) bool
• type Asset
• type Counts
• type IDGen
  • func NewFixedIDGen(t time.Time, entropy io.Reader) *IDGen
  • func NewIDGen() *IDGen
  • func (g *IDGen) New() string
• type Kind
• type Observation
• type Run
  • func (r Run) Duration() time.Duration
• type SourceRun
• type State
• type Violation

Constants

const (
	SourceOK         = "ok"
	SourceSkipped    = "skipped"
	SourceFailed     = "failed"
	SourceTerminated = "terminated"
)

Source statuses recorded in a run summary.

Functions

func NormalizeHostname

func NormalizeHostname(s string) string

NormalizeHostname lowercases a name, strips the trailing dot and any leading wildcard label, so the same host from two sources compares equal.

func ValidHostname

func ValidHostname(s string) bool

ValidHostname reports whether s is a plausible DNS name. It is intentionally permissive about TLDs and strict about characters, because a malformed name from a source must never reach a resolver.

Types

type Asset

type Asset struct {
	Hostname    string    `json:"hostname"`
	State       State     `json:"state"`
	InScope     bool      `json:"in_scope"`
	Sources     []string  `json:"sources"`
	Addresses   []string  `json:"addresses,omitempty"`
	CNAMEChain  []string  `json:"cname_chain,omitempty"`
	CNAMELive   *bool     `json:"cname_live,omitempty"`
	Wildcard    bool      `json:"wildcard"`
	TLSNames    []string  `json:"tls_names,omitempty"`
	HTTPStatus  int       `json:"http_status,omitempty"`
	FinalURL    string    `json:"final_url,omitempty"`
	FirstSeen   time.Time `json:"first_seen"`
	EvidenceIDs []string  `json:"evidence_ids"`
}

Asset is the derived view of one hostname. Every populated field traces to at least one observation listed in EvidenceIDs.

type Counts

type Counts struct {
	Observations int `json:"observations"`
	Assets       int `json:"assets"`
	InScope      int `json:"in_scope"`
	OutOfScope   int `json:"out_of_scope"`
	Corroborated int `json:"corroborated"`
	Resolved     int `json:"resolved"`
	Reachable    int `json:"reachable"`
	Wildcard     int `json:"wildcard"`
}

Counts summarizes a run without the caller reading assets.ndjson.

type IDGen

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

IDGen produces ULIDs: a 48-bit millisecond timestamp followed by 80 bits of entropy, so IDs sort by creation time as plain strings. The clock and entropy are injected so tests can pin both and diff a run directory.

func NewFixedIDGen

func NewFixedIDGen(t time.Time, entropy io.Reader) *IDGen

NewFixedIDGen returns a generator with a fixed clock and caller-supplied entropy, for golden tests.

func NewIDGen

func NewIDGen() *IDGen

NewIDGen returns a generator backed by the wall clock and crypto/rand.

func (*IDGen) New

func (g *IDGen) New() string

New returns the next ULID. It never fails: an entropy read error is unrecoverable and would otherwise force error handling into every emit path.

type Kind

type Kind string

Kind is what an observation claims.

const (
	KindHostname     Kind = "hostname"
	KindCNAME        Kind = "cname"
	KindAddress      Kind = "address"
	KindTLSName      Kind = "tls_name"
	KindHTTPResponse Kind = "http_response"
)

type Observation

type Observation struct {
	ID         string    `json:"id"`
	RunID      string    `json:"run_id"`
	SourceID   string    `json:"source_id"`
	Kind       Kind      `json:"kind"`
	Hostname   string    `json:"hostname"`
	Value      string    `json:"value,omitempty"`
	Query      string    `json:"query,omitempty"`
	RawSHA256  string    `json:"raw_sha256,omitempty"`
	ObservedAt time.Time `json:"observed_at"`
}

Observation is one claim from one source at one time. The ledger is append-only: an observation is never edited or deleted once written.

type Run

type Run struct {
	ID          string      `json:"id"`
	SchemaVer   string      `json:"schema_version"`
	Roots       []string    `json:"roots"`
	Profile     string      `json:"profile"`
	ScopeMode   string      `json:"scope_mode"`
	ScopeSource string      `json:"scope_source,omitempty"`
	Stages      []string    `json:"stages"`
	StartedAt   time.Time   `json:"started_at"`
	FinishedAt  time.Time   `json:"finished_at"`
	Counts      Counts      `json:"counts"`
	Sources     []SourceRun `json:"sources"`
	Violations  []Violation `json:"violations"`
}

Run is the summary record written to summary.json.

func (Run) Duration

func (r Run) Duration() time.Duration

Duration is the wall time of the run.

type SourceRun

type SourceRun struct {
	ID         string        `json:"id"`
	Activity   string        `json:"activity"`
	Status     string        `json:"status"`
	Hostnames  int           `json:"hostnames"`
	DurationMS int64         `json:"duration_ms"`
	Error      string        `json:"error,omitempty"`
	RetryAfter time.Duration `json:"retry_after,omitempty"`
}

SourceRun is what one source did during a run, including why it contributed nothing when that is the case.

type State

type State string

State is how much a hostname has been proven, from a bare claim to a host that answered. It is deliberately discrete: there is no confidence score, because a caller cannot check a decimal against anything.

const (
	StateObserved     State = "observed"
	StateCorroborated State = "corroborated"
	StateResolved     State = "resolved"
	StateReachable    State = "reachable"
)

type Violation

type Violation struct {
	SourceID string    `json:"source_id"`
	Target   string    `json:"target"`
	Reason   string    `json:"reason"`
	At       time.Time `json:"at"`
}

Violation is a module's attempt to reach a host that policy did not authorize. Recording it is not optional: a run that hides one is worse than a run that fails.