client

type ChunkUploadResponse struct {
	ChunkID         string `json:"chunk_id"`
	ReportID        string `json:"report_id"`
	ChunkIndex      int    `json:"chunk_index"`
	Status          string `json:"status"`
	AssetsCreated   int    `json:"assets_created"`
	AssetsUpdated   int    `json:"assets_updated"`
	FindingsCreated int    `json:"findings_created"`
	FindingsUpdated int    `json:"findings_updated"`
	FindingsSkipped int    `json:"findings_skipped"`
}

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

type Command struct {
	ID             string          `json:"id"`
	TenantID       string          `json:"tenant_id,omitempty"`
	SourceID       string          `json:"source_id,omitempty"`
	Type           string          `json:"type"`
	Priority       string          `json:"priority"`
	Payload        json.RawMessage `json:"payload,omitempty"`
	Status         string          `json:"status"`
	ErrorMessage   string          `json:"error_message,omitempty"`
	CreatedAt      time.Time       `json:"created_at"`
	ExpiresAt      *time.Time      `json:"expires_at,omitempty"`
	AcknowledgedAt *time.Time      `json:"acknowledged_at,omitempty"`
	StartedAt      *time.Time      `json:"started_at,omitempty"`
	CompletedAt    *time.Time      `json:"completed_at,omitempty"`
	Result         json.RawMessage `json:"result,omitempty"`
}

type Config struct {
	BaseURL    string        `yaml:"base_url" json:"base_url"`
	APIKey     string        `yaml:"api_key" json:"api_key"`
	SensorID   string        `yaml:"sensor_id" json:"sensor_id"` // Registered sensor ID for audit trail; the pre-rename key agent_id is still read (config_compat.go)
	Timeout    time.Duration `yaml:"timeout" json:"timeout"`
	MaxRetries int           `yaml:"max_retries" json:"max_retries"`
	RetryDelay time.Duration `yaml:"retry_delay" json:"retry_delay"`
	Verbose    bool          `yaml:"verbose" json:"verbose"`

	// UserAgent is this client's product token, "name/version" (for example
	// "openctemio-sensor/0.3.1"), sent before the SDK's own token:
	// "openctemio-sensor/0.3.1 openctem-sdk-go/0.7.4". Empty: the process-wide
	// product set with useragent.SetProduct, if any.
	UserAgent string `yaml:"user_agent" json:"user_agent"`

	// Compression configuration
	EnableCompression bool   `yaml:"enable_compression" json:"enable_compression"` // Enable request compression (default: true)
	CompressionAlgo   string `yaml:"compression_algo" json:"compression_algo"`     // "zstd" or "gzip" (default: "zstd")
	CompressionLevel  int    `yaml:"compression_level" json:"compression_level"`   // 1-9 (default: 3)

	// Protocol selects the results protocol: "auto" (default: v2 when the
	// platform offers it, else v1), "v1" or "v2".
	Protocol string `yaml:"protocol" json:"protocol"`

	// OutboxDir enables the durable outbox (see EnableOutbox) in that
	// directory. New logs, and leaves the outbox off, when it cannot be
	// opened; call EnableOutbox yourself to handle the error.
	OutboxDir string `yaml:"outbox_dir" json:"outbox_dir"`
	// OutboxMaxBytes and OutboxMaxAge override the outbox caps.
	OutboxMaxBytes int64         `yaml:"outbox_max_bytes" json:"outbox_max_bytes"`
	OutboxMaxAge   time.Duration `yaml:"outbox_max_age" json:"outbox_max_age"`

	// Deprecated: the retry queue is replaced by the outbox. EnableRetryQueue
	// enables the outbox (in OutboxDir, else RetryQueueDir/outbox, else
	// ~/.openctem/outbox) and imports the reports an older SDK left in
	// RetryQueueDir. RetryInterval and RetryMaxAttempts are ignored: the
	// outbox retries with back-off until RetryTTL (OutboxMaxAge) evicts.
	EnableRetryQueue bool          `yaml:"enable_retry_queue" json:"enable_retry_queue"`
	RetryQueueDir    string        `yaml:"retry_queue_dir" json:"retry_queue_dir"`
	RetryInterval    time.Duration `yaml:"retry_interval" json:"retry_interval"`
	RetryMaxAttempts int           `yaml:"retry_max_attempts" json:"retry_max_attempts"`
	RetryTTL         time.Duration `yaml:"retry_ttl" json:"retry_ttl"`
}

type EPSSScore struct {
	CVEID      string    `json:"cve_id"`
	Score      float64   `json:"score"`      // 0.0 to 1.0
	Percentile float64   `json:"percentile"` // 0.0 to 100.0
	Date       time.Time `json:"date"`
}

