Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

296 Commits
.github/workflows
.github/workflows
 
 
.specify
.specify
 
 
apps
apps
 
 
config
config
 
 
docs
docs
 
 
infrastructure/postgres/init
infrastructure/postgres/init
 
 
scripts
scripts
 
 
test/performance
test/performance
 
 
.credo.exs
.credo.exs
 
 
.dialyzer_ignore.exs
.dialyzer_ignore.exs
 
 
.dockerignore
.dockerignore
 
 
.envrc
.envrc
 
 
.formatter.exs
.formatter.exs
 
 
.gitignore
.gitignore
 
 
AGENTS.md
AGENTS.md
 
 
CLAUDE.md
CLAUDE.md
 
 
Dockerfile.agent
Dockerfile.agent
 
 
Dockerfile.core
Dockerfile.core
 
 
Dockerfile.core-standalone
Dockerfile.core-standalone
 
 
PRD.md
PRD.md
 
 
README.md
README.md
 
 
REVIEW.md
REVIEW.md
 
 
bun.lock
bun.lock
 
 
bunfig.toml
bunfig.toml
 
 
devenv.nix
devenv.nix
 
 
devenv.yaml
devenv.yaml
 
 
docker-compose.yml
docker-compose.yml
 
 
docker-dev.sh
docker-dev.sh
 
 
flake.lock
flake.lock
 
 
flake.nix
flake.nix
 
 
mix.exs
mix.exs
 
 
mix.lock
mix.lock
 
 
package.json
package.json
 
 

Repository files navigation

SecretHub

Enterprise-grade Machine-to-Machine secrets management platform

Status: 🚀 v1.0.0-rc9 Released

🎯 Project Overview

SecretHub is a secure, reliable, and highly automated secrets management platform designed specifically for Machine-to-Machine (M2M) communication. Built in Elixir with a HashiCorp Vault-like architecture, it eliminates hardcoded credentials through centralized management, dynamic generation, and automatic rotation.

Core Features

Feature Description
🔐 mTLS Everywhere Mutual TLS for all Core-Agent communications with PKI-issued certificates
🔑 Dynamic Secrets Short-lived credentials for PostgreSQL, Redis, and AWS STS
🔄 Automatic Rotation Oban-scheduled zero-downtime secret rotation
📝 Template Rendering EEx-based secret injection into configuration files
📊 Tamper-Proof Audit SHA-256 hash-chained logs with HMAC signatures
🛡️ Vault Seal/Unseal Shamir's Secret Sharing for master key protection
⚡ High Availability Multi-node deployment with distributed locking
🔓 Auto-Unseal AWS KMS, Azure Key Vault, GCP KMS integrations
🚨 Anomaly Detection Real-time security anomaly detection and alerting
📋 Policy Templates Pre-built policy templates for common use cases

🏗️ Architecture

SecretHub implements a two-tier architecture with a central Core service and distributed Agents:

┌─────────────────────────────────────────────────────────────────────┐
│                        SecretHub Core                                │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐       │
│  │    PKI    │  │  Policy   │  │  Secret   │  │   Audit   │       │
│  │  Engine   │  │  Engine   │  │  Engines  │  │  Logger   │       │
│  │           │  │           │  │           │  │           │       │
│  │ • Root CA │  │ • JSONB   │  │ • Static  │  │ • Hash    │       │
│  │ • Int. CA │  │ • Glob    │  │ • Dynamic │  │   Chain   │       │
│  │ • CSR     │  │   Match   │  │ • Leases  │  │ • HMAC    │       │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘       │
│                                                                      │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐       │
│  │  AppRole  │  │   Vault   │  │  Anomaly  │  │   Apps    │       │
│  │   Auth    │  │ Seal/     │  │ Detection │  │  Manager  │       │
│  │           │  │ Unseal    │  │           │  │           │       │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘       │
│                                                                      │
│              REST API + WebSocket + LiveView Admin                  │
└─────────────────────────────────────────────────────────────────────┘
                              ↕ mTLS WebSocket
┌─────────────────────────────────────────────────────────────────────┐
│                       SecretHub Agent                                │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐       │
│  │ Bootstrap │  │Connection │  │   Cache   │  │  Sinker   │       │
│  │           │  │  Manager  │  │   Layer   │  │           │       │
│  │ • Enroll  │  │           │  │           │  │ • Atomic  │       │
│  │ • CSR Gen │  │ • Reconn  │  │ • TTL     │  │   Write   │       │
│  │ • mTLS ID │  │ • Backoff │  │ • LRU     │  │ • Reload  │       │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘       │
│                                                                      │
│  ┌───────────┐  ┌───────────┐  ┌───────────────────────────┐       │
│  │ Template  │  │  Lease    │  │   Unix Domain Socket API   │       │
│  │ Renderer  │  │ Renewer   │  │   (for local applications) │       │
│  └───────────┘  └───────────┘  └───────────────────────────┘       │
└─────────────────────────────────────────────────────────────────────┘
                              ↕ UDS + mTLS
                    ┌──────────────────────┐
                    │    Applications      │
                    └──────────────────────┘

