diff --git a/docs/gitbook/openclaw-keeper-commander-skill-overview.md b/docs/gitbook/openclaw-keeper-commander-skill-overview.md new file mode 100644 index 0000000..251ace5 --- /dev/null +++ b/docs/gitbook/openclaw-keeper-commander-skill-overview.md @@ -0,0 +1,150 @@ +# OpenClaw × Keeper Commander CLI — Skill implementation overview + +This page describes how a **Keeper Commander** capability is packaged as an **OpenClaw skill** so local agents can manage vaults, enterprise administration, and privileged access safely and consistently. + +--- + +## Purpose + +**Keeper Commander** (`keeper`) is Keeper Security’s full-featured CLI and shell for vault operations, enterprise admin, KeeperPAM, KSM application management, and automation. **OpenClaw skills** are reusable instruction bundles (Markdown with structured front matter) that teach an agent *when* to use a tool, *which* commands apply, and *what* guardrails must hold. + +Together, a Commander-focused skill lets OpenClaw delegate complex Keeper workflows without hard-coding Keeper logic into the agent’s core prompt. + +--- + +## How OpenClaw loads skills (context) + +OpenClaw discovers skills from several locations (highest precedence first): + +1. **Workspace skills** — e.g. `/skills` (per-agent or per-project) +2. **Managed / local skills** — typically `~/.openclaw/skills` +3. **Bundled skills** — shipped with the OpenClaw install + +Additional directories may be configured (for example via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). When the same skill name exists in more than one place, **workspace wins**, then managed/local, then bundled. + +Skills are usually distributed via **ClawHub** (`clawhub install …`) or copied from a trusted private repository. Treat third-party skills as **untrusted code**: review source, permissions, and behavior before installation. + +--- + +## What the Keeper Commander skill teaches the agent + +A well-designed Commander skill encodes: + +| Concern | What the skill specifies | +| --- | --- | +| **Triggering** | When to prefer Commander vs other tools (e.g. KSM-only secret injection). | +| **Prerequisites** | Python version, `pip install keepercommander`, optional `tmux`, account permissions. | +| **Workflow** | Order of operations: verify CLI, confirm auth, search metadata before reads, avoid leaking secrets. | +| **Command surface** | Pointers to a command reference and official Keeper docs; use of `keeper --help` / subcommand help. | +| **Interactive execution** | How to preserve login, MFA, and shell context across agent tool invocations (see below). | +| **Guardrails** | No passwords on the command line, confirm destructive actions, redirect runtime secret injection to KSM patterns. | + +Official Commander documentation: [Commander CLI overview](https://docs.keeper.io/en/keeperpam/commander-cli/overview). + +--- + +## Skill bundle layout (implementation shape) + +A minimal skill directory looks like: + +```text +skills/keeper-admin/ # or ~/.openclaw/skills/keeper-admin/ +├── SKILL.md # Primary instructions + YAML front matter (name, description) +└── references/ # Optional deep references + ├── commander-commands.md + ├── enterprise-mgmt.md + ├── pam-commands.md + └── … +``` + +- **`SKILL.md` (or `skill.md`)** — YAML front matter (`name`, `description`) plus narrative instructions the model follows when the skill is active. +- **`references/`** — Long command lists and scenarios kept out of the main file so the agent loads detail only when needed. + +OpenClaw’s ecosystem often uses `skill.md`; Cursor and other agents may expect `SKILL.md`. Use the filename your host expects, or provide both if you support multiple runtimes. + +--- + +## Critical implementation detail: interactive Commander and `tmux` + +Agent shell tools often allocate a **fresh TTY per command**. Keeper Commander, however, relies on **interactive sessions**, **MFA**, and **persistent device login** in many setups. + +The recommended pattern in the skill is: + +1. Create a **dedicated `tmux` session** with a predictable **socket path** (optionally overridden by an environment variable such as `TMUX_SOCKET_DIR`). +2. Start `keeper shell` (or `keeper-commander shell`) inside that session. +3. **Drive** the session with `send-keys` and **read** output with `capture-pane`. + +This preserves authentication context and matches how human operators run Commander over SSH or long-lived terminals. + +Example variables (conceptual): + +- `SOCKET_DIR` — defaults under `${TMPDIR:-/tmp}/keeper-tmux-sockets` unless overridden. +- `SOCKET` — e.g. `keeper-commander.sock` under that directory. +- `SESSION` — unique session name per auth flow (e.g. timestamped `keeper-auth-…`). + +The skill should document **how to tear down** the session when work is done, unless the user explicitly wants a persistent shell. + +--- + +## Commander vs Keeper Secrets Manager (routing) + +The skill should steer the agent clearly: + +| User need | Preferred path | +| --- | --- | +| Enterprise users, teams, roles, nodes | Commander | +| KSM application / client device lifecycle | Commander | +| Password rotation configuration, PAM gateways, remote connect | Commander | +| Interactive vault browsing, batch files, API server mode | Commander | +| **Runtime** secret fetch / env injection for apps | **KSM** (`ksm`) — separate skill | + +This split avoids giving application-style automation a full interactive vault session when KSM is the right tool. + +--- + +## Security and compliance (skill-level) + +Document explicitly in the skill: + +1. **Never** pass master passwords, API tokens, or vault field values on the command line or in URLs (process listing and shell history). +2. Prefer **interactive login**, **persistent device login**, or **documented** non-interactive patterns from Keeper’s official docs—not ad-hoc scripting. +3. **Do not** echo secret field values into chat unless the user explicitly requests it for debugging—and warn first. +4. Require **user confirmation** before destructive enterprise or vault operations. +5. **Supply-chain**: pin or review the Git revision of the skill; prefer installs from a known organization (e.g. Keeper Security’s agent kit) over unvetted ClawHub uploads. + +--- + +## Installing this skill on OpenClaw + +High-level steps: + +1. Install **OpenClaw CLI** and (if you use it) **ClawHub** per your deployment. +2. Install **Keeper Commander** (`pip install keepercommander`) on the same machine or container where the agent runs shell commands. +3. Copy or install the skill into **`/skills`** (workspace-highest precedence) or **`~/.openclaw/skills`** (shared on the host), following OpenClaw’s precedence rules. +4. Configure **minimum** filesystem and network permissions for the agent user. +5. Run a **smoke test**: `keeper version`, then interactive login in the documented `tmux` pattern, then a non-destructive command such as `whoami` in the Commander shell. + +--- + +## Related reading + +- [OpenClaw skills (conceptual overview)](https://www.digitalocean.com/resources/articles/what-are-openclaw-skills) — skill format, ClawHub, security considerations. +- [Keeper Commander CLI](https://docs.keeper.io/en/keeperpam/commander-cli/overview) — installation, shell, batch mode. +- [Keeper Security Agent Kit](https://github.com/Keeper-Security/keeper-agent-kit) — maintained `keeper-admin`, `keeper-secrets`, and `keeper-setup` skill plugins for multiple agent platforms. + +--- + +## GitBook navigation hint + +Suggested placement under your GitBook space: + +- **Parent**: Integrations → OpenClaw +- **Siblings**: Skill authoring, ClawHub policy, deployment hardening +- **Child pages**: Commander command reference, KSM skill overview, tmux runbook + +Add this file to `SUMMARY.md` as needed, for example: + +```markdown +* [OpenClaw](openclaw/README.md) + * [Keeper Commander skill overview](openclaw-keeper-commander-skill-overview.md) +``` diff --git a/plugins/keeper-admin/skills/keeper-admin/SKILL.md b/plugins/keeper-admin/skills/keeper-admin/SKILL.md index 2501bc2..cd4d114 100644 --- a/plugins/keeper-admin/skills/keeper-admin/SKILL.md +++ b/plugins/keeper-admin/skills/keeper-admin/SKILL.md @@ -35,9 +35,56 @@ breadth of vault, enterprise, and PAM operations. 1. Python 3.10+ 2. Install: `pip install keepercommander` 3. A Keeper account with appropriate admin permissions +4. Tmux Check installation: `keeper version` + + +## Workflow + +1. Use `references/commander-commands.md` for interacting with Keeper commander, Use `--help` for getting more information for the command. +2. Verify the session is opened via interactive tmux session. +3. Verify available binaries in related python environments: + - `keeper --help` + - `ksm --help` +4. Confirm session or auth state before any secret read. +5. Check login status using whoami, if not logged in, complete login process and then continue rest flow. +6. ALAWYS ask the user inputs for REQUIRED fields, DONT GUESS REQUIRED fields. +7. Search or inspect metadata first, then retrieve only the exact requested field, do not expose any sensitive data. +8. Prefer secret injection or one-command environment scoping over writing secrets to disk. +9. If syntax differs from expectation, fall back to `--help` and Keeper docs immediately. +10. ALWAYS ask confirmation from users for any delete operations. + + +## REQUIRED tmux session + +The shell tool uses a fresh TTY per command. To preserve Keeper interactive context, authentication state, and MFA prompts, run interactive Keeper commands or secrets manager command inside a dedicated tmux session. + + +Example pattern: + +```bash +SOCKET_DIR="${TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/keeper-tmux-sockets}" +mkdir -p "$SOCKET_DIR" +SOCKET="$SOCKET_DIR/keeper-commander.sock" +SESSION="keeper-auth-$(date +%Y%m%d-%H%M%S)" + +tmux -S "$SOCKET" new -d -s "$SESSION" -n shell +tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "keeper shell || keeper-commander shell || bash" Enter +tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120 +``` + +Then drive the session carefully: + +```bash +tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -l -- "whoami" +tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 Enter +tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120 +``` + +Kill the tmux session when the task is complete unless the user wants a persistent Keeper shell. + ## Authentication ```bash @@ -202,6 +249,12 @@ keeper --batch-mode --commands-file commands.txt echo "list" | keeper --batch-mode --user admin@co.com ``` +## References +- Use `references/endpoint-privilege-management.md` for endpoint privilege management commands like kepm, epm, pedm commands +- Use `references/enterprise-mgmt.md` for enterprise management scenarios and commands. +- Use `references/pam-commands.md` for privileged access management or KeeperPAM functionalities. +- Use `references/msp-management.md` for commands specific to Managed Service Provider (MSP) tenants + ## Guardrails - NEVER expose the user's master password in logs, chat, or code. @@ -213,5 +266,6 @@ echo "list" | keeper --batch-mode --user admin@co.com them to the keeper-secrets skill and KSM CLI. - Commander requires a full user login - it cannot be used in headless environments without persistent login configured. +- ALWAYS ask confirmation from users for any DELETE operations. For detailed command reference, read `references/commander-commands.md`. For `keeper://` URIs and `ksm exec` / `ksm interpolate`, see [Keeper notation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/keeper-notation) and the **keeper-secrets** skill. diff --git a/plugins/keeper-admin/skills/keeper-admin/references/commander-commands.md b/plugins/keeper-admin/skills/keeper-admin/references/commander-commands.md index 40ba097..647defe 100644 --- a/plugins/keeper-admin/skills/keeper-admin/references/commander-commands.md +++ b/plugins/keeper-admin/skills/keeper-admin/references/commander-commands.md @@ -649,3 +649,7 @@ My Vault> audit-report --event-type "record_access" - `2` - Authentication error - `3` - Command syntax error - `4` - Item not found + +## Command References + +Refer [Keeper commander command reference documentation](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference) diff --git a/plugins/keeper-admin/skills/keeper-admin/references/endpoint-privilege-management.md b/plugins/keeper-admin/skills/keeper-admin/references/endpoint-privilege-management.md new file mode 100644 index 0000000..dd89822 --- /dev/null +++ b/plugins/keeper-admin/skills/keeper-admin/references/endpoint-privilege-management.md @@ -0,0 +1,36 @@ +# Endpoint Privilege Manager Commands + +Commands that control Keeper Endpoint Privilege Manager (KEPM) capabilities + +``` +My Vault> epm -h +epm command [--options] + +Command Description +---------- ------------------------------------ +sync-down Sync down EPM data from the backend +deployment Manage EPM deployments +agent Manage EPM agents +policy Manage EPM policies +collection Manage EPM collections +scim Sync EPM user/group collections from AD or AzureAD +approval Manage EPM requests and approvals +``` + +Use epm sync-down to get latest approvals if a approval is not found. + +## EPM Sub commands + +``` +sync-down +deployment +agent +policy +collection +approval +scim +``` +Use -h to know exact syntac and working for each sub-commands. + +Refer [keeper official EPM documentation](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/endpoint-privilege-manager-commands) instead of guessing a particular command. + diff --git a/plugins/keeper-admin/skills/keeper-admin/references/msp-management.md b/plugins/keeper-admin/skills/keeper-admin/references/msp-management.md new file mode 100644 index 0000000..7d8d533 --- /dev/null +++ b/plugins/keeper-admin/skills/keeper-admin/references/msp-management.md @@ -0,0 +1,24 @@ +# MSP Management Commands + +Commands specific to Managed Service Provider (MSP) tenants + +Command, Explanation +msp-info or mi, Display MSP details +msp-down or md, Refresh local MSP data from server +msp-add or ma, Creates Managed Company +msp-remove or mrm, Removes Managed Company +msp-update or mu, Modify Managed Company licenses +msp-billing-report, Generate MSP Billing Reports +msp-legacy-report, Generate MSP Legacy Report +switch-to-mc, Switch context to run commands as a managed company +switch-to-msp, Switch context to run commands as MSP +msp-convert-node, Convert an enterprise node into a managed company +msp-copy-role, Copy role enforcements from MSP to MCs + +Whether using the interactive shell, CLI or JSON config file, Keeper supports the following commands, each command supports additional parameters and options. +To get help on a particular command, run: + +`help ` + +Refer [keeper official MSP Management documentation](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/msp-management-commands) instead of guessing a particular command. +