discovery

type Addr ¶

type Addr struct {
	Host string
	Port int
}

Addr holds the minimal host-connection tuple Discovery needs.

type AuditEmitFunc ¶

type AuditEmitFunc func(ctx context.Context, code audit.Code, ev audit.Event)

AuditEmitFunc is the audit emission seam. Production wires it to audit.Emit; tests use a recorder that counts emissions.

type ConnProfileStore ¶

type ConnProfileStore interface {
	Get(ctx context.Context, hostID uuid.UUID) (connprofile.Profile, error)
	RecordSSHAuth(ctx context.Context, hostID uuid.UUID, m connprofile.SSHAuthMethod) error
}

ConnProfileStore is the subset of connprofile the transport uses to lead with the host's known-good SSH auth method and record what authenticated. nil disables learning (dial in the default key-first order). The host id is read from the context via connprofile.HostIDFrom.

type FactCategory ¶ added in v0.6.0

type FactCategory string

FactCategory groups host_system_info columns by the probe that collects them, so persist() can merge at category granularity: an unobserved category retains its prior stored value rather than being overwritten with an empty read.

const (
	CatOSRelease FactCategory = "os_release"
	CatUname     FactCategory = "uname"
	CatMemory    FactCategory = "memory"
	CatDisk      FactCategory = "disk"
	CatHostname  FactCategory = "hostname"
	CatFQDN      FactCategory = "fqdn"
	CatSELinux   FactCategory = "selinux"
	CatAppArmor  FactCategory = "apparmor"
	CatFirewall  FactCategory = "firewall"
)

type HostDiscoveryJobPayload ¶

type HostDiscoveryJobPayload struct {
	HostID uuid.UUID `json:"host_id"`
}

HostDiscoveryJobPayload is the JSON shape of the host.discovery job payload the worker reads. Carries the host id so the worker can invoke Service.Discover. Exported so the worker package can decode it without importing service internals.

type HostLookup ¶

type HostLookup interface {
	GetForDiscovery(ctx context.Context, hostID uuid.UUID) (Addr, error)
}

HostLookup is the seam Discovery uses to read host connection facts (addr, port) without coupling to the hosts package's full repository API. Production: a small adapter over pgxpool. Tests pre-build the hostFacts and use discoverWithTransport directly.

type PolicyLoader ¶

type PolicyLoader interface {
	LoadSecurity(ctx context.Context) (systemconfig.SecurityConfig, error)
}

Service runs Discovery for a host. Construct via NewService. PolicyLoader returns the current SecurityConfig — the sudo-password fallback (system-ssh-connectivity v1.2.0 C-09 / AC-20) consults AllowCredentialSudoPassword via this seam. Production wires systemconfig.Store.LoadSecurity; tests pass a closure or leave it nil (in which case the fallback path is OFF by default).

type PoolHostLookup ¶

type PoolHostLookup struct {
	Pool *pgxpool.Pool
}

PoolHostLookup adapts a *pgxpool.Pool into the HostLookup interface expected by Service. Production wires this; tests stub the interface directly.

func (p PoolHostLookup) GetForDiscovery(ctx context.Context, hostID uuid.UUID) (Addr, error)

type Publisher ¶

type Publisher interface {
	Publish(ctx context.Context, event eventbus.Event)
}

Publisher is the event-bus subset Discovery uses. The real *eventbus.Bus satisfies it; tests inject a recorder.

type SSHClientSession ¶

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

SSHClientSession is the per-host live SSH client. Each Run opens a fresh ssh.Session (one channel per command) atop the single client. crypto/ssh sessions are not reusable across commands, so this is the idiomatic shape.

func (s *SSHClientSession) Close() error

func (s *SSHClientSession) Run(ctx context.Context, cmd string) ([]byte, int, error)

func (s *SSHClientSession) RunWithStdin(ctx context.Context, cmd string, stdin []byte) ([]byte, int, error)

type SSHSession ¶

type SSHSession interface {
	Run(ctx context.Context, cmd string) (stdout []byte, exitCode int, err error)
	// RunWithStdin is the sudo-password-fallback hook (system-ssh-
	// connectivity v1.1.0 C-10). ssh.RunSudo pipes the credential
	// password through here when the policy allows.
	RunWithStdin(ctx context.Context, cmd string, stdin []byte) (stdout []byte, exitCode int, err error)
	Close() error
}

