diff --git a/plugins/keeper-admin/skills/keeper-admin/SKILL.md b/plugins/keeper-admin/skills/keeper-admin/SKILL.md index db2bea4..2501bc2 100644 --- a/plugins/keeper-admin/skills/keeper-admin/SKILL.md +++ b/plugins/keeper-admin/skills/keeper-admin/SKILL.md @@ -41,14 +41,11 @@ Check installation: `keeper version` ## Authentication ```bash -# Interactive login +# Interactive login (preferred — credentials are not passed as CLI arguments) keeper shell # Prompts for email + master password + 2FA -# Non-interactive -keeper --user admin@company.com --password "master_pw" shell - -# Persistent login (recommended for CLI use) +# Persistent login (recommended for ongoing CLI use) keeper shell My Vault> this-device register My Vault> this-device persistent-login ON @@ -57,6 +54,12 @@ My Vault> this-device persistent-login ON My Vault> biometric register ``` +Do **not** pass master passwords, API tokens, or vault field values on the command +line (e.g. `--password`), in URLs, or in generated scripts—they appear in process +listings and shell history. For automation, use interactive setup once, enable +persistent device login where appropriate, or follow the official Commander CLI +documentation for supported non-interactive patterns. + ## Vault Operations ### Browse & Search @@ -74,9 +77,11 @@ My Vault> get # Show full record details ```bash My Vault> add --record-type login --title "New Record" \ - --field login=admin --field password=s3cur3 + --field login=admin +# Set passwords and other sensitive fields via interactive prompts, or supply values only from the user’s secure input—never embed sample secrets in commands. -My Vault> edit --field password=newpassword +My Vault> edit +# Or non-interactive field updates for non-secret fields only, e.g. --field login=newuser My Vault> rm @@ -159,8 +164,10 @@ My Vault> secrets-manager client remove --app \ My Vault> secrets-manager share --app --email admin2@company.com ``` -The One-Time Access Token output from `client add` is what you pass to -`ksm profile init --token "XX:XXXXXXXXXX"` on the target machine. +The One-Time Access Token output from `client add` is configured on the target +machine using the **keeper-setup** skill (token via `KSM_CLI_TOKEN` or other +supported secure methods—**not** as a literal `--token` argument in shared +examples or chat). ## KeeperPAM Operations 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 a5b6b3d..40ba097 100644 --- a/plugins/keeper-admin/skills/keeper-admin/references/commander-commands.md +++ b/plugins/keeper-admin/skills/keeper-admin/references/commander-commands.md @@ -10,8 +10,7 @@ Official documentation: [Commander CLI](https://docs.keeper.io/en/keeperpam/comm # Start interactive shell keeper shell -# Non-interactive mode -keeper --user admin@company.com --password "master_pw" shell +# Avoid passing passwords or tokens on the command line; use interactive shell or official docs for supported automation. # Batch mode (run commands from file) keeper --batch-mode --commands-file commands.txt @@ -99,7 +98,8 @@ Create a new record. My Vault> add # Interactive mode My Vault> add --record-type login --title "New Login" My Vault> add --record-type login --title "API Key" \ - --field login=user@example.com --field password=secret + --field login=user@example.com +# Add password and other sensitive fields interactively or via secure input—do not put secrets in example commands. My Vault> add --folder --record-type login ``` @@ -125,9 +125,8 @@ Edit a record. ```bash My Vault> edit # Interactive editor My Vault> edit --field login=newuser -My Vault> edit --field password=newpass \ - --field login=newuser -My Vault> edit -t "Record Title" --field password=rotated +# For password fields, use interactive edit or values from secure input only. +My Vault> edit -t "Record Title" ``` ### rm @@ -376,7 +375,7 @@ Create and manage Client Devices (machine accounts). # Add client device (generates One-Time Token) My Vault> secrets-manager client add --app \ --name "Web Server 1" -# Output shows: XX:XXXXXXXXXX (One-Time Token) +# Output includes a one-time token; treat it as secret and configure the target per keeper-setup (KSM_CLI_TOKEN, not pasted into chat). # Add with IP unlocking My Vault> secrets-manager client add --app \ @@ -572,7 +571,7 @@ cat commands.txt | keeper --batch-mode ```bash --user # Keeper user email ---password # Master password (not recommended) +# Avoid --password: use interactive login or documented secure automation; CLI passwords leak via process listings and history. --profile # Profile file location --batch-mode # Batch/non-interactive mode --config # Config file @@ -617,8 +616,7 @@ My Vault> secrets-manager client add --app \ --name "Production Web Server" # Note the One-Time Token displayed -# On the server: -# ksm profile init --token "XX:XXXXXXXXXX" +# On the server: initialize KSM CLI using KSM_CLI_TOKEN (see keeper-setup skill and Keeper profile init docs)—do not pass tokens on the command line. ``` ### Rotate Database Password @@ -627,8 +625,8 @@ My Vault> secrets-manager client add --app \ # Get record My Vault> get -# Update password (also update in DB) -My Vault> edit --field password=newsecurepass +# Update password via interactive edit (also update in DB); do not embed secrets in commands. +My Vault> edit # Verify My Vault> get --json | jq '.fields[] | select(.type=="password")' diff --git a/plugins/keeper-admin/skills/keeper-admin/references/pam-commands.md b/plugins/keeper-admin/skills/keeper-admin/references/pam-commands.md index 4fc79ad..73862c8 100644 --- a/plugins/keeper-admin/skills/keeper-admin/references/pam-commands.md +++ b/plugins/keeper-admin/skills/keeper-admin/references/pam-commands.md @@ -341,10 +341,9 @@ PAM records are stored in Keeper Vault. ### Store PAM Record ```bash -# Create PAM login record +# Create PAM login record (set password flag at runtime via interactive add or secure input) My Vault> add --record-type login --title "Prod DB Admin" \ --field login=postgres \ - --field password=SuperSecret123 \ --field host=db.prod.example.com \ --field port=5432 \ --custom-field database=production diff --git a/plugins/keeper-admin/skills/keeper-admin/references/rotation-commands.md b/plugins/keeper-admin/skills/keeper-admin/references/rotation-commands.md index 3f385e6..7de21d5 100644 --- a/plugins/keeper-admin/skills/keeper-admin/references/rotation-commands.md +++ b/plugins/keeper-admin/skills/keeper-admin/references/rotation-commands.md @@ -365,8 +365,8 @@ My Vault> pam rotation create --record \ ```bash My Vault> add --record-type login \ --title "GitHub Token" \ - --field password=ghp_xxxxxxxxxxxx \ --custom-field repository=company/main +# Set the token/password field interactively or from secure input—do not embed secrets in example commands. My Vault> pam rotation create --record \ --target-type github_api \ diff --git a/plugins/keeper-secrets/skills/keeper-secrets/SKILL.md b/plugins/keeper-secrets/skills/keeper-secrets/SKILL.md index 0372334..e4beff2 100644 --- a/plugins/keeper-secrets/skills/keeper-secrets/SKILL.md +++ b/plugins/keeper-secrets/skills/keeper-secrets/SKILL.md @@ -47,25 +47,26 @@ by default when installed with keyring support. # Install with keyring support (recommended) pip install keeper-secrets-manager-cli[keyring] -# Initialize with One-Time Access Token -ksm profile init --token "XX:XXXXXXXXXX" +# Initialize with One-Time Access Token (set KSM_CLI_TOKEN in your shell first—see Keeper profile docs; do not pass --token with a literal value) +ksm profile init # For containers/CI (no keyring available) pip install keeper-secrets-manager-cli -ksm profile init --token "XX:XXXXXXXXXX" +# Prerequisite: export KSM_CLI_TOKEN from a trusted source, then: +ksm profile init # Creates keeper.ini with 0600 permissions -# Auto-create profile from environment variable -export KSM_TOKEN="XX:XXXXXXXXXX" -ksm secret list # Profile auto-created on first use +# Auto-create profile from environment variable (containers; see Keeper docs) +ksm secret list # When KSM_TOKEN is set, profile may be auto-created on first use ``` ### Multiple Profiles ```bash ksm profile list -ksm profile init --profile production --token "XX:XXXXXXXXXX" -ksm profile init --profile staging --token "YY:YYYYYYYYYY" +# After exporting KSM_CLI_TOKEN for each setup step: +ksm profile init --profile production +ksm profile init --profile staging ksm secret list --profile production ``` @@ -73,7 +74,8 @@ ksm secret list --profile production | Variable | Purpose | | --- | --- | -| `KSM_TOKEN` | One-Time Access Token for auto-init | +| `KSM_CLI_TOKEN` | One-Time Access Token for `ksm profile init` without `--token` on the CLI (preferred) | +| `KSM_TOKEN` | One-Time Access Token for auto-init in some container flows (see Keeper docs) | | `KSM_CONFIG` | Base64 config string (for K8s/containers) | | `KSM_CONFIG_FILE` | Path to keeper.ini | | `KSM_CLI_PROFILE` | Active profile name | @@ -169,12 +171,12 @@ ksm interpolate --in-file config.tmpl --out-file config.yaml # Create from editor ksm secret add editor --record-type login --title "New API Key" -# Create from field arguments +# Create from field arguments (supply sensitive field values from secure input, not sample literals) ksm secret add field --record-type login --title "New API Key" \ - --field "login=admin" --field "password=s3cur3" + --field "login=admin" -# Update a field -ksm secret update -u --field "password=newpassword123" +# Update a field (use secure input for password fields) +ksm secret update -u --field "login=newuser" # Delete a record ksm secret delete -u @@ -247,7 +249,8 @@ kubectl create secret generic ksm-config \ ```bash # One-time setup pip install keeper-secrets-manager-cli[keyring] -ksm profile init --token "XX:XXXXXXXXXX" +# Prerequisite: export KSM_CLI_TOKEN, then: +ksm profile init # Daily use - run your app with secrets injected DB_URL="keeper:///field/url" \ diff --git a/plugins/keeper-secrets/skills/keeper-secrets/references/ksm-commands.md b/plugins/keeper-secrets/skills/keeper-secrets/references/ksm-commands.md index ade37d2..43c291b 100644 --- a/plugins/keeper-secrets/skills/keeper-secrets/references/ksm-commands.md +++ b/plugins/keeper-secrets/skills/keeper-secrets/references/ksm-commands.md @@ -34,16 +34,18 @@ pip install keeper-secrets-manager-cli Initialize a new profile with One-Time Access Token. +Prefer **`KSM_CLI_TOKEN`** in the environment so the token is not passed as a `--token` argument (see [Keeper profile command](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/profile-command)). `--token` overrides the environment if both are set. + ```bash -ksm profile init --token "US:XXXXXXXXXX" -ksm profile init --profile production --token "US:XXXXXXXXXX" -ksm profile init --token "US:XXXXXXXXXX" --hostname keepersecurity.com -ksm profile init --token "US:XXXXXXXXXX" --ini-file /etc/keeper/config.ini +ksm profile init +ksm profile init --profile production +ksm profile init --hostname keepersecurity.com +ksm profile init --ini-file /etc/keeper/config.ini ``` **Options:** -- `--token ` - One-Time Access Token (required) +- `--token ` - One-Time Access Token (prefer `KSM_CLI_TOKEN` instead of a literal on the CLI) - `--profile ` - Profile name (default: 'default') - `--hostname ` - Keeper host (keepersecurity.com, keepersecurity.eu, etc.) - `--ini-file ` - Path to config file (default: ~/.keeper/keeper.ini) @@ -178,14 +180,13 @@ Create a new secret record. # Interactive editor ksm secret add editor --record-type login --title "New Secret" -# From command-line fields +# From command-line fields (set password fields via interactive editor or secure input—not sample literals) ksm secret add field --record-type login --title "API Key" \ - --field "login=user@example.com" \ - --field "password=secret123" + --field "login=user@example.com" # Add to specific folder ksm secret add field --record-type login --title "DB Cred" \ - --field "login=admin" --field "password=secret" \ + --field "login=admin" \ --folder-uid # Custom fields @@ -427,7 +428,8 @@ client_id = ### Environment Variables -- `KSM_TOKEN` - One-Time Access Token for auto-init +- `KSM_CLI_TOKEN` - One-Time Access Token for `ksm profile init` without passing `--token` on the command line (preferred) +- `KSM_TOKEN` - One-Time Access Token for auto-init (e.g. containers; see Keeper docs) - `KSM_CONFIG` - Base64-encoded config (replaces keeper.ini) - `KSM_CONFIG_FILE` - Path to keeper.ini - `KSM_HOSTNAME` - Override keeper host diff --git a/plugins/keeper-setup/skills/keeper-setup/SKILL.md b/plugins/keeper-setup/skills/keeper-setup/SKILL.md index 8e85726..fd765bb 100644 --- a/plugins/keeper-setup/skills/keeper-setup/SKILL.md +++ b/plugins/keeper-setup/skills/keeper-setup/SKILL.md @@ -18,6 +18,12 @@ Keeper provides two CLI tools. Install what you need: | KSM CLI (`ksm`) | `keeper-secrets-manager-cli` | Machine secrets retrieval & injection | | Commander (`keeper`) | `keepercommander` | Admin, vault management, PAM, sessions | +## Installation security + +- **Prefer PyPI** (`pip install …`) so you consume the published packages with version pins in your own dependency files. That is the default path for these tools. +- **Official sources only**: release binaries and source live under the **Keeper-Security** organization on GitHub. Before running any installer or `pip install` from a clone, confirm the remote URL and publisher match Keeper’s official documentation; use release tags or checksums published on the release page when you need extra assurance. +- **Agents must not** fabricate or echo one-time tokens, master passwords, or vault field values in chat or generated scripts. Direct the user to paste or inject secrets only in their own secure terminal or secret store. + ## Quick Install ### KSM CLI @@ -33,17 +39,17 @@ pip install keeper-secrets-manager-cli ksm version ``` -**Binary installers** (no Python required) are available for Windows, macOS, -and Linux at: +**Binary installers** (no Python required) are published for Windows, macOS, and Linux on the official **Keeper-Security/secrets-manager** GitHub Releases page linked from [Secrets Manager CLI](https://docs.keeper.io/en/keeperpam/secrets-manager/overview) documentation. Download only from that release page; verify checksums or signatures when the release provides them. ### Commander ```bash pip install keepercommander -# Or from source -git clone https://github.com/Keeper-Security/Commander +# Optional: install from a local clone of the official repository (verify remote and use a tagged release) +git clone https://github.com/Keeper-Security/Commander.git cd Commander +git checkout python -m venv venv && source venv/bin/activate pip install -r requirements.txt && pip install -e . @@ -59,11 +65,20 @@ You need a One-Time Access Token from a KSM Application. If you don't have one, your Keeper admin can create it via the Vault UI or Commander (see keeper-admin skill). +Provide the token **via environment variable** so it is not passed as a `--token` +argument (which can show up in shell history and process listings). Official docs: +[Profile command / init](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/profile-command). + ```bash -ksm profile init --token "US:XXXXXXXXXX" +# Prerequisite: export KSM_CLI_TOKEN in this shell from Vault or Commander output (see Keeper profile docs). Never paste token values into chat or committed files. +ksm profile init +# Optional: unset KSM_CLI_TOKEN when finished in this shell. + ksm secret list # Verify access ``` +In CI or secret managers, inject the same variable without placing the value on the command line. For containers, see also `KSM_TOKEN` / `KSM_INI_DIR` behavior in the Keeper Secrets Manager CLI documentation. + ### Commander Setup ```bash @@ -89,7 +104,7 @@ My Vault> this-device persistent-login ON | Issue | Fix | | --- | --- | -| "Not authenticated" | Re-run `ksm profile init` with a new token | +| "Not authenticated" | Re-run `ksm profile init` after setting `KSM_CLI_TOKEN` from a new Client Device token | | "Token expired" | Generate a new Client Device in Commander or Vault UI | | IP lock errors | Use `--unlock-ip` when creating the client, or init from the locked IP | | Keyring not available | Install with `[keyring]` extra or use `--ini-file` flag |