Keeper Commander

The Nested Share Folder (NSF) command suite allows for advanced folder management, record organization, and granular sharing within Keeper Commander. Commands are categorized into Folder, Record, Sharing, and Inspection operations.

Folder Commands

• nsf-mkdir: Create a folder.
• nsf-rndir: Rename or recolor a folder.
• nsf-list: List folders and records.
• nsf-rmdir: Remove folder(s).
• nsf-share-folder: Grant or remove folder access.

Record Commands

• nsf-record-add: Create a record.
• nsf-record-update: Update a record.
• nsf-rm: Remove, trash, or unlink a record.
• nsf-ln: Link a record into a folder.
• nsf-shortcut list: List multi-folder records.
• nsf-shortcut keep: Keep a record in one folder and unlink it from all others.

Sharing Commands

• nsf-share-record: Grant, revoke, or transfer ownership of a specific record.
• nsf-record-permission: Bulk update sharing permissions across a folder tree.
• nsf-transfer-record: Transfer record ownership.
• nsf-share-folder: Grant or revoke access to an entire folder.

Inspection Commands

• nsf-get: Show full record or folder details.
• nsf-record-details: Get record metadata in batch mode.

The importer maps CyberArk platforms and fields to specific KeeperPAM structures.

Platform to Record Type Mapping

• UnixSSH, UnixSSHKey, PaloAltoNetworks, CiscoIOS, etc. $\rightarrow$ pamMachine (Protocol: ssh, Port: 22)
• WinDomain, WinLocalAccount, etc. $\rightarrow$ pamMachine (Protocol: rdp, Port: 3389)
• MSSql $\rightarrow$ pamDatabase (Protocol: mssql, Port: 1433)
• Oracle $\rightarrow$ pamDatabase (Protocol: oracle, Port: 1521)
• MySQL $\rightarrow$ pamDatabase (Protocol: mysql, Port: 3306)
• PostgreSQL $\rightarrow$ pamDatabase (Protocol: postgresql, Port: 5432)
• BusinessWebsite $\rightarrow$ login

Key Field Mappings

• address $\rightarrow$ host (on resource)
• platformAccountProperties.Port $\rightarrow$ port (on resource and pam_settings.connection)
• userName $\rightarrow$ login (on pamUser)
• password $\rightarrow$ password (on pamUser)
• password (for SSH keys) $\rightarrow$ private_pem_key (on pamUser)
• safeName $\rightarrow$ folder_path (on resource and users)

Data Structures

Resource pam_settings structure:

{
  "pam_settings": {
    "options": {
      "rotation": "on|off",
      "connections": "on",
      "tunneling": "off",
      "graphical_session_recording": "off"
    },
    "connection": {
      "protocol": "ssh|rdp|mssql|...",
      "port": "22|3389|...",
      "launch_credentials": "username@resource-title"
    }
  }
}

User rotation_settings structure:

{
  "rotation_settings": {
    "rotation": "general",
    "enabled": "on|off",
    "schedule": {"type": "on-demand"}
  }
}

The Service Mode uses an asynchronous request queue system to ensure reliable command execution. This is enabled by default (queue_enabled: y).

Key Concepts

• Sequential Processing: Requests are processed one at a time in FIFO (First-In-First-Out) order.
• Request Tracking: Every request is assigned a unique request_id used to track progress and retrieve results.
• API Versioning:
  • Queue Enabled: Use /api/v2/ for asynchronous processing. /api/v1/executecommand remains available as a synchronous compatibility endpoint.
  • Queue Disabled: /api/v1/ runs in standalone legacy mode with direct synchronous execution only.

Request States

• queued: Request accepted and waiting in queue.
• processing: Currently being executed.
• completed: Successfully completed.
• failed: Execution failed.
• expired: Request timed out before processing.

Queue Configuration

Settings can be defined in the service configuration (YAML/JSON):

queue_max_size: 100          # Maximum queued requests
request_timeout: 300         # Request timeout (seconds)
result_retention: 3600       # Result retention (seconds)

When importing, the latest version of a GCP secret is decoded as UTF-8 and parsed into Keeper record fields using the following priority order:

1. JSON object: If the payload is a valid JSON object, each key/value pair becomes a separate field.
2. KEY=VALUE lines: If not JSON, it attempts to parse newline-separated KEY=VALUE pairs (shell-style). Lines starting with # or blank lines are ignored.
3. Plain string: If neither of the above applies, the entire string is stored in a single field named value.

Field Mapping Logic

Parsed keys are mapped to specific Keeper field types (case-insensitive):

Note: If a semantic type (like login) appears multiple times, the first occurrence uses the typed field, and subsequent ones are stored as custom fields.

# Example JSON payload
{
  "username": "admin",
  "password": "s3cur3P@ss!",
  "host": "db.internal.example.com"
}

# Example KEY=VALUE payload
username=admin
password=s3cur3P@ss!
host=db.internal.example.com

# Example Plain string
s3cur3P@ss!

When importing PAM resources, you can define access workflows to control how users request and receive access. The workflow configuration is part of the pam_settings.options.workflow object.

Key Workflow Fields

• approvals_needed (int, default 0): Number of approvals required.
• checkout_needed (bool, default false): Requires explicit check-out before launching a session.
• start_access_on_approval (bool, default false): Starts the access window immediately upon approval rather than at session launch.
• require_reason / require_ticket (bool, default false): Prompts the user for a reason or ticket reference during the request.
• require_mfa (bool, default false): Requires MFA at session launch.
• access_duration (string, default "1d"): Validity of approved access. Use formats like Xm (minutes), Xh (hours), or Xd (days), e.g., "30m", "8h", "2d". A bare integer is treated as minutes.

Time Restrictions (allowed_times)

• allowed_days (list of strings): Restricts access to specific weekdays (e.g., "mon", "monday").
• time_ranges (list of {start, end} objects): Daily windows in HH:MM (24-hour) format.
  • Note: If a range spans midnight (e.g., 22:00–06:00), split it into two ranges within the same day (e.g., 22:00–23:59 and 00:00–06:00).
• timezone (string): IANA timezone name (e.g., "UTC", "America/New_York"). Required if time_ranges is used.

Approvers (approvers[])

Each approver entry contains:

• principal.type: Either "user" or "team".
• principal.email: Required for users (must exist in the enterprise).
• principal.team_uid_base64url: Required for teams (base64url-encoded vault UID).
• escalation (bool): If this approver is part of an escalation chain.
• escalation_after (duration string, optional): Wait time before escalating to this approver. Requires escalation: true.

When importing, the command parses the Azure Key Vault secret value into named fields using the following priority order:

1. JSON object: If the value is a valid JSON object, each key/value pair becomes a field.
2. KEY=VALUE lines: If not JSON, it parses newline-separated KEY=VALUE pairs (shell-style). Lines starting with # or blank lines are ignored.
3. Plain string: If neither of the above, the entire string is stored in a single field named value.

Field Mapping Logic

Parsed keys are mapped to Keeper field types (case-insensitive):

Note: If a semantic type (like login) appears multiple times, the first occurrence is a typed field and subsequent ones become custom fields. note and notes are always written to the record's Notes section.

{
  "username": "admin",
  "password": "s3cur3P@ss!",
  "host": "db.internal.example.com"
}

The PAM import process follows specific rules for workflow application and validation:

• Trivial Workflow Detection: If none of the following are set (approvals_needed > 0, checkout_needed, require_mfa, start_access_on_approval, allowed_times.allowed_days, or allowed_times.time_ranges), the workflow block is treated as absent and no Router call is made.
• Dry-run Validation: Using the --dry-run flag performs pre-flight validation. It checks for bad durations, malformed HH:MM times, missing timezones, escalation rule violations, and unknown team UIDs. It reports errors without writing to the vault.
• Dry-run Execution: During a --dry-run, Router calls (creating/updating workflows and reconciling approvers) are skipped. They only execute during a real run.
• The extend Flag: When using extend, the workflow configuration is only applied to newly created resources; existing resources are not modified.

SuperShell is a full-screen terminal user interface (TUI) designed for browsing and managing Keeper vault records. It is built on the Textual framework and uses a modular architecture consisting of:

• Main Application (app.py): The SuperShellApp class manages the UI layout (tree, detail pane, search bar, shell pane), application state, and component coordination.
• Keyboard Handling (handlers/keyboard.py): Implements a dispatcher pattern where a KeyboardDispatcher routes events to specific handlers (e.g., GlobalExitHandler, SearchInputHandler).
• State Management (state/): Uses Python dataclasses like VaultData (for records and folders) and UIState (for view modes and search queries) to provide type-safe state.
• Search (data/search.py): Provides smart tokenized search that matches query tokens against record fields (title, URL, username, custom fields, notes) or folder names, regardless of token order.
• Renderers (renderers/): Formats data for display using Rich markup, including JsonRenderer for syntax-highlighted JSON and specialized formatters for passwords and TOTP codes.
• Themes (themes/): Supports multiple color schemes (green, blue, magenta, yellow, white) defined via color properties and Textual CSS.