compliancekit

type Check struct {
	// ID is the stable identifier, kebab-case. Convention:
	// "<provider>-<service>-<concise-rule>", e.g. "do-spaces-public-acl".
	// Never rename an ID; deprecate via the Deprecated field instead.
	ID string `yaml:"id" json:"id"`

	// Title is the short human-readable summary shown in reports.
	Title string `yaml:"title" json:"title"`

	// Severity is the impact classification. See severity.go.
	Severity Severity `yaml:"severity" json:"severity"`

	// Provider names the provider this check targets, e.g. "digitalocean".
	Provider string `yaml:"provider" json:"provider"`

	// Service narrows the provider area, e.g. "spaces", "droplets".
	Service string `yaml:"service,omitempty" json:"service,omitempty"`

	// ResourceType identifies the resource kind the check examines.
	ResourceType string `yaml:"resource_type,omitempty" json:"resource_type,omitempty"`

	// Description explains the check in prose. Shown in `checks show` and
	// the HTML report.
	Description string `yaml:"description" json:"description"`

	// Rationale optionally captures the "why this is bad" -- typically
	// citing an incident or threat model.
	Rationale string `yaml:"rationale,omitempty" json:"rationale,omitempty"`

	// Remediation is the human-readable fix. Specific commands beat
	// generic advice; CHECKS.md spells this out.
	Remediation string `yaml:"remediation" json:"remediation"`

	// Frameworks maps framework ID to the control IDs it satisfies,
	// e.g. {"soc2": ["CC6.1", "CC6.6"], "cis-v8": ["3.3"]}.
	Frameworks map[string][]string `yaml:"frameworks" json:"frameworks"`

	// Tags are filter labels propagated to Findings.
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty"`

	// References link to authoritative external sources (docs, CWEs, etc.).
	References []string `yaml:"references,omitempty" json:"references,omitempty"`

	// Scanner names the Go CheckFunc registered in the registry under
	// this ID. Mutually exclusive with Policy.
	Scanner string `yaml:"scanner,omitempty" json:"scanner,omitempty"`

	// Policy points at a Rego file. Available from v0.13 once the Rego
	// evaluator lands. Mutually exclusive with Scanner.
	Policy string `yaml:"policy,omitempty" json:"policy,omitempty"`

	// Deprecated marks the check as scheduled for removal.
	Deprecated bool `yaml:"deprecated,omitempty" json:"deprecated,omitempty"`

	// DeprecatedIn records the version in which deprecation was announced,
	// e.g. "v0.7".
	DeprecatedIn string `yaml:"deprecated_in,omitempty" json:"deprecated_in,omitempty"`

	// ReplacedBy is the ID of the check that supersedes this one.
	ReplacedBy string `yaml:"replaced_by,omitempty" json:"replaced_by,omitempty"`
}

type CheckFunc func(ctx context.Context, graph *ResourceGraph) ([]Finding, error)

type Collector interface {
	// Name returns the provider identifier, e.g. "digitalocean" or "linux".
	// Used in logs, error messages, and the resource ID prefix.
	Name() string

	// Collect fetches resources from the provider. The returned slice is
	// added to the engine's ResourceGraph; the engine handles ordering
	// and de-duplication across collectors.
	Collect(ctx context.Context) ([]Resource, error)
}

type Comment struct {
	// ID is the daemon's opaque identifier for this comment.
	ID string `json:"id"`

	// Author is the operator who wrote the comment. May be a zero
	// User if the original author was deleted from the daemon (the
	// comment text is preserved; Author.ID is empty in that case).
	Author User `json:"author"`

	// Body is the markdown source the author wrote.
	Body string `json:"body"`

	// BodyHTML is the rendered, sanitized HTML. Cached at write time
	// and refreshed only on Edit. Empty for embedders that don't
	// populate it.
	BodyHTML string `json:"body_html,omitempty"`

	// CreatedAt is the timestamp the comment was first persisted.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt tracks the most recent write, including edits.
	UpdatedAt time.Time `json:"updated_at"`

	// EditedAt is non-nil when the comment has been edited at least
	// once after creation. The UI renders "edited 3m ago" when set.
	EditedAt *time.Time `json:"edited_at,omitempty"`

	// Source records how the comment entered compliancekit: 'ui',
	// 'slack', 'teams', 'github-pr', 'jira', 'linear'. Empty string
	// is treated as 'ui' for backwards compatibility.
	Source string `json:"source,omitempty"`

	// ExternalID is the originating sink's native id (Slack thread
	// timestamp, GitHub comment id, Jira/Linear comment id) — populated
	// for non-UI comments so two-way sync can dedup re-delivery.
	ExternalID string `json:"external_id,omitempty"`
}

