memory

Documentation

Overview

Package memory manages the .vulnetix/memory.yaml file that persists scan state between runs — last scan summary, history, and cached findings.

Index

• Constants
• func Save(vulnetixDir string, m *Memory) error
• type CWSSData
• type Decision
• type DiscoveryInfo
• type EnvironmentContext
• type FindingRecord
• type HistoryEntry
• type Memory
  • func Load(vulnetixDir string) (*Memory, error)
  • func (m *Memory) GetFinding(cveID string) *FindingRecord
  • func (m *Memory) RecordScan(rec ScanRecord)
  • func (m *Memory) RecordVDBQuery(q VDBQuery)
  • func (m *Memory) RecordVulnLookup(vulnID string, data interface{})
  • func (m *Memory) SetFinding(cveID string, data FindingRecord)
  • func (m *Memory) UpdateEnvironment(env *EnvironmentContext)
• type ScanRecord
• type ScopeStats
• type ThreatModel
• type VDBQuery
• type VersionInfo

Constants

const (
	// FileName is the basename of the memory file inside .vulnetix/.
	FileName = "memory.yaml"
)

Functions

func Save

func Save(vulnetixDir string, m *Memory) error

Save writes m to memory.yaml inside vulnetixDir, creating the directory if needed.

Types

type CWSSData

type CWSSData struct {
	Score    float64            `yaml:"score"`
	Priority string             `yaml:"priority,omitempty"`
	Factors  map[string]float64 `yaml:"factors,omitempty"`
}

CWSSData holds a CWSS-derived priority score.

type Decision

type Decision struct {
	Choice string `yaml:"choice"`
	Reason string `yaml:"reason"`
	Date   string `yaml:"date"` // RFC3339
	Actor  string `yaml:"actor,omitempty"`
}

Decision records a user's decision about a vulnerability.

type DiscoveryInfo

type DiscoveryInfo struct {
	Date   string `yaml:"date"`
	Source string `yaml:"source"` // scan | hook | user | vulnetix-triage | github-triage
	File   string `yaml:"file,omitempty"`
	SBOM   string `yaml:"sbom,omitempty"`
}

DiscoveryInfo records how and when a vulnerability was discovered.

type EnvironmentContext

type EnvironmentContext struct {
	Platform        string `yaml:"platform,omitempty"`
	GitLocalDir     string `yaml:"git_local_dir,omitempty"`
	GitBranch       string `yaml:"git_branch,omitempty"`
	GitCommit       string `yaml:"git_commit,omitempty"`
	GitRemoteURL    string `yaml:"remote_url,omitempty"`
	GitRemoteBranch string `yaml:"remote_branch,omitempty"`
	CommitterName   string `yaml:"committer_name,omitempty"`
	CommitterEmail  string `yaml:"committer_email,omitempty"`
	GithubOrg       string `yaml:"github_org,omitempty"`
	GithubRepo      string `yaml:"github_repo,omitempty"`
	GithubPR        string `yaml:"github_pr,omitempty"`
	PackageManager  string `yaml:"package_manager,omitempty"`
	ManifestFormat  string `yaml:"manifest_format,omitempty"`
}

EnvironmentContext captures the auto-gathered or flag-provided context for a VDB query session. This schema is shared with the Claude Code plugin.

type FindingRecord

type FindingRecord struct {
	Aliases        []string       `yaml:"aliases,omitempty"`
	Package        string         `yaml:"package,omitempty"`
	Ecosystem      string         `yaml:"ecosystem,omitempty"`
	Discovery      *DiscoveryInfo `yaml:"discovery,omitempty"`
	Versions       *VersionInfo   `yaml:"versions,omitempty"`
	Severity       string         `yaml:"severity,omitempty"`
	SafeHarbour    float64        `yaml:"safe_harbour,omitempty"`
	Status         string         `yaml:"status,omitempty"` // not_affected | affected | fixed | under_investigation
	Justification  string         `yaml:"justification,omitempty"`
	ActionResponse string         `yaml:"action_response,omitempty"`
	ThreatModel    *ThreatModel   `yaml:"threat_model,omitempty"`
	CWSS           *CWSSData      `yaml:"cwss,omitempty"`
	Decision       *Decision      `yaml:"decision,omitempty"`
	History        []HistoryEntry `yaml:"history,omitempty"`
	Source         string         `yaml:"source,omitempty"` // "vulnetix" | "github"
}

FindingRecord stores all triage data for a single vulnerability. This schema is shared with the Claude Code plugin SKILL files.

type HistoryEntry

type HistoryEntry struct {
	Date   string `yaml:"date"`
	Event  string `yaml:"event"`
	Detail string `yaml:"detail,omitempty"`
}

HistoryEntry is an append-only log entry for a finding.

type Memory

