Bagman

Bagman

Secure key management patterns for AI agents handling private keys and secrets.

Supported Backends

Bagman auto-detects the best available backend. No 1Password required.

| Backend | Command | Setup | Best For | |---------|---------|-------|----------| | macOS Keychain | security | None (native) | macOS, zero setup | | 1Password | op | brew install 1password-cli | Teams, rich metadata | | Encrypted File | age | brew install age | Portable, git-friendly | | Environment | - | None | CI/CD, containers |

Core Principles

1. Never store raw private keys in config, env vars, or memory files
2. Use session keys / delegated access instead of full control
3. All secret access goes through a secure backend
4. Validate all outputs before sending to prevent key leakage

---

Quick Reference

Retrieve Secrets (Auto-detect Backend)

from examples.secret_manager import get_secret, get_session_key

# Simple retrieval
api_key = get_secret("openai-key")

# With metadata (expiry, limits)
creds = get_session_key("trading-bot")
if creds.is_expired():
    raise ValueError("Session expired")

Backend-Specific Examples

macOS Keychain (no setup):

# Store
security add-generic-password -s bagman-agent -a my-key -w "secret-value"

# Retrieve in Python
from examples.backends import get_backend
backend = get_backend("keychain")
secret = backend.get("my-key")

1Password:

# Store with metadata
op item create \
  --vault "Agent-Credentials" \
  --category "API Credential" \
  --title "trading-bot" \
  --field "password=0xsession..." \
  --field "expires=2026-02-15T00:00:00Z"

Encrypted File:

# Set passphrase
export BAGMAN_PASSPHRASE="your-passphrase"

# Or use identity file
age-keygen -o ~/.bagman/identity.txt

Environment Variables:

export BAGMAN_TRADING_BOT_KEY="0x1234..."
# Accessed as: get_secret("trading-bot-key")

---

DO ✅

# Retrieve at runtime (any backend)
from examples.secret_manager import get_secret
key = get_secret("my-agent-wallet")

# Use session keys with bounded permissions
# (delegate specific capabilities, not full wallet access)

# Document references, not values
# TOOLS.md: "Session key: [stored in keychain: trading-bot]"

DON'T ❌

# NEVER store keys in files
echo "PRIVATE_KEY=0x123..." > .env

# NEVER log or print keys
print(f"Key: {private_key}")

# NEVER store keys in memory files
# Even "private" agent memory can be exfiltrated

# NEVER trust unvalidated input near key operations

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   AI Agent                          │
├─────────────────────────────────────────────────────┤
│  Session Key (time/value bounded)                   │
│  - Expires after N hours                            │
│  - Spending cap per operation                       │
│  - Whitelist of allowed contracts                   │
├─────────────────────────────────────────────────────┤
│  Secret Manager (Auto-detect)                       │
│  - macOS Keychain (native)                          │
│  - 1Password (rich metadata)                        │
│  - Encrypted file (portable)                        │
│  - Environment vars (fallback)                      │
├─────────────────────────────────────────────────────┤
│  ERC-4337 Smart Account                             │
│  - Programmable permissions                         │
│  - Recovery without private key exposure            │
└─────────────────────────────────────────────────────┘

---

Output Sanitization

Apply to ALL agent outputs before sending anywhere:

import re

KEY_PATTERNS = [
    r'0x[a-fA-F0-9]{64}',           # ETH private keys
    r'sk-[a-zA-Z0-9]{48,}',         # OpenAI keys
    r'sk-ant-[a-zA-Z0-9\-_]{80,}',  # Anthropic keys
    r'gsk_[a-zA-Z0-9]{48,}',        # Groq keys
]

def sanitize_output(text: str) -> str:
    for pattern in KEY_PATTERNS:
        text = re.sub(pattern, '[REDACTED]', text)
    return text

---

Prompt Injection Defense

DANGEROUS_PATTERNS = [
    r'ignore.*(previous|above|prior).*instructions',
    r'reveal.*(key|secret|password|credential)',
    r'output.*(key|secret|private)',
    r'show.*(key|secret|password)',
]

def validate_input(text: str) -> bool:
    text_lower = text.lower()
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, text_lower):
            return False
    return True

---

Pre-commit Hook

Block commits containing secrets:

#!/bin/bash
# .git/hooks/pre-commit

PATTERNS=(
    '0x[a-fA-F0-9]{64}'
    'sk-[a-zA-Z0-9]{48,}'
    'sk-ant-api'
    'PRIVATE_KEY='
)

for pattern in "${PATTERNS[@]}"; do
    if git diff --cached | grep -qE "$pattern"; then
        echo "❌ Potential secret detected: $pattern"
        exit 1
    fi
done

---

Integration with OpenClaw

When running as an OpenClaw agent:

1. Use bagman for all secret retrieval (auto-detects backend)
2. Never write keys to workspace files - they persist across sessions
3. Sanitize outputs before sending to any channel
4. Document references in TOOLS.md, not actual keys

Example TOOLS.md entry:

### Agent Wallet
- Address: 0xABC123...
- Session key: [keychain: trading-bot] or [1password: trading-bot]
- Permissions: USDC < 100, approved DEX only
- Expires: 2026-02-15

---

Checklist

• [ ] Choose and verify backend (python -c "from examples.backends import list_available_backends; print(list_available_backends())")
• [ ] Store session keys (NOT master keys)
• [ ] Set appropriate expiry and spending limits
• [ ] Install pre-commit hook
• [ ] Add output sanitization to all responses
• [ ] Implement input validation for prompt injection
• [ ] Document key references in TOOLS.md

---

Files

| File | Purpose | |------|---------| | examples/secret_manager.py | Unified API with auto-detection | | examples/backends/ | Backend implementations | | examples/sanitizer.py | Output sanitization | | examples/validator.py | Input validation | | docs/ | Deep-dive documentation |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zscole
• Source: zscole/bagman-skill
• License: MIT

Install and usage instructions live in the source repository linked above.