type Control struct {
	ID          string   `yaml:"-"`
	Name        string   `yaml:"name"`
	Description string   `yaml:"description,omitempty"`
	Family      string   `yaml:"family,omitempty"`
	Tags        []string `yaml:"tags,omitempty"`
	References  []string `yaml:"references,omitempty"`
}

type Evaluator interface {
	// Evaluate runs all configured checks against the graph and returns
	// every Finding produced. Findings of any Status are returned;
	// filtering by status, severity, or check ID is the caller's
	// responsibility.
	Evaluate(ctx context.Context, graph *ResourceGraph) ([]Finding, error)
}

type EvidencePtr struct {
	Path string `json:"path,omitempty"`
}

type Finding struct {
	// CheckID identifies the originating check; matches Check.ID exactly.
	CheckID string `json:"check_id"`

	// Status is the evaluation outcome (pass / fail / skip / error).
	Status Status `json:"status"`

	// Severity is denormalized from the originating Check so reporters
	// and CLI filters can act on it without joining against the catalog.
	Severity Severity `json:"severity"`

	// Resource identifies the resource the finding is about. A scan
	// targeting account-level configuration may use a synthetic
	// account resource here.
	Resource ResourceRef `json:"resource"`

	// Message is a short human-readable description specific to this
	// finding, typically including the offending attribute value.
	// Example: `bucket "assets" has acl=public-read`.
	Message string `json:"message,omitempty"`

	// Evidence optionally points at captured raw data for the evidence pack.
	// Empty for findings derived from cross-resource logic with no single
	// underlying API response.
	Evidence EvidencePtr `json:"evidence,omitempty"`

	// Tags propagate filter labels from the check or resource. CLI flags
	// (--tags) match against this slice.
	Tags []string `json:"tags,omitempty"`

	// Timestamp is when the finding was produced (engine end-of-scan time).
	// All findings from a single scan share the same Timestamp.
	Timestamp time.Time `json:"timestamp"`

	// Source records the provenance of this finding: native scan, or
	// ingested from an external tool (Trivy, AWS Security Hub, OSCAL
	// assessment results, …). nil for legacy findings written before
	// v0.13; reporters and the evidence pack treat absence as native
	// for backwards compatibility.
	//
	// v0.13+. Populated by either the engine (native) or an
	// internal/ingest adapter (external).
	Source *Source `json:"source,omitempty"`

	// Vulnerability is the v0.14+ typed metadata block populated when
	// the finding represents a CVE / GHSA / vendor advisory rather
	// than a posture issue. Trivy / Grype / Snyk / Dependabot ingest
	// adapters populate it; native checks leave it nil. Reporters
	// render CVE IDs natively when present.
	Vulnerability *Vulnerability `json:"vulnerability,omitempty"`

	// Secret is the v0.14+ typed metadata block populated when the
	// finding represents a leaked credential discovered by a secret
	// scanner (gitleaks, TruffleHog). Always carries a redacted
	// fingerprint, never the raw secret value — ADR-010 codifies
	// this hard rule.
	Secret *Secret `json:"secret,omitempty"`

	// Waiver is the v0.18+ typed metadata block populated when a
	// matching waiver muted this finding. Auditor-visible by
	// design: the Finding flows through every reporter as
	// StatusSkip with this block populated so the auditor sees
	// the acknowledgement + reason + approver. A nil Waiver means
	// the finding ran through the normal status machinery, NOT
	// that it was waived for an unrelated reason. See ADR-013.
	Waiver *WaiverRef `json:"waiver,omitempty"`

	// Comments is the v1.8+ ordered conversation attached to this
	// finding by Fingerprint(). Empty for CLI-only scans; populated
	// only when the finding is loaded from the serve daemon or
	// re-rendered through `compliancekit render --server=...`. ADR-014
	// — additive, backwards-compatible.
	Comments []Comment `json:"comments,omitempty"`

	// Assignee is the v1.8+ operator currently accountable for the
	// finding. nil when no assignee is set. Resolves to the same
	// fingerprint-keyed row across scans.
	Assignee *User `json:"assignee,omitempty"`

	// Followers is the v1.8+ set of operators who opted in to receive
	// notifications about findings on this Resource. Populated from
	// the resource_follower table when the finding is loaded from the
	// daemon. nil/empty for CLI-only scans.
	Followers []User `json:"followers,omitempty"`
}

