woodstar

module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 29, 2026 License: Apache-2.0

README ΒΆ

Woodstar ⭐️

Self-hosted macOS management for the gaps Intune leaves. Woodstar brings together Munki for software, Santa for execution policy, and Orbit with osquery for enrollment, inventory, and checks.

[!WARNING] This project may be unstable or have bugs, use with caution. Also expect breaking changes between releases for now.

🌱 What's inside

  • Hosts and inventory from Orbit or osquery, with hardware, software, users, and query results in one place.
  • Munki manifests, catalogs, packages, icons, client resources, and software assignments.
  • Santa rules, client configuration, sync, and execution events.
  • osquery reports, scheduled checks, live queries, and dynamic labels.
  • Labels shared across software, rules, reports, and checks.
  • Entra directory sync for people, groups, user affinity, and label membership.

🏑 Running Locally

Start with the example environment and a storage capability key:

cp .env.example .env
openssl rand -hex 32

Add the generated key to WOODSTAR_STORAGE_CAPABILITY_KEY, check the URL and certificate paths, then start Woodstar and PostgreSQL:

docker compose up -d
docker compose exec woodstar /woodstar user create \
  --email you@example.com \
  --name "Your Name" \
  --role admin

Compose uses the published rolling image. Uncomment the build block in docker-compose.yml to build the current checkout instead.

The Docker Compose guide covers certificates, hostnames, storage, and first sign-in.

πŸ“š Documentation

The Woodstar docs cover the web app, configuration, client protocols, AutoPkg, and the API. For code changes, head to the development setup and command reference.

πŸ§‘β€πŸ’» Development

mise owns the toolchain and everyday 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 full command list includes the PostgreSQL, end-to-end, and storage integration lanes.

🀝 Contributing

Contributions are welcome! Please open an issue before starting a larger change.

πŸ“„ License

Woodstar is licensed under the Apache License 2.0 - see the LICENSE file for details.

πŸ™ Acknowledgments

  • Munki - Managed software installation for macOS
  • MunkiAdmin - Graphical editor for Munki repositories
  • AutoPkg - Automation framework for macOS software packaging
  • 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
