snapshot

Documentation

Overview

Package snapshot persists and lists Snapshots as gzipped JSON. No database: one file per run under salient-data/snapshots plus an index.json. Files are written 0600 in 0700 dirs — topology artifacts are sensitive (§14).

Index

• func Load(path string) (graph.Snapshot, error)
• func Save(dataRoot string, snap graph.Snapshot) (string, error)
• func SnapshotsDir(dataRoot string) string
• type ArtifactEntry
  • func ScanArtifacts(dataDir string) ([]ArtifactEntry, error)
• type Diff
  • func Compare(from, to graph.Snapshot, opts DiffOptions) Diff
• type DiffOptions
• type IdentityChange
• type IndexEntry
  • func List(dataRoot string) ([]IndexEntry, error)
• type MigrationSource
• type NewProvider
• type ProviderDisplacement
• type RankChange
• type RoleChange

Functions

func Load

func Load(path string) (graph.Snapshot, error)

Load reads a snapshot from a .json.gz file path (or a bare name resolved against the snapshots dir).

func Save

func Save(dataRoot string, snap graph.Snapshot) (string, error)

Save writes the snapshot as <timestamp>.json.gz and appends to index.json. Returns the file path.

func SnapshotsDir

func SnapshotsDir(dataRoot string) string

SnapshotsDir returns the snapshots directory under the data root.

Types

type ArtifactEntry

type ArtifactEntry struct {
	Timestamp string
	Report    string
	Map       string
	Snapshot  string
}

ArtifactEntry groups locally stored artifacts from one scan.

func ScanArtifacts

func ScanArtifacts(dataDir string) ([]ArtifactEntry, error)

ScanArtifacts lists stored reports, maps, and snapshots newest first.

type Diff

type Diff struct {
	FromMeta              graph.SnapshotMeta     `json:"from"`
	ToMeta                graph.SnapshotMeta     `json:"to"`
	CompatibilityWarnings []string               `json:"compatibility_warnings,omitempty"`
	AppearedNodes         []graph.Node           `json:"appeared_nodes"`
	DisappearedNodes      []graph.Node           `json:"disappeared_nodes"`
	RankChanges           []RankChange           `json:"rank_changes"`
	NewEdgesToTop         []graph.Edge           `json:"new_edges_to_top"`
	VanishedCriticalEdges []graph.Edge           `json:"vanished_critical_edges"`
	RoleChanges           []RoleChange           `json:"role_changes"`
	IdentityChanges       []IdentityChange       `json:"identity_changes,omitempty"`
	NewProviders          []NewProvider          `json:"new_providers"`
	ProviderDisplacements []ProviderDisplacement `json:"provider_displacements"`
}

Diff is the analyst-relevant drift between two snapshots.

func Compare

func Compare(from, to graph.Snapshot, opts DiffOptions) Diff

Compare returns deterministic drift signals required by Phase 2.

type DiffOptions

type DiffOptions struct {
	RankDelta int
	TopN      int
}

DiffOptions controls which rank and critical-edge changes are reported.

type IdentityChange

type IdentityChange struct {
	IP       string   `json:"ip"`
	Protocol string   `json:"protocol"`
	Added    []string `json:"added,omitempty"`
	Removed  []string `json:"removed,omitempty"`
}

type IndexEntry

type IndexEntry struct {
	File      string    `json:"file"`
	CreatedAt time.Time `json:"created_at"`
	Window    string    `json:"window"`
	Nodes     int       `json:"nodes"`
	Edges     int       `json:"edges"`
	Cluster   string    `json:"cluster"`
}

IndexEntry is one line of index.json summarizing a stored snapshot.

func List

func List(dataRoot string) ([]IndexEntry, error)

List returns index entries, newest first.

type MigrationSource

type MigrationSource struct {
	IP      string `json:"ip"`
	Port    uint16 `json:"port"`
	Clients int    `json:"clients"`
}

MigrationSource is one prior provider some of a new provider's clients came from, and how many.

type NewProvider

type NewProvider struct {
	IP      string `json:"ip"`
	Port    uint16 `json:"port"`
	Service string `json:"service"`
	Clients int    `json:"clients"`
	NewHost bool   `json:"new_host"`
	Rank    int    `json:"rank"`
}

NewProvider is a responder that began providing a sensitive service between the snapshots, regardless of terrain rank — a new low-ranked DNS/DHCP/auth/file/DB provider is an investigation lead, not proof of malicious intent.

type ProviderDisplacement

type ProviderDisplacement struct {
	IP           string            `json:"ip"`
	Port         uint16            `json:"port"`
	Service      string            `json:"service"`
	ClientsAdded int               `json:"clients_added"` // clients new to this service entirely, not from a tracked prior provider
	MigratedFrom []MigrationSource `json:"migrated_from,omitempty"`
	Rank         int               `json:"rank,omitempty"`
}

ProviderDisplacement summarizes client movement into one provider from other providers of the same service between two snapshots — e.g. "14 clients that used Y now use X." Purely descriptive: which clients moved and from where, never an intent judgment. Only the gaining provider gets an entry; a provider that only lost clients isn't tracked here.

type RankChange

type RankChange struct {
	IP       string `json:"ip"`
	FromRank int    `json:"from_rank"`
	ToRank   int    `json:"to_rank"`
	Delta    int    `json:"delta"`
}

RankChange uses a positive Delta when a node moved toward rank 1.

type RoleChange

type RoleChange struct {
	IP   string       `json:"ip"`
	From []graph.Role `json:"from"`
	To   []graph.Role `json:"to"`
}