type Framework struct {
	ID          string `yaml:"id"`
	Name        string `yaml:"name"`
	Version     string `yaml:"version,omitempty"`
	Description string `yaml:"description,omitempty"`
	URL         string `yaml:"url,omitempty"`
	// Category distinguishes audit-shaped compliance frameworks
	// (default) from threat-model frameworks like MITRE ATT&CK.
	// Empty == compliance for back-compat with v0.3-era yamls.
	Category string `yaml:"category,omitempty"`
	// Source cites the authoritative document the catalog was
	// derived from, for auditor transparency.
	Source string `yaml:"source,omitempty"`
	// Tactics is populated only for threat-model frameworks
	// (Category=threat_model). Ordered along the kill chain.
	Tactics  []Tactic           `yaml:"tactics,omitempty"`
	Controls map[string]Control `yaml:"controls"`
}

type Package struct {
	Name      string `json:"name"`
	Version   string `json:"version,omitempty"`
	Ecosystem string `json:"ecosystem,omitempty"` // "apk", "deb", "pypi", "npm", "go", "maven", …
	// PURL is the canonical Package URL (pkg:apk/alpine/openssl@3.0.7?...).
	// Trivy and Grype both emit it; older tools may not.
	PURL string `json:"purl,omitempty"`
}

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

type Reporter interface {
	// Format returns the lowercase identifier matching the config value
	// (e.g. "json", "html"). The scan command compares against this.
	Format() string

	// Render writes findings in this reporter's format. The graph is
	// passed so reporters that need raw resource detail (the evidence
	// pack reporter at v0.4, primarily) can access it without forcing
	// every check to denormalize attributes into Findings.
	//
	// Implementations must honor ctx.Done() -- a large evidence pack
	// can take meaningful wall time to write.
	Render(ctx context.Context, findings []Finding, graph *ResourceGraph, w io.Writer) error
}

type ResolvedControl struct {
	Framework *Framework
	Control   Control
}

type Resource struct {
	// ID is globally unique across providers, e.g. "digitalocean.droplet.123456".
	// Convention: "<provider>.<type>.<provider-native-id>".
	ID string `json:"id"`

	// Type is the resource type, e.g. "digitalocean.droplet".
	// Convention: "<provider>.<resource-kind>".
	Type string `json:"type"`

	// Name is the human-friendly identifier, typically the name set in the
	// cloud console. Surfaced in finding messages and the HTML report.
	Name string `json:"name"`

	// Provider is the source, e.g. "digitalocean" or "linux".
	Provider string `json:"provider"`

	// Region is the cloud region or, for hosts, a logical zone.
	// Empty for resources without a regional concept (e.g. accounts).
	Region string `json:"region,omitempty"`

	// Attributes carries provider-specific fields. Access via the typed
	// helpers (Attr / AttrInt / AttrBool) so scanners stay agnostic of
	// how a particular value was decoded.
	Attributes map[string]any `json:"attributes,omitempty"`

	// Relations maps an edge name to the IDs of related resources.
	// Example: a droplet may have Relations["firewall"] = []string{"do-fw-1"}.
	// Collectors populate edges; scanners traverse them via ResourceGraph.Related.
	Relations map[string][]string `json:"relations,omitempty"`

	// Tags are arbitrary string labels assigned to the resource in the cloud.
	Tags []string `json:"tags,omitempty"`

	// RawPath points to the captured raw API response on disk, for the
	// evidence pack to copy into the audit-ready output. Empty when the
	// collector did not persist raw evidence (e.g. in tests).
	RawPath string `json:"raw_path,omitempty"`
}

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

type ResourceRef struct {
	ID        string `json:"id"`
	Type      string `json:"type"`
	Name      string `json:"name"`
	Provider  string `json:"provider"`
	Region    string `json:"region,omitempty"`
	AccountID string `json:"account_id,omitempty"`
}

type SearchResponse struct {
	Query      string         `json:"query"`
	Results    []SearchResult `json:"results"`
	NextCursor string         `json:"next_cursor,omitempty"`
}

type SearchResult struct {
	Type     SearchType `json:"type"`
	ID       string     `json:"id"`
	Title    string     `json:"title"`
	Subtitle string     `json:"subtitle,omitempty"`
	Href     string     `json:"href"`
	Score    float64    `json:"score"`
}

type SearchType string

type Secret struct {
	// RuleID is the producing scanner's rule identifier
	// ("aws-access-key-id", "github-pat", "stripe-secret-key", …).
	RuleID string `json:"rule_id"`

	// RuleName is the human-readable rule description.
	RuleName string `json:"rule_name,omitempty"`

	// Fingerprint is a redacted derivation of the secret — typically
	// the first 4 + last 4 characters of the captured string with the
	// middle replaced by "..." (e.g. "AKIA...A2X9"). Adapters MUST
	// NOT emit the full secret value. The full secret never leaves
	// the producing tool's report; we read only the fingerprint.
	Fingerprint string `json:"fingerprint,omitempty"`

	// File / Line locate the secret within the scanned repo.
	File string `json:"file,omitempty"`
	Line int    `json:"line,omitempty"`

	// Commit (optional) is the git commit SHA where the secret was
	// introduced; gitleaks ships this when it scans the full history.
	Commit string `json:"commit,omitempty"`

	// Author / Email / Date describe the commit metadata the secret
	// was introduced in. Useful for revocation routing.
	Author string `json:"author,omitempty"`
	Email  string `json:"email,omitempty"`
	Date   string `json:"date,omitempty"`
}

type Severity int

type Source struct {
	// Type is "native" for engine-produced findings or "ingest" for
	// findings projected from an external tool's output.
	Type string `json:"type"`

	// Tool identifies the producer when Type=="ingest", e.g. "trivy",
	// "checkov", "aws-security-hub", "gcp-scc", "defender". Empty
	// when Type=="native".
	Tool string `json:"tool,omitempty"`

	// ToolVersion (optional) records the producing tool's version,
	// e.g. "v0.50.2". Useful for audit-trail reproducibility.
	ToolVersion string `json:"tool_version,omitempty"`

	// Format names the wire format the finding was decoded from
	// ("sarif", "ocsf", "oscal-ar"). Empty for native findings.
	Format string `json:"format,omitempty"`

	// File (optional) is the path of the source file the ingest
	// adapter read. Aids reproducibility but never relied on for
	// correctness — the finding is fully described without it.
	File string `json:"file,omitempty"`
}

type Status string

type Tactic struct {
	ID          string   `yaml:"id"`
	Name        string   `yaml:"name"`
	Description string   `yaml:"description,omitempty"`
	Techniques  []string `yaml:"techniques,omitempty"`
}

type User struct {
	// ID is the daemon's internal opaque user id. Embedders that need
	// to correlate against an external IdP should join on Email.
	ID string `json:"id"`

	// Email is the user's primary contact address. Required.
	Email string `json:"email"`

	// DisplayName is the operator-visible label ("Alex Lee"). Falls
	// back to the local-part of Email when unset.
	DisplayName string `json:"display_name,omitempty"`
}

