god-eye/internal/store/store.go

// Package store defines the Store interface used by pipeline modules to record
// per-host findings. Full implementations (in-memory + BoltDB-backed) live in
// this same package — this file only declares the interface so other packages
// can depend on it without pulling in storage backends.
package store

import (
	"context"
	"time"
)

// Host is the aggregate per-subdomain record. Fields are populated
// incrementally as modules publish events.
//
// Field names intentionally mirror the legacy config.SubdomainResult shape so
// migrating JSON output in F0.6 is mechanical. Over time this struct will
// diverge (more fields, richer types) as v2 features land.
type Host struct {
	Subdomain string
	IPs       []string
	CNAME     string
	PTR       string

	// Resolution metadata
	ASN     string
	Org     string
	Country string
	City    string

	// HTTP probe
	URL           string
	StatusCode    int
	ContentLength int64
	Title         string
	Server        string
	Technologies  []string
	Headers       map[string]string
	ResponseMs    int64

	// TLS
	TLSVersion     string
	TLSIssuer      string
	TLSExpiry      time.Time
	TLSSelfSigned  bool
	TLSAltNames    []string
	TLSFingerprint *TLSFingerprint

	// Classification
	CloudProvider string
	WAF           string
	Ports         []int

	// Analysis
	Vulnerabilities []Vulnerability
	Secrets         []Secret
	CVEs            []CVE
	AIFindings      []AIFinding
	Takeover        *Takeover

	// Discovery metadata
	DiscoveredVia []string // e.g. ["passive:crt.sh", "brute"]
	FirstSeen     time.Time
	LastUpdated   time.Time
}

// TLSFingerprint identifies a security appliance (firewall, VPN, load balancer)
// from its TLS certificate.
type TLSFingerprint struct {
	Vendor        string
	Product       string
	Version       string
	ApplianceKind string
	InternalHosts []string
}

// Vulnerability is a single finding recorded on a host.
type Vulnerability struct {
	ID          string
	Title       string
	Description string
	Severity    string
	URL         string
	Evidence    string
	Remediation string
	CVEs        []string
	OWASP       string
	CVSS        float64
	FoundAt     time.Time
}

// Secret is a credential/token discovered on a host.
type Secret struct {
	Kind        string
	Match       string
	Value       string
	Location    string
	Validated   bool
	Severity    string
	Description string
	FoundAt     time.Time
}

// CVE is a CVE match correlated to a detected technology.
type CVE struct {
	ID          string
	Technology  string
	Version     string
	Severity    string
	CVSS        float64
	Description string
	URL         string
	InKEV       bool
	FoundAt     time.Time
}

// AIFinding is an AI/agent-produced insight.
type AIFinding struct {
	Agent       string
	Model       string
	Severity    string
	Title       string
	Description string
	Evidence    string
	CVEs        []string
	OWASP       string
	Confidence  float64
	FoundAt     time.Time
}

// Takeover is a confirmed or candidate subdomain takeover.
type Takeover struct {
	Service   string
	CNAME     string
	Evidence  string
	PoC       string
	Confirmed bool
	FoundAt   time.Time
}

// Store is the aggregate interface modules use to record findings. Methods
// must be safe for concurrent use by many goroutines.
type Store interface {
	// Upsert merges patch into the record for subdomain. Only non-zero fields
	// in patch overwrite existing data; slice/map fields are appended/merged.
	// The mutator is invoked under a per-host lock so concurrent callers see
	// consistent state.
	Upsert(ctx context.Context, subdomain string, mutate func(*Host)) error

	// Get returns a snapshot copy of the record for subdomain.
	Get(ctx context.Context, subdomain string) (*Host, bool)

	// All returns a snapshot slice of every host. The slice is sorted by
	// subdomain for deterministic output.
	All(ctx context.Context) []*Host

	// Count returns the number of hosts in the store.
	Count(ctx context.Context) int

	// Close releases resources (e.g. BoltDB handle). Idempotent.
	Close() error
}