feat(pam): add KCM database import command with auto-detect and group filtering

[jlima8900]

Summary

Adds pam project kcm-import — a new command that imports connections directly from a KCM/Guacamole database into Keeper PAM, and pam project kcm-cleanup to reverse imports.

Key features

• Docker auto-detect: discovers KCM DB container, detects MySQL/PostgreSQL, resolves container IP, extracts credentials
• Group filtering: --groups, --exclude-groups, --list-groups with wildcard support
• Interactive pickers: gateway selection, group selection, vault password search
• Adaptive throttling: probes server RTT, adjusts batch size/delay to avoid HTTP 403
• 2-phase batched import: external users first, then resources with nested users
• Gateway token capture: includes in report and vault record custom fields
• Per-record tracking: pass/fail/skip breakdown by record type
• Import report: vault record with copyable fields + MD file attachment
• 150+ KCM parameter mappings: SSH, RDP, VNC, Telnet, HTTP, MySQL, PostgreSQL, Oracle, SQL Server, LDAP, K8s
• Cleanup command: pam project kcm-cleanup

Usage

```bash

Auto-detect everything from Docker (simplest)

pam project kcm-import --docker-detect --name "My KCM Migration"

Preview without vault changes

pam project kcm-import --docker-detect --dry-run

List available connection groups

pam project kcm-import --docker-detect --list-groups

Import only specific groups (wildcard support)

pam project kcm-import --docker-detect --groups "Production*,Staging*" --name "Prod"

Exclude groups from import

pam project kcm-import --docker-detect --exclude-groups "Test*,Incomplete*"

Manual database connection with vault-stored password

pam project kcm-import --db-host 10.0.0.5 --db-type postgresql --db-password-record "KCM DB Creds" --db-ssl --name "Production KCM"

Extend an existing PAM config with new groups

pam project kcm-import --docker-detect --config "Existing Config" --groups "NewDept*"

Save JSON for review before importing

pam project kcm-import --docker-detect --output ~/kcm-review.json

Non-interactive batch mode

pam project kcm-import --docker-detect --name "Auto Import" --gateway "My GW" --yes

Size estimate without importing

pam project kcm-import --docker-detect --estimate

Clean up an import (reverse everything)

pam project kcm-cleanup --name "KCM Migration" --dry-run
pam project kcm-cleanup --name "KCM Migration" --yes
```

Security: DB passwords are never accepted as CLI arguments. Use `--db-password-record` (vault record) or respond to the interactive prompt. Dry-run output redacts all credentials.

Gateway

• If no existing gateway is specified with `--gateway`, the command creates a new one
• `--max-instances N` sets the gateway pool size (0 = skip pool creation)
• In interactive mode, an online gateway picker is shown
• The deploy command (`docker run`) is included in the report record for easy copy/paste

Import Report

After a successful import, a vault record is created at the project's top-level folder containing:

• Copyable custom fields: `Deploy Gateway (copy & paste)` with the full docker command, Gateway Token, Config UID, Gateway UID, KSM App UID, folder names
• KCM-Import-Report.md file attachment with the full report
• Per-record pass/fail/skip breakdown by type (including nested users)
• Failed/skipped records with reasons
• Throttle statistics
• Redacted CLI command for reproducibility

Files changed

File	Change
`kcm_import.py`	New — 4340 lines
`kcm_mappings.json`	New — parameter mappings
`commands.py`	Register kcm-import + kcm-cleanup
`base.py` / `edit.py`	Minor pamUser validation
`README.md`	Updated with new flags/examples
`KCM_IMPORT.md`	New — quick-start guide
`test_kcm_import.py`	New — 206 tests, 3779 lines

Test plan

• 206 unit tests passing
• E2E live import: 129 records, 0 throttles, report saved
• E2E cleanup: records + folders + gateway + app deleted
• Security audit: 0 critical/high
• Code quality audit: clean
• Docker auto-detect tested against live KCM PostgreSQL
• Group filtering tested (216→65 resources)
• Batch mode tested (`--yes`)

[jlima8900]

Note: Credential history resolved

The branch has been squashed to a single commit (2b894b05). The previously flagged hardcoded test database password (_LIVE_DB_PASS) no longer exists in git history.

The test file now uses os.environ.get('KCM_TEST_DB_PASS', '') — no credentials in code.

[jlima8900]

@aaunario — ready for review. Squashed to single commit, 79 unit tests + 27 E2E tests passing, no hardcoded credentials.

[jlima8900]

Closing in favor of a clean PR — same branch, squashed to single commit.