Known Hosts Management

Manage and verify SSH host fingerprints to protect against man-in-the-middle attacks and ensure you're connecting to the right servers.

What are Known Hosts?

Simple Explanation: Known Hosts is a security feature that remembers the "fingerprint" (unique identifier) of each SSH server you connect to. When you connect again, it verifies the server hasn't changed.

Analogy:

Like checking someone's ID:

First visit:
- Server shows ID (host key)
- You record it in your address book (known_hosts)

Next visit:
- Server shows ID again
- You check: "Is this the same ID as before?"
- If yes: Safe to connect ✓
- If no: Warning! Possible imposter! ⚠️

Why It's Important

Security Protection

Prevents Man-in-the-Middle Attacks:

Without verification:
You → Attacker's Server (pretending to be yours) → Your Real Server
         ↑ Attacker sees everything!

With verification:
You → Unknown Server
      ↑ Fingerprint doesn't match!
      ⚠️ WARNING: Host key changed!
      ✗ Connection blocked

Real-world scenario:

You: Connect to production server
SSH: Warning! Host key has changed!

Reasons (good):
✓ Server was reinstalled
✓ SSH was updated
✓ IP address changed

Reasons (bad):
✗ Someone intercepting connection
✗ DNS hijacked
✗ You're connecting to wrong server

How It Works

First Connection

What happens:

1. You connect to server (first time)
   ssh user@server.com

2. Server sends its public key (fingerprint)

3. SSH shows warning:
   ┌────────────────────────────────────────┐
   │ The authenticity of host 'server.com'  │
   │ can't be established.                  │
   │                                        │
   │ ED25519 key fingerprint is:            │
   │ SHA256:abcd1234...xyz7890               │
   │                                        │
   │ Are you sure you want to continue?     │
   │ [yes/no]                               │
   └────────────────────────────────────────┘

4. You verify fingerprint (if possible)
   - Contact server admin
   - Check server console
   - Verify through other channel

5. You accept: "yes"

6. Fingerprint saved in known_hosts
   
7. Future connections: Automatic verification ✓

Subsequent Connections

Automatic verification:

1. You connect: ssh user@server.com

2. Server sends fingerprint

3. SSH compares with saved fingerprint

4. If match: Connection proceeds ✓

5. If different: Connection blocked ⚠️

Known Hosts in Xermius

Viewing Known Hosts

Access:

1. Sidebar → "Known Hosts"
2. Or: Settings → Security → Known Hosts

Interface:

┌────────────────────────────────────────────────┐
│ Known Hosts                        [Import] [▼]│
├────────────────────────────────────────────────┤
│ [🔍 Search]  [Key Type ▼]  [Status ▼]         │
├────────────────────────────────────────────────┤
│                                                │
│ ✓ production.example.com          ED25519     │
│   SHA256:abc123...                 Trusted     │
│   Last verified: 2 hours ago                   │
│                                                │
│ ⚠ staging.example.com              RSA         │
│   SHA256:def456...                 Warning     │
│   Last verified: Never                         │
│                                                │
│ ✗ old-server.com                   ECDSA       │
│   SHA256:ghi789...                 Revoked     │
│   Last verified: 3 months ago                  │
│                                                │
└────────────────────────────────────────────────┘

Known Host Details

View details:

Click on any known host

┌────────────────────────────────────────────────┐
│ Known Host Details                      [Edit] │
├────────────────────────────────────────────────┤
│ Hostname:                                      │
│ production.example.com                         │
│                                                │
│ IP Address:                                    │
│ 192.168.1.100                                  │
│                                                │
│ Port:                                          │
│ 22                                             │
│                                                │
│ Key Type:                                      │
│ ssh-ed25519                                    │
│                                                │
│ Fingerprint (SHA256):                          │
│ abc123def456ghi789jkl012mno345pqr678stu901     │
│                                                │
│ Fingerprint (MD5):                             │
│ 01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab     │
│                                                │
│ Trust Status:                                  │
│ [✓] Trusted                                    │
│                                                │
│ First Seen:                                    │
│ Jan 15, 2024 10:30 AM                          │
│                                                │
│ Last Verified:                                 │
│ 2 hours ago (Jan 17, 2024 2:45 PM)            │
│                                                │
│ Verification Count:                            │
│ 47 times                                       │
│                                                │
│ Comment:                                       │
│ Production web server - verified 2024-01-15    │
│                                                │
│        [Update Trust]  [Delete]  [Close]       │
└────────────────────────────────────────────────┘