SSHSession is one live session against a remote host. Run executes a single command and returns stdout + exit code; the same session can be reused for every command the probe needs. Close releases the underlying transport.

type SSHTransport ¶

type SSHTransport interface {
	Dial(ctx context.Context, host string, port int, cred *credential.Credential) (SSHSession, error)
}

SSHTransport is the seam between the discovery service and the actual SSH path. Production uses sshTransport (wraps owssh.Dial + ssh.Session); tests use stubSSHTransport.

Dial MUST be called at most once per Discover (spec C-10).

type SSHTransportProd ¶

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

SSHTransportProd is the production SSHTransport. Wraps internal/ssh.Dial to honor the project's host-key + auth policy. Exported so cmd/openwatch and tests that want a real (not stubbed) transport can construct one without internal package boundaries.

func NewSSHTransport(mode owssh.Mode, store owssh.KnownHostsStore) *SSHTransportProd

func (t *SSHTransportProd) Dial(ctx context.Context, host string, port int, cred *credential.Credential) (SSHSession, error)

func (t *SSHTransportProd) WithProfiles(p ConnProfileStore) *SSHTransportProd

type Service ¶

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

func NewService(pool *pgxpool.Pool, emit AuditEmitFunc, bus Publisher) *Service

func (s *Service) Discover(ctx context.Context, hostID uuid.UUID) (SystemFacts, error)

func (s *Service) RunDiscovery(ctx context.Context, hostID uuid.UUID) error

func (s *Service) WithCredentialService(c *credential.Service) *Service

func (s *Service) WithHostLookup(h HostLookup) *Service

func (s *Service) WithPolicyLoader(p PolicyLoader) *Service

func (s *Service) WithProfiles(p SudoProfileStore) *Service

func (s *Service) WithSSHTransport(t SSHTransport) *Service

type SudoProfileStore ¶

type SudoProfileStore interface {
	Get(ctx context.Context, hostID uuid.UUID) (connprofile.Profile, error)
	RecordSudoMode(ctx context.Context, hostID uuid.UUID, m connprofile.SudoMode) error
}

SudoProfileStore is the subset of connprofile the discovery service uses to learn the host's SUDO mode for the firewall probe: lead with the recorded mode and record the mode a sudo firewall command confirms. nil disables sudo-mode learning. (SSH auth-method learning is handled separately by the profile-aware transport.) Spec system-connection- profile v1.2.0.

type SystemFacts ¶

type SystemFacts struct {
	// /etc/os-release
	OSName             string
	OSVersion          string
	OSVersionFull      string
	OSID               string
	OSIDLike           string
	OSPrettyName       string
	PlatformIdentifier string
	OSFamily           string // derived from OSID + OSIDLike

	// uname -srvm
	KernelName    string
	KernelRelease string
	KernelVersion string
	Architecture  string

	// /proc/meminfo (MB)
	MemTotalMB     int
	MemAvailableMB int
	SwapTotalMB    int

	// df -BG /
	DiskTotalGB int
	DiskUsedGB  int
	DiskFreeGB  int

	// hostname
	Hostname string
	FQDN     string

	// security posture
	SELinuxStatus   string
	AppArmorEnabled bool

	// firewall (may be empty when sudo unavailable)
	FirewallService string
	FirewallStatus  string

	CollectedAt time.Time

	// Observed records which fact CATEGORIES this run actually collected (the
	// probe ran and returned usable output). persist() carries forward the
	// prior stored value for any category NOT observed, so a failed or denied
	// probe never blanks previously-good data (spec C-08, v1.5.0). An observed
	// category keeps the run's values even when genuinely empty/zero — that is
	// a real observation, not a missing one.
	Observed map[FactCategory]bool

	// Attempts records WHY a non-observed category was not collected this run
	// (denied | failed | timeout), so the persisted freshness can tell an
	// operator whether a stale value is a fixable sudo denial or a transient
	// connectivity failure. Only categories that were attempted-but-not-observed
	// appear here; an observed category is absent from this map. Spec C-14,
	// v1.7.0.
	Attempts map[FactCategory]string
}

SystemFacts is the typed bundle of every fact one Discover run collected. Mirrors the host_system_info column layout one-for-one so persist() is a straight value-to-column map.