{"id":30705337,"url":"https://github.com/billchurch/ssh_test","last_synced_at":"2026-03-01T13:05:45.230Z","repository":{"id":311479384,"uuid":"1043813481","full_name":"billchurch/ssh_test","owner":"billchurch","description":"A fully configurable SSH server Docker container designed specifically for integration testing, development, and SSH client validation. Built with security best practices and complete runtime configurability.","archived":false,"fork":false,"pushed_at":"2026-02-09T15:14:24.000Z","size":152,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-09T19:44:06.703Z","etag":null,"topics":["automation","ci","ci-cd","cicd","ssh","ssh-server","test-automation","testing","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/billchurch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-24T17:12:32.000Z","updated_at":"2026-02-09T15:14:20.000Z","dependencies_parsed_at":"2025-08-24T22:00:08.513Z","dependency_job_id":"29f1f1d5-15f2-41fe-aea2-65eb7b5d137d","html_url":"https://github.com/billchurch/ssh_test","commit_stats":null,"previous_names":["billchurch/ssh_test"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/billchurch/ssh_test","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billchurch%2Fssh_test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billchurch%2Fssh_test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billchurch%2Fssh_test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billchurch%2Fssh_test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/billchurch","download_url":"https://codeload.github.com/billchurch/ssh_test/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/billchurch%2Fssh_test/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29969715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T12:56:10.327Z","status":"ssl_error","status_checked_at":"2026-03-01T12:55:24.744Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","ci","ci-cd","cicd","ssh","ssh-server","test-automation","testing","testing-tools"],"created_at":"2025-09-02T18:53:16.304Z","updated_at":"2026-03-01T13:05:45.224Z","avatar_url":"https://github.com/billchurch.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SSH Test Server\n\n[![Build and Push](https://github.com/billchurch/ssh_test/actions/workflows/build-and-push.yml/badge.svg)](https://github.com/billchurch/ssh_test/actions/workflows/build-and-push.yml)\n[![Integration Tests](https://github.com/billchurch/ssh_test/actions/workflows/test.yml/badge.svg)](https://github.com/billchurch/ssh_test/actions/workflows/test.yml)\n\nA fully configurable SSH server Docker container designed specifically for integration testing, development, and SSH client validation. Built with security best practices and complete runtime configurability.\n\n**Available in three optimized variants:**\n\n- **Debian-based** (`ghcr.io/billchurch/ssh_test:debian`): 118MB - Maximum compatibility with full GNU toolchain\n- **Alpine-based** (`ghcr.io/billchurch/ssh_test:alpine`): 13.8MB - Ultra-minimal footprint for resource-constrained environments\n- **Dropbear** (`ghcr.io/billchurch/ssh_test:dropbear`): ~5MB - BusyBox-style SSH with SCP but **no SFTP** ([webssh2 #483](https://github.com/billchurch/webssh2/issues/483))\n\n## Features\n\n- 🔧 **Fully Configurable**: All SSH settings configurable via environment variables\n- 🔐 **Multiple Auth Methods**: Password, public key, and keyboard-interactive authentication\n- 🏗️ **Multi-Architecture**: Supports AMD64 and ARM64 architectures\n- 🍎 **Apple Container Ready**: Native support for Apple Container on Apple Silicon Macs\n- 🛡️ **Security Focused**: Configurable security hardening options\n- 🐛 **Debug Support**: Adjustable SSH debug levels with proper logging\n- 📊 **CI/CD Ready**: Automated builds, testing, and container registry publishing\n- 🧪 **Testing Tools**: Comprehensive test scripts and integration tests included\n- 📡 **Optional Telnet**: Built-in telnet server for terminal client testing (Debian only)\n\n## Quick Start\n\nYou can run the SSH test server using Docker, Docker Compose, or Apple Container (for macOS with Apple Silicon).\n\n### Choosing Your Image\n\nChoose the image variant that best fits your needs:\n\n```bash\n# Alpine - Ultra-minimal (13.8MB)\ndocker pull ghcr.io/billchurch/ssh_test:alpine\n\n# Debian - Full compatibility (118MB, default)\ndocker pull ghcr.io/billchurch/ssh_test:debian\n# or\ndocker pull ghcr.io/billchurch/ssh_test:latest  # same as debian\n\n# Dropbear - SCP only, no SFTP (~5MB)\ndocker pull ghcr.io/billchurch/ssh_test:dropbear\n```\n\n### Using Docker\n\n```bash\n# Basic password authentication (Alpine - minimal)\ndocker run -d --name ssh-test-alpine \\\n  -p 2225:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass123 \\\n  ghcr.io/billchurch/ssh_test:alpine\n\n# Basic password authentication (Debian - full compatibility)\ndocker run -d --name ssh-test-debian \\\n  -p 2224:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass123 \\\n  ghcr.io/billchurch/ssh_test:debian\n\n# Dropbear - SCP only, no SFTP (simulates BusyBox devices)\ndocker run -d --name ssh-test-dropbear \\\n  -p 2226:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass123 \\\n  ghcr.io/billchurch/ssh_test:dropbear\n\n# Test the connections\nssh -p 2225 testuser@localhost  # Alpine\nssh -p 2224 testuser@localhost  # Debian\nssh -p 2226 testuser@localhost  # Dropbear\n```\n\n### Using Docker Compose\n\n```bash\n# Clone the repository\ngit clone https://github.com/billchurch/ssh-test-server.git\ncd ssh-test-server/examples\n\n# Run Alpine version (minimal)\ndocker-compose --profile alpine up -d\n\n# Run Debian version (full compatibility)\ndocker-compose --profile debian up -d\n\n# Run both versions simultaneously\ndocker-compose --profile all up -d\n\n# Run Dropbear version (SCP only, no SFTP)\ndocker-compose --profile dropbear up -d\n\n# Telnet server (Debian with telnet enabled)\ndocker-compose --profile telnet up -d\n\n# Traditional profiles still available\ndocker-compose --profile basic up -d        # Basic password auth\ndocker-compose --profile pubkey up -d       # Public key auth only\ndocker-compose --profile hardened up -d     # Security hardened\ndocker-compose --profile scp-only up -d     # SCP-only testing alias\n```\n\n### Using Apple Container (macOS with Apple Silicon)\n\n[Apple Container](https://github.com/apple/container) is Apple's native tool for running Linux containers as lightweight VMs on Apple Silicon Macs. The SSH test server works seamlessly with Apple Container since it produces OCI-compatible images.\n\n#### Requirements\n\n- Mac with Apple Silicon (M1/M2/M3/M4)\n- macOS 26 (latest beta)\n- Apple Container installed: `brew install apple/tools/container`\n\n#### First-Time Setup\n\nBefore running containers, start the container system (one-time setup):\n\n```bash\n# Start the container system (will prompt to install kernel if needed)\ncontainer system start\n```\n\nThe first time you run this, it will prompt to install the recommended default kernel. Accept the prompt to continue.\n\n#### Basic Usage\n\n```bash\n# Pull and run Alpine variant (minimal - 13.8MB)\ncontainer run --rm -d --name ssh-test-alpine \\\n  -p 2224:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpassword \\\n  --cpus 1 \\\n  --memory 96mb \\\n  ghcr.io/billchurch/ssh_test:alpine\n\n# Pull and run Debian variant (full compatibility - 118MB)\ncontainer run --rm -d --name ssh-test-debian \\\n  -p 2224:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass123 \\\n  --cpus 1 \\\n  --memory 96mb \\\n  ghcr.io/billchurch/ssh_test:debian\n\n# Test the connections\nssh -p 2225 testuser@localhost  # Alpine\nssh -p 2224 testuser@localhost  # Debian\n\n# View logs\ncontainer logs ssh-test-alpine\n\n# Stop and remove\ncontainer stop ssh-test-alpine\ncontainer rm ssh-test-alpine\n```\n\n#### Public Key Authentication with Apple Container\n\n```bash\n# Generate a test key\nssh-keygen -t ed25519 -f test_key -N \"\"\n\n# Start container with public key\ncontainer run -d --name ssh-key-test \\\n  -p 2224:22 \\\n  -e SSH_USER=keyuser \\\n  -e \"SSH_AUTHORIZED_KEYS=$(cat test_key.pub)\" \\\n  -e SSH_PERMIT_PASSWORD_AUTH=no \\\n  -e SSH_PERMIT_PUBKEY_AUTH=yes \\\n  ghcr.io/billchurch/ssh_test:alpine\n\n# Connect with the key\nssh -i test_key -p 2224 keyuser@localhost\n```\n\n**Note**: All Docker examples in this README work with Apple Container by replacing `docker` with `container`. Apple Container uses the same command-line interface and options as Docker.\n\n## Configuration\n\nAll configuration is done through environment variables:\n\n### Basic Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `SSH_USER` | `testuser` | SSH username to create |\n| `SSH_PASSWORD` | *(empty)* | Password for the SSH user |\n| `SSH_PORT` | `22` | SSH server port |\n| `SSH_DEBUG_LEVEL` | `0` | Debug level (0=none, 1=verbose, 2=debug, 3=debug3) |\n\n### Authentication Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `SSH_PERMIT_PASSWORD_AUTH` | `yes` | Enable password authentication |\n| `SSH_PERMIT_PUBKEY_AUTH` | `yes` | Enable public key authentication |\n| `SSH_CHALLENGE_RESPONSE_AUTH` | `no` | Enable keyboard-interactive auth |\n| `SSH_AUTHORIZED_KEYS` | *(empty)* | SSH public keys (newline separated) |\n| `SSH_AUTH_METHODS` | `any` | Specific auth methods to require |\n\n### Security Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `SSH_PERMIT_ROOT_LOGIN` | `no` | Allow root login |\n| `SSH_PERMIT_EMPTY_PASSWORDS` | `no` | Allow empty passwords |\n| `SSH_MAX_AUTH_TRIES` | `6` | Maximum authentication attempts |\n| `SSH_LOGIN_GRACE_TIME` | `120` | Login grace time in seconds |\n| `SSH_USE_DNS` | `no` | Perform DNS lookups |\n\n### Forwarding Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `SSH_X11_FORWARDING` | `no` | Enable X11 forwarding |\n| `SSH_AGENT_FORWARDING` | `no` | Enable SSH agent forwarding |\n| `SSH_TCP_FORWARDING` | `no` | Enable TCP forwarding |\n\n### Telnet Configuration (Debian Only)\n\nThe Debian image includes an optional telnet server for testing terminal clients against a plaintext protocol. Disabled by default.\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `TELNET_ENABLED` | `no` | Enable telnet server (`yes`/`no`) |\n| `TELNET_PORT` | `23` | Telnet server port |\n\nAuthentication reuses `SSH_USER` and `SSH_PASSWORD` — telnet spawns `/bin/login` which authenticates against the system user.\n\n### SSH Agent Configuration\n\nThe SSH test server includes comprehensive SSH agent support for testing agent-based authentication and forwarding scenarios.\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `SSH_AGENT_START` | `no` | Start internal SSH agent in container |\n| `SSH_AGENT_KEYS` | *(empty)* | Base64-encoded private keys to load into agent (newline-separated) |\n| `SSH_AGENT_SOCKET_PATH` | `/tmp/ssh-agent.sock` | Custom path for SSH agent socket |\n\n#### SSH Agent Features\n\n- **Internal Agent**: Start an SSH agent inside the container with `SSH_AGENT_START=yes`\n- **Key Loading**: Automatically load private keys into the agent using `SSH_AGENT_KEYS`\n- **Agent Forwarding**: Allow client agents to be forwarded with `SSH_AGENT_FORWARDING=yes`\n- **Custom Socket**: Use custom socket paths for testing specific scenarios\n- **Environment Setup**: Automatically configures user environment for agent access\n\n#### SSH Agent Security Notes\n\n⚠️ **Important**: The `SSH_AGENT_KEYS` variable contains sensitive private key data. In production or CI/CD environments:\n\n- Load keys from secure environment variables or secrets management\n- Never commit private keys to version control\n- Use temporary keys for testing when possible\n- Consider using key passphrases for additional security\n\n### Advanced Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `SSH_HOST_KEYS` | *(auto-generated)* | Custom host keys (base64 encoded) |\n| `SSH_CUSTOM_CONFIG` | *(empty)* | Additional sshd_config directives |\n| `SSH_USE_PAM` | `no` | Use PAM for authentication |\n\n#### SSH_CUSTOM_CONFIG Examples\n\nThe `SSH_CUSTOM_CONFIG` environment variable allows you to add any additional SSH configuration directives that aren't explicitly handled by other environment variables. Multiple directives can be stacked using newlines.\n\n```bash\n# Allow specific environment variables from SSH client\ndocker run -d \\\n  -p 2244:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpassword \\\n  -e SSH_AUTHORIZED_KEYS=\"$(cat ./test-keys/*.pub)\" \\\n  -e SSH_DEBUG_LEVEL=3 \\\n  -e SSH_PERMIT_PASSWORD_AUTH=yes \\\n  -e SSH_PERMIT_PUBKEY_AUTH=yes \\\n  -e SSH_CUSTOM_CONFIG=$'PermitUserEnvironment yes\\nAcceptEnv FOO' \\\n  ghcr.io/billchurch/ssh_test:alpine\n\n# Multiple custom configurations\ndocker run -d \\\n  -e SSH_CUSTOM_CONFIG=$'MaxSessions 10\\nClientAliveInterval 30\\nClientAliveCountMax 3' \\\n  ghcr.io/billchurch/ssh_test:alpine\n```\n\n## Usage Examples\n\n### Password Authentication Only\n\n```bash\ndocker run -d --name ssh-password-test \\\n  -p 2224:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=secure123 \\\n  -e SSH_PERMIT_PASSWORD_AUTH=yes \\\n  -e SSH_PERMIT_PUBKEY_AUTH=no \\\n  ghcr.io/billchurch/ssh_test:latest\n```\n\n### Public Key Authentication Only\n\n```bash\n# Generate a test key\nssh-keygen -t ed25519 -f test_key -N \"\"\n\n# Start container with public key\ndocker run -d --name ssh-key-test \\\n  -p 2224:22 \\\n  -e SSH_USER=keyuser \\\n  -e \"SSH_AUTHORIZED_KEYS=$(cat test_key.pub)\" \\\n  -e SSH_PERMIT_PASSWORD_AUTH=no \\\n  -e SSH_PERMIT_PUBKEY_AUTH=yes \\\n  ghcr.io/billchurch/ssh_test:latest\n\n# Connect with the key\nssh -i test_key -p 2224 keyuser@localhost\n```\n\n**Note:** When no password is provided (`SSH_PASSWORD` not set), the user account is automatically unlocked by setting a dummy password hash (`*`) to enable SSH key authentication while still preventing password logins.\n\n### Security Hardened Configuration\n\n```bash\ndocker run -d --name ssh-secure-test \\\n  -p 2224:22 \\\n  -e SSH_USER=secureuser \\\n  -e SSH_PASSWORD=VerySecureP@ss123 \\\n  -e SSH_PERMIT_ROOT_LOGIN=no \\\n  -e SSH_MAX_AUTH_TRIES=3 \\\n  -e SSH_LOGIN_GRACE_TIME=60 \\\n  -e SSH_USE_DNS=no \\\n  -e SSH_X11_FORWARDING=no \\\n  -e SSH_AGENT_FORWARDING=no \\\n  -e SSH_TCP_FORWARDING=no \\\n  ghcr.io/billchurch/ssh_test:latest\n```\n\n### Debug Mode\n\n```bash\ndocker run -d --name ssh-debug-test \\\n  -p 2224:22 \\\n  -e SSH_USER=debuguser \\\n  -e SSH_PASSWORD=debugpass \\\n  -e SSH_DEBUG_LEVEL=3 \\\n  ghcr.io/billchurch/ssh_test:latest\n\n# View debug logs\ndocker logs -f ssh-debug-test\n```\n\n### SSH Agent Examples\n\n#### Basic Agent with Forwarding\n\n```bash\ndocker run -d --name ssh-agent-test \\\n  -p 2224:22 \\\n  -e SSH_USER=agentuser \\\n  -e SSH_PASSWORD=agentpass \\\n  -e SSH_AGENT_START=yes \\\n  -e SSH_AGENT_FORWARDING=yes \\\n  ghcr.io/billchurch/ssh_test:latest\n```\n\n#### Agent with Preloaded Keys\n\n```bash\n# Generate a test key\nssh-keygen -t ed25519 -f test_agent_key -N \"\" -C \"test@example.com\"\n\n# Encode the private key for the container\nKEY_DATA=$(base64 -i test_agent_key | tr -d '\\n')\n\n# Run container with agent and key\ndocker run -d --name ssh-agent-keys \\\n  -p 2224:22 \\\n  -e SSH_USER=keyuser \\\n  -e SSH_AUTHORIZED_KEYS=\"$(cat test_agent_key.pub)\" \\\n  -e SSH_PERMIT_PASSWORD_AUTH=no \\\n  -e SSH_AGENT_START=yes \\\n  -e SSH_AGENT_KEYS=\"${KEY_DATA}\" \\\n  ghcr.io/billchurch/ssh_test:latest\n\n# Test SSH connection using the agent\nssh -p 2224 keyuser@localhost\n\n# Cleanup\nrm -f test_agent_key test_agent_key.pub\n```\n\n#### Agent Forwarding Only (No Internal Agent)\n\n```bash\n# For testing client agent forwarding\ndocker run -d --name ssh-forwarding-test \\\n  -p 2224:22 \\\n  -e SSH_USER=forwarduser \\\n  -e SSH_PASSWORD=forwardpass \\\n  -e SSH_AGENT_FORWARDING=yes \\\n  -e SSH_AGENT_START=no \\\n  ghcr.io/billchurch/ssh_test:latest\n\n# Connect with agent forwarding enabled\nssh -A -p 2224 forwarduser@localhost\n```\n\n### Telnet Server (Debian Only)\n\n```bash\n# Run Debian image with telnet enabled\ndocker run -d --name ssh-telnet-test \\\n  -p 2224:22 \\\n  -p 2323:23 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass123 \\\n  -e TELNET_ENABLED=yes \\\n  ghcr.io/billchurch/ssh_test:debian\n\n# Connect via telnet\ntelnet localhost 2323\n\n# SSH still works alongside telnet\nssh -p 2224 testuser@localhost\n\n# Custom telnet port\ndocker run -d --name ssh-telnet-custom \\\n  -p 2224:22 \\\n  -p 8023:8023 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass123 \\\n  -e TELNET_ENABLED=yes \\\n  -e TELNET_PORT=8023 \\\n  ghcr.io/billchurch/ssh_test:debian\n```\n\n## Testing Tools\n\nThe project includes comprehensive testing tools:\n\n### Basic Connection Test\n\n```bash\n# Test password authentication\n./scripts/test-connection.sh --host localhost --port 2224 --user testuser --password testpass123\n\n# Test public key authentication\n./scripts/test-connection.sh --host localhost --port 2224 --user testuser --key ~/.ssh/id_rsa\n\n# Verbose mode\n./scripts/test-connection.sh --host localhost --port 2224 --user testuser --password testpass123 --verbose\n```\n\n### Authentication Methods Test\n\n```bash\n# Test against a running container\n./scripts/test-auth-methods.sh --container ssh-test-server --user testuser\n\n# Generate test keys and run comprehensive tests\n./scripts/test-auth-methods.sh --container ssh-test-server --user testuser --generate-keys --cleanup-keys\n```\n\n### Integration Test Suite\n\n```bash\n# Run full integration tests\n./tests/integration/run-tests.sh\n\n# Run tests with custom image\n./tests/integration/run-tests.sh --image your-custom-image:latest\n\n# Run tests in parallel with reporting\n./tests/integration/run-tests.sh --parallel --report test-results.txt\n```\n\n## Development\n\n### Building the Images\n\n```bash\n# Build both variants\nmake build-all\n\n# Build specific variants\nmake build-debian    # Debian-based image\nmake build-alpine    # Alpine-based image\nmake build-dropbear  # Dropbear-based image (SCP only, no SFTP)\n\n# Build for local testing\nmake build-dev       # Development version (Debian)\n\n# Build multi-architecture (requires buildx)\ndocker buildx build --platform linux/amd64,linux/arm64 -f docker/Dockerfile -t ssh-test-server:multi .\n```\n\n### Running Tests\n\n```bash\n# Test both image variants\nmake test-all\n\n# Test specific variants\nmake test-debian     # Test Debian image\nmake test-alpine     # Test Alpine image\nmake test-dropbear   # Test Dropbear image\n\n# Run connection tests\nmake test-connection-debian   # Test Debian container connection\nmake test-connection-alpine   # Test Alpine container connection\n\n# Run authentication tests  \nmake test-auth-debian        # Test Debian auth methods\nmake test-auth-alpine        # Test Alpine auth methods\n\n# Compare image sizes\nmake compare-sizes\n\n# Full integration test with build\nmake integration-test        # Build both + test both\n```\n\n### Contributing\n\nWe welcome contributions! This project uses automated releases and conventional commit messages.\n\n**Quick Start:**\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make changes following our [contribution guidelines](CONTRIBUTING.md)\n4. Use [conventional commit messages](https://conventionalcommits.org/): `feat: add new feature`\n5. Run tests: `./tests/integration/run-tests.sh`\n6. Submit a pull request\n\n**Important:** Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:\n\n- Conventional commit message format\n- Development workflow\n- Testing requirements  \n- Release process\n- Code style guidelines\n\n## CI/CD Pipeline\n\nThe project uses GitHub Actions for:\n\n- **Multi-architecture builds** for AMD64 and ARM64\n- **Automated testing** with comprehensive integration tests\n- **Security scanning** with Trivy vulnerability scanner\n- **Container publishing** to GitHub Container Registry\n- **SBOM generation** for supply chain security\n\n### GitHub Container Registry\n\nImages are automatically published to GitHub Container Registry:\n\n```bash\n# Latest stable release (Debian)\ndocker pull ghcr.io/billchurch/ssh_test:latest\n\n# Specific version (Debian)\ndocker pull ghcr.io/billchurch/ssh_test:v1.0.2\n\n# Specific version with variant\ndocker pull ghcr.io/billchurch/ssh_test:v1.0.2-alpine\ndocker pull ghcr.io/billchurch/ssh_test:v1.0.2-debian\ndocker pull ghcr.io/billchurch/ssh_test:v1.0.2-dropbear\n\n# Latest variant tags\ndocker pull ghcr.io/billchurch/ssh_test:alpine\ndocker pull ghcr.io/billchurch/ssh_test:debian\ndocker pull ghcr.io/billchurch/ssh_test:dropbear\n\n# Development builds\ndocker pull ghcr.io/billchurch/ssh_test:main\n```\n\n## Use Cases\n\n### Integration Testing\n\nPerfect for testing SSH clients, automation tools, and deployment scripts:\n\n```bash\n# Start test environment\ndocker-compose --profile basic up -d\n\n# Run your SSH client tests\npytest tests/ssh_client_tests.py\n\n# Cleanup\ndocker-compose --profile basic down\n```\n\n### WebSSH Testing\n\nIdeal for testing web-based SSH clients like WebSSH2:\n\n```bash\n# Start SSH test server\ndocker run -d --name webssh-test \\\n  -p 4444:22 \\\n  -e SSH_USER=webuser \\\n  -e SSH_PASSWORD=webpass123 \\\n  -e SSH_DEBUG_LEVEL=2 \\\n  ghcr.io/billchurch/ssh_test:latest\n\n# Configure your WebSSH client to connect to localhost:4444\n```\n\n### Development Environment\n\nUse as a consistent SSH target for development:\n\n```bash\n# Development setup with volume mounts\ndocker run -d --name dev-ssh \\\n  -p 2224:22 \\\n  -e SSH_USER=developer \\\n  -e SSH_PASSWORD=devpass \\\n  -v ./workspace:/home/developer/workspace \\\n  ghcr.io/billchurch/ssh_test:latest\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Container fails to start:**\n\n```bash\n# Check container logs\ndocker logs container-name\n\n# Verify environment variables\ndocker inspect container-name | jq '.Config.Env'\n```\n\n**SSH connection refused:**\n\n```bash\n# Test port connectivity\nnc -zv localhost 2224\n\n# Check if SSH service is running\ndocker exec container-name ps aux | grep sshd\n```\n\n**Authentication failures:**\n\n```bash\n# Enable debug mode\ndocker run ... -e SSH_DEBUG_LEVEL=3 ...\n\n# Check authentication configuration\ndocker exec container-name cat /etc/ssh/sshd_config\n```\n\n**SSH Public Key Authentication Issues:**\n\nWhen using public key authentication without setting a password (SSH_PASSWORD not provided), the container automatically unlocks the user account to allow key-based authentication. This is necessary because:\n\n1. Linux locks user accounts that have no password set (marked with `!` in `/etc/shadow`)\n2. SSH daemon refuses authentication to locked accounts, even with valid SSH keys\n3. The entrypoint script sets a dummy password hash (`*`) which:\n   - Unlocks the account for SSH key authentication\n   - Still prevents password-based login (no valid password can match `*`)\n\nIf you experience issues with key authentication:\n\n```bash\n# Check if user account is locked\ndocker exec container-name grep username /etc/shadow\n# If you see '!' or '!!' in the password field, the account is locked\n\n# Manually unlock (if needed)\ndocker exec container-name usermod -p '*' username\n\n# Verify SSH key is properly set\ndocker exec container-name cat /home/username/.ssh/authorized_keys\n```\n\n### Enabling Debug Mode\n\nEnable maximum debug output:\n\n```bash\ndocker run -d --name ssh-debug \\\n  -p 2224:22 \\\n  -e SSH_USER=testuser \\\n  -e SSH_PASSWORD=testpass \\\n  -e SSH_DEBUG_LEVEL=3 \\\n  ghcr.io/billchurch/ssh_test:latest\n\n# Watch debug logs in real-time\ndocker logs -f ssh-debug\n```\n\n## Security Considerations\n\nWhile designed for testing, security best practices are followed:\n\n- Non-root user execution when possible\n- Configurable authentication restrictions\n- No default passwords in production images\n- Regular security updates via automated rebuilds  \n- Minimal attack surface with optimized Debian slim base\n\n**Note**: This container is designed for testing environments. Do not expose it directly to the internet without additional security measures.\n\n## Choosing Your Variant\n\n### Use Dropbear When\n\n- **Testing SCP fallback**: Your application needs to handle devices without SFTP\n- **BusyBox simulation**: Mimicking embedded/IoT devices that only support SSH + SCP\n- **webssh2 File Browser**: Testing the SCP fallback for [webssh2 #483](https://github.com/billchurch/webssh2/issues/483)\n- **Smallest footprint**: ~5MB image with just SSH and SCP\n\n### Use Alpine When\n\n- **Size matters**: Ultra-minimal 13.8MB footprint\n- **Resource-constrained environments**: Kubernetes pods, edge computing\n- **Fast deployment**: Quicker download and startup times\n- **Security**: Smaller attack surface with minimal components\n- **Simple SSH testing**: Basic SSH client validation\n\n### Use Debian When\n\n- **Maximum compatibility**: Full GNU toolchain and libraries\n- **Complex applications**: Applications requiring specific libraries\n- **Legacy systems**: Compatibility with older SSH clients\n- **Development**: More debugging tools and utilities available\n- **Production-like testing**: Closer to typical server environments\n- **Telnet testing**: Optional telnet server for terminal client testing\n\n### Performance Comparison\n\n| Metric | Dropbear | Alpine | Debian |\n| --- | --- | --- | --- |\n| **Image Size** | ~5MB | 13.8MB | 118MB |\n| **Download Time** | ~1 second | ~2 seconds | ~15 seconds |\n| **Memory Usage** | ~4MB | ~8MB | ~20MB |\n| **Startup Time** | ~1 second | ~1 second | ~2 seconds |\n| **SSH** | Yes | Yes | Yes |\n| **SCP** | Yes | Yes | Yes |\n| **SFTP** | **No** | Yes | Yes |\n| **Telnet** | **No** | **No** | Optional |\n| **Compatibility** | Limited | Good | Excellent |\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n\n## Support\n\n- 🐛 **Issues**: Report bugs and feature requests on [GitHub Issues](https://github.com/billchurch/ssh-test-server/issues)\n- 📖 **Documentation**: Comprehensive documentation in this README and code comments\n- 💬 **Discussions**: Community support via [GitHub Discussions](https://github.com/billchurch/ssh-test-server/discussions)\n\n## Acknowledgments\n\n- **Debian variant**: Built with [Debian](https://www.debian.org/) bookworm-slim for optimal size and compatibility (118MB)\n- **Alpine variant**: Built with [Alpine Linux](https://alpinelinux.org/) for ultra-minimal footprint (13.8MB)\n- **Dropbear variant**: Built with [Dropbear](https://matt.ucc.asn.au/dropbear/dropbear.html) for SCP-only testing (~5MB)\n- Uses [OpenSSH](https://www.openssh.com/) for robust SSH implementation (Debian/Alpine)\n- Uses [Dropbear](https://matt.ucc.asn.au/dropbear/dropbear.html) for lightweight SSH (Dropbear variant)\n- Optimized Docker images with smart OS detection and adaptive configuration\n- Multi-architecture support with 88% size reduction possible via Alpine\n- Inspired by the need for better SSH integration testing tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbillchurch%2Fssh_test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbillchurch%2Fssh_test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbillchurch%2Fssh_test/lists"}