SSH-KLM Quickstart

SSH-KLM Quickstart

Get SSH-KLM running in 5 minutes and discover your first SSH keys.

This guide walks you through deploying SSH-KLM locally, running your first discovery scan, and viewing discovered keys in the dashboard.

Use Cases

• Evaluate SSH-KLM features quickly
• Development and testing environments
• Proof of concept deployments
• Learning the platform before production rollout

Prerequisites

Requirement	Details
Docker	Version 20.10+ with Docker Compose
Ports	8081 (UI), 5432 (PostgreSQL), 6379 (Redis)
Memory	Minimum 4GB RAM available
Target Server	SSH access to at least one Linux server (for testing)

Step-by-Step Guide

Step 1: Clone and Start Services

# Clone the repository
git clone https://github.com/qcecuring/ssh-klm.git
cd ssh-klm

# Start all services
docker-compose up -d

# Verify services are running
docker-compose ps

Expected output:

NAME                STATUS              PORTS
ssh-klm-api         Up                  0.0.0.0:8081->8081/tcp
ssh-klm-db          Up                  0.0.0.0:5432->5432/tcp
ssh-klm-redis       Up                  0.0.0.0:6379->6379/tcp
ssh-klm-worker      Up

Step 2: Access the Dashboard

1. Open http://localhost:8081 in your browser
2. Login with default credentials:
   • Username: admin@qcecuring.local
   • Password: changeme123
3. Important: Change the default password immediately

Step 3: Add Your First Host

Navigate to Inventory → Add Host and enter:

Host: server01.example.com
Port: 22
Username: root  # or your SSH user
Authentication: Password  # or SSH Key

Alternatively, use the SDK:

import { QcClient } from '@qcecuring/ssh-sdk';

const client = new QcClient({
  apiKey: process.env.QC_API_KEY,
  baseUrl: 'http://localhost:8081'
});

// Add a host
await client.ssh.addHost({
  hostname: 'server01.example.com',
  port: 22,
  username: 'root',
  authMethod: 'password',
  credential: process.env.SSH_PASSWORD
});

Step 4: Run Discovery Scan

1. Go to Discovery → New Scan
2. Select your host from the inventory
3. Click Start Discovery

Or via SDK:

// Trigger discovery
const scan = await client.ssh.startDiscovery({
  hosts: ['server01.example.com'],
  scanType: 'full'  // 'full' | 'incremental'
});

console.log(`Scan started: ${scan.id}`);

Step 5: View Discovered Keys

After the scan completes (typically 1-2 minutes):

1. Navigate to Keys → All Keys
2. View discovered SSH keys with details:
   • Key fingerprint
   • Algorithm (RSA, ED25519, ECDSA)
   • Key age and last used
   • Risk score

// List discovered keys
const keys = await client.ssh.listKeys({
  host: 'server01.example.com',
  status: 'active'
});

keys.forEach(key => {
  console.log(`${key.fingerprint} - ${key.algorithm} - Risk: ${key.riskScore}`);
});

Step 6: Rotate a Key (Optional)

Test key rotation on a non-production key:

1. Select a key from the list
2. Click Actions → Rotate Key
3. Choose rotation options:
   • Generate new key pair
   • Update authorized_keys
   • Archive old key

// Rotate a specific key
await client.ssh.rotateKey({
  keyId: 'KEY-12345',
  algorithm: 'ed25519',
  archiveOld: true
});

Examples

Complete Discovery Flow

import { QcClient } from '@qcecuring/ssh-sdk';

async function discoverAndReport() {
  const client = new QcClient({ apiKey: process.env.QC_API_KEY });

  // Add hosts
  const hosts = ['server01', 'server02', 'server03'];
  for (const host of hosts) {
    await client.ssh.addHost({ hostname: `${host}.example.com` });
  }

  // Run discovery
  const scan = await client.ssh.startDiscovery({
    hosts: hosts.map(h => `${h}.example.com`)
  });

  // Wait for completion
  await client.ssh.waitForScan(scan.id);

  // Get results
  const keys = await client.ssh.listKeys({ scanId: scan.id });

  console.log(`Discovered ${keys.length} SSH keys`);
  console.log(`High risk keys: ${keys.filter(k => k.riskScore > 80).length}`);
}

Troubleshooting

Services Not Starting

Issue: Docker containers fail to start

Solution:

# Check logs
docker-compose logs -f

# Restart services
docker-compose down
docker-compose up -d

Cannot Connect to Host

Issue: Discovery fails with connection error

Solution:

• Verify SSH port (22) is accessible
• Check firewall rules
• Validate credentials
• Test manually: ssh user@host

Discovery Returns No Keys

Issue: Scan completes but no keys found

Solution:

• Verify user has permission to read ~/.ssh/ and /etc/ssh/
• Check scan logs in Discovery → Scan History
• Try running with elevated privileges

Next Steps

Now that you have SSH-KLM running:

Guide	Description
Docker Installation	Production Docker deployment
Kubernetes Setup	Deploy on K8s
Discovery Concepts	How discovery works
Rotation Policies	Configure automated rotation
API Overview	Full API documentation

Related Pages

• Architecture Overview
• Agent Installation
• Troubleshooting Guide