Credential Vault

Encrypted credential storage for OpenClaw agents. Stop storing API keys in plaintext.

Security Scan

The skill is a coherent local encrypted vault implementation, but there are mismatches and risky behaviors (declared primary env var unused, session key persisted to disk without explicit hardening, and the docs include examples that encourage storing the master password in plaintext for automation).

Purpose & Capability

The code and SKILL.md implement a local AES-256-GCM encrypted vault as described (CRUD, audit, expiry, env export). Required binary 'uv' and local storage paths are consistent with the stated purpose. However the package metadata declares a primary credential name (VAULT_MASTER_PASSWORD) while the CLI implementation expects interactive entry (getpass) and does not read that environment variable — this is an inconsistency that could confuse usage or expectations about non-interactive unlocking.

Instruction Scope

Runtime instructions and code operate only on local files under ~/.openclaw/vault and do not perform network access (matches the 'local only' claim). However the documentation includes explicit insecure automation examples (storing the master password in plaintext and piping it to unlock in a cron job). The CLI writes a session key file to disk for session reuse — the SKILL.md warns about persistence but provides no secure automation alternatives. These guidance and behaviors expand scope into patterns that can leak the master key if used carelessly.

Install Mechanism

This is instruction-only from the registry perspective (no formal install spec); code files are present and the README instructs users to run 'uv sync' and 'uv run' to use the CLI. There are no remote downloads or obscure URLs in the manifest; dependencies are standard (cryptography). Risk from install mechanism is low, but the absence of an explicit install spec combined with reliance on 'uv' means runtime behavior depends on that package manager/environment.

Credentials

The skill declares VAULT_MASTER_PASSWORD as the primary credential in metadata, but the implementation exclusively prompts for the master password via getpass and does not consume that environment variable. No other unrelated credentials are requested. Declaring a primaryEnv that the code doesn't use is an incoherence and could mislead users into exporting their master password as an env var (a risky practice).

Persistence & Privilege

The vault writes a session key file (~/.openclaw/vault/session) to disk to support multi-command sessions. The code does not explicitly set file permissions on the session file (only on the vault file). This means the session key could persist across reboots or be left with default permissions depending on umask, increasing attack surface. The skill does not request elevated or cross-skill privileges and always:false, but the session-file behavior and the provided cron examples increase risk if followed.

What to consider before installing

This skill largely does what it says (a local encrypted vault), but a few things don't add up or are risky: 1) the metadata lists VAULT_MASTER_PASSWORD as the primary credential but the CLI always prompts interactively — don't assume you can safely set your master password in an env var to automate unlocks; 2) the vault stores a raw session key to ~/.openclaw/vault/session without explicitly hardening that file — consider inspecting/modifying the code to chmod the session file to 0600 or avoid writing the session key to disk; 3) the docs include an example that stores the master password in plaintext for cron jobs — treat that as unsafe and prefer more secure automation (OS keyring, dedicated secrets manager, or short-lived service credentials for CI); 4) review the code yourself (or run tests in an isolated environment) before using it for high-value secrets. If you want to proceed, at minimum: audit and patch session-file permissions, remove/avoid examples that write plaintext master passwords, and consider adding support for secure non-interactive unlocking (e.g., OS keyring) rather than env vars or plaintext files.

Encrypted credential storage for OpenClaw agents. Stop storing API keys in plaintext.

Overview

Credential Vault provides AES-256-GCM encrypted local storage for API keys, tokens, and other secrets. Instead of scattering credentials across .env files, centralize them in an encrypted vault with audit logging and expiry tracking.

Features

• AES-256-GCM encryption with PBKDF2 key derivation (600,000 iterations)
• CRUD operations for credentials
• Tag-based organization (by skill, project, etc.)
• Environment variable injection for easy integration
• Expiry tracking with notifications
• Audit logging (who accessed what, when)
• Session-based unlocking (no password re-entry)

Installation

cd ~/ubik-collective/systems/ubik-pm/skills/credential-vault
uv sync

Quick Start

# Initialize vault (one-time setup)
uv run vault init

