SSH Key Safety Pre-Flight

The most important safety feature in StackSentry’s auto-fix engine is the SSH key pre-flight for HOST-SSH-001. This page explains exactly what happens and why.

The Problem

HOST-SSH-001 applies PermitRootLogin prohibit-password to harden SSH access. This is the right security control — it prevents brute-force attacks on the root password.

But if you are currently authenticating with a password and you apply this change, you will be permanently locked out of your server. The change takes effect on the next SSH session — and your password will no longer work.

Standard auto-fix tools apply this change without warning. StackSentry does not.

The Four-Step Pre-Flight

When --fix is used with --ssh-password and HOST-SSH-001 needs to be applied, StackSentry runs a four-step pre-flight before touching sshd_config:

Step 1: Generate Ed25519 key pair locally
        Private key → ~/.stacksentry/keys/server_20260411_123456.pem
        Public key  → ~/.stacksentry/keys/server_20260411_123456.pub
 
Step 2: Install public key on the server
        Uses the existing password session to append the key to
        ~/.ssh/authorized_keys on the remote host
 
Step 3: Verify key login works
        Opens a new SSH connection using ONLY the new key
        Does NOT use the password for this test
 
Step 4: Apply PermitRootLogin prohibit-password
        Only if Step 3 succeeded
        Modifies /etc/ssh/sshd_config
        Restarts sshd

If Step 3 fails for any reason: sshd_config is never touched. The engine reports exactly what went wrong and exits.

Dry-Run Output

Running with --dry-run shows the full plan before anything happens:

⚠️  PASSWORD → KEY MIGRATION REQUIRED
    This fix disables root password login (PermitRootLogin prohibit-password).
    Since you are using --ssh-password, StackSentry will first:
 
    Step 1: Generate Ed25519 key pair locally
            Private key → ~/.stacksentry/keys/YOUR-SERVER-IP_20260411_123456.pem
 
    Step 2: Install public key on YOUR_SERVER_IP
    Step 3: Verify key login works (test connection before changing sshd)
    Step 4: Apply PermitRootLogin prohibit-password
 
    After applying, connect with:
    ssh -i ~/.stacksentry/keys/YOUR-SERVER-IP_20260411_123456.pem root@YOUR_SERVER_IP
 
    Run without --dry-run to apply.

Key Generation Details

Ed25519 is preferred for its shorter key length and stronger security guarantees. RSA 4096 is used as a fallback for environments running Paramiko versions older than 3.x that do not support Ed25519Key.generate().

After the Fix

Once HOST-SSH-001 is applied successfully, save the key path and use it for all future connections:

# Future SSH connections
ssh -i ~/.stacksentry/keys/server_20260411_123456.pem root@your-server-ip
 
# Future StackSentry scans
stacksentry -t https://your-app.com --mode full --fix \
  --ssh-host your-server-ip --ssh-user root \
  --ssh-key ~/.stacksentry/keys/server_20260411_123456.pem

Already Using a Key?

If you are already authenticating with --ssh-key, the pre-flight is skipped entirely. StackSentry detects that key-based auth is in use and applies prohibit-password directly.