README
¶
Knox - Self-Hosted Secret Management
Knox is a self-hosted secret management service forked from pinterest/knox. The target for this fork is a sturdy secret manager for Unix systems, CLI workflows, and optional FreeDesktop Secret Service integration.
Current Status
Knox is under active stabilization. The codebase has meaningful pieces in place:
- AES-256-GCM envelope encryption for stored secrets
- HTTP API with ACL-aware key operations
- CLI commands for key, ACL, and config workflows
- Filesystem, SQLite, memory, and etcd storage packages
- D-Bus Secret Service bridge implementation
- Tests across crypto, storage, server, client, and D-Bus packages
The current server, storage, crypto, and CLI paths are covered by the Go test suite. The D-Bus bridge still needs live verification with Secret Service clients before it should be treated as a dependable desktop secret store.
Intended Use
The practical deployment model is:
Unix server or workstation
knox-server
filesystem or SQLite storage
master key from /etc/knox/master.key or KNOX_MASTER_KEY_FILE
TLS and simple auth appropriate for the deployment
Unix workstation or laptop
knox CLI
optional knox-dbus launched by a user service or XDG autostart entry
local scripts and services
scripts and services using knox CLI or the HTTP API
Build
Prerequisites:
- Go 1.24 or later
Build the three main binaries:
go build -o bin/knox ./cmd/client
go build -o bin/knox-server ./cmd/server
go build -o bin/knox-dbus ./cmd/dbus
Server Configuration
knox-server is currently configured through a YAML file. By default it reads
/etc/knox/server.yaml; pass a different path with --config.
Minimal local example:
bind_address: "127.0.0.1:9000"
storage:
backend: "filesystem"
filesystem_dir: "/var/lib/knox/keys"
# SQLite is also available through the ORM backend:
# backend: "sqlite"
# sqlite_path: "/var/lib/knox/knox.db"
auth:
providers:
- type: "mock"
observability:
metrics:
enabled: true
endpoint: "/metrics"
logging:
level: "info"
format: "text"
audit:
enabled: true
output: "stdout"
limits:
rate_limit_per_principal: 100
max_key_size: "1MB"
max_keys_per_list: 1000
The server needs a 32-byte master key. Supported sources, in priority order:
KNOX_MASTER_KEY, as base64 or hexKNOX_MASTER_KEY_FILE, pointing to an absolute path/etc/knox/master.key
Key files must be owner-only, for example:
install -d -m 0700 /etc/knox
openssl rand -base64 32 > /etc/knox/master.key
chmod 0600 /etc/knox/master.key
Start the server:
knox-server --config /etc/knox/server.yaml
CLI
Initialize client configuration:
knox config init --server 127.0.0.1:9000
Common workflows:
echo "secret-value" | knox key create app:test
knox key get app:test
knox key list
knox key rotate app:test --data "new-secret-value"
knox acl get app:test
See docs/CLI_GUIDE.md for current command details.
Desktop Integration
knox-dbus implements a FreeDesktop Secret Service bridge. The intended Unix
desktop path is to launch it with a user service manager or an XDG
session/autostart mechanism.
Current D-Bus limitations are documented in
docs/DBUS_GUIDE.md. Browser/libsecret compatibility should
be verified with secret-tool and real desktop applications before relying on it
for daily use.
Stabilization Checklist
Current stabilization state:
go test ./...passes- the server uses one canonical route path
- storage backend create/update/delete semantics are tested
- supported backends are limited to memory, filesystem, SQLite, and etcd
- audit logging covers key and ACL operations without logging secret values
- master-key rotation protects data that still needs previous cryptors
- generic service-manager examples exist
- backup and restore are documented and tested
- D-Bus behavior still needs live verification with
secret-tool
Documentation
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client implements the Knox CLI client commands.
|
Package client implements the Knox CLI client commands. |
|
cmd
|
|
|
client
command
Package main provides the production Knox CLI client.
|
Package main provides the production Knox CLI client. |
|
dbus
command
Package main provides the Knox D-Bus Secret Service bridge daemon.
|
Package main provides the Knox D-Bus Secret Service bridge daemon. |
|
server
command
Package main provides the Knox production HTTP server.
|
Package main provides the Knox production HTTP server. |
|
test-encryption
command
Package main provides a test utility to verify encryption at rest is working correctly.
|
Package main provides a test utility to verify encryption at rest is working correctly. |
|
Package log implements a simple logging package.
|
Package log implements a simple logging package. |
|
pkg
|
|
|
auth
Package auth provides authentication providers for Knox.
|
Package auth provides authentication providers for Knox. |
|
config
Package config provides configuration management for Knox.
|
Package config provides configuration management for Knox. |
|
crypto
Package crypto provides cryptographic operations for Knox.
|
Package crypto provides cryptographic operations for Knox. |
|
dbus
Package dbus implements the FreeDesktop Secret Service API.
|
Package dbus implements the FreeDesktop Secret Service API. |
|
observability/logging
Package logging provides structured logging for Knox CLI components.
|
Package logging provides structured logging for Knox CLI components. |
|
observability/metrics
Package metrics provides Prometheus metrics for Knox.
|
Package metrics provides Prometheus metrics for Knox. |
|
storage
Package storage provides a storage backend adapter that connects our storage.Backend interface to Knox's keydb.DB interface.
|
Package storage provides a storage backend adapter that connects our storage.Backend interface to Knox's keydb.DB interface. |
|
storage/etcd
Package etcd provides an etcd-based storage backend for Knox.
|
Package etcd provides an etcd-based storage backend for Knox. |
|
storage/filesystem
Package filesystem provides a filesystem-based storage backend for Knox.
|
Package filesystem provides a filesystem-based storage backend for Knox. |
|
storage/memory
Package memory provides an in-memory storage backend for Knox.
|
Package memory provides an in-memory storage backend for Knox. |
|
storage/orm
Package orm provides an ORM-based SQLite storage backend for Knox.
|
Package orm provides an ORM-based SQLite storage backend for Knox. |
|
types
Package types is a package to provide the basic types to be used across client and server.
|
Package types is a package to provide the basic types to be used across client and server. |
|
xdg
Package xdg provides XDG Base Directory Specification helpers for Knox.
|
Package xdg provides XDG Base Directory Specification helpers for Knox. |
|
Package server provides the HTTP API server for Knox secret management.
|
Package server provides the HTTP API server for Knox secret management. |
|
auth
Package auth provides authentication providers for the Knox server.
|
Package auth provides authentication providers for the Knox server. |
|
keydb
Package keydb provides cryptographic operations for Knox key storage.
|
Package keydb provides cryptographic operations for Knox key storage. |
Click to show internal directories.
Click to hide internal directories.