# Unlock vault
uv run vault unlock

# Add credentials
uv run vault add OPENAI_API_KEY "sk-..." --tag openai
uv run vault add TAVILY_API_KEY "tvly-..." --tag tavily --expires 2026-12-31

# List credentials
uv run vault list

# Get a credential
uv run vault get OPENAI_API_KEY

# Export for a skill
eval $(uv run vault env --tag tavily)

# Lock when done
uv run vault lock

Security Model

Encryption

• Master password → PBKDF2-SHA256 (600,000 iterations) → 256-bit key
• Each secret encrypted with AES-256-GCM (unique nonce per entry)
• Authentication tags verify integrity
• Master password never stored (only verification hash)

Storage

• Vault: ~/.openclaw/vault/vault.enc.json (encrypted)
• Audit log: ~/.openclaw/vault/audit.log (plaintext, no values)
• Session key: ~/.openclaw/vault/session (temporary, cleared on lock)

Permissions

• Vault file: 0600 (owner read/write only)
• Session key: deleted on vault lock

Threat Model

Protects against:

• ✅ Accidental credential leaks (git commits, logs)
• ✅ Casual file browsing
• ✅ Malware reading .env files

Does NOT protect against:

• ❌ Keyloggers (can capture master password)
• ❌ Root-level system compromise
• ❌ Memory dumps while vault is unlocked

Usage Examples

See EXAMPLE.md for detailed usage patterns.

Commands

vault init

Initialize a new vault with a master password.

vault unlock

Unlock the vault for the current session.

vault lock

Lock the vault and clear session key.

vault status

Show vault status (locked/unlocked, credential count).

vault add KEY_NAME [VALUE] [--tag TAG] [--expires DATE]

Add or update a credential. If VALUE is omitted, prompts securely.

vault get KEY_NAME

Retrieve and decrypt a credential.

vault list [--tag TAG]

List all credentials (values masked). Optionally filter by tag.

vault remove KEY_NAME [-y]

Remove a credential. Prompts for confirmation unless -y is passed.

vault env [--tag TAG]

Export credentials as KEY=VALUE for environment injection.

Example:

eval $(uv run vault env --tag openai)
echo $OPENAI_API_KEY  # Now available

vault audit [--last N]

View recent audit log entries.

vault expiring [--days N]

Check for credentials expiring within N days (default: 7).

vault rotate KEY_NAME [NEW_VALUE]

Replace a credential with a new value (preserves tags/metadata).

Integration with Skills

Pattern: Inject credentials before running a skill

# Tavily search skill
eval $(uv run vault env --tag tavily)
uv run scripts/search.py "OpenClaw release date"

Pattern: Skill checks vault directly

from lib.store import Store

store = Store()
# Assumes vault is unlocked by user beforehand
api_key = store.get("TAVILY_API_KEY")

Pattern: Auto-unlock in HEARTBEAT.md

# HEARTBEAT.md
Check if vault is locked. If so, prompt user to unlock before running daily checks.

Best Practices

1. Use tags consistently — Tag credentials by skill name for easy filtering
2. Set expiry dates — Track when API keys need rotation
3. Lock when idle — Run vault lock when not actively using credentials
4. One vault per machine — Don't sync the vault file across machines
5. Rotate regularly — Use vault expiring to track upcoming expirations
6. Review audit logs — Check vault audit periodically

Limitations

• Local only — No network sync (by design)
• Single-user — No multi-user access control
• No backup — User responsible for backing up ~/.openclaw/vault/
• Session key on disk — vault unlock stores decryption key until vault lock

Troubleshooting

"Vault is locked"

Run uv run vault unlock and enter your master password.

"Incorrect master password"

Double-check your password. If forgotten, you'll need to reinitialize (losing all credentials).

"Vault not initialized"

Run uv run vault init to create a new vault.

Session key persists after reboot

Session file is cleared on vault lock, but not automatically on reboot. Run vault lock explicitly.

Development

Run tests

uv run pytest

Add a test

See tests/test_roundtrip.py for examples.

License

MIT-0 (public domain equivalent)