AWS Marketplace

Deploy Keeper Commander in Service Mode using the Keeper Commander AMI available in AWS Marketplace

What is an AMI?

An Amazon Machine Image (AMI) is a pre-configured template used to launch EC2 instances in AWS. AMIs contain the operating system, installed software, and configuration settings needed to deploy a server without manual setup. Using an AMI ensures consistent, repeatable deployments across AWS infrastructure.

Keeper Commander AMI

The Keeper Commander AMI is available through the AWS Marketplace and provides a ready-to-deploy EC2 image for running Keeper Commander in Service Mode. This deployment option exposes Commander CLI capabilities through a secure REST API without requiring manual installation or configuration.

The Keeper Commander AMI includes:

• Preconfigured Ubuntu-based EC2 image
• Keeper Commander installed and ready to use
• Python virtual environment configured
• Support for Commander Service Mode (REST API)

Use Cases

Commander Service Mode enables REST API access to any supported Keeper Commander CLI command, including vault operations, record management, reporting, rotation, and administrative functions. By specifying an allowlist of commands during service creation, organizations can tailor the API to their specific requirements. For a complete list of available commands, see the Commander Command Reference.

• Automation and orchestration workflows
• PAM integrations with third-party platforms
• Secure service-to-service access
• CI/CD pipelines requiring dynamic secrets retrieval

---

Prerequisites

Before you begin, ensure you have the following:

Requirement	Description
AWS Account	Permissions to launch and manage EC2 instances
Keeper Commander AMI	Available via AWS Marketplace
Keeper Tenant	Enterprise tenant with KeeperPAM enabled
Tunnel Credentials	Ngrok or Cloudflare Tunnel authentication token
SSH Client	Remote access to instance through KeeperPAM or local client

---

Step 1: Launch an EC2 Instance Using the Keeper Commander AMI

1. Open the AWS Marketplace listing: Keeper Commander AMI
2. Select Continue to Subscribe, then Continue to Configuration.
3. Launch a new EC2 instance using the recommended configuration below.

Recommended Instance Configuration

Setting	Value
Instance Type	t3.micro
AMI	Keeper Commander AMI
VPC/Subnet	Default or customer-defined
Storage	Default

---

Step 2: Configure the Security Group

Create or select a security group with the following rules.

Inbound Rules

Protocol	Port	Source	Purpose
TCP	22	Trusted IP range only	SSH administrative access

Outbound Rules

Protocol	Port	Destination	Purpose
All	All	0.0.0.0/0	Tunnel connectivity and updates

Do not expose the Commander service port directly to the internet. Use Ngrok or Cloudflare Tunnel for external access.

---

Step 3: Create and Attach an SSH Key Pair

1. Create a new SSH key pair or select an existing one.
2. Download the .pem file and store it securely.
3. Attach the key pair to the EC2 instance during launch.

---

Step 4: Connect to the EC2 Instance via SSH

After the instance is running, connect using SSH:

ssh -i "[KEY_PATH]" ubuntu@[SERVER_PUBLIC_DNS]

Example:

ssh -i "key1.pem" [e-mail]

---

Step 5: Switch to the Keeper User and Activate the Environment

Once connected, switch to the keeper user:

sudo su keeper

Activate the Python virtual environment:

source ~/venv/bin/activate

Start Keeper Commander:

keeper shell

---

Step 6: Register the Device and Enable Persistent Login

Enable persistent login for this instance:

this-device persistent-login on

Register the device with your Keeper tenant:

this-device register

Configure credential expiration:

this-device timeout 30d

Credential Timeout Guidance

The timeout value defines how long device credentials remain valid before requiring re-authentication.

Duration	Security Level	Use Case
1d–7d	High	Production environments with strict policies
14d–30d	Moderate	Standard operational environments
60d–90d	Lower	Development or low-risk environments

Choose a duration that balances security requirements with operational continuity.

---

Step 7: Create the Commander Service (Service Mode)

Commander Service Mode exposes a REST API with restricted command execution.

Command Restrictions

Service Mode enforces a command allowlist to limit API exposure. When creating a service, only the commands specified in the -c parameter can be executed through the REST API.

Parameter	Format	Example
-c	Comma-separated command list	'record-add,whoami,tree'

Best practice: Enable only the commands required for your specific use case. Avoid broad access to reduce attack surface.

For the full list of available commands, see the Command Reference.

---

Option A: Create a Service Using Ngrok

service-create \
  -p 9090 \
  -c 'record-add,whoami' \
  -ng [NGROK_TOKEN] \
  -cd [NGROK_DOMAIN]

---

Option B: Create a Service Using Cloudflare Tunnel

service-create \
  -p 9090 \
  -c 'record-add,whoami' \
  -cf [CLOUDFLARE_TOKEN] \
  -cfd [CLOUDFLARE_DOMAIN]

---

Service Mode API Usage Examples

Keeper Commander Service Mode exposes a REST API for executing pre-approved Commander commands.

Base Service URL

• Ngrok: https://<ngrok-domain>
• Cloudflare Tunnel: https://<cloudflare-domain>

Example: WhoAmI

curl -X POST https://<SERVICE_DOMAIN>/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "whoami"
  }'

Example: Create a Record

curl -X POST https://<SERVICE_DOMAIN>/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "record-add",
    "args": [
      "--title", "API Created Record",
      "--login", "admin",
      "--password", "StrongPassword123!",
      "--url", "https://example.com"
    ]
  }'

Command Restriction Enforcement

If a command was not allowed during service-create, the API returns:

{
  "status": "error",
  "message": "Command not allowed"
}

---

Security Considerations

• Allow only required commands
• Do not expose service ports publicly
• Use Ngrok or Cloudflare Tunnel exclusively
• Restrict SSH access to trusted IP ranges
• Protect SSH private keys
• Rotate and re-register devices periodically

---

Troubleshooting

Authentication Issues

Symptom: Commands fail with authentication or session errors.

Resolution: Device credentials may have expired. Re-register the device:

bash

this-device register

Service Not Reachable

Symptom: API requests fail to connect to the service endpoint.

Resolution:

• Validate Ngrok or Cloudflare authentication token
• Confirm tunnel domain is correctly configured
• Verify the security group allows outbound traffic

Command Denied

Symptom: API returns "Command not allowed" error.

Resolution:

• Verify the command is included in the -c allowlist used during service-create
• Restart the service after making configuration changes

SSH Access Issues

Symptom: Unable to connect to the EC2 instance via SSH.

Resolution:

• Verify the SSH key file path and permissions (chmod 400)
• Confirm the security group allows inbound TCP port 22
• Connect using the ubuntu user (not root or keeper)