README.md

OpenWatch documentation

An index of the operator documentation tracked in this repository. Every document linked below is in the repository, so it is available from a clean clone.

Start here: Introduction | Quickstart

Three starting points, in the order to read them:

If you are	Read, in order
An operator installing, scanning and fixing	Introduction, then Installation, then Quickstart, then Scanning and compliance and Hosts and remediation
An administrator running it day to day	User roles, then Environment reference, Secret rotation, Backup and recovery and Upgrade procedure
A contributor changing the code	AGENTS.md, then CONTRIBUTING.md, then the contracts under specs/ and Releasing

This index links documents rather than restating what they say. Version numbers, supported platforms, rule counts, permission counts and configuration values live in the guides themselves, so there is one place to correct each of them.

---

Getting started

Document	Description
Introduction	What OpenWatch does, how it compares, the architecture and the security model
Quickstart	First 15 minutes: log in, add a host, run a scan, read results
Installation	Deploy from a native RPM or DEB package, or from source

Operator guides

Document	Description
Scanning and compliance	Run scans, read posture scores, detect drift, manage alerts
Hosts and remediation	Add hosts, configure credentials, remediate findings, roll back
User roles	Built-in roles, the permission registry, and the workflow for each role
API guide	REST API reference for automation and CI/CD integration
Verifying a report	Check a report's content hash and Ed25519 signature, and what that does not prove
Compliance controls	NIST, CIS, CMMC and FedRAMP control mapping
Supported Linux distributions	Target distributions for the RPM and DEB packages

Operations

Document	Description
Production deployment	Deployment procedures for the single openwatch binary
Environment reference	Environment variables and configuration settings
Database migrations	Migration procedures using openwatch migrate
Monitoring setup	Prometheus, Grafana and health checks
Security hardening	TLS, FIPS, rate limiting and audit logging
Scaling guide	Horizontal scaling and performance tuning
Backup and recovery	PostgreSQL backup, restore and disaster recovery
Secret rotation	Rotating database, session and encryption keys
Upgrade procedure	Upgrading OpenWatch, with the rollback path
Releasing	The gated pre-release process and signing-key setup

Incident response runbooks

Runbook	Trigger
Service down	Health check failure, service unavailable
Database issues	Connection errors, slow queries, replication lag
High CPU	CPU use above threshold
Disk full	Disk space critically low
Security incident	Unauthorized access, suspected breach

Other tracked references

Document	Description
Guides index	A second index covering the guides/ directory alone
Repository README	The landing page: install recipe, starting points, community, license
Changelog	Release history, including breaking changes and required operator actions
Contributing	Contributor workflow, hooks and pull request rules
Security policy	How to report a vulnerability
api/openapi.yaml	The API contract, and the source of truth for request and response shapes