Vault Admin

🔐 Professional web console for HashiCorp Vault KV v2 secret management. Browse, edit, search, audit, and restore secrets with a modern, intuitive interface — no terminal required after setup.

Designed for: DevOps engineers, platform teams, and Vault administrators who need a reliable local UI for daily secret management.

🚀 Quick Start

# Install globally (requires Node.js ≥ 20)
npm install -g vault-admin

# Launch — browser opens automatically
vault-admin

# Optional: install as a background service (no terminal needed)
vault-admin --install-service

The UI opens automatically at http://localhost:3001.
Config and audit logs persist in ~/.vault-kv-ui/.

Environment Setup

# Pre-configure your Vault address
VAULT_ADDR=https://vault.company.com vault-admin

# Or provide a token to skip OIDC login
VAULT_ADDR=https://vault.company.com \
VAULT_TOKEN=hvs.xxxxxx \
vault-admin

# Use a different port
BFF_PORT=4000 vault-admin

✨ Features

🔍 Secret Browser

• Navigate KV folders with breadcrumb trail and history
• View secrets in a clean key/value table with inline key deletion
• Edit secrets with full before/after diff preview (form or paste-JSON mode)
• Create secrets with intelligent namespace-based presets
• Delete individual secrets or entire folder trees with selective checkboxes
• Download any path or mount as a single JSON file
• Auto-hide empty secrets with a one-click reveal toggle

🔎 Global Search

Press Ctrl+K (or use the search bar) to open the full-power search modal.

• Search by path — find secrets whose path matches a term
• Search by key — find secrets containing a matching key name (default)
• Search by value — find secrets whose values contain a term (scans all keys, including nested JSON)
• Path scope — restrict the search to a subtree (e.g. project/staging); leave empty to search the entire mount
• Result count & stats — always shows N result(s), secrets scanned, and elapsed time
• Highlighted matches — matched terms highlighted in amber in results
• Masked values — matched values shown as •••••• with a per-key eye toggle and global show/hide all
• Click to navigate — clicking a result opens the secret AND navigates the browser to its parent folder
• Search history — last 8 queries remembered (localStorage); searchable from both the modal and the inline bar

⚙️ Bulk Operations

All bulk actions exclude production paths by default (configurable).

| Operation | Use Case | |---|---| | Feature Flag | Apply a flag to many secrets at once | | Find & Replace | Update a key's value across multiple paths | | Adjust Values | Modify a key path-by-path with per-secret overrides | | Rename Keys | Fix misnamed keys in bulk | | Remove Keys | Delete a key from matching secrets | | Batch Edit | Edit multiple secret JSONs with unified diff preview |

🔐 Multi-Namespace & Authentication

• Switch namespaces at runtime; each maintains its own token
• OIDC login — complete browser-based Vault OIDC flow (no CLI required)
• Token resolution — in-memory store → env vars → ~/.env file
• Admin mode — read-only toggle, logging controls, user-friendly audit trail

📊 Admin Dashboard

• Stats — total/daily writes, logins, failures (namespace-scoped)
• Audit log — complete write/delete/login history with before/after diffs
• Restore — one-click rollback of any write or deletion
• Settings — disable editing globally, toggle event logging
• Persistence — auto-save on namespace switch; manual save; local JSON export
• Vault export — write audit session as readable secret in Vault

🔔 Update Notifier

• A badge appears in the footer when a newer version is published to npm
• Click it to open an update guide with the exact command for your OS (macOS/Linux or Windows)
• The check is cached for 1 hour; a startup banner is also printed in the terminal

🖥️ Background Service (no terminal required)

Run Vault Admin silently in the background, starting automatically at login:

# Install the service
vault-admin --install-service

# Remove the service
vault-admin --uninstall-service

| Platform | Method | Launcher | |---|---|---| | Linux | systemd --user service | .desktop entry in app launcher (GNOME, KDE…) | | macOS | launchd user agent | Open http://localhost:3001 or drag to Dock | | Windows | Task Scheduler (at logon) | Desktop + Start Menu .url shortcuts |

🌐 User Interface

• Dark theme optimized for extended use
• Keyboard shortcuts — Ctrl+K global search, arrow keys for breadcrumbs, Ctrl/Cmd+S to save
• Responsive design — works on desktop and tablet