type ExposureEvent struct {
	// Event type: new_asset, asset_removed, exposure_detected, exposure_resolved
	Type string `json:"type"`

	// Asset identifier
	AssetID   string `json:"asset_id,omitempty"`
	AssetType string `json:"asset_type,omitempty"`
	AssetName string `json:"asset_name,omitempty"`

	// Exposure details
	ExposureType string `json:"exposure_type,omitempty"` // port_open, service_exposed, etc.
	Protocol     string `json:"protocol,omitempty"`
	Port         int    `json:"port,omitempty"`
	Service      string `json:"service,omitempty"`

	// Detection info
	DetectedAt  time.Time `json:"detected_at"`
	DetectedBy  string    `json:"detected_by,omitempty"` // scan source
	Severity    string    `json:"severity,omitempty"`
	Description string    `json:"description,omitempty"`

	// Resolution
	ResolvedAt *time.Time `json:"resolved_at,omitempty"`

	// Metadata
	Tags       []string       `json:"tags,omitempty"`
	Properties map[string]any `json:"properties,omitempty"`
}

type HTTPError struct {
	StatusCode int    `json:"status_code"`
	Body       string `json:"body"`
	RequestID  string `json:"request_id,omitempty"`
	// RetryAfter is the server's Retry-After (429/503), 0 when absent.
	RetryAfter time.Duration `json:"retry_after,omitempty"`
}

type HeartbeatOutbox struct {
	PendingCount     int   `json:"pending_count"`
	PendingBytes     int64 `json:"pending_bytes"`
	OldestAgeSeconds int64 `json:"oldest_age_seconds"`
	DeadLetterCount  int   `json:"dead_letter_count"`
	EvictedCount     int64 `json:"evicted_count"`
}

type HeartbeatRequest struct {
	Name     string           `json:"name,omitempty"`
	Status   core.SensorState `json:"status"`
	Version  string           `json:"version,omitempty"`
	Hostname string           `json:"hostname,omitempty"`
	// InstanceID is this sensor process's random id
	// (core.ProcessInstanceID): a restart changes it once, a key running in
	// two places makes two ids alternate, which the platform flags (api
	// RFC-032 Phase 0). Platforms that do not know it ignore it.
	InstanceID string   `json:"instance_id,omitempty"`
	Message    string   `json:"message,omitempty"`
	Scanners   []string `json:"scanners,omitempty"`
	Collectors []string `json:"collectors,omitempty"`
	Uptime     int64    `json:"uptime_seconds,omitempty"`
	TotalScans int64    `json:"total_scans,omitempty"`
	Errors     int64    `json:"errors,omitempty"`

	// System Metrics
	CPUPercent    float64 `json:"cpu_percent,omitempty"`
	MemoryPercent float64 `json:"memory_percent,omitempty"`
	ActiveJobs    int     `json:"active_jobs,omitempty"`
	Region        string  `json:"region,omitempty"`
	// ActiveJobsReported sends active_jobs even when it is 0 (the sensor
	// measured it). Without it a 0 is left out, as before.
	ActiveJobsReported bool `json:"-"`

	// Outbox is the durable outbox's state (absent without an outbox).
	Outbox *HeartbeatOutbox `json:"outbox,omitempty"`

	// The sensor-reported capabilities (core.CapabilityReport): absent when
	// the sensor reports nothing, and an empty list when it reports none.
	Tools             []core.ToolInfo `json:"tools,omitzero"`
	Capabilities      []string        `json:"capabilities,omitzero"`
	MaxConcurrentJobs int             `json:"max_concurrent_jobs,omitempty"`
	OS                string          `json:"os,omitempty"`
	Arch              string          `json:"arch,omitempty"`

	// The sensor's work now (core.SensorStatus; api RFC-030): absent when
	// not reported.
	Resources       *resource.HostResources `json:"resources,omitempty"`
	Capacity        *resource.Capacity      `json:"capacity,omitempty"`
	Queue           *core.QueueStats        `json:"queue,omitempty"`
	RunningCommands []string                `json:"running,omitzero"`

	// SDK and Sensor name the SDK and the sensor binary. Every heartbeat
	// sends both: what the status carries, else the SDK linked into this
	// binary and a sensor block built from the status's version.
	SDK    *core.SDKInfo     `json:"sdk,omitempty"`
	Sensor *core.SensorBuild `json:"sensor,omitempty"`
}

type IngestResponse struct {
	ScanID          string   `json:"scan_id"`
	AssetsCreated   int      `json:"assets_created"`
	AssetsUpdated   int      `json:"assets_updated"`
	FindingsCreated int      `json:"findings_created"`
	FindingsUpdated int      `json:"findings_updated"`
	FindingsSkipped int      `json:"findings_skipped"`
	Errors          []string `json:"errors,omitempty"`
}

type KEVEntry struct {
	CVEID                      string    `json:"cve_id"`
	VendorProject              string    `json:"vendor_project"`
	Product                    string    `json:"product"`
	VulnerabilityName          string    `json:"vulnerability_name"`
	DateAdded                  time.Time `json:"date_added"`
	ShortDescription           string    `json:"short_description"`
	RequiredAction             string    `json:"required_action"`
	DueDate                    time.Time `json:"due_date"`
	KnownRansomwareCampaignUse string    `json:"known_ransomware_campaign_use"`
}

type Option func(*Client)

type OutboxConfig struct {
	// Dir is the outbox directory (required). The sensor's default is
	// /var/lib/openctem/outbox.
	Dir string
	// KeyFile is the encryption key file (default <Dir>/outbox.key).
	KeyFile string
	// MaxBytes caps the bytes on disk (default 1 GiB, and never more than
	// half of the space the outbox could use).
	MaxBytes int64
	// MaxAge evicts items older than this (default 7 days).
	MaxAge time.Duration
	// Concurrency is 1 (default) or 2.
	Concurrency int
	// SyncWait is how long PushFindings/PushAssets wait for the first
	// delivery before answering "queued" (default 30s; negative: do not
	// wait).
	SyncWait time.Duration
	// LegacyRetryQueueDir is a pre-outbox retry-queue directory whose
	// reports are imported once (default ~/.openctem/retry-queue; "-" skips
	// the import).
	LegacyRetryQueueDir string
	// Logf receives the outbox's log lines (default: stderr with a
	// timestamp).
	Logf func(format string, args ...any)
	// OnEvict is told when the caps dropped results (turn it into an alert).
	OnEvict func(evicted []outbox.Meta, reason string)
}

type PushExposuresResult struct {
	EventsCreated int `json:"events_created"`
	EventsUpdated int `json:"events_updated"`
	EventsSkipped int `json:"events_skipped"`
}

type RefusedError struct {
	DeadLetter outbox.DeadLetter
}

type SuppressionRule struct {
	RuleID      string  `json:"rule_id,omitempty"`
	ToolName    string  `json:"tool_name,omitempty"`
	PathPattern string  `json:"path_pattern,omitempty"`
	AssetID     *string `json:"asset_id,omitempty"`
	ExpiresAt   *string `json:"expires_at,omitempty"`
}

type V2Error struct {
	Status     int
	Problem    *protov2.Problem
	RetryAfter time.Duration
	// Body is the raw answer when it was not a problem document (truncated).
	Body      string
	RequestID string
}

type V2Progress struct {
	// ReportID in use (it changes only when the report had to be restarted:
	// expired, or re-split after a 413).
	ReportID string `json:"report_id"`
	// Unbound: the command is gone; the report is sent unsolicited.
	Unbound bool `json:"unbound,omitempty"`
	// SegFindings and SegBytes cap the segments after a 413 (0: the
	// server's limits). Each 413 halves the segment that was refused.
	SegFindings int `json:"seg_findings,omitempty"`
	SegBytes    int `json:"seg_bytes,omitempty"`
	// Split is true once the report was split after a 413: it is then sent
	// as segments plus a commit even when one segment remains.
	Split bool `json:"split,omitempty"`
	// Segments is the planned segment count (0: not planned yet).
	Segments int `json:"segments,omitempty"`
	// Acked maps a segment number to the Content-Digest the server
	// acknowledged for it.
	Acked map[int]string `json:"acked,omitempty"`
	// Restarts counts report-id restarts (bounded).
	Restarts int `json:"restarts,omitempty"`
	// contains filtered or unexported fields
}

type V2PushOptions struct {
	// ReportID is the stable report id (lower-case UUID). Empty: a new
	// UUIDv7. Retries MUST reuse it.
	ReportID string
	// CommandID binds the report to a command this sensor claimed ("" for
	// unsolicited results).
	CommandID string
	// Progress resumes an earlier attempt (nil: start).
	Progress *V2Progress
	// OnProgress persists progress after every acknowledged segment and
	// every restart. An error stops the push.
	OnProgress func(V2Progress) error
	// Logf receives restarts and fall-backs. Nil: silent.
	Logf func(format string, args ...any)
	// MaxFindingsPerSegment lowers the server's per-segment finding limit
	// (0: the server's). For constrained links and conformance tests.
	MaxFindingsPerSegment int
}