Trust Status Levels

1. Trusted (Green ✓)

Meaning:

• Host key verified and accepted
• Safe to connect
• Regular use

When set:

• First connection accepted
• Manually marked as trusted
• Imported from system SSH

Indicators:

• Green checkmark ✓
• "Trusted" badge
• No warnings on connection

2. Warning (Yellow ⚠)

Meaning:

• Host key not verified yet
• Requires attention
• Use with caution

When set:

• First time seen (pending verification)
• Manually marked for review
• Suspicious activity detected

Indicators:

• Yellow warning ⚠
• "Warning" badge
• Prompt on connection

What to do:

1. Verify fingerprint:
   - Contact server admin
   - Check server console
   - Compare with records

2. If correct:
   → Change to "Trusted"

3. If incorrect:
   → Change to "Revoked"
   → Don't connect!

3. Revoked (Red ✗)

Meaning:

• Host key changed unexpectedly
• Known to be compromised
• Blocked from connection

When set:

• Host key changed (automatic)
• Server compromised (manual)
• Decommissioned server (manual)

Indicators:

• Red X mark ✗
• "Revoked" badge
• Connection blocked

What to do:

1. Investigate why key changed

2. Verify it's legitimate:
   - Server reinstalled?
   - SSH updated?
   - Authorized change?

3. If legitimate:
   → Delete old entry
   → Add new key as "Trusted"

4. If suspicious:
   → Keep as "Revoked"
   → Report to security team
   → Don't connect!

Managing Known Hosts

Search and Filter

Search:

Search by:
- Hostname: production.example.com
- IP address: 192.168.1.100
- Fingerprint: SHA256:abc123...

Filter by Key Type:

Dropdown: [Key Type ▼]
- All Types
- RSA (ssh-rsa)
- ECDSA (ecdsa-sha2-nistp256)
- ED25519 (ssh-ed25519) ← Most secure

Filter by Status:

Dropdown: [Status ▼]
- All Statuses
- Trusted (✓)
- Warning (⚠)
- Revoked (✗)

Adding Host Manually

When to add:

• Before first connection (if you have fingerprint)
• After server setup
• When migrating

Steps:

1. Click "Add Known Host"

2. Fill in details:
   Hostname: production.example.com
   Port: 22
   Key Type: ssh-ed25519
   Fingerprint: [paste from server]
   Trust Status: Trusted
   Comment: Production server, added 2024-01-17

3. Click "Add"

4. Host ready for connection

Updating Trust Status

Change trust level:

1. Find host in list

2. Click to open details

3. Click "Update Trust"

4. Choose new status:
   [✓] Trusted
   [⚠] Warning
   [✗] Revoked

5. Add reason (optional):
   "Server reinstalled - verified via console"

6. Save

7. Status updated

Deleting Known Hosts

Single delete:

1. Click host

2. Click "Delete" button

3. Confirm:
   "Delete known host for production.example.com?"
   [Cancel] [Delete]

4. Host removed

Bulk delete:

1. Select multiple hosts (Ctrl+Click)

2. Right-click → "Delete Selected"

3. Confirm:
   "Delete 3 known hosts?"
   [Cancel] [Delete]

4. Hosts removed

Delete all:

1. Menu → "Delete All Known Hosts"

2. Warning shown:
   ⚠️ This will delete ALL known hosts!
   You'll need to verify servers again.
   
   Type "DELETE ALL" to confirm:
   [_____________]

3. Type confirmation

4. All hosts removed

Import & Export

Export to File

OpenSSH format:

1. Click "Export" → "OpenSSH Format"

2. Choose location:
   Save as: known_hosts
   Location: ~/Documents/

3. File created:
   production.example.com ssh-ed25519 AAAAC3...
   staging.example.com ssh-rsa AAAAB3...
   
4. Compatible with:
   - Standard SSH clients
   - Other terminals
   - Backup purposes

JSON backup:

1. Click "Export" → "Backup (JSON)"

2. Choose location:
   Save as: known_hosts_backup_20240117.json
   
3. File created with all data:
   {
     "version": "1.0",
     "createdAt": "2024-01-17T10:30:00Z",
     "count": 15,
     "hosts": [...]
   }

4. Includes:
   - All metadata
   - Trust status
   - Comments
   - Verification history

Import from File

From OpenSSH format:

1. Click "Import" → "From File"

2. Select file:
   ~/ssh_backups/known_hosts

3. Preview shown:
   ┌──────────────────────────────────────┐
   │ Import Preview                       │
   ├──────────────────────────────────────┤
   │ Found 12 hosts                       │
   │                                      │
   │ ✓ 8 new hosts (will add)             │
   │ ⚠ 3 conflicts (already exist)        │
   │ ✗ 1 error (invalid format)           │
   │                                      │
   │ Conflicts:                           │
   │ • production.example.com             │
   │   [Skip] [Replace] [Keep Both]       │
   │                                      │
   │      [Cancel]  [Import]              │
   └──────────────────────────────────────┘

4. Handle conflicts:
   - Skip: Don't import (keep existing)
   - Replace: Overwrite existing
   - Keep Both: Import with different name

5. Complete import

From JSON backup:

1. Click "Import" → "Restore from Backup"

2. Select JSON file:
   known_hosts_backup_20240115.json

3. Preview and resolve conflicts

4. Restore with full metadata:
   - Trust status preserved
   - Comments restored
   - History maintained

Import from System SSH

From ~/.ssh/known_hosts:

1. Click "Import" → "From System SSH"

2. Scans: ~/.ssh/known_hosts

3. Shows preview:
   ┌──────────────────────────────────────┐
   │ Import from System SSH               │
   ├──────────────────────────────────────┤
   │ Found 25 hosts in:                   │
   │ ~/.ssh/known_hosts                   │
   │                                      │
   │ ✓ 20 new hosts                       │
   │ ⚠ 5 already in Xermius (skip)        │
   │                                      │
   │ [Cancel]  [Import All]               │
   └──────────────────────────────────────┘

4. Import automatically:
   - Sets all as "Trusted"
   - Adds comment: "Imported from system"
   - Preserves fingerprints

5. Complete

Benefits:

• Quick migration to Xermius
• Preserve existing trust
• No re-verification needed

Verification Workflow

When Connecting

First time connection:

1. You connect to new server

2. Xermius shows prompt:
   ┌────────────────────────────────────────┐
   │ Unknown Host                           │
   ├────────────────────────────────────────┤
   │ You're connecting to:                  │
   │ production.example.com (192.168.1.100) │
   │                                        │
   │ Host fingerprint:                      │
   │ ED25519: SHA256:abc123def456...        │
   │ MD5: 01:23:45:67:89:ab:cd:ef           │
   │                                        │
   │ ⚠️ Verify this fingerprint before      │
   │ accepting!                             │
   │                                        │
   │ [Cancel]  [Trust Once]  [Trust Always]│
   └────────────────────────────────────────┘

3. Choose action:
   - Trust Once: Connect now, ask again next time
   - Trust Always: Save and auto-verify future
   - Cancel: Don't connect

4. If "Trust Always":
   → Added to Known Hosts
   → Future connections automatic

Host key changed:

1. You connect to known server

2. Xermius detects change:
   ┌────────────────────────────────────────┐
   │ ⚠️ WARNING: HOST KEY CHANGED!          │
   ├────────────────────────────────────────┤
   │ The fingerprint for                    │
   │ production.example.com                 │
   │ has changed!                           │
   │                                        │
   │ Old fingerprint:                       │
   │ SHA256:abc123def456...                 │
   │                                        │
   │ New fingerprint:                       │
   │ SHA256:xyz789uvw012...                 │
   │                                        │
   │ ⚠️ This could mean:                     │
   │ • Server was reinstalled               │
   │ • Man-in-the-middle attack             │
   │ • Wrong server                         │
   │                                        │
   │ DO NOT CONNECT unless you know why!    │
   │                                        │
   │ [Cancel]  [View Details]  [Update Key] │
   └────────────────────────────────────────┘

3. Investigate:
   - Contact server admin
   - Check server console
   - Verify legitimacy

4. If legitimate:
   → Click "Update Key"
   → Add reason
   → Save new fingerprint

5. If suspicious:
   → Cancel connection
   → Report to security
   → Mark as "Revoked"

Security Best Practices

1. Verify Fingerprints

Always verify on first connection:

DON'T:
✗ Blindly accept fingerprints
✗ Trust without verification
✗ Ignore warnings