📋 Requirements

• Node.js ≥ 20 (LTS or latest)
• HashiCorp Vault 1.13+ with KV v2 and OIDC auth enabled

📦 Installation

Global (Recommended)

npm install -g vault-admin
vault-admin

As a Background Service

npm install -g vault-admin
vault-admin --install-service
# Vault Admin now starts automatically at login — no terminal needed

To remove:

vault-admin --uninstall-service

Local Development

git clone https://github.com/ismailhac/vault-kv-ui.git
cd vault-kv-ui
npm install && npm install --prefix app
npm run dev

Open http://localhost:5173 in your browser.

🖥️ CLI Reference

Usage: vault-admin [options]

Options:
  --install-service    Install as a background service (auto-starts at login)
  --uninstall-service  Remove the background service
  --version, -v        Print version and exit
  --help, -h           Show this help

Environment:
  BFF_PORT             Port to listen on (default: 3001)
  VAULT_ADDR           Vault server URL
  VAULT_TOKEN          Default Vault token

⚙️ Configuration

Environment Variables

| Variable | Default | Description | |---|---|---| | VAULT_ADDR | (none) | Your Vault server URL (e.g., https://vault.company.com) | | VAULT_TOKEN | (none) | Pre-set token to skip OIDC login | | VAULT_NAMESPACE | (none) | Default namespace on startup | | BFF_PORT | 3001 | Backend server port | | OIDC_CALLBACK_PORT | 8250 | Local OIDC callback server port | | LOGS_FILE | ~/.vault-kv-ui/audit-logs.json | Audit log persistence path |

Adding Namespaces

Launch the app and use the Setup Wizard to add Vault namespaces via the UI. They're stored in ~/.vault-kv-ui/config.json.

Or pre-configure in your shell:

export VAULT_ADDR=https://vault.company.com
export VAULT_NAMESPACE=org/team/my-namespace
vault-admin

🏗️ Architecture

┌─────────────────────┐
│   Browser UI        │  Vue 3 + TypeScript + Pinia
│  (localhost:3001)   │  served as static files by BFF
└──────────┬──────────┘
           │ /api/* →
┌──────────▼──────────┐
│  BFF Server         │  Express.js (ESM, single file)
│  (localhost:3001)   │  • Token management
└──────────┬──────────┘  • Vault proxying
           │ ←HTTP→      • Audit logging
┌──────────▼──────────┐  • OIDC orchestration
│  HashiCorp Vault    │  • Global search (path/key/value)
│  (KV v2 + OIDC)     │
└─────────────────────┘

• Frontend — Single-page Vue app with centralized Pinia state
• Backend — Single Express file handling all Vault proxying, auth, logging, and search
• Persistence — ~/.vault-kv-ui/config.json (settings), ~/.vault-kv-ui/audit-logs.json (logs)

🛠️ Development

npm run dev          # Start BFF + Vite dev server (recommended)
npm run bff          # BFF only (port 3001)
npm run ui           # Vite dev server only (port 5173)
npm run build        # Type-check + production build

See CONTRIBUTING.md for development guidelines and contribution process.

📝 Changelog

See CHANGELOG.md for release notes and version history.

🔒 Security

Vault Admin is a local development tool designed for single-user workstations in trusted environments.

• Localhost-only — BFF binds to 127.0.0.1 by default
• No per-user auth — whoever runs the CLI has full access
• Audit logging — all operations logged to persistent JSON
• Token management — tokens cached in-memory and ~/.vault-kv-ui/
• Value masking — search results mask secret values by default (eye toggle to reveal)

For security disclosures, email [email protected] instead of opening a public issue.

See SECURITY.md for detailed security considerations.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Code style guidelines
• Release process
• Bug reporting

📄 License

MIT © Ismail

💡 Use Cases

• Local secret inspection — quickly view and search secrets without Vault CLI
• Value search — find which secret contains a specific API key or password
• Testing & development — safely edit/restore test environment secrets
• Onboarding — familiar UI for new team members to understand secret structure
• Bulk operations — rename keys, apply flags, or adjust values across namespaces
• Audit trail — full before/after history with restore capability
• Configuration rotation — update database passwords, API keys, certificates in bulk
• Always-on access — install as a service; open http://localhost:3001 from any app

Questions? Open an issue on GitHub.