Woodstar runs the central server and its administrative commands.
Woodstar runs the central server and its administrative commands.
internal
agentauth
Package agentauth manages shared secrets accepted by agent-facing protocols.
Package agentauth manages shared secrets accepted by agent-facing protocols.
api
Package api wires Woodstar's HTTP server and app API surface.
Package api wires Woodstar's HTTP server and app API surface.
api/ctxkeys
Package ctxkeys defines typed request-context keys shared by API layers.
Package ctxkeys defines typed request-context keys shared by API layers.
api/handlers
Package handlers implements Woodstar's administrative HTTP API operations.
Package handlers implements Woodstar's administrative HTTP API operations.
api/middleware
Package middleware provides authentication, logging, and browser HTTP policy.
Package middleware provides authentication, logging, and browser HTTP policy.
auth
Package auth handles login, API keys, and sessions.
Package auth handles login, API keys, and sessions.
buildinfo
Package buildinfo exposes version metadata injected into Woodstar builds.
Package buildinfo exposes version metadata injected into Woodstar builds.
config
Package config loads, normalizes, and validates Woodstar process settings.
Package config loads, normalizes, and validates Woodstar process settings.
database
Package database opens PostgreSQL connections and applies embedded migrations.
Package database opens PostgreSQL connections and applies embedded migrations.
dbutil
Package dbutil provides shared pgx query, scan, and list primitives.
Package dbutil provides shared pgx query, scan, and list primitives.
directory
Package directory owns local and external user and group identities.
Package directory owns local and external user and group identities.
directory/entra
Package entra imports Microsoft Entra users and groups into the directory.
Package entra imports Microsoft Entra users and groups into the directory.
enrollment
Package enrollment owns shared host-enrollment primitives.
Package enrollment owns shared host-enrollment primitives.
hosts
Package hosts owns canonical host identity, credentials, and observations.
Package hosts owns canonical host identity, credentials, and observations.
httpx
Package httpx provides helpers for raw net/http endpoints that bypass Huma.
Package httpx provides helpers for raw net/http endpoints that bypass Huma.
inventory
Package inventory projects observed host hardware and software state.
Package inventory projects observed host hardware and software state.
labels
Package labels manages manual, dynamic, and derived host membership.
Package labels manages manual, dynamic, and derived host membership.
logging
Package logging configures the application's slog logger.
Package logging configures the application's slog logger.
munki
Package munki coordinates Munki client observations and repository delivery.
Package munki coordinates Munki client observations and repository delivery.
munki/clientresources
Package clientresources owns Munki's deployed Managed Software Center resources.
Package clientresources owns Munki's deployed Managed Software Center resources.
munki/mdp
Package mdp manages Munki distribution points: ordered mirror nodes that Woodstar redirects Munki clients to for package installers.
Package mdp manages Munki distribution points: ordered mirror nodes that Woodstar redirects Munki clients to for package installers.
munki/mdp/grant
Package grant mints and verifies Munki distribution point download grants.
Package grant mints and verifies Munki distribution point download grants.
munki/mdp/protocol
Package protocol serves the Munki distribution point worker protocol.
Package protocol serves the Munki distribution point worker protocol.
munki/mdp/wire
Package wire defines the Munki distribution point wire protocol.
Package wire defines the Munki distribution point wire protocol.
munki/mdp/worker
Package worker runs the `woodstar mdp` face: it mirrors the desired Munki package installers from Woodstar, verifies them, reports its state, and serves them under per-DP grants.
Package worker runs the `woodstar mdp` face: it mirrors the desired Munki package installers from Woodstar, verifies them, reports its state, and serves them under per-DP grants.
munki/packages
Package packages models and persists Munki installers and package metadata.
Package packages models and persists Munki installers and package metadata.
munki/protocol
Package protocol exposes Munki repository endpoints.
Package protocol exposes Munki repository endpoints.
munki/software
Package software manages Munki desired software and host targeting.
Package software manages Munki desired software and host targeting.
openapischema
Package openapischema provides Huma schema helpers for API-facing model metadata.
Package openapischema provides Huma schema helpers for API-facing model metadata.
orbit
Package orbit owns Orbit enrollment and inventory application behavior.
Package orbit owns Orbit enrollment and inventory application behavior.
orbit/protocol
Package protocol exposes Orbit endpoints.
Package protocol exposes Orbit endpoints.
osquery
Package osquery implements service behavior for Orbit-managed osquery.
Package osquery implements service behavior for Orbit-managed osquery.
osquery/catalog
Package catalog defines the osquery queries that populate host inventory.
Package catalog defines the osquery queries that populate host inventory.
osquery/checks
Package checks persists query-backed pass/fail policies and per-host results.
Package checks persists query-backed pass/fail policies and per-host results.
osquery/ingest
Package ingest projects osquery result rows into Woodstar-owned host state.
Package ingest projects osquery result rows into Woodstar-owned host state.
osquery/livequery
Package livequery runs ephemeral browser-session live queries in-process.
Package livequery runs ephemeral browser-session live queries in-process.
osquery/protocol
Package protocol exposes osquery TLS-plugin endpoints.
Package protocol exposes osquery TLS-plugin endpoints.
osquery/reports
Package reports manages scheduled osquery reports and their result snapshots.
Package reports manages scheduled osquery reports and their result snapshots.
randtoken
Package randtoken creates URL-safe random tokens.
Package randtoken creates URL-safe random tokens.
santa
Package santa coordinates host state, events, rules, and sync configuration.
Package santa coordinates host state, events, rules, and sync configuration.
santa/configurations
Package configurations resolves Santa configuration assigned to each host.
Package configurations resolves Santa configuration assigned to each host.
santa/events
Package events persists and queries Santa execution and file-access events.
Package events persists and queries Santa execution and file-access events.
santa/payloadhash
Package payloadhash produces stable hashes for Santa sync payloads.
Package payloadhash produces stable hashes for Santa sync payloads.
santa/protocol
Package protocol exposes Santa sync endpoints.
Package protocol exposes Santa sync endpoints.
santa/rules
Package rules validates, targets, and persists Santa rules.
Package rules validates, targets, and persists Santa rules.
santa/syncstate
Package syncstate tracks versioned Santa rule synchronization per host.
Package syncstate tracks versioned Santa rule synchronization per host.
storage
Package storage is woodstar's blob store: a small backend-agnostic interface over local files or S3, plus a database registry of the objects it holds.
Package storage is woodstar's blob store: a small backend-agnostic interface over local files or S3, plus a database registry of the objects it holds.
storage/capability
Package capability signs and verifies short-lived HMAC transfer tokens.
Package capability signs and verifies short-lived HMAC transfer tokens.
targeting
Package targeting evaluates label inclusion and exclusion for hosts.
Package targeting evaluates label inclusion and exclusion for hosts.
testutil/storagecontract
Package storagecontract provides shared backend conformance assertions.
Package storagecontract provides shared backend conformance assertions.
testutil/testdb
Package testdb provides isolated PostgreSQL databases for tests.
Package testdb provides isolated PostgreSQL databases for tests.
validation
Package validation provides the shared structural validation boundary.
Package validation provides the shared structural validation boundary.
webui
Package webui serves the embedded Woodstar frontend.
Package webui serves the embedded Woodstar frontend.
test
e2e
Package e2e exercises Woodstar through its external interfaces.
Package e2e exercises Woodstar through its external interfaces.
e2e/adminapi
Package adminapi provides primitives to interact with the openapi HTTP API.
Package adminapi provides primitives to interact with the openapi HTTP API.
integration/storage
Package storageintegration verifies Woodstar storage backends against their exported contract.
Package storageintegration verifies Woodstar storage backends against their exported contract.
Package webdist embeds the production frontend into the Woodstar binary.
Package webdist embeds the production frontend into the Woodstar binary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL