Daemon for osctrl, the fast and efficient osquery management.
osctrld is the daemon component for osctrl. It keeps osquery clients aligned with their osctrl environment by managing flags, enrollment secrets, server certificates, extensions, and local osquery restarts.
It is designed to run close to osquery as a small operational companion: it can perform one-shot enrollment and verification tasks, or run continuously as a daemon that periodically syncs configuration from osctrl.
osctrld can:
- ✨ Enroll and remove nodes using osctrl-provided scripts.
- 📥 Retrieve osquery flags and TLS certificates from osctrl.
- 🔎 Verify local flags, certificates, and secrets against the server.
- ⚡ Run as a daemon with a configurable sync interval and jitter.
- 🔁 Restart osquery when managed files or extensions change.
- 🧩 Deploy osquery extensions from osctrl extension manifests.
- ⚙️ Use YAML or JSON configuration files, CLI flags, or environment variables.
- 📋 Emit human-readable or JSON structured logs.
- 🖥️ Run on Linux, macOS, and Windows.
⚠️ Warningosctrld manages files and actions that affect osquery execution. Review configuration, file permissions, TLS settings, and extension sources before deploying it to production endpoints.
osquery is powerful, but keeping endpoint configuration current across many systems can become repetitive and error-prone. osctrld provides a narrow, auditable daemon that lets osctrl manage the local osquery client state without embedding that logic in deployment scripts.
The goal is to keep endpoint-side lifecycle work predictable: retrieve the desired state from osctrl, write it to the expected local paths, detect changes, and restart osquery only when needed.
Full documentation for the osctrl project is available at https://osctrl.net.
For this repository, the most useful starting points are:
- service/osctrld-sample.yaml for a YAML configuration example.
- service/linux/systemd.service for Linux service deployment.
- service/darwin/net.osctrl.daemon.plist for macOS launchd deployment.
- SECURITY.md for vulnerability reporting and operator security guidance.
.
├── cmd/osctrld/ # osctrld CLI, daemon logic, and tests
├── service/
│ ├── darwin/ # macOS launchd service definition
│ ├── linux/ # Linux systemd service definition
│ └── osctrld-sample.yaml # Sample YAML configuration
├── tests/ # Test configuration fixtures
├── .github/workflows/ # CI and release automation
├── .goreleaser.yml # Multi-platform release configuration
├── Makefile # Local build, test, and release helpers
└── SECURITY.md # Security policy
osctrld is a Go CLI built around a small set of commands:
enrollandremoveexecute osctrl-provided lifecycle scripts for a node.flagsandcertfetch managed osquery files and write them locally.verifychecks whether local osquery configuration matches osctrl.serviceruns the daemon loop and repeatedly syncs managed state.check-configvalidates a configuration file and exits.default-configprints a generated YAML configuration template.
The daemon mode performs a sync cycle on a configurable interval. During each cycle, osctrld retrieves flags, certificates, and extension manifests from osctrl, writes changed content to disk, and restarts osquery through the operating system service manager when a managed artifact changes.
Configuration is loaded from the osctrld section of a YAML or JSON file and can be overridden by CLI flags or environment variables. YAML is the default format for new deployments. Runtime defaults are applied before commands run, and wrapped commands validate the effective configuration before doing work.
Download the latest release from the Releases page.
go build -o osctrld ./cmd/osctrld/You can also use the Makefile:
make buildExample YAML configuration:
osctrld:
# osctrl enrollment secret value used to authenticate requestsosctrlSecret: "thisisthesecret"# Local path where the osquery enrollment secret file is written or verifiedosquerySecretFile: "/path/to/osquery.secret"osqueryFlagFile: "/path/to/osquery.flags"osqueryCertFile: "/path/to/osquery.crt"environment: "environment_name_or_UUID"baseurl: "https://osctrl.url"insecure: falseverbose: falseforce: truelogFormat: "text"interval: 60extensionsDir: "/path/to/extensions/"JSON configuration files are also supported. Use a .json extension and osctrld will detect the format automatically.
check-config, service, enroll, remove, flags, cert, and verify all validate the effective configuration before running.
| Field | Description | Default |
|---|---|---|
osctrlSecret | osctrl enrollment secret value used to authenticate requests | Required for enrollment workflows |
osquerySecretFile | Local path where the osquery enrollment secret file is written or verified | OS-dependent |
osqueryFlagFile | Path to the osquery flags file | OS-dependent |
osqueryCertFile | Path to the osquery TLS certificate file | OS-dependent |
enrollScript | Path to the enroll script | OS-dependent |
removeScript | Path to the remove script | OS-dependent |
osquery | Path to the osquery installation directory | OS-dependent |
environment | osctrl environment name or UUID | Required for most workflows |
baseurl | Base URL of the osctrl server | Required |
insecure | Ignore TLS certificate warnings | false |
verbose | Enable debug logging | false |
force | Overwrite existing managed files | false |
logFormat | Log format: text or json | text |
interval | Sync interval in minutes for daemon mode | 60 |
extensionsDir | Directory for osquery extension binaries | OS-dependent |
NAME:
osctrld - Daemon for osctrl, the fast and efficient osquery management
COMMANDS:
enroll Enroll a new node in osctrl, using new secret and flag files
remove Remove enrolled node from osctrl, clearing secret and flag files
verify Verify flags, cert and secret for an enrolled node in osctrl
flags Retrieve flags for osquery from osctrl and write them locally
cert Retrieve server certificate for osquery from osctrl and write it locally
service Run as a daemon, periodically syncing flags and certificate
check-config Validate configuration and exit
default-config Print a default YAML configuration
Validate configuration before launching:
osctrld check-config --config /etc/osctrld/osctrld.yamlGenerate a fresh config template:
osctrld default-configRetrieve flags and certificates:
osctrld flags --config /etc/osctrld/osctrld.yaml
osctrld cert --config /etc/osctrld/osctrld.yamlEnroll a node:
osctrld enroll --config /etc/osctrld/osctrld.yamlVerify a node:
osctrld verify --config /etc/osctrld/osctrld.yamlRun in daemon mode:
osctrld service --config /etc/osctrld/osctrld.yaml --interval 60In daemon mode, osctrld will:
- Sync flags, certificates, and extensions from osctrl every
--intervalminutes with jitter. - Detect whether managed content changed on disk.
- Restart osquery through the OS service manager when changes are detected.
- Shut down gracefully on
SIGINTorSIGTERM.
cp osctrld /opt/osctrld/
cp service/linux/systemd.service /etc/systemd/system/osctrld.service
cp service/osctrld-sample.yaml /etc/osctrld/osctrld.yaml
systemctl daemon-reload
systemctl enable osctrld
systemctl start osctrldEdit /etc/osctrld/osctrld.yaml with the correct osctrl URL, environment, secret, and local osquery paths before starting the service in production.
cp osctrld /usr/local/bin/
mkdir -p /usr/local/etc/osctrld
cp service/osctrld-sample.yaml /usr/local/etc/osctrld/osctrld.yaml
cp service/darwin/net.osctrl.daemon.plist /Library/LaunchDaemons/
launchctl load /Library/LaunchDaemons/net.osctrl.daemon.plistEdit the plist so it points to your installed binary and /usr/local/etc/osctrld/osctrld.yaml, then update that configuration file for your environment before loading the daemon.
Install Go, then run the test suite:
go test ./cmd/osctrld/ -vUseful Makefile targets:
make build
make test
make test_cover
make release-snapshotRun the same checks used by CI before opening a pull request:
go test ./cmd/osctrld/ -race -coverprofile=coverage.out -v
go tool cover -func=coverage.out--configuration FILE, -c FILE Configuration file for osctrld
--secret value, -s value osctrl enrollment secret
--environment value, -e value osctrl environment name or UUID
--secret-file FILE, -S FILE Local osquery enrollment secret file
--flagfile FILE, -F FILE Local osquery flags file
--certificate FILE, -C FILE Local osquery TLS certificate file
--osctrl-url value, -U value Base URL for the osctrl server
--osquery-path FILE, -o FILE Path to osquery installation
--insecure, -i Ignore TLS warnings
--verbose, -V Enable debug logging
--force, -f Overwrite existing managed files
--log-format value, -L value Log output format: text or json
--interval value, -I value Sync interval in minutes for service mode
All flags can also be set through environment variables, including OSCTRL_CONFIG, OSCTRL_SECRET, OSCTRL_ENV, OSQUERY_SECRET, OSQUERY_FLAGFILE, OSQUERY_CERTIFICATE, OSCTRL_URL, OSQUERY_PATH, OSCTRL_INSECURE, OSCTRL_VERBOSE, OSCTRL_FORCE, OSCTRL_LOG_FORMAT, and OSCTRL_INTERVAL.
Find us in the #osctrl channel in the official osquery Slack community (Request an auto-invite!).
osctrld is licensed under the MIT License.
If you believe you have found a security issue in osctrld, please do not open a public GitHub issue. Follow the process in SECURITY.md.
We ❤️ contributions!
Contributions are welcome. Please open an issue or pull request with a clear description of the problem, proposed change, and validation performed.