Agent Lifecycle

  1. Enrollment Phase: Host identity discovery → pending enrollment → operator approval → TLS CSR + SSH host-key proof → certificate issuance
  2. Operational Phase: Core-issued mTLS WebSocket identity → Secret requests → Local caching
  3. Delivery Phase: EEx template rendering → Atomic file writes → Application reload triggers
  4. Local Access: Unix Domain Socket API for application secret retrieval

🔒 Security Architecture

Encryption

Layer Algorithm Details
At Rest AES-256-GCM Per-secret nonces, 128-bit auth tags
Master Key Shamir's Secret Sharing Configurable N shares, K threshold
Key Derivation PBKDF2-SHA256 100,000 iterations

Authentication Flow

┌─────────────┐   pending enrollment     ┌─────────────┐
│   Agent     │ ─────────────────────────▶│    Core     │
│ Enrollment  │   SSH host public key     │  Approval   │
└─────────────┘                           └─────────────┘
       │                                         │
       │       TLS CSR + SSH proof               │
       │ ────────────────────────────────────────▶
       │                                         │
       │       Agent client certificate          │
       │ ◀───────────────────────────────────────│
       │                                         │
       ▼                                         ▼
┌─────────────┐   Core-issued mTLS WS    ┌─────────────┐
│   Agent     │ ◀═══════════════════════▶│    Core     │
│   Runtime   │    certificate identity   │   Runtime   │
└─────────────┘                           └─────────────┘

PKI Hierarchy

  • Root CA: Self-signed, RSA-4096 or ECDSA P-384
  • Intermediate CA: Root-signed, issues client certificates
  • Client Certificates: 1-year validity, auto-renewal 7 days before expiry

🔑 Secret Engines

Static Secrets

  • Encrypted storage with versioning
  • Oban-scheduled rotation
  • Template rendering support

Dynamic Secrets

Engine Description Lease Management
PostgreSQL Temporary users with VALID UNTIL, custom SQL templates Auto-revocation
Redis Dynamic ACL-based credentials Auto-revocation
AWS STS Temporary IAM credentials via AssumeRole TTL-based

🚀 Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/gsmlg-dev/secrethub.git
cd secrethub

# Activate devenv (or use direnv allow)
devenv shell

# Set up the database
db-setup

# Start the development server
server

Available at:

Quick Commands

# Database
db-setup        # Create and migrate database
db-reset        # Reset database (drop, create, migrate, seed)

# Development
server          # Start Phoenix server
console         # Start IEx shell with app loaded

# Testing
mix test                    # Run all tests
mix coveralls.html          # Generate coverage report

# Code Quality
quality         # Run format, credo, dialyzer

📁 Project Structure

secrethub/                              # Elixir Umbrella Application
├── apps/
│   ├── secrethub_core/                 # Core Business Logic
│   │   └── lib/secrethub_core/
│   │       ├── auth/app_role.ex        # AppRole authentication
│   │       ├── pki/ca.ex               # PKI/CA management
│   │       ├── policies.ex             # Policy engine
│   │       ├── policy_templates.ex     # Pre-built policy templates
│   │       ├── apps.ex                 # Application management
│   │       ├── audit.ex                # Hash-chained audit logs
│   │       ├── vault/seal_state.ex     # Seal/unseal with Shamir
│   │       ├── engines/dynamic/        # PostgreSQL, Redis, AWS STS
│   │       ├── auto_unseal/providers/  # AWS KMS, Azure KV, GCP KMS
│   │       ├── anomaly_detection.ex    # Security anomaly detection
│   │       ├── alerting.ex             # Multi-channel alerting
│   │       ├── lease_manager.ex        # Lease lifecycle
│   │       └── rotation_manager.ex     # Oban-scheduled rotation
│   │
│   ├── secrethub_web/                  # Phoenix Web Layer
│   │   └── lib/secrethub_web_web/
│   │       ├── controllers/            # REST API endpoints
│   │       ├── live/admin/             # LiveView admin dashboard
│   │       ├── channels/               # Agent WebSocket channels
│   │       └── plugs/                  # Rate limiter, mTLS verification
│   │
│   ├── secrethub_agent/                # Distributed Agent Daemon
│   │   └── lib/secrethub_agent/
│   │       ├── bootstrap.ex            # Legacy AppRole bootstrap guard
│   │       ├── connection.ex           # WebSocket client with reconnect
│   │       ├── cache.ex                # TTL + LRU secret cache
│   │       ├── sinker.ex               # Atomic file writer
│   │       ├── template_renderer.ex    # EEx template engine
│   │       ├── uds_server.ex           # Unix Domain Socket API
│   │       └── lease_renewer.ex        # Auto lease renewal
│   │
│   └── secrethub_shared/               # Shared Code
│       └── lib/secrethub_shared/
│           ├── schemas/                # 20+ Ecto schemas
│           └── crypto/                 # AES-256-GCM, Shamir
│
├── config/                             # Environment configs
├── infrastructure/                     # IaC
│   └── postgres/                       # PostgreSQL init scripts
└── .github/workflows/                  # CI/CD pipelines