DO:
✓ Get fingerprint from admin
✓ Check server console
✓ Verify through separate channel
✓ Compare carefully

How to get server fingerprint:

# On the server, run:
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

# Output:
256 SHA256:abc123def456... root@server (ED25519)
       ↑ This should match client's shown fingerprint

2. Prefer ED25519 Keys

Key type security:

Most Secure:
✓ ED25519 (recommended)
  - Modern, fast, secure
  - Small keys, strong security

Secure:
✓ ECDSA
  - Good security
  - Smaller than RSA

Legacy:
⚠ RSA (2048+ bits)
  - Still secure if large enough
  - Avoid RSA < 2048 bits

Check server key types:

# On server
ls -la /etc/ssh/ssh_host_*_key.pub

# Prefer ED25519
ssh_host_ed25519_key.pub  ← Use this

3. Regular Audits

Monthly review:

1. Open Known Hosts

2. Review each entry:
   - Still in use?
   - Trust status correct?
   - Last verified recently?

3. Clean up:
   - Delete unused hosts
   - Update comments
   - Verify suspicious entries

4. Export backup

4. Document Changes

Add comments:

Good comments:
✓ "Production web server - verified 2024-01-15"
✓ "Key updated due to server reinstall (ticket #1234)"
✓ "Staging environment - rotate monthly"

Bad comments:
✗ "server"
✗ ""
✗ "prod"

5. Backup Regularly

Backup schedule:

Weekly: Export JSON backup
Monthly: Export OpenSSH format
Before: Major changes, migrations

6. Handle Warnings Seriously

Never ignore:

⚠️ Host key changed → STOP!
⚠️ Unknown host → Verify!
⚠️ Revoked host → Don't connect!

Investigate before proceeding!

Troubleshooting

Can't Connect - Host Key Mismatch

Issue: Server's key doesn't match saved fingerprint

Causes:

• Server reinstalled
• SSH updated
• IP address reused
• Security breach

Solution:

1. Verify legitimate change:
   - Contact admin
   - Check change logs
   - Confirm reason

2. If legitimate:
   Option A - Update:
   - Find host in Known Hosts
   - Click "Update Key"
   - Save new fingerprint
   
   Option B - Delete and reconnect:
   - Delete old entry
   - Reconnect (will add new)

3. If suspicious:
   - Don't connect!
   - Report to security
   - Investigate

Lost All Known Hosts

Issue: Known hosts database empty

Solutions:

Restore from backup:

1. Import → "Restore from Backup"
2. Select latest .json backup
3. Restore all hosts

Import from system SSH:

1. Import → "From System SSH"
2. Imports from ~/.ssh/known_hosts
3. All system hosts added

Manually re-add:

Connect to each server
Accept new fingerprints
Verify carefully

Import Failed

Issue: Import shows errors

Common errors:

"Invalid format"
→ File not in correct format
→ Try different import method

"Duplicate entries"
→ Hosts already exist
→ Choose "Replace" or "Skip"

"Empty file"
→ No hosts found
→ Check file path

Can't Delete Host

Issue: Delete button disabled

Causes:

• Host currently in use (active connection)
• Database locked

Solution:

1. Close all connections to that host
2. Wait a moment
3. Try delete again

Integration with SSH

How Xermius Uses Known Hosts

Two storage locations:

1. Xermius database:
   - Full metadata
   - Trust status
   - Comments
   - History

2. System known_hosts (optional):
   - Standard format
   - Compatible with other tools
   - Sync available

Sync options:

Settings → Security → Known Hosts

[✓] Sync with system SSH
    - Auto-update ~/.ssh/known_hosts
    - Two-way sync
    - Keep both in sync

[ ] Use Xermius only
    - Independent storage
    - More features
    - Not compatible with other tools

OpenSSH Compatibility

Export format:

Standard OpenSSH format:
hostname ssh-keytype public-key

Example:
production.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...
192.168.1.100 ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB...

Import support:

✓ Standard known_hosts files
✓ Hashed hostnames
✓ Multiple key types
✓ IP addresses
✓ Port numbers ([host]:port)

Next Steps

• 🔐 Host Key Verification - Detailed verification process
• 🛡️ Trust Management - Managing trust levels
• 🔗 Creating SSH Connections - Connect to servers
• 🔒 Security Best Practices - Complete security guide