PAM Project KCM Import

pam project kcm-import reads connections, users and groups directly from a Keeper Connection Manager (a.k.a. Apache Guacamole) database, maps the 150+ KCM connection parameters to KeeperPAM equivalents via kcm_mappings.json, then delegates to pam project import (new project) or pam project extend (existing project) under the hood. You never write the import JSON by hand.

Synopsis

pam project kcm-import
  ( --db-host=HOST [--db-port=PORT] [--db-name=DB] [--db-user=USER]
    [--db-password-record=UID] [--db-ssl]
  | --docker-detect [--docker-container=NAME] )
  [--db-type=mysql|postgresql]
  [--name=PROJECT | --config=UID_OR_TITLE]
  [--gateway=UID_OR_NAME]
  [--folder-mode=ksm|exact|flat]
  [--output=FILE | --dry-run]
  [--skip-users]
  [--include-disabled]

Either --db-host or --docker-detect is required. Everything else has a default.

Prerequisites

• Authenticated Commander session — run keeper login first.

• Network access to the KCM database from wherever you're running Commander.

• Database driver installed in the same Python that runs Commander:

  • MySQL → pymysql (preferred) or mysql-connector-python. Install: pip3 install pymysql

  • PostgreSQL → psycopg2-binary. Install: pip3 install psycopg2-binary

• docker CLI on PATH if using --docker-detect.

• A Keeper role with permission to create PAM projects, gateways and shared folders.

• kcm_mappings.json present at keepercommander/commands/pam_import/kcm_mappings.json.

Command Line Options

Either --db-host or --docker-detect is required; everything else has a default.

Source: where to read KCM from

• --db-host → KCM database hostname or IP. Required unless --docker-detect is used.

• --docker-detect → Auto-detect host/port/db/user/password by reading MYSQL_* / POSTGRES_* env vars from a Docker container via docker inspect. Required unless --db-host is used.

• --docker-container → Container name to inspect when --docker-detect is set. Default: guacamole.

• --db-type → Database engine. Choices: mysql, postgresql. Default: mysql.

• --db-port → TCP port for the DB. Default: 3306 for mysql, 5432 for postgresql.

• --db-name → Database name. Default: guacamole_db.

• --db-user → DB username. Default: guacamole_user. Read-only SELECT is enough.

• --db-password-record → Keeper record UID containing the DB password. Without this and without --docker-detect, the command prompts for the password via hidden getpass. Never accepts a password as a CLI argument.

• --db-ssl → Require TLS for the DB connection. The command emits a warning if you connect to a non-local/non-RFC1918 host without it.

Destination: where the data lands in Keeper

• --name, -n → Project name for a brand-new import. Default: KCM-Import-<YYYYMMDD-HHMMSS>. Mutually exclusive with --config.

• --config, -c → Existing PAM Configuration UID or title. Switches to extend mode. Mutually exclusive with --name.

• --gateway, -g → Existing gateway UID or name. Without it an interactive picker lists online gateways. Ignored in --config mode.

• --folder-mode → How KCM connection groups map to Keeper shared folders. Choices: ksm, exact, flat. Default: ksm.

Output mode

These three are mutually exclusive. Default (no flag) imports into the vault.

• --dry-run, -d → Print the assembled pam_data JSON to stdout with sensitive fields replaced by [REDACTED]. No vault writes.

• --output, -o → Write the full JSON (cleartext passwords) to a 0600 file. No vault writes.

• (no flag) → Default. Delegates to pam project import (new project) or pam project extend (existing config).

Filtering

• --skip-users → Skip generating pamUser records.

• --include-disabled → Include KCM connections marked disabled (max_connections == 0).

Quick Start

# KCM running locally in Docker, auto-detect credentials:
pam project kcm-import --docker-detect --docker-container=guacamole \
    --db-type=postgresql --name="My KCM Migration" --dry-run

# Remote KCM database, prompt for password:
pam project kcm-import --db-host=kcm-db.internal --db-type=postgresql \
    --db-name=guacamole_db --db-user=guacamole_user \
    --name="Prod KCM" --dry-run

# Pull the password from a Keeper record instead of prompting:
pam project kcm-import --db-host=kcm-db.internal --db-type=postgresql \
    --db-password-record=<RECORD_UID> --name="Prod KCM" --dry-run

Always run with --dry-run first, then drop it to actually create the project.

Three Ways to Give It Database Credentials

• Docker auto-detect (--docker-detect [--docker-container=NAME]) → KCM running in Docker on the same host as Commander.

• Vault record (--db-host=H --db-password-record=<UID>) → Repeatable runs / scripted migrations.

• Interactive prompt (--db-host=H with no record) → One-off run. Hidden getpass prompt. Never pass the password as a CLI argument.

Database Privileges Needed

The DB user needs SELECT on these Guacamole tables (read-only; the command never writes to the source DB):

• guacamole_connection

• guacamole_connection_parameter

• guacamole_connection_attribute

• guacamole_connection_group

• guacamole_connection_permission

• guacamole_entity

• information_schema.tables

PostgreSQL — minimal read-only role:

CREATE USER keeper_kcm_ro WITH PASSWORD '...';
GRANT CONNECT ON DATABASE guacamole_db TO keeper_kcm_ro;
GRANT USAGE ON SCHEMA public TO keeper_kcm_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO keeper_kcm_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO keeper_kcm_ro;

MySQL — minimal read-only role:

CREATE USER 'keeper_kcm_ro'@'%' IDENTIFIED BY '...';
GRANT SELECT ON guacamole_db.* TO 'keeper_kcm_ro'@'%';
FLUSH PRIVILEGES;

