# 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](https://docs.keeper.io/en/keeperpam/commander-cli/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](https://us-east-1.console.aws.amazon.com/marketplace/search/listing/prodview-krkbznhplq4vy) |
| Keeper Tenant        | Enterprise tenant with KeeperPAM enabled                                                                                    |
| Tunnel Credentials   | [Ngrok](https://ngrok.com/) or [Cloudflare](https://www.cloudflare.com/) 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](https://us-east-1.console.aws.amazon.com/marketplace/search/listing/prodview-krkbznhplq4vy)
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 |

{% hint style="warning" %}
Do not expose the Commander service port directly to the internet. Use Ngrok or Cloudflare Tunnel for external access.
{% endhint %}

***

### 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" ubuntu@ec2-3-88-236-125.compute-1.amazonaws.com
```

***

### 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.

<table><thead><tr><th width="107.5078125">Parameter</th><th>Format</th><th>Example</th></tr></thead><tbody><tr><td><code>-c</code></td><td>Comma-separated command list</td><td><code>'record-add,whoami,tree'</code></td></tr></tbody></table>

**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](https://docs.keeper.io/en/keeperpam/commander-cli/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

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

#### Example: Create a Record

```bash
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:

```json
{
  "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

```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)`