type Memory struct {
	Version     string                   `yaml:"version"`
	LastScan    *ScanRecord              `yaml:"last_scan,omitempty"`
	History     []ScanRecord             `yaml:"history,omitempty"`
	Findings    map[string]FindingRecord `yaml:"findings,omitempty"`    // triage findings keyed by CVE ID
	Environment *EnvironmentContext      `yaml:"environment,omitempty"` // last-gathered env context
	VDBQueries  []VDBQuery               `yaml:"vdb_queries,omitempty"` // recent VDB query log
}

Memory is the top-level .vulnetix/memory.yaml structure.

func Load

func Load(vulnetixDir string) (*Memory, error)

Load reads memory.yaml from the given .vulnetix directory. If the file does not exist, a fresh Memory is returned without error. If the file is corrupt, a fresh Memory is returned (non-fatal).

func (*Memory) GetFinding

func (m *Memory) GetFinding(cveID string) *FindingRecord

GetFinding returns the triage finding for a given CVE ID, or nil if none exists.

func (*Memory) RecordScan

func (m *Memory) RecordScan(rec ScanRecord)

RecordScan prepends rec to History, sets LastScan, and trims history to maxHistory. If rec.Timestamp is empty it is set to the current UTC time.

func (*Memory) RecordVDBQuery

func (m *Memory) RecordVDBQuery(q VDBQuery)

RecordVDBQuery prepends a VDB query to the log, capping at maxVDBQueries.

func (*Memory) RecordVulnLookup

func (m *Memory) RecordVulnLookup(vulnID string, data interface{})

RecordVulnLookup upserts a FindingRecord from a VDB vuln response. It extracts the vulnId, aliases, severity, and scores from the opaque API response data. This is best-effort; missing fields are silently skipped.

func (*Memory) SetFinding

func (m *Memory) SetFinding(cveID string, data FindingRecord)

SetFinding stores or updates triage data for a CVE ID.

func (*Memory) UpdateEnvironment

func (m *Memory) UpdateEnvironment(env *EnvironmentContext)

UpdateEnvironment replaces the stored environment context.

type ScanRecord

type ScanRecord struct {
	Timestamp      string                `yaml:"timestamp"`
	Path           string                `yaml:"path,omitempty"`
	GitBranch      string                `yaml:"git_branch,omitempty"`
	GitCommit      string                `yaml:"git_commit,omitempty"`
	GitRemote      string                `yaml:"git_remote,omitempty"`
	FilesScanned   int                   `yaml:"files_scanned"`
	Packages       int                   `yaml:"packages"`
	Vulns          int                   `yaml:"vulns"`
	Critical       int                   `yaml:"critical"`
	High           int                   `yaml:"high"`
	Medium         int                   `yaml:"medium"`
	Low            int                   `yaml:"low"`
	SBOMPath       string                `yaml:"sbom_path,omitempty"`
	ScopeBreakdown map[string]ScopeStats `yaml:"scope_breakdown,omitempty"`
	IDSRulesPath   string                `yaml:"ids_rules_path,omitempty"`
	IDSRulesCount  int                   `yaml:"ids_rules_count,omitempty"`
}

ScanRecord summarises one scan run.

type ScopeStats

type ScopeStats struct {
	Packages int `yaml:"packages"`
	Vulns    int `yaml:"vulns"`
}

ScopeStats records package and vulnerability counts for a single scope bucket.

type ThreatModel

type ThreatModel struct {
	Techniques         []string `yaml:"techniques,omitempty"`
	Tactics            []string `yaml:"tactics,omitempty"`
	AttackVector       string   `yaml:"attack_vector,omitempty"`
	AttackComplexity   string   `yaml:"attack_complexity,omitempty"`
	PrivilegesRequired string   `yaml:"privileges_required,omitempty"`
	UserInteraction    string   `yaml:"user_interaction,omitempty"`
	Reachability       string   `yaml:"reachability,omitempty"`
	Exposure           string   `yaml:"exposure,omitempty"`
}

ThreatModel holds MITRE ATT&CK-derived threat modelling data.

type VDBQuery

type VDBQuery struct {
	Timestamp  string `yaml:"timestamp"`
	Command    string `yaml:"command"`        // e.g. "vuln", "fixes", "exploits"
	Args       string `yaml:"args,omitempty"` // e.g. "CVE-2021-44228"
	APIVersion string `yaml:"api_version,omitempty"`
}

VDBQuery records a single VDB API query in the memory log.

type VersionInfo

type VersionInfo struct {
	Current       string `yaml:"current,omitempty"`
	CurrentSource string `yaml:"current_source,omitempty"`
	FixedIn       string `yaml:"fixed_in,omitempty"`
	FixSource     string `yaml:"fix_source,omitempty"`
}

VersionInfo tracks package versions relevant to a finding.