README
¶
An open-source osquery manager
Checkpost is an osquery manager that implements the osquery remote configuration endpoints. It enrolls hosts, serves osquery configuration, schedules queries, evaluates policies, and collects results without needing a separate management stack, all in a single binary.
The system is read-only by design: Checkpost only observes endpoints and doesn't make any changes. Use it to automate posture checks, audit endpoint configurations, investigate hosts with ad-hoc queries, and scan files with YARA.
Features
- Inventory: track hosts, owners, asset IDs, groups, and last-seen state.
- Scheduled queries: run queries on a schedule and ship results to multiple backends.
- Ad-hoc queries: run on-demand SQL queries against hosts.
- Policies: check device posture across enrolled hosts.
- YARA: scan files for YARA matches.
- Alerts: get notified on policy failures.
- Access control: role-based access with SSO (OIDC).
- GitOps: manage resources defined in YAML via the
checkpostCLI.
Quick start
Requires Docker. Starts Checkpost + Postgres:
docker compose up
Open http://localhost:1323 and log in with the default credentials (checkpost_admin / checkpost_password). Enrollment key defaults to secret-key.
TLS
The default Compose configuration serves Checkpost over HTTP. Osquery agents require an HTTPS endpoint, so enable TLS before enrolling agents.
Choose one of these options:
- Enable Checkpost's built-in TLS and mount the certificate and private key into the container. Set
CHECKPOST_APP__USE_TLS=true, configureCHECKPOST_APP__HTTP_TLS_CERTandCHECKPOST_APP__HTTP_TLS_KEY, and setCHECKPOST_APP__ROOT_URLto the HTTPS URL agents will use. - Put Checkpost behind a TLS-terminating reverse proxy such as Caddy. Set
CHECKPOST_APP__ROOT_URLto the proxy's public HTTPS URL.
The commented Caddy service in docker-compose.yml shows a minimal reverse-proxy setup. Replace checkpost.example.com with a domain that resolves to the Docker host, update CHECKPOST_APP__ROOT_URL to match, and uncomment the Caddy service and volumes. Caddy will obtain and renew a publicly trusted certificate automatically.
Configuration
Copy the template and edit as needed (TLS, OIDC/SSO, database, osquery bootstrap packages):
cp config.toml.example config.toml
All settings can also be set via CHECKPOST_<SECTION>__<KEY> environment variables (see docker-compose.yml).
Build from source
Requires Go (with a CGO toolchain) and Node.js:
make # builds the frontend + checkpost binary
./checkpost # runs the server
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets holds the static files embedded into the binary that are consumed by the internal packages (email templates, osquery bootstrap scripts, and the Casbin RBAC model).
|
Package assets holds the static files embedded into the binary that are consumed by the internal packages (email templates, osquery bootstrap scripts, and the Casbin RBAC model). |
|
cmd
|
|
|
checkpost
command
|
|
|
internal
|
|
|
core
Package systemmetrics maps is_system osquery schedules to canonical device-metric snapshots.
|
Package systemmetrics maps is_system osquery schedules to canonical device-metric snapshots. |
|
results
Package results defines the generic Sink/Reader interfaces and shared types for delivering scheduled-query results.
|
Package results defines the generic Sink/Reader interfaces and shared types for delivering scheduled-query results. |
|
results/clickhouse
Package clickhouse implements a result Sink that inserts rows into a ClickHouse table.
|
Package clickhouse implements a result Sink that inserts rows into a ClickHouse table. |
|
results/ndjson
Package ndjson implements a result Sink that writes rows as newline-delimited JSON to a file or stdout for an external log pipeline to tail.
|
Package ndjson implements a result Sink that writes rows as newline-delimited JSON to a file or stdout for an external log pipeline to tail. |
|
results/parquet
Package parquet implements the local result backend: scheduled-query results are written as Hive-partitioned Parquet files under a single root directory and queried through an embedded DuckDB engine.
|
Package parquet implements the local result backend: scheduled-query results are written as Hive-partitioned Parquet files under a single root directory and queried through an embedded DuckDB engine. |