{"id":39907819,"url":"https://github.com/hellqvio86/docker-zyxel-ssh-connector","last_synced_at":"2026-06-14T09:00:55.120Z","repository":{"id":329956104,"uuid":"1120485983","full_name":"hellqvio86/docker-zyxel-ssh-connector","owner":"hellqvio86","description":"Docker container for connecting to old Zyxel gear over SSH","archived":false,"fork":false,"pushed_at":"2026-06-07T04:30:19.000Z","size":506,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T06:20:10.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/hellqvio86.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-12-21T10:20:56.000Z","updated_at":"2026-06-07T04:30:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hellqvio86/docker-zyxel-ssh-connector","commit_stats":null,"previous_names":["hellqvio86/docker-zyxel-ssh-connector"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/hellqvio86/docker-zyxel-ssh-connector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellqvio86%2Fdocker-zyxel-ssh-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellqvio86%2Fdocker-zyxel-ssh-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellqvio86%2Fdocker-zyxel-ssh-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellqvio86%2Fdocker-zyxel-ssh-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hellqvio86","download_url":"https://codeload.github.com/hellqvio86/docker-zyxel-ssh-connector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellqvio86%2Fdocker-zyxel-ssh-connector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34315075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-01-18T16:02:01.941Z","updated_at":"2026-06-14T09:00:55.079Z","avatar_url":"https://github.com/hellqvio86.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docker-zyxel-ssh-connector\n\n[![Docker Image](https://img.shields.io/badge/docker-zyxel--ssh--connector-blue.svg)](https://hub.docker.com/r/hellqvio/zyxel-ssh-connector)\n[![Docker Image](https://img.shields.io/badge/docker-zyxel--ssh--bash-blue.svg)](https://hub.docker.com/r/hellqvio/zyxel-ssh-bash)\n[![Latest Release](https://img.shields.io/github/v/release/hellqvio86/docker-zyxel-ssh-connector)](https://github.com/hellqvio86/docker-zyxel-ssh-connector/releases)\n[![zyxel-ssh-connector pulls](https://img.shields.io/docker/pulls/hellqvio/zyxel-ssh-connector.svg?label=zyxel-ssh-connector%20pulls)](https://hub.docker.com/r/hellqvio/zyxel-ssh-connector)\n[![zyxel-ssh-bash pulls](https://img.shields.io/docker/pulls/hellqvio/zyxel-ssh-bash.svg?label=zyxel-ssh-bash%20pulls)](https://hub.docker.com/r/hellqvio/zyxel-ssh-bash)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)\n[![Python CI](https://github.com/hellqvio86/docker-zyxel-ssh-connector/actions/workflows/python_ci.yml/badge.svg?branch=main)](https://github.com/hellqvio86/docker-zyxel-ssh-connector/actions/workflows/python_ci.yml)\n[![Bash CI](https://github.com/hellqvio86/docker-zyxel-ssh-connector/actions/workflows/bash_ci.yml/badge.svg?branch=main)](https://github.com/hellqvio86/docker-zyxel-ssh-connector/actions/workflows/bash_ci.yml)\n[![Coverage](coverage.svg)](coverage.svg)\n[![mypy](https://img.shields.io/badge/mypy-checked-brightgreen)](https://github.com/python/mypy)\n[![python](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/)\n\nPython CLI tool and Docker container for connecting to legacy Zyxel network equipment over SSH. This tool uses compatible SSH algorithms required by older Zyxel switches and routers.\n\n## Why This Tool?\n\nModern SSH clients (OpenSSH 8.8+) have deprecated older algorithms like `ssh-rsa`, `diffie-hellman-group1-sha1`, and legacy ciphers. This makes it impossible to connect to older network equipment. This tool provides two solutions:\n- **Python CLI**: Direct command-line tool (requires compatible SSH setup)\n- **Docker Container**: Includes legacy SSH support (works everywhere)\n\n## Quick Start\n\n### Option 1: Using Pre-built Docker Containers (Recommended)\n\nThe fastest way to get started without installing anything or cloning the repo.\n\n```bash\n# Get switch version\ndocker run --rm --net=host hellqvio/zyxel-ssh-connector:latest zyxel-cli -H 192.168.1.1 version\n\n# Start an interactive session\ndocker run -it --rm --net=host hellqvio/zyxel-ssh-connector:latest zyxel-cli -H 192.168.1.1 interactive\n\n# Or use the minimal bash-only container\ndocker run -it --rm --net=host hellqvio/zyxel-ssh-bash:latest\n```\n\n### Option 2: Local Docker Development\n\nBest for active development or if you need to build the containers locally:\n\n```bash\n# Build the runtime container\nmake build\n\n# Use local build via Makefile\nmake show-version host=192.168.1.1\nmake connect host=192.168.1.1\n```\n\n### Option 3: Local Python CLI\n\nBest for developers contributing to the code.\n\n```bash\n# Set up environment and install\nmake python-build\nmake python-install\n\n# Use the CLI directly\nuv run zyxel-cli -H 192.168.1.1 version\n```\n\n**Note**: The local CLI (Option 3) may require legacy SSH support on your host. If you have connection issues, use the Docker method (Option 1).\n\n### Options \u0026 Parameters\n\nWhen using the `Makefile` (both for local CLI and Docker), you can pass parameters using the `name=value` syntax:\n\n| Parameter | Used in | Description |\n|-----------|---------|-------------|\n| `host`    | **Required** | IP or hostname of the switch. |\n| `user`    | Optional | SSH username (default: `admin`). |\n| `password`| Optional | SSH password (will prompt if not provided). |\n| `cmd`     | Optional | Raw command to execute (used with `cli-exec`). |\n| `args`    | Optional | Extra flags passed to the `zyxel-cli` (e.g., `args=\"--output-json --debug\"`). |\n\n#### Supported CLI Arguments\n\nThese can be passed via the `args=` parameter in the Makefile, or directly to the `zyxel-cli` binary if running in a virtual environment:\n\n| Flag | Description |\n|---|---|\n| `-H`, `--host` | **Required.** Hostname or IP of the switch. |\n| `-u`, `--user` | SSH username (default: `admin`). |\n| `-p`, `--password` | SSH password (will prompt if not provided). |\n| `--port` | SSH port (default: 22). |\n| `--debug` | Enable detailed JSON execution logging to `zyxel_ssh_debug.log`. |\n| `--output-json` | Output command results in structured JSON format. |\n\n#### Available Commands (Subcommands)\n\nThese are the subcommands you can execute (e.g., `zyxel-cli [options] \u003ccommand\u003e`):\n\n| Command | Description |\n|---|---|\n| `version` | Display switch firmware version and model info. |\n| `config` | Show the complete running configuration. |\n| `interfaces` | Show detailed status and statistics for ALL ports (iterates through ports automatically). |\n| `vlans` | Show the current VLAN configuration. |\n| `mac-table` | Show the MAC address table. |\n| `exec \u003ccmd\u003e`| Execute a custom raw command on the switch. |\n| `interactive` | Start an interactive SSH shell session. |\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n- Python 3.14+ (for local development)\n- [uv](https://github.com/astral-sh/uv) - Python package installer\n- Docker or Podman (for containerized usage)\n\n### Initial Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/docker-zyxel-ssh-connector.git\ncd docker-zyxel-ssh-connector\n\n# Set up Python environment\nmake python-build\n\n# Activate virtual environment\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install development dependencies\nmake python-install\n\n# Run tests to verify setup\nmake test\n```\n\n### Validation\n\nWe use `uv` for dependency management and development tasks. Run the project validation (formatting and static typing checks) with:\n\n```bash\nmake python-validate\n```\n\nThis runs `isort`, `black`, and `mypy` (via `uv`) to ensure imports, formatting, and types are correct.\n\nNote: `python-validate` assumes development tools are already installed. Run the following once to install dev dependencies before using the validation target:\n\n```bash\nmake python-install\nmake python-validate\n```\n\n## Usage\n\n### Local CLI Commands\n\nUse these for development and testing (requires legacy SSH support):\n\n```bash\n# Show switch information\nmake cli-version host=192.168.1.1\n\n\n# Network configuration\nmake cli-interfaces host=192.168.1.1\nmake cli-vlans host=192.168.1.1\nmake cli-config host=192.168.1.1\n\n# MAC address table\nmake cli-mac-table host=192.168.1.1\n\n# Interactive session\nmake cli-connect host=192.168.1.1\n\n# Execute custom command\nmake cli-exec host=192.168.1.1 cmd=\"show ip interface\"\n\n# With authentication\nmake cli-version host=192.168.1.1 user=admin password=mypass\n```\n\n### Docker Commands\n\nUse these for guaranteed compatibility with legacy switches:\n\n```bash\n# Build the final runtime image (builds builder first)\nmake docker-final\n\n# If you want to inspect or rebuild only the builder image:\nmake docker-build\n\n# Show switch information\nmake show-version host=192.168.1.1\n\n\n# Network configuration\nmake show-interfaces host=192.168.1.1\nmake show-vlans host=192.168.1.1\nmake show-config host=192.168.1.1\n\n# MAC address table\nmake show-mac-table host=192.168.1.1\n\n# Interactive session\nmake connect host=192.168.1.1\n\n# Run bash in container\nmake run\n```\n\n### Direct Python Usage\n\nIf you have the virtual environment activated:\n\n```bash\n# Show version\nzyxel-cli -H 192.168.1.1 -u admin version\n\n# Get configuration\nzyxel-cli -H 192.168.1.1 -u admin config\n\n# Interactive session\nzyxel-cli -H 192.168.1.1 -u admin interactive\n\n# Execute custom command\nzyxel-cli -H 192.168.1.1 -u admin exec \"show ip interface\"\n\n# Password will be prompted if not provided with -p\nzyxel-cli -H 192.168.1.1 -u admin -p mypassword version\n```\n\n#### Command Supported with JSON Output\n\nFollowing commands are supported with JSON output:\n\n| Command | Description | Status | Example output |\n|---------|-------------|--------|----------------|\n| `version` | Show switch version | ✅ | [version_cmd.json](https://raw.githubusercontent.com/hellqvio86/docker-zyxel-ssh-connector/main/src/tests/data/version_cmd.json) |\n| `config` | Show running configuration | ❌ | [config_cmd.json](https://raw.githubusercontent.com/hellqvio86/docker-zyxel-ssh-connector/main/src/tests/data/config_cmd.json) |\n| `interfaces` | Show interface status | ✅ | [intefaces_cmd.json](https://raw.githubusercontent.com/hellqvio86/docker-zyxel-ssh-connector/main/src/tests/data/intefaces_cmd.json) |\n| `vlans` | Show VLAN configuration | ✅ | [vlans_cmd.json](https://raw.githubusercontent.com/hellqvio86/docker-zyxel-ssh-connector/main/src/tests/data/vlans_cmd.json) |\n| `mac-table` | Show MAC address table | ✅| [mac_tabble_cmd.json](https://raw.githubusercontent.com/hellqvio86/docker-zyxel-ssh-connector/main/src/tests/data/mac_table_cmd.json) |\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run with verbose output\nmake test-verbose\n\n# Run with coverage report\nmake test-cov\n\n# View coverage report\nopen htmlcov/index.html\n```\n\n### Code Quality\n\n```bash\n# Check code style\nmake lint\n\n# Fix code style issues automatically\nmake lint-fix\n\n# Format code with black\nmake format\n\n# Check formatting without changes\nmake format-check\n```\n\n### Project Structure\n\n```\ndocker-zyxel-ssh-connector/\n├── src/\n│   └── zyxel_cli/\n│       ├── __init__.py\n│       ├── client.py          # SSH session handling\n│       └── cli.py             # CLI interface\n├── src/tests/\n│   ├── test_client.py         # Client tests\n│   └── test_cli.py            # CLI tests\n├── Dockerfile                 # Multi-stage Docker container definition (builder + runtime)\n├── pyproject.toml             # Python project configuration\n├── Makefile                   # Build and run commands\n└── README.md\n```\n\n## Makefile Commands Reference\n\n### Quick Start\n| Command | Description |\n|---------|-------------|\n| `make python-build` | Set up Python venv and install package |\n| `make python-install` | Install with dev dependencies |\n| `make test` | Run tests |\n\n### Local CLI (without Docker)\n| Command | Description | Example |\n|---------|-------------|---------|\n| `make cli-version` | Show version | `make cli-version host=192.168.1.1` |\n| `make cli-config` | Show config | `make cli-config host=switch.local` |\n| `make cli-interfaces` | Show interfaces | `make cli-interfaces host=192.168.1.1` |\n| `make cli-vlans` | Show VLANs | `make cli-vlans host=192.168.1.1` |\n| `make cli-mac-table` | Show MAC table | `make cli-mac-table host=192.168.1.1` |\n| `make cli-connect` | Interactive SSH | `make cli-connect host=192.168.1.1` |\n| `make cli-exec` | Custom command | `make cli-exec host=192.168.1.1 cmd='show ip'` |\n\n### Docker CLI (recommended for legacy devices)\n| Command | Description | Example |\n|---------|-------------|---------|\n| `make build` | Build container | `make build` |\n| `make show-version` | Show version | `make show-version host=192.168.1.1` |\n| `make show-config` | Show config | `make show-config host=192.168.1.1` |\n| `make show-interfaces` | Show interfaces | `make show-interfaces host=192.168.1.1` |\n| `make show-vlans` | Show VLANs | `make show-vlans host=192.168.1.1` |\n| `make show-mac-table` | Show MAC table | `make show-mac-table host=192.168.1.1` |\n| `make connect` | Interactive SSH | `make connect host=192.168.1.1` |\n| `make run` | Bash shell | `make run` |\n\n### Using Arguments with Makefile\nYou can pass any global CLI flag using the `args=` parameter:\n```bash\n# Get JSON output via Docker\nmake show-version host=192.168.1.1 args=\"--output-json\"\n\n# Enable debug logging\nmake show-interfaces host=192.168.1.1 args=\"--debug\"\n\n# Combine multiple arguments\nmake show-vlans host=192.168.1.1 args=\"--output-json --debug\"\n```\n\n### Testing \u0026 Quality\n| Command | Description |\n|---------|-------------|\n| `make test` | Run tests |\n| `make test-verbose` | Run tests with verbose output |\n| `make test-cov` | Run tests with coverage report |\n| `make lint` | Check code style |\n| `make lint-fix` | Fix code style issues |\n| `make format` | Format code with black |\n\n### Cleanup\n| Command | Description |\n|---------|-------------|\n| `make python-clean` | Clean Python artifacts |\n| `make clean` | Remove Docker image |\n\n## Supported Devices\n\nThis tool should work with any legacy network equipment requiring older SSH algorithms, including:\n\n- Zyxel GS1900 series switches\n- Zyxel XGS series switches\n- Zyxel routers and firewalls\n- Other network equipment with OpenSSH 6.x or older\n\n## Troubleshooting\n\n### Local CLI Connection Issues\n\nIf the local CLI doesn't work:\n```bash\n# Your system's SSH may not support legacy algorithms\n# Solution: Use Docker commands instead\nmake build\nmake show-version host=192.168.1.1\n```\n\n### Docker Network Access\n\nThe container uses `--net=host` to access your local network. If using a different network configuration, you may need to adjust network settings.\n\n### Test Failures\n\n```bash\n# Clean and rebuild environment\nmake python-clean\nmake python-build\nmake python-install\nmake test\n```\n\n## Security Note\n\nThis tool intentionally uses legacy SSH algorithms to connect to older equipment. Only use this for connecting to trusted devices on secure networks. Consider upgrading your network equipment if possible.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`make test`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellqvio86%2Fdocker-zyxel-ssh-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhellqvio86%2Fdocker-zyxel-ssh-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellqvio86%2Fdocker-zyxel-ssh-connector/lists"}