Folder Layout — --folder-mode

KCM organises connections in a tree of "connection groups". This flag controls how that tree maps to Keeper shared folders. Resources land under KCM Resources - <root> and users under KCM Users - <root> regardless of mode.

• ksm (default) → Groups marked with a KSM config become roots; descendants stay nested under them.

• exact → Mirrors the full KCM group hierarchy 1:1.

• flat → Every group becomes a top-level shared folder (no nesting).

Group names are sanitised — /, \ and .. are replaced with _ to prevent path traversal.

Protocol → Record-Type Mapping

KCM protocol	Keeper record type	Notes
ssh	pamMachine	SFTP sub-resources auto-extracted
rdp	pamMachine	RDP options mapped via kcm_mappings.json
vnc	pamMachine
telnet	pamMachine	Login regex parameters carry over
kubernetes	pamMachine	Namespace/pod/container/cert fields carry over
mysql	pamDatabase	database_type = "mysql"
postgres	pamDatabase	KCM uses postgres, KeeperPAM uses postgresql
sql-server	pamDatabase
http	pamRemoteBrowser	RBI only
anything else	pamMachine	Unknown protocols fall back

Each non-disabled KCM connection produces one resource record, one pamUser record wired as launch_credentials, and (SSH with SFTP) an extra SFTP resource + user pair.

What Gets Created in the Vault

Running without --dry-run / --output produces (in order):

1. Top-level project folder named after --name.

2. Two shared folders per group root — KCM Resources - <root> and KCM Users - <root>.

3. A PAM Configuration record (skipped in extend mode).

4. A gateway — reused if --gateway is given, otherwise interactive picker with [N] Create new.

5. Resource records (pamMachine / pamDatabase / pamRemoteBrowser).

6. User records (pamUser) wired to their resource's launch_credentials.

7. SFTP sub-resources and sub-users for SSH connections with SFTP configured.

Gateway Selection

• --gateway=<UID|name> → reuse that existing gateway (must be online).

• No --gateway flag → interactive prompt; pick a number to reuse or N to provision a new one.

• No online gateways available → falls through to "create new" without prompting.

• --config mode → gateway flag is ignored.

Output Mode Details

# 1. Dry-run: print JSON to stdout with passwords [REDACTED]
pam project kcm-import --db-host=... --dry-run

# 2. Output file: write full JSON (cleartext passwords) to a 0600 file
pam project kcm-import --db-host=... --output=/tmp/kcm-export.json

# 3. Default: import into the vault
pam project kcm-import --db-host=... --name="Prod KCM"

Re-Running and Cleanup

Re-running with the same --name — pam project import matches records by title and skips existing ones. New connections are added; changes to existing connections are not picked up automatically.

To add new KCM connections to an existing project — use --config=<UID_OR_TITLE> instead of --name.

Rolling back an import:

1. Right-click the project folder in the vault → Delete folder.

2. Delete the gateway separately via Admin Console → Privileged Access → Gateways (if needed).

Best practice: always do --dry-run first, then --output=/tmp/kcm-preview.json to inspect with cleartext values, then the real import.

Examples

# 1. Smoke test — local Docker, PostgreSQL, 3 connections
pam project kcm-import --db-host=192.168.32.10 --db-type=postgresql \
    --db-user=guacamole_user --db-name=guacamole_db --db-port=5432 \
    --name="Live-Test-Guac" --dry-run

# 2. Larger POC — 25 HTTP+SSH connections
pam project kcm-import --db-host=172.29.0.3 --db-type=postgresql \
    --db-user=guacamole_user --db-name=guacamole_db --db-port=5432 \
    --name="Live-Test-KCM" --dry-run

# 3. Save full JSON to disk for review
pam project kcm-import --db-host=192.168.32.10 --db-type=postgresql \
    --db-user=guacamole_user --db-name=guacamole_db --db-port=5432 \
    --name="Output-Test" --output=/tmp/kcm-output-test.json

# 4. Skip user records
pam project kcm-import --db-host=172.29.0.3 --db-type=postgresql \
    --db-user=guacamole_user --db-name=guacamole_db --db-port=5432 \
    --name="Skip-Users-Test" --skip-users --dry-run

# 5. Flat folder mode
pam project kcm-import --db-host=172.29.0.3 --db-type=postgresql \
    --db-user=guacamole_user --db-name=guacamole_db --db-port=5432 \
    --name="Flat-Mode-Test" --folder-mode=flat --dry-run

# 6. Docker auto-detect
pam project kcm-import --docker-detect --docker-container=kcm-setup-guacamole-1 \
    --db-type=postgresql --name="Docker-Detect-Test" --dry-run

Common Pitfalls

• Either --db-host or --docker-detect is required → you forgot both; one is mandatory.

• No PAM configuration found for gateway "X" → the gateway doesn't have a PAM config yet. Run pam config create first.

• Database connection failed: <ErrorType> → Commander hides the underlying message to avoid leaking credentials. Re-run with debug logging (-d at shell-launch) to see the full exception.

• Connecting to a remote DB without --db-ssl → you'll get a WARNING; credentials transit in cleartext. Always set --db-ssl for non-local hosts.

• Docker auto-detect with the wrong container name → default is guacamole; Compose deployments often use <project>-guacamole-1. Run docker ps --format '{{.Names}}' to check.

• pam project import complains about kcm_mappings.json missing → the file ships with Commander. Verify with git ls-files keepercommander/commands/pam_import/kcm_mappings.json; if missing, fetch from upstream release.