feat: rewrite pass_mgr with build-time AES key, update pcexec & install
pass_mgr: - Complete rewrite using build-time AES key (injected via ldflags) - New command format: get-secret/get-username --key, set --key --secret - Admin commands: init, handoff, init-from (rejected when AGENT_* env set) - Inline pcguard check for agent commands - Legacy 'get <key>' kept for backward compat - Storage: pc-pass-store/<agent-id>/<key>.gpg with AES-256-GCM - Admin password stored as SHA-256 hash in .pass_mgr/admin.json pcexec.ts: - Support new 'get-secret --key' pattern alongside legacy 'get <key>' - Pass environment to fetchPassword for pcguard validation - Deduplicate matches, sanitize all resolved passwords from output install.mjs: - Generate random 32-byte hex build secret (.build-secret) - Reuse existing secret on rebuilds - Pass to go build via -ldflags -X main.buildSecret=<secret> README.md: - Document new pass_mgr command format - Document admin handoff/init-from workflow - Document security model limitations - Update project structure
This commit is contained in:
97
README.md
97
README.md
@@ -8,26 +8,42 @@
|
||||
|
||||
OpenClaw plugin for secure password management, safe command execution, and coordinated agent restart.
|
||||
|
||||
## ⚠️ Security Model
|
||||
|
||||
> **pcexec + pcguard mitigate light model hallucination / misoperation / prompt forgetting.**
|
||||
> They **do not** defend against malicious attacks.
|
||||
> For stronger security, use **sandbox mode** instead of this plugin.
|
||||
|
||||
## Features
|
||||
|
||||
### 1. pass_mgr — Password Manager (Go)
|
||||
### 1. pass\_mgr — Password Manager (Go)
|
||||
|
||||
AES-256-GCM encryption, per-agent key-based encryption/decryption.
|
||||
AES-256-GCM encryption with a **build-time secret** injected at compile time.
|
||||
Secrets are stored per-agent under `pc-pass-store/<agent-id>/<key>.gpg`.
|
||||
|
||||
**Agent commands** (require pcguard — must run through pcexec):
|
||||
|
||||
```bash
|
||||
pass_mgr admin init # Initialize
|
||||
pass_mgr get <key> # Get password
|
||||
pass_mgr set <key> <password> # Set password (human only)
|
||||
pass_mgr generate <key> # Generate password
|
||||
pass_mgr unset <key> # Delete
|
||||
pass_mgr rotate <key> # Rotate
|
||||
pass_mgr list # List keys for current agent
|
||||
pass_mgr get-secret --key <key> # Output secret
|
||||
pass_mgr get-username --key <key> # Output username
|
||||
pass_mgr set --key <key> --secret <s> [--username <u>] # Set entry
|
||||
pass_mgr generate --key <key> [--username <u>] # Generate random secret
|
||||
pass_mgr unset --key <key> # Delete entry
|
||||
pass_mgr get <key> # Legacy (maps to get-secret)
|
||||
```
|
||||
|
||||
**Admin commands** (human-only — rejected if any `AGENT_*` env var is set):
|
||||
|
||||
```bash
|
||||
pass_mgr admin init # Set admin password (interactive or PC_ADMIN_PASS)
|
||||
pass_mgr admin handoff [file] # Export build secret to file (default: pc-pass-store.secret)
|
||||
pass_mgr admin init-from [file] # Re-encrypt all data from old build secret to current
|
||||
```
|
||||
|
||||
### 2. pcguard — Exec Guard (Go)
|
||||
|
||||
Validates that a process is running inside a pcexec context by checking environment sentinels (`AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE`). Returns exit code 1 with error message if any check fails.
|
||||
|
||||
Scripts can call `pcguard` at the top to ensure they're executed via pcexec:
|
||||
Validates that a process is running inside a pcexec context by checking environment sentinels (`AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE`). Returns exit code 1 if any check fails.
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
@@ -38,7 +54,8 @@ pcguard || exit 1
|
||||
### 3. pcexec — Safe Execution Tool (TypeScript)
|
||||
|
||||
Drop-in replacement for `exec` that:
|
||||
- Resolves `$(pass_mgr get key)` inline and sanitizes passwords from output
|
||||
- Resolves `$(pass_mgr get-secret --key <key>)` and legacy `$(pass_mgr get <key>)` inline
|
||||
- Sanitizes all resolved passwords from stdout/stderr
|
||||
- Injects `AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE` environment variables
|
||||
- Appends `$(openclaw path)/bin` to `PATH` (making `pcguard` and `pass_mgr` available)
|
||||
|
||||
@@ -46,19 +63,6 @@ Drop-in replacement for `exec` that:
|
||||
|
||||
Agent state management and coordinated gateway restart.
|
||||
|
||||
**Agent States:** idle → busy → focus → freeze → pre-freeze
|
||||
|
||||
**APIs:**
|
||||
- `POST /query-restart` — Query restart readiness
|
||||
- `POST /restart-result` — Report restart result
|
||||
- `GET /status` — Get all statuses
|
||||
|
||||
## ⚠️ Security Limitations
|
||||
|
||||
> **PCEXEC + PCGUARD only mitigate light model hallucination / misoperation / prompt forgetting.**
|
||||
> They **do not** defend against malicious attacks.
|
||||
> For stronger security, use **sandbox mode** instead of this plugin.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
@@ -76,8 +80,6 @@ PaddedCell/
|
||||
│ └── src/main.go
|
||||
├── pcguard/ # Go exec guard binary
|
||||
│ └── src/main.go
|
||||
├── docs/ # Documentation
|
||||
├── scripts/ # Utility scripts
|
||||
├── dist/padded-cell/ # Build output
|
||||
├── install.mjs # Installer
|
||||
└── README.md
|
||||
@@ -99,27 +101,46 @@ node install.mjs --build-only
|
||||
node install.mjs --uninstall
|
||||
```
|
||||
|
||||
The installer automatically generates a random 32-byte build secret (stored in `.build-secret`, gitignored) and injects it into `pass_mgr` at compile time. Subsequent builds reuse the same secret.
|
||||
|
||||
### Install paths
|
||||
|
||||
The installer resolves the openclaw base path with this priority:
|
||||
1. `--openclaw-profile-path` CLI argument
|
||||
2. `$OPENCLAW_PATH` environment variable
|
||||
3. `~/.openclaw` (default)
|
||||
Priority: `--openclaw-profile-path` → `$OPENCLAW_PATH` → `~/.openclaw`
|
||||
|
||||
Binaries go to `$(openclaw path)/bin/`, plugin files to `$(openclaw path)/plugins/padded-cell/`.
|
||||
Binaries → `$(openclaw path)/bin/`, plugin files → `$(openclaw path)/plugins/padded-cell/`.
|
||||
|
||||
## Plugin Update Workflow (admin handoff)
|
||||
|
||||
When you rebuild PaddedCell (which generates a new build secret), existing encrypted data needs re-encryption:
|
||||
|
||||
```bash
|
||||
# 1. Before updating — export current build secret
|
||||
~/.openclaw/bin/pass_mgr admin handoff
|
||||
|
||||
# 2. Rebuild & reinstall (generates new .build-secret)
|
||||
rm .build-secret
|
||||
node install.mjs
|
||||
|
||||
# 3. After updating — re-encrypt data with new secret
|
||||
~/.openclaw/bin/pass_mgr admin init-from
|
||||
|
||||
# 4. Restart gateway
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Initialize pass_mgr
|
||||
# Initialize admin password
|
||||
~/.openclaw/bin/pass_mgr admin init
|
||||
|
||||
# Set and get passwords
|
||||
~/.openclaw/bin/pass_mgr set mykey mypassword
|
||||
~/.openclaw/bin/pass_mgr get mykey
|
||||
# Agent sets and gets passwords (via pcexec)
|
||||
pass_mgr set --key myservice --secret s3cret --username admin
|
||||
pass_mgr get-secret --key myservice
|
||||
pass_mgr get-username --key myservice
|
||||
|
||||
# Use pcguard in scripts
|
||||
pcguard || exit 1
|
||||
# Use in shell commands (pcexec resolves and sanitizes)
|
||||
curl -u "$(pass_mgr get-username --key myservice):$(pass_mgr get-secret --key myservice)" https://api.example.com
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Reference in New Issue
Block a user