README
¶
OpenWatch
The Compliance Operating System. See Everything, Continuously.
An auditor asks: "Were these 200 servers compliant with STIG on January 15th?"
With manual processes, that question takes a week to answer. With point-in-time scanning tools, you can only answer it if you happened to scan that day. With OpenWatch, it is a query: answered in seconds, backed by machine-verifiable evidence, exportable as CSV, JSON, PDF or OSCAL.
OpenWatch is a continuous compliance platform for Linux fleets under CIS, STIG, NIST 800-53, NIST 800-171, CMMC Level 2 and PCI DSS. It connects to your servers over SSH, runs the 779-rule Kensa corpus, and keeps posture as a timeline: what is passing now, what was passing last Tuesday, what drifted since your last assessment, and what needs attention before the next one. Read the introduction for what it does and how it is built.
Project status: Go rebuild, generally available. OpenWatch is a single Go binary that serves both the REST API and the embedded React UI (the original Python/FastAPI implementation was archived out of the repo on 2026-06-05). The Go tree lives at the repo root: Go 1.26 backend (
cmd/,internal/), React 19 + TanStack frontend (frontend/), PostgreSQL-only. The current version is0.8.4, on the general-availability line that opened with0.2.0.
Deploy in 10 minutes
Requirements: a Linux host (RHEL/Rocky/Fedora/Oracle or Ubuntu/Debian), PostgreSQL, and 4 GB RAM. No Docker, Podman, or containers are required.
sudo dnf install ./openwatch-*.rpm ./kensa-rules-*.noarch.rpm # RHEL / Rocky / Fedora / Oracle
sudo apt install ./openwatch_*.deb ./kensa-rules_*.deb # Ubuntu / Debian
sudo openwatch setup # provision PostgreSQL, migrate, create the admin, start
kensa-rules is the rule corpus; the openwatch package requires it. setup
shows its plan and waits for confirmation before changing anything; the
installation guide covers every option and the
manual path.
Open https://localhost:8443 and sign in with the admin user you created.
Run your first scan
- Add credentials: Settings > System Credentials > add your SSH user/key
- Add a host: Hosts > Add Host > enter IP, select credentials
- Scan: Click Scan on the host card
Results appear in under a minute. OpenWatch ships with the built-in Kensa rule corpus (the count per framework is kept in one place): human-readable YAML, not XML, ready to go.
Documentation
Start with the introduction: the problem, what OpenWatch does, how it compares, the architecture and the security model. Then three starting points: an operator reads Installation, then the Quickstart, then Scanning and compliance; an administrator reads User roles and the runbooks; a contributor reads AGENTS.md and CONTRIBUTING.md. The full index is docs/README.md.
| Topic | Link |
|---|---|
| Introduction | docs/guides/INTRODUCTION.md |
| API contract | api/openapi.yaml (source of truth) |
| API guide | docs/guides/API_GUIDE.md |
| Full documentation | hanalyx.com/docs/openwatch |
| Quickstart | docs/guides/QUICKSTART.md |
| Production deployment | docs/guides/PRODUCTION_DEPLOYMENT.md |
| Security hardening | docs/guides/SECURITY_HARDENING.md |
| Security policy | SECURITY.md (how to report a vulnerability, supported versions) |
| Behavioral specs (engineering SSOT) | specs/, registered in specter.yaml |
Part of the Hanalyx Compliance Platform
OpenWatch is the compliance operating system: the dashboard, the scheduler, the governance layer. Kensa is the compliance engine underneath: 779 rules, 29 remediation mechanisms, automatic rollback, all over SSH.
If you want a CLI that integrates into scripts and pipelines, start with Kensa. If you want a platform for your team with a dashboard, scheduling, and audit workflows, start here.
Community
Have a question, idea, or want to share how you're using OpenWatch?
- Q&A: Get help with setup, scanning, and configuration
- Ideas: Propose features and integrations
- Show and Tell: Share your compliance workflows
Found a bug? Open an issue. Found a vulnerability? Email security@hanalyx.com as described in SECURITY.md, not a public issue.
Contributing
The Go tree lives at the repo root. make build builds the UI, embeds it and
writes dist/openwatch; a bare go build ./... fails on a fresh clone
because the server embeds a directory that only the build produces.
make ci-local runs what CI runs.
make build # Go 1.26 backend + React 19 frontend, one binary
make ci-local # build, vet, tests, spec coverage, doc style
The legacy Python implementation is archived outside the repo and is no longer built or tested here. See CONTRIBUTING.md before submitting a PR.
License
OpenWatch is licensed under the Apache License 2.0 (see LICENSE and NOTICE).
- Free to use, modify, self-host, and redistribute under Apache 2.0.
- The compiled binary statically links the Kensa compliance engine, which is BSL-1.1, so a binary distribution is a combined Apache/BSL work (see NOTICE).
Third-party dependency licenses: THIRD-PARTY-NOTICES.md. Commercial inquiries: legal@hanalyx.com
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
openwatch
command
openwatch is the OpenWatch backend daemon (Go rebuild).
|
openwatch is the OpenWatch backend daemon (Go rebuild). |
|
internal
|
|
|
accountpolicy
Background password-expiry sweep, wired in serve.
|
Background password-expiry sweep, wired in serve. |
|
activity
Package activity merges alerts + transactions + intelligence_events + audit_events into a single time-ordered feed, with per-source RBAC and seek-cursor pagination.
|
Package activity merges alerts + transactions + intelligence_events + audit_events into a single time-ordered feed, with per-source RBAC and seek-cursor pagination. |
|
alertrouter
Package alertrouter is the bridge between OpenWatch's in-process event bus (internal/eventbus) and external notification channels (Slack, email, webhook, PagerDuty).
|
Package alertrouter is the bridge between OpenWatch's in-process event bus (internal/eventbus) and external notification channels (Slack, email, webhook, PagerDuty). |
|
alertrouter/channels/stdout
Package stdout implements an alertrouter.Channel that logs alerts to the structured slog default logger at INFO level.
|
Package stdout implements an alertrouter.Channel that logs alerts to the structured slog default logger at INFO level. |
|
alerts
Package alerts owns the lifecycle service for persisted alerts — acknowledge / silence / resolve / dismiss transitions plus the auto-resolve hook that closes host_unreachable when host_recovered arrives.
|
Package alerts owns the lifecycle service for persisted alerts — acknowledge / silence / resolve / dismiss transitions plus the auto-resolve hook that closes host_unreachable when host_recovered arrives. |
|
apitoken
Package apitoken manages API service-account tokens for automation (CI, scripts) that call the REST API without an interactive session.
|
Package apitoken manages API service-account tokens for automation (CI, scripts) that call the REST API without an interactive session. |
|
audit
Package audit emits and stores audit events per the contract in docs/engineering/audit_event_taxonomy.md and specs/system/audit-emission.spec.yaml.
|
Package audit emits and stores audit events per the contract in docs/engineering/audit_event_taxonomy.md and specs/system/audit-emission.spec.yaml. |
|
auth
Package auth provides RBAC: a codegen-typed permission registry, built-in roles, and the RequirePermission middleware that combines RBAC and license-gate checks in one pass.
|
Package auth provides RBAC: a codegen-typed permission registry, built-in roles, and the RequirePermission middleware that combines RBAC and license-gate checks in one pass. |
|
authpolicy
Package authpolicy manages the workspace-wide authentication policy: the require-MFA flag and the session idle/absolute timeout windows.
|
Package authpolicy manages the workspace-wide authentication policy: the require-MFA flag and the session idle/absolute timeout windows. |
|
compliance
Package compliance owns the single definition of a compliance score.
|
Package compliance owns the single definition of a compliance score. |
|
config
Package config loads OpenWatch runtime configuration.
|
Package config loads OpenWatch runtime configuration. |
|
connprofile
Package connprofile is the per-host "last known good" SSH connection memory shared by every path that talks to a managed host (the liveness privilege probe, OS discovery, OS intelligence collection, and the compliance scan).
|
Package connprofile is the per-host "last known good" SSH connection memory shared by every path that talks to a managed host (the liveness privilege probe, OS discovery, OS intelligence collection, and the compliance scan). |
|
corpus
Package corpus defines which host_rule_state rows still count.
|
Package corpus defines which host_rule_state rows still count. |
|
correlation
Package correlation propagates a request-scoped correlation ID across HTTP entry, audit emission, log lines, and outbound calls.
|
Package correlation propagates a request-scoped correlation ID across HTTP entry, audit emission, log lines, and outbound calls. |
|
credential
Package credential owns SSH credential storage and the system→host resolver.
|
Package credential owns SSH credential storage and the system→host resolver. |
|
cron
Package cron is the minimal Stage-0 cron scheduler.
|
Package cron is the minimal Stage-0 cron scheduler. |
|
db
Package db owns PostgreSQL connectivity for the openwatch binary.
|
Package db owns PostgreSQL connectivity for the openwatch binary. |
|
db/corpustest
Package corpustest seeds host_rule_state rows that are actually IN a host's current corpus.
|
Package corpustest seeds host_rule_state rows that are actually IN a host's current corpus. |
|
db/dbtest
Package dbtest gives each test BINARY (i.e.
|
Package dbtest gives each test BINARY (i.e. |
|
db/migrations
Package migrations embeds the SQL migration files and exposes the goose runner that applies them.
|
Package migrations embeds the SQL migration files and exposes the goose runner that applies them. |
|
dbbackup
Package dbbackup creates a plain-SQL pg_dump of the OpenWatch database, used as the pre-upgrade restore point before migrations run.
|
Package dbbackup creates a plain-SQL pg_dump of the OpenWatch database, used as the pre-upgrade restore point before migrations run. |
|
drift
Package drift implements OpenWatch's compliance drift detector.
|
Package drift implements OpenWatch's compliance drift detector. |
|
eventbus
Package eventbus implements OpenWatch's in-process typed pub/sub.
|
Package eventbus implements OpenWatch's in-process typed pub/sub. |
|
exception
Background expiry sweep, wired in serve.
|
Background expiry sweep, wired in serve. |
|
fleetrollup
Package fleetrollup answers "how is my fleet doing right now?" via read-only aggregations over the Slice B persistence layer (host_rule_state, transactions, host_liveness).
|
Package fleetrollup answers "how is my fleet doing right now?" via read-only aggregations over the Slice B persistence layer (host_rule_state, transactions, host_liveness). |
|
framework
Package framework groups the corpus's per-rule framework reference keys (host_rule_state.framework_refs) into user-facing FAMILIES and lists them for the "default compliance lens" picker.
|
Package framework groups the corpus's per-rule framework reference keys (host_rule_state.framework_refs) into user-facing FAMILIES and lists them for the "default compliance lens" picker. |
|
group
Package group implements host groups: operator-curated SITES (manual membership) and OS CATEGORIES (auto membership derived from hosts.os_family, or manual workload groups).
|
Package group implements host groups: operator-curated SITES (manual membership) and OS CATEGORIES (auto membership derived from hosts.os_family, or manual workload groups). |
|
host
Package host owns the hosts table — the inventory of machines the platform can talk to.
|
Package host owns the hosts table — the inventory of machines the platform can talk to. |
|
httpclient
Package httpclient is the outbound HTTP wrapper that forwards the correlation ID from request context as X-Correlation-Id on every call.
|
Package httpclient is the outbound HTTP wrapper that forwards the correlation ID from request context as X-Correlation-Id on every call. |
|
idempotency
Package idempotency provides the middleware that makes mutating HTTP requests safely retryable.
|
Package idempotency provides the middleware that makes mutating HTTP requests safely retryable. |
|
identity
Package identity owns the auth primitives: password hashing (Argon2id), NIST SP 800-63B password-policy validation, breach-corpus checking, session token lifecycle, RS256 JWT mint/verify, and TOTP MFA.
|
Package identity owns the auth primitives: password hashing (Argon2id), NIST SP 800-63B password-policy validation, breach-corpus checking, session token lifecycle, RS256 JWT mint/verify, and TOTP MFA. |
|
intelligence/collector
Package collector implements OS Intelligence — the recurring, write-on-change counterpart to OS Discovery.
|
Package collector implements OS Intelligence — the recurring, write-on-change counterpart to OS Discovery. |
|
intelligence/discovery
Package discovery owns the one-shot SSH OS-fingerprint flow that captures os_family, os_version, kernel, architecture, hostname / FQDN, SELinux + AppArmor + firewall posture, and a hardware summary for each host on first contact + on-demand.
|
Package discovery owns the one-shot SSH OS-fingerprint flow that captures os_family, os_version, kernel, architecture, hostname / FQDN, SELinux + AppArmor + firewall posture, and a hardware summary for each host on first contact + on-demand. |
|
intelligence/discovery/scheduler
Package scheduler is the recurring driver for OS discovery — the loop that finds hosts whose hosts.os_discovered_at column is stale (NULL or older than the policy interval) and enqueues host.discovery jobs through internal/queue so the worker pool picks them up and runs discovery.Service.Discover on them.
|
Package scheduler is the recurring driver for OS discovery — the loop that finds hosts whose hosts.os_discovered_at column is stale (NULL or older than the policy interval) and enqueues host.discovery jobs through internal/queue so the worker pool picks them up and runs discovery.Service.Discover on them. |
|
intelligence/probe
Package probe holds pure parsers for the OS-fingerprint commands the Discovery service runs over SSH.
|
Package probe holds pure parsers for the OS-fingerprint commands the Discovery service runs over SSH. |
|
intelligence/scheduler
Package scheduler is the recurring driver for OS Intelligence collection — the cron-like loop that turns the one-shot collector.Service.RunCycle into a continuous per-host cadence.
|
Package scheduler is the recurring driver for OS Intelligence collection — the cron-like loop that turns the one-shot collector.Service.RunCycle into a continuous per-host cadence. |
|
internalrace
Package internalrace exposes a single helper for adjusting performance budgets when the race detector is on.
|
Package internalrace exposes a single helper for adjusting performance budgets when the race detector is on. |
|
isotree
Package isotree gives a test a private copy of part of the repository.
|
Package isotree gives a test a private copy of part of the repository. |
|
kensa
RuleCatalog — in-memory kensa rule id -> {title, category, severity} lookup for read-path endpoints (the failed-rules listing resolves titles through it).
|
RuleCatalog — in-memory kensa rule id -> {title, category, severity} lookup for read-path endpoints (the failed-rules listing resolves titles through it). |
|
knownhosts
Package knownhosts is a PostgreSQL-backed ssh.KnownHostsStore.
|
Package knownhosts is a PostgreSQL-backed ssh.KnownHostsStore. |
|
license
Package license owns license file loading, JWT validation, atomic state for hot-path IsEnabled checks, the RequireFeature HTTP middleware, and the license.* audit emissions.
|
Package license owns license file loading, JWT validation, atomic state for hot-path IsEnabled checks, the RequireFeature HTTP middleware, and the license.* audit emissions. |
|
liveness
Package liveness implements OpenWatch's periodic host reachability probe loop.
|
Package liveness implements OpenWatch's periodic host reachability probe loop. |
|
log
Package log provides the slog handler that automatically tags every log record with the correlation_id from context.
|
Package log provides the slog handler that automatically tags every log record with the correlation_id from context. |
|
notification
Package notification manages operator-configured alert-delivery channels (Slack, generic webhook).
|
Package notification manages operator-configured alert-delivery channels (Slack, generic webhook). |
|
notifyfeed
Package notifyfeed is the durable, per-user in-app notification feed — the data layer behind the bell.
|
Package notifyfeed is the durable, per-user in-app notification feed — the data layer behind the bell. |
|
perftest
Package perftest gates latency-budget assertions behind an explicit opt-in.
|
Package perftest gates latency-budget assertions behind an explicit opt-in. |
|
policy
Package policy is the Stage-0 policies-as-data framework.
|
Package policy is the Stage-0 policies-as-data framework. |
|
posture
Package posture maintains daily per-host compliance posture snapshots and serves the trend reads built on them.
|
Package posture maintains daily per-host compliance posture snapshots and serves the trend reads built on them. |
|
queue
Package queue is the PostgreSQL-native async job queue.
|
Package queue is the PostgreSQL-native async job queue. |
|
remediation
Remediation execution lifecycle (Phase 7, Tier A free-core).
|
Remediation execution lifecycle (Phase 7, Tier A free-core). |
|
report
Package report implements the Reports library: point-in-time, immutable, Ed25519-signed compliance artifacts.
|
Package report implements the Reports library: point-in-time, immutable, Ed25519-signed compliance artifacts. |
|
reportschedule
Package reportschedule recurs report generation on a daily/weekly/monthly cadence and delivers the rendered PDF by email.
|
Package reportschedule recurs report generation on a daily/weekly/monthly cadence and delivers the rendered PDF by email. |
|
retention
Package retention holds one registry of retention policies and one sweeper that walks it.
|
Package retention holds one registry of retention policies and one sweeper that walks it. |
|
scanresult
Package scanresult persists and reads durable, point-in-time per-scan compliance results plus content-addressed evidence.
|
Package scanresult persists and reads durable, point-in-time per-scan compliance results plus content-addressed evidence. |
|
scanruns
Package scanruns owns the scan_runs table — the operational record ("logbook") of compliance-scan attempts.
|
Package scanruns owns the scan_runs table — the operational record ("logbook") of compliance-scan attempts. |
|
scheduler
Package scheduler implements the adaptive compliance scan scheduler.
|
Package scheduler implements the adaptive compliance scan scheduler. |
|
secretkey
Package secretkey owns the AES-256-GCM data encryption key (DEK) used to encrypt at-rest secrets.
|
Package secretkey owns the AES-256-GCM data encryption key (DEK) used to encrypt at-rest secrets. |
|
server
Audit attribution for handler-emitted events: who acted, and on what.
|
Audit attribution for handler-emitted events: who acted, and on what. |
|
server/api
Package api provides primitives to interact with the openapi HTTP API.
|
Package api provides primitives to interact with the openapi HTTP API. |
|
setup
Preflight, plan rendering, execution, and the receipt.
|
Preflight, plan rendering, execution, and the receipt. |
|
specfixture
Package specfixture loads acceptance-criteria fixtures out of a Specter spec so tests are driven by the spec rather than by numbers copied beside it.
|
Package specfixture loads acceptance-criteria fixtures out of a Specter spec so tests are driven by the spec rather than by numbers copied beside it. |
|
ssh
Package ssh is the OpenWatch SSH dial layer.
|
Package ssh is the OpenWatch SSH dial layer. |
|
sshprivilege
Package sshprivilege implements liveness.PrivilegeProbeFunc: dial SSH with the host's resolved credential, run `sudo -n true`, and report whether passwordless privilege escalation is configured.
|
Package sshprivilege implements liveness.PrivilegeProbeFunc: dial SSH with the host's resolved credential, run `sudo -n true`, and report whether passwordless privilege escalation is configured. |
|
sso
Package sso implements single sign-on via OpenID Connect: admin-managed providers (config plane) and the authorization-code sign-in flow (runtime plane).
|
Package sso implements single sign-on via OpenID Connect: admin-managed providers (config plane) and the authorization-code sign-in flow (runtime plane). |
|
systemconfig
Package systemconfig is the runtime config store.
|
Package systemconfig is the runtime config store. |
|
transactionlog
Package transactionlog implements OpenWatch's compliance write-on-change persistence layer.
|
Package transactionlog implements OpenWatch's compliance write-on-change persistence layer. |
|
userpref
Package userpref owns per-user UI preferences, stored as the JSONB users.preferences column (migration 0040).
|
Package userpref owns per-user UI preferences, stored as the JSONB users.preferences column (migration 0040). |
|
users
Package users owns the users + user_roles tables.
|
Package users owns the users + user_roles tables. |
|
version
FIPS reporting, sourced from the runtime rather than from a build flag.
|
FIPS reporting, sourced from the runtime rather than from a build flag. |
|
worker
JSONB payload + HMAC signing for remediation jobs.
|
JSONB payload + HMAC signing for remediation jobs. |
Click to show internal directories.
Click to hide internal directories.