Service Mode REST API

Creating a REST API with Keeper Commander Service Mode

Keeper Commander Service Mode

The Service Mode module for Keeper Commander enables REST API integration by providing a secure, configurable API server that can be deployed with minimal setup. This module allows users to execute Commander CLI commands through a REST API interface while maintaining security and configuration flexibility. The service can be run locally and it can optionally be integrated with Ngrok or Cloudflare tunnels for creating a routable address.

Features

Core Functionality

API Server: Flask-based REST API server for executing Commander CLI commands
Service Management: Complete lifecycle management for the API service
Configuration Management: Flexible configuration system with both interactive and streamlined setup options
Security Controls: Comprehensive security features including API key management, access controls, rate limiting and IP allow/deny.
API Versioning: Two API versions supporting both synchronous (v1) and asynchronous (v2) operations
Request Queue System: Advanced asynchronous request processing with tracking and status monitoring
Flexible Hosting Options: Run on-prem, Docker container or in the cloud with integrated Ngrok or Cloudflare tunnel agent.

Service Commands

Command

Description

service-create

Initialize and configure the service with customizable settings

service-start

Start the service with existing configuration

service-stop

Gracefully stop the running service

service-status

Display current service status

service-config-add

Add new API configuration and command access settings

Security Features

API key authentication
Configurable token expiration (minutes/hours/days)
Optional AES-256 GCM encryption for API responses
TLS support with provided certificate (.pem)
Rate limiting with configurable rules
IP Allow list (whitelist) and IP Deny list (blacklist) management.
Request validation and policy enforcement
Local service config JSON or YAML file encryption using private key

Security

The Keeper Commander Service Mode feature is a self-hosted middleware that wraps an existing Commander session with a REST API. This feature is suited to environments where high speed requests and simple HTTPS-based APIs are desired.

To ensure the most secure use of this feature, we recommend the following:

Limit the scope of the Command access controls to only those commands which are required based on the use case.
Apply IP allowlist for accessing the REST API endpoint
Protect access to the machine running the Commander service
Use different API tokens for different commands and use cases

Usage

Basic Setup

Start Keeper Commander:

keeper shell

Log in with your Keeper credentials when prompted. To streamline the flow, enable either biometric login or persistent login on the startup.

Biometric Login:

biometric register

Persistent login session:

My Vault> this-device persistent-login on
My Vault> this-device register
My Vault> this-device timeout 30d

Service Mode Create : Using Interactive Configuration

Create and configure the service with interactive prompts:

My Vault> service-create

You'll be prompted to configure:

Port number
Ngrok auth token (optional)
Cloudflare tunnel token (optional)
TLS certificate path (optional)
Request Queue system (y/n)
Security settings (optional)
Config format (yaml/json) (if not previously created)
Run mode (foreground/background)
Command access controls

Example: Create Service Mode using TSL certificate(https)

My Vault> service-create
Enter Port No:9090
Enable Ngrok Tunneling? (y/n):n
Enable TLS Certificate (y/n):y
Enter Certificate Path:/Users/cert/cert.pem
Enter Certificate Password:/Users/cert/key.pem
Enable Request Queue? (y/n):y
Enable Advanced Security? (y/n):n
Select Run Mode (foreground/background):foreground
List of supported commands, Enter comma separated:whoami,record-add,tree,ls
Select configuration format (json/yaml):yaml
Generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Uploading service_config.yaml ...
Commander Service starting on https://localhost:9090/api/v2/
Commander Service started with PID: 35215

Streamlined Configuration:

Configure the service quickly with a single command (default is foreground mode with http) :

# The parameters details you can find below
My Vault> service-create -p 9090 -c 'record-add,whoami' -f json

Configure the service quickly with Ngrok:

# It needs two more paratemer -ng (Ngrok auth token) and -cd (domain name)
My Vault> service-create -p 9090 -c 'record-add,whoami' -ng xxxxxxxxxxx -cd myname

Configure the service quickly with Cloudflare:

# It needs two more parameter -cf (Cloudflare auth token) and -cfd (cloudflare domain name)
My Vault> service-create -p 9090 -c 'record-add,whoami' -cf xxxxxxxxxxx -cfd myname

Configure the service with advanced options:

My Vault> service-create -p <port> -f <json-or-yaml> -c <command-list> -rm <foreground-or-background> -q <y-or-n> -crtf <certificate-file-path> -crtp <certificate-password-key-path> -aip <allowed-ip-list> -dip <denied-ip-list>

Streamline Parameters:

-p, --port: Port number for the service (required to trigger streamline configuration)
-c, --commands: Comma-separated list of allowed commands (required)
-ng, --ngrok: Ngrok authentication token for cloud managed URL access (Optional)
-cd: Ngrok custom domain, just subdomain portion (Optional)
-cf,--cloudflare: Cloudflare tunnel token for cloud managed URL access (Optional)
-cfd: Cloudflare custom domain (Optional)
-aip, --allowedip: IP allow list (Optional) - Default: 0.0.0.0/0
-dip: denied IP list (Optional)
-crtf, --certfile: SSL certificate file path, accepts .crt, .pem or .key (Optional)
-crtp, --certpassword: SSL certificate password (Optional)
-q, --queue_enabled: Enable request queue system (y/n) - Default: y
-rm, --run_mode: Service run mode (foreground/background) - Default: foreground
-f, --fileformat: Configuration file format (json/yaml) - The service checks the local config file and Vault for an existing configuration format before prompting for setup.

Configuration File

After the initial configuration, Commander will create a record in the vault with the title of "Commander Service Mode". This record will contain a YAML/JSON file called service_config.

Subsequent startups require the service-start command with no parameters. Configuration is loaded from the local encrypted service_config file.

Note: Although the config is stored securely in Vault, the service uses a locally cached encrypted file for startup. To force a reload from Vault, delete the local config file (~/.keeper/service_config.json or .yaml) before running service-start.

Example: Starting from the Terminal in the Foreground

The service can be started from the system terminal. For example, the below command runs the /api/v1 in foreground mode. (Enable queue mode (-q y) for /api/v2):

keeper service-create -p 8090 -f json -c 'sync-down,whoami,record-add,login-status' -rm foreground -q n

Ctrl-C will stop the service. Once the service has been created, subsequent terminal commands can just start up the service like this:

 keeper service-start

If biometric login or persistent login mode is enabled, the service startup is seamless.

Service Management

Check service status:

My Vault> service-status
Current status: Commander Service is Running (PID: 12345, Terminal: /dev/ttys003)

Add additional configuration:

My Vault> service-config-add
List of supported commands, Enter comma separated:tree
Generated API key: zGCJjbbY6u0WkCbzoMu7XIxn5F7LQasWCeMdfTSBW3w=

Uploading service_config.yaml ...
Config Record with API key created successfully.

Start the service:

My Vault> service-start
Commander Service starting on https://localhost:8900/api/v2/
Commander Service started with PID: 12345

Stop the service:

My Vault> service-stop
Service stopped successfully

Support

For support or feature requests, please open a Github issue or contact:

Email: [email protected]

Next Steps

PreviousAutomatic Execution NextAPI Usage

Last updated 1 month ago

Was this helpful?