README
¶
woodstar ⭐️
Manages macOS devices with Munki, Santa, and Orbit/osquery.
[!WARNING] This project may be unstable or have bugs, use with caution. Also expect breaking changes between releases for now.
🌱 What's inside
- Host enrollment, hardware, software, users, and query results
- Munki repositories, manifests, packages, and assignments
- Santa rules, client configuration, sync, and events
- osquery reports, policies, live queries, and dynamic labels
- Entra directory sync for people, groups, and user affinity
- Distribution-point workers for local package delivery
- Stemma plugin for publishing installers and Munki metadata
🚀 Usage
Download server archives for macOS or Linux from the latest release, or use the container ghcr.io/woodleighschool/woodstar:rolling.
Docker Compose
Start from the example environment:
cp .env.example .env
openssl rand -hex 32
Before starting, set these values in .env:
| Variable | Value |
|---|---|
WOODSTAR_URL |
HTTPS address used by browsers and managed clients |
WOODSTAR_TLS_CERT_FILE |
Certificate for that address |
WOODSTAR_TLS_KEY_FILE |
Matching private key |
WOODSTAR_STORAGE_CAPABILITY_KEY |
Output from openssl rand -hex 32 |
docker compose up -d
docker compose exec woodstar /woodstar user create \
--email you@example.com \
--name "Your Name" \
--role admin
The getting started guide covers certificates, first sign-in, and the optional distribution point worker.
⚙️ Configuration
The documentation covers configuration, storage, client protocols, Stemma, and the API.
🧑💻 Development
Mise owns the toolchain and commands:
mise install
mise run dev
mise run test
mise run lint
Backend code lives under cmd/woodstar and internal/; the React app lives under web/; the documentation site lives under docs/.
See the development setup and command reference for PostgreSQL, end-to-end, storage, generation, and docs workflows.
📄 License
Licensed under the Apache License 2.0.
🙏 Acknowledgments
- Munki - Managed software installation for macOS
- MunkiAdmin - Graphical editor for Munki repositories
- Santa - Binary authorization and endpoint security for macOS
- osquery - SQL-powered operating system instrumentation
- Fleet - Open-source device management platform and home of Orbit
- Zentral - Event-driven platform for endpoint management
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
woodstar
command
|
|
|
internal
|
|
|
account
Package account owns the application's account HTTP endpoints.
|
Package account owns the application's account HTTP endpoints. |
|
activity
Package activity records a small, curated stream of durable actions.
|
Package activity records a small, curated stream of durable actions. |
|
activity/httpapi
Package httpapi exposes the activity timeline.
|
Package httpapi exposes the activity timeline. |
|
osquery/history
Package history stores the small set of historical osquery status aggregates.
|
Package history stores the small set of historical osquery status aggregates. |
|
patch
Package patch applies typed JSON merge patches to editable resource models.
|
Package patch applies typed JSON merge patches to editable resource models. |
|
rbac
Package rbac owns the application's resource catalogue and role policy.
|
Package rbac owns the application's resource catalogue and role policy. |
|
testutil/testbloby
Package testbloby provides file-backed storage for application integration tests.
|
Package testbloby provides file-backed storage for application integration tests. |
|
test
|
|
|
e2e/adminapi
Package adminapi provides primitives to interact with the openapi HTTP API.
|
Package adminapi provides primitives to interact with the openapi HTTP API. |
|
tools
|
|
|
geoipdb
command
|
|