dotfiles/local/bin/x-ssh-audit.md

x-ssh-audit

POSIX-compliant SSH security auditing and management script for analyzing and hardening SSH configurations across multiple hosts.

Features

• Security Auditing: Analyze SSH configurations for security issues
• Multi-Host Support: Audit multiple servers from a single host list
• Smart Authentication: Automatic SSH key detection with intelligent fallback
• Comprehensive Checks: Password auth, root login, key auth, empty passwords, X11 forwarding
• System Analysis: Automated updates detection, pending reboot status
• Auto-Remediation: Optional automatic security hardening
• Detailed Reporting: CSV reports and comprehensive logs
• POSIX Compliant: Works with sh, dash, bash, ksh, zsh

Usage

x-ssh-audit <host_list_file> [auto-remediate:yes|no]

Host List File Format

hostname:username[:ssh_key]

• hostname – The host to connect to (FQDN or IP address)
• username – SSH username for authentication
• ssh_key – (Optional) Path to SSH private key file

SSH Key Authentication Priority

The script automatically tries authentication methods in this order:

1. Specific key (if provided in host file)
2. Auto-detected default keys (~/.ssh/id_ed25519, id_rsa, id_ecdsa, id_dsa)
3. SSH agent or system default authentication

This means you can mix hosts with and without specific keys, and the script will intelligently try all available authentication methods.

Host List Examples

# Simple format without specific SSH keys
server1.example.com:admin
192.168.1.10:root

# With specific SSH keys
production.example.com:deploy:~/.ssh/production_key
staging.example.com:staging-user:~/.ssh/staging_key
database.example.com:dbadmin:/home/user/.ssh/db_server_key

# Cloud instances with specific keys
aws-instance.compute.amazonaws.com:ec2-user:~/.ssh/aws-keypair.pem
gcp-instance.compute.google.com:ubuntu:~/.ssh/gcp-instance-key

# Mixed authentication (specific keys + fallback)
cluster-node-01.example.com:cluster-admin:~/.ssh/cluster_key
cluster-node-02.example.com:cluster-admin
cluster-node-03.example.com:cluster-admin

Usage Examples

# Basic audit
x-ssh-audit hosts.txt

# Audit with automatic remediation
x-ssh-audit hosts.txt yes

# Review results
cat ./ssh-audit/20251017_143022/report.csv
tail ./ssh-audit/20251017_143022/log.log

Output Structure

All output is organized in a timestamped directory:

./ssh-audit/
└── 20251017_143022/
    ├── backup/          # SSH config backups from remote hosts
    ├── tmp/             # Temporary state files (auto-cleaned)
    ├── log.log          # Detailed audit log with timestamps
    └── report.csv       # Summary report with all findings

Security Checks

• Password Authentication: Warns if password auth is enabled
• Root Login: Warns if root login is not disabled
• Empty Passwords: Error if empty passwords are permitted
• X11 Forwarding: Warns if X11 forwarding is enabled
• Public Key Authentication: Verifies key-based auth is available
• SSH Protocol: Checks protocol version
• Automated Updates: Detects if automatic updates are configured
• Pending Reboots: Checks if system requires reboot

Auto-Remediation

When enabled, the script will:

1. Create backups of SSH configurations
2. Disable password authentication
3. Ensure key-based authentication is required
4. Disable root login
5. Set conservative SSH connection limits
6. Reload SSH daemon with new configuration
7. Generate updated report with remediation status

Configuration

Fallback usernames (tried if primary user fails):

FALLBACK_USERS="root ubuntu ivuorinen"

Default SSH keys (automatically detected):

~/.ssh/id_ed25519
~/.ssh/id_rsa
~/.ssh/id_ecdsa
~/.ssh/id_dsa

SSH connection parameters:

SSH_TIMEOUT=10
SSH_RETRIES=3

Requirements

• POSIX-compliant shell (sh, dash, bash, ksh, zsh)
• SSH client with key-based authentication
• sudo access on remote hosts for configuration changes
• Standard Unix utilities: cut, grep, sed, awk, wc

Exit Codes

• 0 – Audit completed successfully
• 1 – Error occurred (check log file for details)

CSV Report Columns

• Timestamp: When the host was audited
• Hostname: The target host
• Username: Connected username
• SSH Status: Connection status (audited, connection_failed)
• Password Auth: Password authentication status (yes/no)
• Key Auth: Public key authentication status (yes/no)
• Root Login: Root login permission status
• Auto Updates: Automated updates status
• Reboot Required: Pending reboot status (yes/no)
• Security Issues: Number of security issues found
• Remediation: Remediation status (none, success, failed)

Supported Distributions

• Debian/Ubuntu: unattended-upgrades detection
• RHEL/CentOS/Rocky/AlmaLinux/Fedora: dnf-automatic and yum-cron detection
• Other: Basic SSH security checks

Tips

1. Test First: Run without auto-remediation first to review findings
2. Backup Keys: Ensure you have backup SSH keys before hardening
3. Staged Rollout: Test on non-critical hosts first
4. Review Logs: Check log files for detailed information
5. Preserve Access: Script ensures key-based auth works before disabling passwords

Version

Version: 2.0-POSIX Date: 2025-10-17 License: MIT Author: Ismo Vuorinen https://github.com/ivuorinen