🌐 API Reference

System Endpoints (/v1/sys)

Endpoint Method Description
/v1/sys/init POST Initialize vault with Shamir shares
/v1/sys/seal POST Seal the vault
/v1/sys/unseal POST Unseal vault with key shares
/v1/sys/seal-status GET Get vault seal status
/v1/sys/health GET Health check
/v1/sys/health/ready GET Kubernetes readiness probe
/v1/sys/health/live GET Kubernetes liveness probe

Authentication (/v1/auth)

Endpoint Method Description
/v1/auth/approle/login POST AppRole login
/v1/auth/approle/role GET List all roles
/v1/auth/approle/role/:role_name POST Create AppRole
/v1/auth/approle/role/:role_name DELETE Delete AppRole
/v1/auth/approle/role/:role_name/role-id GET Get Role ID
/v1/auth/approle/role/:role_name/secret-id POST Generate Secret ID

Secrets (/v1/secrets)

Endpoint Method Description
/v1/secrets/:path GET Read secret
/v1/secrets/:path POST Write secret
/v1/secrets/:path DELETE Delete secret
/v1/secrets/dynamic/postgresql/creds/:role POST Generate PostgreSQL credentials
/v1/secrets/dynamic/redis/creds/:role POST Generate Redis credentials
/v1/secrets/dynamic/aws/creds/:role POST Generate AWS STS credentials

PKI (/v1/pki)

Endpoint Method Description
/v1/pki/ca/root/generate POST Generate Root CA
/v1/pki/ca/intermediate/generate POST Generate Intermediate CA
/v1/pki/issue POST Issue certificate
/v1/pki/sign-request POST Sign a CSR
/v1/pki/certificates GET List certificates
/v1/pki/certificates/:id GET Get certificate details
/v1/pki/certificates/:id/revoke POST Revoke certificate
/v1/pki/app/issue POST Issue app certificate (bootstrap)
/v1/pki/app/renew POST Renew app certificate

Applications (/v1/apps)

Endpoint Method Description
/v1/apps GET List applications
/v1/apps POST Register application
/v1/apps/:id GET Get application details
/v1/apps/:id PUT Update application
/v1/apps/:id DELETE Delete application
/v1/apps/:id/suspend POST Suspend application
/v1/apps/:id/activate POST Activate application
/v1/apps/:id/certificates GET List app certificates

Leases (/v1/sys/leases)

Endpoint Method Description
/v1/sys/leases GET List active leases
/v1/sys/leases/stats GET Get lease statistics
/v1/sys/leases/renew POST Renew a lease
/v1/sys/leases/revoke POST Revoke a lease

🖥️ Admin Dashboard

The LiveView-based admin dashboard (/admin) provides:

Core Management

  • Dashboard: System overview, health metrics, quick stats
  • Secrets: Secret browser, version history, bulk operations
  • Policies: Policy editor, entity bindings, simulator
  • Policy Templates: Pre-built templates for common scenarios

Security & PKI

  • PKI: Root/Intermediate CA management, certificate issuance
  • Certificates: Certificate browser, revocation, renewal
  • AppRoles: Role management, secret ID rotation

Infrastructure

  • Agents: Connected agents, status monitoring, health checks
  • Dynamic Engines: PostgreSQL/Redis engine configuration
  • Engine Health: Real-time engine status dashboard
  • Leases: Active lease management, bulk revocation

Operations

  • Audit: Log viewer, search, CSV export
  • Rotations: Rotation schedules, history, manual triggers
  • Templates: Secret template management

Cluster & Monitoring

  • Cluster: Node health, distributed state, deployment status
  • Auto-Unseal: KMS provider configuration
  • Alerts: Alert rules, notification channels
  • Anomalies: Anomaly detection rules, triggered alerts
  • Performance: Performance metrics dashboard

🚨 Anomaly Detection

SecretHub includes a built-in anomaly detection engine with rules for:

Rule Type Description
Failed Logins Detect brute-force authentication attempts
Bulk Deletion Alert on mass secret deletion
Unusual Access Time Detect access outside business hours
Mass Secret Access Alert on abnormal secret read patterns
Credential Export Spike Detect unusual credential generation
Rotation Failures Alert on failed secret rotations
Policy Violations Detect policy bypass attempts

Alert Channels

  • Email notifications
  • Slack webhooks
  • Generic webhooks
  • PagerDuty integration
  • Opsgenie integration

📋 Policy Templates

Pre-built policy templates for common scenarios:

Template Description
business_hours Access restricted to business hours (9-5)
ip_restricted Access limited to specific IP ranges
read_only Read-only access to secrets
emergency_access Break-glass emergency access
dev_environment Development environment access
production_readonly Production read-only access
time_limited Time-limited access with expiration
multi_region Multi-region access policies

🚢 Deployment

Start with the deployment guide for current Core, Agent, and CLI deployment steps. The detailed production runbook and operational checklists live under docs/deployment.

Release Artifacts

Artifact Platforms Includes
secrethub_core-<tag>-linux-*.tar.gz Linux amd64, Linux arm64 Core + Web + Shared
secrethub_agent-<tag>-*.tar.gz Linux, macOS, FreeBSD Agent + Shared
secrethub_agent-<tag>-windows-amd64.zip Windows amd64 Agent + Shared
secrethub_cli Hex.pm package CLI escript

Docker Images

docker pull ghcr.io/gsmlg-dev/secrethub/core:v1.0.0-rc9
docker pull ghcr.io/gsmlg-dev/secrethub/core-standalone:v1.0.0-rc9
docker pull ghcr.io/gsmlg-dev/secrethub/agent:v1.0.0-rc9

Core with external PostgreSQL:

docker run -d -p 4664:4664 \
  -e PHX_SERVER=true \
  -e PORT=4664 \
  -e PHX_HOST=secrethub.example.com \
  -e DATABASE_URL="postgresql://secrethub:password@postgres/secrethub_prod" \
  -e SECRET_KEY_BASE="$(openssl rand -base64 48)" \
  -e SECRET_HUB_CLUSTER_NODE_ID=core-replica-a \
  ghcr.io/gsmlg-dev/secrethub/core:v1.0.0-rc9

Agent:

docker run -d \
  -e SECRET_HUB_AGENT_CORE_URL="https://secrethub.example.com" \
  -v /var/lib/secrethub-agent:/app/.local/state/secrethub/agent \
  -v /var/run/secrethub:/var/run/secrethub \
  ghcr.io/gsmlg-dev/secrethub/agent:v1.0.0-rc9

For production, run migrations before starting Core, expose the trusted Agent mTLS endpoint, and persist Agent state. See docs/deploy.md.

Required Runtime Environment

Service Required
Core PHX_SERVER=true, DATABASE_URL, SECRET_KEY_BASE, PHX_HOST, SECRET_HUB_CLUSTER_NODE_ID
Core trusted Agent endpoint SECRET_HUB_AGENT_ENDPOINT_SERVER=true, endpoint cert/key/CA paths
Agent SECRET_HUB_AGENT_CORE_URL

SECRET_HUB_CLUSTER_NODE_ID must be stable across restarts and unique to each concurrently running Core replica.

🧪 Development Status

✅ Completed Features

  • Umbrella project structure with 4 apps
  • PostgreSQL 16 with UUID, pgcrypto extensions (Unix socket support)
  • AppRole authentication (RoleID/SecretID)
  • Full PKI engine (Root CA, Intermediate CA, CSR)
  • Vault seal/unseal with Shamir's Secret Sharing
  • Policy engine with glob patterns and conditions
  • Policy templates for common scenarios
  • Tamper-evident audit logging (hash chains + HMAC)
  • Dynamic secret engines (PostgreSQL, Redis, AWS STS)
  • Auto-unseal providers (AWS KMS, Azure Key Vault, GCP KMS)
  • Agent bootstrap and mTLS WebSocket connection
  • Secret caching with TTL and LRU eviction
  • Template rendering and atomic file writes
  • Lease management with auto-renewal
  • Oban-scheduled secret rotation
  • Application management system
  • Anomaly detection engine
  • Multi-channel alerting (Email, Slack, PagerDuty, Opsgenie)
  • LiveView admin dashboard (20+ pages)
  • CI/CD with GitHub Actions
  • Multi-arch Docker images (amd64/arm64)
  • Production deployment guide and operational runbooks

📝 Contributing

Commit Convention

type(scope): subject

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat(core): implement AWS STS dynamic secret engine

- Add AssumeRole credential generation
- Implement lease management
- Add integration tests

📄 License

MIT License

🔗 Links

About

SecretHub is a secure, reliable, and highly automated secrets management platform.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages