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
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
service-docker-setup
Automated Docker service mode setup with KSM configuration
slack-app-setup
Automated Slack App integration setup with Commander Service Mode
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:
Use a service account dedicated to the Commander service, which is limited in scope to the necessary rights and capabilities.
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
Install Keeper Commander and then login to the shell.
Log in with your Keeper credentials when prompted. Since the Commander Service Mode is typically run as a service, it is recommended to use biometric login or a persistent login session.
Biometric Login:
Or create a persistent login session using the commands below:
Service Mode Create : Using Interactive Configuration
Create and configure the service with interactive prompts:
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)
Streamlined Configuration:
Configure the service quickly with a single command (default is foreground mode with http) :
Configure the service quickly with Ngrok (providing Ngrok auth token and Ngrok subdomain)
Configure the service quickly with Cloudflare (providing Cloudflare auth token and domain name)
Configure the service with advanced options:
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)-crtf, --certfile: SSL certificate file path, accepts.crt,.pemor.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.-rl, --ratelimit: Rate limit per endpoint per IP (e.g.,10/minute,100/hour,1000/day) (Optional)-aip, --allowedip: IP allow list (Optional) - Default: 0.0.0.0/0,::/0-dip: Denied IP list (Optional)-ek, --encryption_key: Base64-encoded 32-byte key for AES-256 response encryption (Optional)-te, --token_expiration: API key expiration time (e.g.,30m,24h,7d) (Optional)
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.
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):
Ctrl-C will stop the service. Once the service has been created, subsequent terminal commands can just start up the service like this:
If biometric login or persistent login mode is enabled, the service startup is seamless.
Service Management
Check service status:
Add additional configuration:
Start the service:
Stop the service:
Health Check
Commander Service Mode provides a health check URL for checking the service status. Example with the service running on localhost port 8080:
Request:
Response:
Support
For support or feature requests, please open a Github issue or contact:
Email: [email protected]
Next Steps
Last updated
Was this helpful?