feat: refactor project structure + add pcguard + AGENT_VERIFY injection
- Restructure: pcexec/ and safe-restart/ → plugin/{tools,core,commands}
- New pcguard Go binary: validates AGENT_VERIFY, AGENT_ID, AGENT_WORKSPACE
- pcexec now injects AGENT_VERIFY env + appends openclaw bin to PATH
- plugin/index.ts: unified TypeScript entry point with resolveOpenclawPath()
- install.mjs: support --openclaw-profile-path, install pcguard, new paths
- README: updated structure docs + security limitations note
- Removed old root index.js and openclaw.plugin.json
This commit is contained in:
152
README.md
152
README.md
@@ -10,128 +10,116 @@ OpenClaw plugin for secure password management, safe command execution, and coor
|
||||
|
||||
## Features
|
||||
|
||||
### 1. pass_mgr - Password Manager Binary (Go)
|
||||
### 1. pass_mgr — Password Manager (Go)
|
||||
|
||||
AES-256-GCM encryption, per-agent key-based encryption/decryption.
|
||||
|
||||
```bash
|
||||
# Initialize
|
||||
pass_mgr admin init [--key-path <path>]
|
||||
|
||||
# Get password
|
||||
pass_mgr get <key> [--username]
|
||||
|
||||
# Generate password (agent can use)
|
||||
pass_mgr generate <key> [--username <user>]
|
||||
|
||||
# Set password (human only)
|
||||
pass_mgr set <key> <password> [--username <user>]
|
||||
|
||||
# Delete password
|
||||
pass_mgr unset <key>
|
||||
|
||||
# Rotate password
|
||||
pass_mgr rotate <key>
|
||||
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
|
||||
```
|
||||
|
||||
**Security Features:**
|
||||
- Agents cannot execute `set` (detected via environment variables)
|
||||
- All operations fail before initialization
|
||||
- Admin password leak detection (monitors messages/tool calls)
|
||||
### 2. pcguard — Exec Guard (Go)
|
||||
|
||||
### 2. pcexec - Safe Execution Tool (TypeScript)
|
||||
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.
|
||||
|
||||
Compatible with OpenClaw native exec interface, automatically handles `pass_mgr get` and sanitizes output.
|
||||
Scripts can call `pcguard` at the top to ensure they're executed via pcexec:
|
||||
|
||||
```typescript
|
||||
import { pcexec } from 'pcexec';
|
||||
|
||||
const result = await pcexec('echo $(pass_mgr get mypassword)', {
|
||||
cwd: '/workspace',
|
||||
timeout: 30000,
|
||||
});
|
||||
// Passwords in result.stdout will be replaced with ######
|
||||
```bash
|
||||
#!/bin/bash
|
||||
pcguard || exit 1
|
||||
# ... rest of script
|
||||
```
|
||||
|
||||
### 3. safe-restart - Safe Restart Module (TypeScript)
|
||||
### 3. pcexec — Safe Execution Tool (TypeScript)
|
||||
|
||||
Provides agent state management and coordinated restart.
|
||||
Drop-in replacement for `exec` that:
|
||||
- Resolves `$(pass_mgr get key)` inline and sanitizes passwords from output
|
||||
- Injects `AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE` environment variables
|
||||
- Appends `$(openclaw path)/bin` to `PATH` (making `pcguard` and `pass_mgr` available)
|
||||
|
||||
**Agent States:**
|
||||
- `idle` - Idle
|
||||
- `busy` - Processing messages
|
||||
- `focus` - Focus mode (workflow)
|
||||
- `freeze` - Frozen (not accepting new messages)
|
||||
- `pre-freeze` - Preparing to freeze
|
||||
- `pre-freeze-focus` - Preparing to freeze (focus mode)
|
||||
### 4. safe-restart — Coordinated Restart (TypeScript)
|
||||
|
||||
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
|
||||
- `POST /query-restart` — Query restart readiness
|
||||
- `POST /restart-result` — Report restart result
|
||||
- `GET /status` — Get all statuses
|
||||
|
||||
**Slash Commands:**
|
||||
```
|
||||
/padded-cell-ctrl status
|
||||
/padded-cell-ctrl enable pass-mgr|safe-restart
|
||||
/padded-cell-ctrl disable pass-mgr|safe-restart
|
||||
```
|
||||
## ⚠️ 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
|
||||
|
||||
```
|
||||
PaddedCell/
|
||||
├── pass_mgr/ # Go password manager binary
|
||||
│ ├── src/
|
||||
│ │ └── main.go
|
||||
│ └── go.mod
|
||||
├── pcexec/ # TypeScript safe execution tool
|
||||
│ ├── src/
|
||||
│ │ └── index.ts
|
||||
├── plugin/ # Plugin source (TypeScript)
|
||||
│ ├── commands/ # Slash commands
|
||||
│ ├── core/ # Core modules (safe-restart, status, api)
|
||||
│ ├── hooks/ # Lifecycle hooks
|
||||
│ ├── tools/ # Tool definitions (pcexec)
|
||||
│ ├── index.ts # Plugin entry point
|
||||
│ ├── openclaw.plugin.json
|
||||
│ ├── package.json
|
||||
│ └── tsconfig.json
|
||||
├── safe-restart/ # TypeScript safe restart module
|
||||
│ ├── src/
|
||||
│ │ ├── index.ts
|
||||
│ │ ├── status-manager.ts
|
||||
│ │ ├── api.ts
|
||||
│ │ ├── safe-restart.ts
|
||||
│ │ └── slash-commands.ts
|
||||
│ ├── package.json
|
||||
│ └── tsconfig.json
|
||||
├── docs/ # Documentation
|
||||
├── PROJECT_PLAN.md # Project plan
|
||||
├── AGENT_TASKS.md # Task list
|
||||
├── README.md # This file (English)
|
||||
└── README.zh-CN.md # Chinese version
|
||||
├── pass_mgr/ # Go password manager binary
|
||||
│ └── 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
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Install
|
||||
node install.mjs --install
|
||||
# Install (default: ~/.openclaw)
|
||||
node install.mjs
|
||||
|
||||
# Install with custom openclaw profile path
|
||||
node install.mjs --openclaw-profile-path /path/to/.openclaw
|
||||
|
||||
# Build only (no install)
|
||||
node install.mjs --build-only
|
||||
|
||||
# Uninstall
|
||||
node install.mjs --uninstall
|
||||
```
|
||||
|
||||
### 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)
|
||||
|
||||
Binaries go to `$(openclaw path)/bin/`, plugin files to `$(openclaw path)/plugins/padded-cell/`.
|
||||
|
||||
## Usage
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
### pass_mgr
|
||||
|
||||
```bash
|
||||
# Initialize (required before first use)
|
||||
# Initialize pass_mgr
|
||||
~/.openclaw/bin/pass_mgr admin init
|
||||
|
||||
# Set password
|
||||
# Set and get passwords
|
||||
~/.openclaw/bin/pass_mgr set mykey mypassword
|
||||
|
||||
# Get password
|
||||
~/.openclaw/bin/pass_mgr get mykey
|
||||
|
||||
# Use pcguard in scripts
|
||||
pcguard || exit 1
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Reference in New Issue
Block a user