analysis

type Account struct {
	ID, Status  string
	AgentLinked bool
	CreatedAt   time.Time
	// LastOrderAt is zero when the account never ordered.
	LastOrderAt time.Time
}

type Agent struct {
	ID, Hostname, Version string
	// Status is active, disabled or revoked.
	Status      string
	Deployments []Deployment
}

type Agents interface {
	ListAgents(ctx context.Context, who keys.Who) ([]agents.Agent, error)
	GetAgent(ctx context.Context, who keys.Who, id string) (*agents.Agent, error)
}

type Analysis struct {
	GeneratedAt time.Time
	// Results has one entry per rule, in the order of Rules.
	Results []Result
	// Findings are all findings of all rules, most severe first. Like
	// Results it holds at most MaxFindingsPerRule per rule; Summary counts
	// every finding.
	Findings []Finding
	Summary  Summary
}

type CA struct {
	ID, Name string
	// Issuing: active, with a key that is not offline, so it signs
	// end-entity certificates.
	Issuing bool
	// MaxValidityDays caps the validity of the leaves the CA issues; the
	// engine shortens a longer default to it. 0 = not known, no cap assumed.
	MaxValidityDays int
	Generations     []Generation
}

type Certificate struct {
	ID, Serial, Fingerprint string
	// Source is the certificates.source column: issued, imported or external.
	Source string
	CAID   string
	CAName string
	// DNSNames and IPs are the names; CommonName is used when there are none.
	DNSNames, IPs []string
	CommonName    string
	// Class and IssuerKey say who issued it (ca.SourceUI, ca.SourceACME,
	// ca.SourceAgent; "ui", "acme:<account>", "agent:<id>"). Both are "" for
	// an imported or external certificate, and for an issued one whose origin
	// could not be read.
	Class, IssuerKey               string
	NotBefore, NotAfter, CreatedAt time.Time
	// Traits is nil when the DER could not be parsed.
	Traits *ca.Traits
}

type Counts struct{ Critical, Warning, Info int }

type Deployment struct {
	Name, State, Serial, CertificateID, Fingerprint string
	Removed                                         bool
}

type Deps struct {
	Tenant string // for the permission check of Service.Get
	Engine Engine
	Agents Agents    // nil = the agent listener is off
	Scan   Endpoints // nil = no scanning
	// ScanOff: scanning is switched off (monitor.scan_interval: off); the
	// endpoints that are entered then keep their last result, which no rule
	// should lean on.
	ScanOff       bool
	ServerVersion string
	Clock         clock.Clock
	// Who reads the data: a system principal that may read the whole tenant.
	// The zero value means authz.System("analysis").
	Who keys.Who
	// Log gets the debug line with the duration of a run; nil = no logging.
	Log *slog.Logger
}

type Endpoint struct {
	ID, Host string
	Port     int
	// Name is the name the certificate is expected for (SNI, else the host).
	Name string
	// LastOKAt is the last successful scan; zero = never. Fingerprint is the
	// leaf it served then (it stays while later scans fail) and
	// FingerprintSince the first successful scan that saw it.
	LastOKAt         time.Time
	Fingerprint      string
	FingerprintSince time.Time
}

type Endpoints interface {
	List(ctx context.Context, who keys.Who) ([]tlsscan.Endpoint, error)
}

type Engine interface {
	Certificates(ctx context.Context, who keys.Who, f ca.CertificateFilter) (*ca.CertificatePage, error)
	CAs(ctx context.Context, who keys.Who) ([]ca.CAInfo, error)
	CertificateTraits(ctx context.Context, who keys.Who) (map[string]ca.Traits, error)
	CertificateOrigins(ctx context.Context, who keys.Who) (map[string]ca.Origin, error)
	CertificateNames(ctx context.Context, who keys.Who) ([]ca.CertName, error)
	ACMEAccountActivity(ctx context.Context, who keys.Who) (accounts []ca.AccountActivity, truncated bool, err error)
	ListDomains(ctx context.Context, who keys.Who) ([]ca.Domain, error)
}

type Finding struct {
	// Key is "rule:subject id", stable between runs.
	Key  string
	Rule string
	// Severity is SeverityInfo, SeverityWarning or SeverityCritical.
	Severity string
	// Subject names what it is about (a certificate, an agent, a week).
	Subject string
	// Seen is what the snapshot shows; Why says why it matters; Recommendation
	// says what to do. A finding never states more than Seen.
	Seen, Why, Recommendation string
	// Href is a path inside the UI ("/certificates/<id>"), or "".
	Href string
}

type Generation struct {
	Number  int64
	Current bool
	// Signed: the certificate exists (a pending generation has none).
	Signed  bool
	Revoked bool
	// Intermediate: the CA certificate has an issuer; a root signs itself.
	Intermediate bool
	NotAfter     time.Time
	Signature    x509.SignatureAlgorithm
}

type Missing struct {
	// Agents: the agent listener is off, so there is no agent data.
	Agents string
	// Scan: the TLS scan is off, so no endpoint was scanned.
	Scan string
}

type Result struct {
	ID, Title string
	// State is StateOK, StateFindings or StateUnknown.
	State string
	// Counts are all findings of the rule by severity; Findings holds at most
	// MaxFindingsPerRule of them, most severe first.
	Counts   Counts
	Findings []Finding
	// Unassessed is how many things the rule could not judge for lack of data;
	// UnknownReason says why. With State unknown the reason is the whole
	// answer; with State findings it qualifies them ("and N could not be
	// assessed").
	Unassessed    int
	UnknownReason string
}

type Rule struct {
	ID    string
	Title string
	Eval  func(Snapshot) Result
}

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

type Snapshot struct {
	Now time.Time
	// ServerVersion is the running version; "dev" for a development build.
	ServerVersion string

	// Certificates are the valid end-entity certificates, whatever their
	// source (agent identity certificates are left out).
	Certificates []Certificate
	// Recent are the certificates created within RecentWindow of Now, valid
	// or not: a revoked or expired one still counts as something a client got.
	Recent []Certificate
	// Names are the DNS names and IPs of every certificate of the tenant,
	// whatever its status.
	Names []ca.CertName

	CAs     []CA
	Domains []ca.Domain
	// Accounts are the ACME accounts that were read, newest first. If there
	// are more than the engine reads, AccountsLimit is how many it did read and
	// the older accounts are not in the list; 0 = every account is.
	Accounts      []Account
	AccountsLimit int
	Agents        []Agent
	Endpoints     []Endpoint

	// Missing says why a section is not there ("" = it is).
	Missing Missing
}

type Summary struct {
	Critical, Warning, Info int
	// Unknown is the number of rules that cannot be assessed.
	Unknown int
}