Documentation
¶
Overview ¶
Audit attribution for handler-emitted events: who acted, and on what.
Every handler event goes through one of three typed helpers, so the actor cannot be passed as an arbitrary string. Before this, a single emitAudit(r, code, actorID, detail) took the actor as a string, and fourteen call sites passed the id of the object they acted on, so the trail named a host or a user account as the actor and never the person (bugs/OW-099).
Spec system-audit-emission C-10, C-11.
Capability discovery: what THIS deployment may use.
Spec api-capabilities.
Per-host failing-rule listing — GET /hosts/{id}/compliance/failed-rules.
Reads host_rule_state rows with current_status='fail' for the host, scoped to its current corpus (internal/corpus) so a retired rule is not listed as an actionable failure. It is not actionable: the scan engine no longer ships a handler for it, so no fix can clear it. Severity-ordered (critical > high > medium > low > unset, then last_checked_at DESC), with titles/categories resolved from the in-memory kensa RuleCatalog. SECURITY: the query projects an explicit column list — the stored per-rule check output (which may contain sensitive host configuration) is never selected; spec AC-06 enforces that invariant by source inspection of this file.
Spec: specs/api/host-compliance.spec.yaml.
Per-host compliance lens — GET /hosts/{id}/compliance and GET /hosts/{id}/compliance/frameworks.
The lens is the "one scan, many framework views" projection: the host's CURRENT corpus (internal/corpus: the host_rule_state rows the host's most recent completed scan evaluated, bounded at ~539 rows) is read in ONE unpaginated query, optionally filtered to a framework, and summarized three ways — summary counts, per-category breakdown (computed in Go from the kensa RuleCatalog), and the full rules list. The frameworks endpoint lists the lens options.
SECURITY: both queries project explicit column lists — the stored per-rule check output (which may contain sensitive host configuration) is never selected; spec AC-13 enforces that invariant by source inspection of this file.
Spec: specs/api/host-compliance.spec.yaml v1.1.0.
On-demand compliance scan — POST /hosts/{id}/scans.
Creates the scan_runs logbook row and enqueues the HMAC-signed scan job the worker executes via Kensa. The response is 202 + scan_id; the scan is asynchronous (completion lands in host_rule_state/transactions and on the event bus).
Spec: specs/api/host-scan.spec.yaml.
Package server runs the OpenWatch HTTPS API server.
Day 4 ships: chi router with correlation middleware, TLS hot-reload via GetCertificate, locked http.Server timeouts. Day 5+ register real endpoints onto the router exposed via the Routes accessor.
Spec: specs/system/http-server.spec.yaml.
Index ¶
- Constants
- type Server
- func (s *Server) Routes() chi.Router
- func (s *Server) Run(ctx context.Context) error
- func (s *Server) ScanWorkerRegistered() bool
- func (s *Server) StartWorker(ctx context.Context)
- func (s *Server) StopWorker()
- func (s *Server) WithActivity(a *activity.Service) *Server
- func (s *Server) WithAlerts(a *alerts.Service) *Server
- func (s *Server) WithConnectivityConfig(store *systemconfig.Store, live *liveness.Service) *Server
- func (s *Server) WithDiscovery(d *discovery.Service) *Server
- func (s *Server) WithEventBus(bus *eventbus.Bus) *Server
- func (s *Server) WithExceptions(e *exception.Service) *Server
- func (s *Server) WithGroups(g *group.Service) *Server
- func (s *Server) WithNotifications(svc *notification.Service) *Server
- func (s *Server) WithNotifyFeed(store *notifyfeed.Store) *Server
- func (s *Server) WithRemediation(rm *remediation.Service) *Server
- func (s *Server) WithRemediationPlan(p kensa.PlanFunc) *Server
- func (s *Server) WithRemediationWorker(rw *worker.RemediationWorker) *Server
- func (s *Server) WithReportSchedules(svc *reportschedule.Service) *Server
- func (s *Server) WithReportWorker(rp worker.ReportRenderer) *Server
- func (s *Server) WithReports(rep *report.Service) *Server
- func (s *Server) WithRuleCatalog(c *kensa.RuleCatalog) *Server
- func (s *Server) WithRuleLibrary(l *kensa.RuleLibrary) *Server
- func (s *Server) WithScanQueue(queueKey []byte) *Server
- func (s *Server) WithScanResults(rd *scanresult.Reader) *Server
- func (s *Server) WithScanWorker(sw *worker.ScanWorker) *Server
- func (s *Server) WithVariableCatalog(c *kensa.VariableCatalog) *Server
Constants ¶
const DocsPath = "/docs"
DocsPath is the route Swagger UI is mounted at.
const SpecPath = "/api/v1/openapi.yaml"
SpecPath is the route the OpenAPI YAML is served from. Swagger UI loads its schema from here.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server holds the running HTTP server state. Build via New; start with Run.
func New ¶
New constructs a Server from validated config and DB pool. The returned Server has the foundation middleware chain mounted (correlation first, then idempotency) and the Stage-0 API routes generated from api/openapi.yaml registered.
func (*Server) Routes ¶
Routes returns the chi router so handler packages can register their endpoints. Not goroutine-safe; call from setup only, before Run.
func (*Server) Run ¶
Run starts the HTTPS listener and blocks until ctx is canceled. On cancellation, srv.Shutdown is called with a 30s grace period.
Returns nil on graceful shutdown, or the underlying ListenAndServeTLS error otherwise.
func (*Server) ScanWorkerRegistered ¶ added in v0.8.0
WithScanWorker registers the scan processor on the in-process job worker, so "scan" jobs claimed by the serve process execute instead of dead-ending (queue.Dequeue is not type-filtered). Spec api-host-scan / system-scan-runs. ScanWorkerRegistered reports whether the in-process job worker carries a scan processor. system-worker-subcommand AC-19 asserts it against a server built the way serve builds one, which is how the criterion notices a registration that is present in the source and never runs.
func (*Server) StartWorker ¶
StartWorker starts the in-process job worker. Run() invokes this automatically; tests that bypass Run() (e.g., httptest.NewServer against s.router) must call it explicitly when they need the worker to drain jobs.
func (*Server) StopWorker ¶
func (s *Server) StopWorker()
StopWorker stops the in-process job worker. Idempotent.
func (*Server) WithActivity ¶
WithActivity threads the unified Activity feed service into the API handlers so /api/v1/activity is routable. Spec api-activity.
func (*Server) WithAlerts ¶
WithAlerts threads the alert lifecycle service into the API handlers so /api/v1/alerts and the :verb endpoints are routable. Spec system-alerts + api-alerts.
func (*Server) WithConnectivityConfig ¶
WithConnectivityConfig threads the systemconfig store + live liveness Service into the API handlers so the /system/connectivity/* endpoints can read/write config and the on-demand /hosts/{id}/connectivity:check endpoint can trigger probes. Spec api-system-connectivity, api-host-connectivity-check.
func (*Server) WithDiscovery ¶
WithDiscovery threads the OS Discovery service into the API handlers AND the in-process worker so /hosts/{id}/discovery:run can trigger a one-shot fingerprint and the worker can drain host.discovery jobs. Spec system-host-discovery.
func (*Server) WithEventBus ¶
WithEventBus threads the in-process pub/sub bus into the handlers so the SSE endpoint can subscribe and fan events out to operator browsers. Spec api-events-stream (Track B).
func (*Server) WithExceptions ¶
WithExceptions threads the compliance exception governance service into the API handlers. Nil makes the exception endpoints 503. Spec api-compliance-exceptions.
func (*Server) WithGroups ¶
WithGroups threads the host group service (sites + OS categories) into the API handlers so /api/v1/groups and its sub-routes are routable. Nil makes the group endpoints 503. Spec api-groups.
func (*Server) WithNotifications ¶
func (s *Server) WithNotifications(svc *notification.Service) *Server
WithNotifications threads the notification-channel service into the API handlers so /api/v1/notifications/channels is routable. Nil makes the notification endpoints 503. Spec api-notifications.
func (*Server) WithNotifyFeed ¶
func (s *Server) WithNotifyFeed(store *notifyfeed.Store) *Server
WithNotifyFeed threads the in-app notification feed store into the API handlers so /api/v1/notifications (the bell) is routable. Nil makes those endpoints 503. Spec system-notifications / api-notifications.
func (*Server) WithRemediation ¶
func (s *Server) WithRemediation(rm *remediation.Service) *Server
WithRemediation threads the remediation governance service (free core) into the API handlers. Nil makes the remediation endpoints 503. Spec api-remediation.
func (*Server) WithRemediationPlan ¶ added in v0.7.1
WithRemediationPlan threads the read-only plan closure into the API handlers so a request can be previewed before it is approved. Nil leaves the endpoint 503, which is the honest answer when the rule corpus is missing: an empty preview would read as "this fix does nothing". Spec api-remediation.
func (*Server) WithRemediationWorker ¶
func (s *Server) WithRemediationWorker(rw *worker.RemediationWorker) *Server
WithRemediationWorker registers the remediation processor on the in-process job worker, so "remediation" jobs claimed by the serve process execute instead of dead-ending. Spec api-remediation.
func (*Server) WithReportSchedules ¶
func (s *Server) WithReportSchedules(svc *reportschedule.Service) *Server
WithReportSchedules wires the report schedule service for the /api/v1/reports/schedules endpoints. Spec system-report-schedule.
func (*Server) WithReportWorker ¶
func (s *Server) WithReportWorker(rp worker.ReportRenderer) *Server
WithReportWorker registers the report render processor on the in-process job worker, so "report.render" jobs claimed by the serve process render the report's faces and publish ReportReady instead of dead-ending. Spec api-reports.
func (*Server) WithReports ¶
WithReports threads the reports library service into the API handlers so /api/v1/reports and its sub-routes are routable. Nil makes the report endpoints 503. Spec api-reports.
func (*Server) WithRuleCatalog ¶
func (s *Server) WithRuleCatalog(c *kensa.RuleCatalog) *Server
WithRuleCatalog threads the in-memory kensa rule catalog into the API handlers so /hosts/{id}/compliance/failed-rules can resolve rule titles and categories. Nil-safe: without a catalog the endpoint falls back to rule ids. Spec api-host-compliance.
func (*Server) WithRuleLibrary ¶
func (s *Server) WithRuleLibrary(l *kensa.RuleLibrary) *Server
WithRuleLibrary threads the normalized kensa rule library into the API handlers so /api/v1/rules is routable. Nil makes that endpoint 503. Spec api-rules.
func (*Server) WithScanQueue ¶
WithScanQueue threads the scan-job HMAC key into the API handlers so POST /hosts/{id}/scans can sign and enqueue jobs the worker accepts. Spec api-host-scan.
func (*Server) WithScanResults ¶
func (s *Server) WithScanResults(rd *scanresult.Reader) *Server
WithScanResults threads the durable per-scan results reader into the API handlers so /api/v1/scans and its sub-routes are routable. Nil makes the scan endpoints 503. Spec api-scans.
func (*Server) WithScanWorker ¶
func (s *Server) WithScanWorker(sw *worker.ScanWorker) *Server
func (*Server) WithVariableCatalog ¶
func (s *Server) WithVariableCatalog(c *kensa.VariableCatalog) *Server
WithVariableCatalog threads the kensa variable catalog into the API handlers so /system/scan/variables can list corpus-used variables and validate override names. Nil-safe. Spec api-system-scan-config.
Source Files
¶
- activity_handler.go
- alerts_handlers.go
- audit_actor.go
- audit_export_handler.go
- auth_handlers.go
- authpolicy_handlers.go
- capabilities_handler.go
- compliance_handlers.go
- compliance_trend_handlers.go
- credentials_handlers.go
- csrf.go
- discovery_config_handlers.go
- exception_handlers.go
- fleet_handlers.go
- fleet_helpers.go
- group_handlers.go
- handlers.go
- host_change_events.go
- host_compliance_handler.go
- host_compliance_lens_handler.go
- host_connectivity_check_handler.go
- host_discovery_handler.go
- host_monitoring_handlers.go
- host_scan_handler.go
- host_system_info_handler.go
- hosts_enrichment.go
- hosts_handlers.go
- intelligence_config_handlers.go
- intelligence_handlers.go
- notifications_handlers.go
- notifyfeed_handlers.go
- openapi_docs.go
- ratelimit.go
- remediation_handlers.go
- report_handlers.go
- report_schedule_handlers.go
- request_errors.go
- rules_handler.go
- scan_config_handlers.go
- scans_handlers.go
- security_headers.go
- server.go
- spa.go
- sse_handler.go
- sso_handlers.go
- systemconfig_handlers.go
- tls.go
- tokens_handlers.go
- userpref_handlers.go
- users_admin_handlers.go
- users_handlers.go
Directories