type Vulnerability struct {
	// ID is the canonical advisory identifier. CVE IDs ("CVE-2026-XXXXX")
	// are preferred; GHSA IDs are accepted when the upstream tool only
	// emits those. Other vendor-specific IDs flow into Aliases.
	ID string `json:"id"`

	// Aliases lists any equivalent identifiers the producing tool
	// reported alongside ID (RHSA, USN, GHSA when ID is CVE,
	// vendor-specific tickets).
	Aliases []string `json:"aliases,omitempty"`

	// CVSSScore is the CVSS base score (0.0-10.0) the producing tool
	// attributed to the advisory. Zero means "unknown" — reporters
	// should fall through to compliancekit's severity scale rather
	// than rendering "0.0".
	CVSSScore float64 `json:"cvss_score,omitempty"`

	// CVSSVector is the full vector string ("CVSS:3.1/AV:N/AC:L/...")
	// when the tool ships it. Useful for downstream consumers that
	// want to re-score with different temporal/environmental modifiers.
	CVSSVector string `json:"cvss_vector,omitempty"`

	// Package identifies the vulnerable package: name, version,
	// ecosystem, and the canonical PURL (Package URL) where known.
	Package Package `json:"package,omitempty"`

	// FixedVersion is the smallest version that addresses the CVE.
	// Empty when no fix is yet available; reporters render "unpatched"
	// or similar in that case.
	FixedVersion string `json:"fixed_version,omitempty"`

	// Description is a short prose summary of the advisory, typically
	// 1-2 sentences. Used as the Finding.Message when the producing
	// adapter doesn't synthesize one.
	Description string `json:"description,omitempty"`

	// PrimaryURL is the canonical URL pointing at the upstream
	// advisory (NVD / GHSA / vendor advisory page). Reporters render
	// it as a clickable reference.
	PrimaryURL string `json:"primary_url,omitempty"`

	// PublishedDate / LastModifiedDate are the advisory dates as
	// reported by the producing tool. Useful for age-based filters
	// ("CVEs published in the last 30 days"). Stored as RFC3339
	// strings rather than time.Time to preserve whatever precision
	// the tool emitted (some tools omit time-of-day).
	PublishedDate    string `json:"published_date,omitempty"`
	LastModifiedDate string `json:"last_modified_date,omitempty"`

	// Image identifies the container image when the finding came from
	// an image scan (Trivy image, Grype container, Defender image
	// scan). Empty for filesystem / package scans.
	Image string `json:"image,omitempty"`
}

type WaiverRef struct {
	// CheckID is the catalog ID the waiver matched on. Always
	// non-empty; helps round-tripping when a reporter drops the
	// surrounding Finding.CheckID for some reason.
	CheckID string `json:"check_id"`

	// ResourceID is the resource the waiver matched. Always
	// non-empty; the matcher requires both CheckID + ResourceID
	// in v0.18 (broader scopes deferred — see ADR-013).
	ResourceID string `json:"resource_id"`

	// Reason is the operator-supplied justification. Required by
	// the loader; an empty Reason fails waiver validation. The
	// auditor reads this to understand WHY the deviation is
	// acceptable.
	Reason string `json:"reason"`

	// Approver is the human who signed off. Required by the loader.
	// Convention: email address or "@github-username"; the auditor
	// uses this to chase up if context is needed.
	Approver string `json:"approver"`

	// Expires is the date the waiver lapses. Expired waivers stop
	// muting and emit their own info-level finding ("waiver X
	// expired N days ago") so the auditor sees the lapse instead
	// of silent re-coverage. UTC date; loader parses YYYY-MM-DD.
	Expires time.Time `json:"expires"`

	// Source identifies where the waiver was declared. Three values
	// at v0.18: "file" (waivers.yaml entry), "annotation" (in-code
	// // compliancekit:waive ... comment), or "" (legacy / unknown).
	Source string `json:"source,omitempty"`

	// SourcePath optionally points at the file the waiver was
	// declared in. waivers.yaml path for Source=="file"; the
	// annotated source file for Source=="annotation".
	SourcePath string `json:"source_path,omitempty"`
}