https://github.com/tbotnz/cisshgo
simple concurrent ssh server posing as cisco ios
https://github.com/tbotnz/cisshgo
ansible ci cicd cisco-ios netdev netdevops
Last synced: 3 months ago
JSON representation
simple concurrent ssh server posing as cisco ios
- Host: GitHub
- URL: https://github.com/tbotnz/cisshgo
- Owner: tbotnz
- Created: 2020-08-22T00:11:04.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-03-04T16:12:05.000Z (about 2 years ago)
- Last Synced: 2024-08-10T11:02:39.198Z (almost 2 years ago)
- Topics: ansible, ci, cicd, cisco-ios, netdev, netdevops
- Language: Go
- Homepage:
- Size: 2.1 MB
- Stars: 131
- Watchers: 7
- Forks: 26
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# cisshgo
Simple, small, fast, concurrent SSH server to emulate network equipment (i.e. Cisco IOS) for testing purposes.
[](https://github.com/tbotnz/cisshgo/actions/workflows/test.yml)
[](https://github.com/tbotnz/cisshgo/actions/workflows/test.yml)
[](https://goreportcard.com/report/github.com/tbotnz/cisshgo)
[](https://pkg.go.dev/github.com/tbotnz/cisshgo)
[](https://github.com/tbotnz/cisshgo/releases)
[](https://opensource.org/licenses/MIT)
## Quick Start
### Using Pre-built Binaries
Download the latest release from [GitHub Releases](https://github.com/tbotnz/cisshgo/releases) and run:
```bash
./cisshgo
```
### Building from Source
#### Quick Run
```bash
go run cissh.go
```
#### Build and Run
```bash
go build -o cisshgo cissh.go
./cisshgo
```
### Using Docker
Pull and run the latest release:
```bash
docker run -d -p 10000-10049:10000-10049 ghcr.io/tbotnz/cisshgo:latest
```
Or run with custom options:
```bash
docker run -d -p 10000:10000 ghcr.io/tbotnz/cisshgo:latest --listeners 1 --starting-port 10000
```
Or build locally:
```bash
docker build -t cisshgo .
docker run -d -p 10000-10049:10000-10049 cisshgo
```
### Using GoReleaser (for maintainers)
Build a local snapshot release:
```bash
goreleaser release --snapshot --clean --skip=publish
```
## Releasing
Releases are automated via GitHub Actions. To create a new release:
1. Update the changelog and tag:
```bash
git-cliff --tag v1.2.3 -o CHANGELOG.md
git add CHANGELOG.md
git commit -m "docs: update changelog for v1.2.3"
git tag -a v1.2.3 -m "v1.2.3"
git push origin master v1.2.3
```
2. GitHub Actions will automatically:
- Build binaries for all platforms (linux/darwin/windows, amd64/arm64)
- Create multi-arch Docker images and push to GitHub Container Registry (ghcr.io)
- Generate release notes from git-cliff
- Generate SBOMs for security compliance
- Create GitHub Release with binaries, archives, and checksums
- Build deb/rpm packages
> No additional secrets are required. Docker images are published to `ghcr.io` using the built-in `GITHUB_TOKEN`.
## Connecting
SSH into any of the open ports with `admin` as the password:
```bash
ssh -p 10000 admin@localhost
```
Default password: `admin`
## Example Session
```text
test_device#show version
Cisco IOS XE Software, Version 16.04.01
Cisco IOS Software [Everest], CSR1000V Software (X86_64_LINUX_IOSD-UNIVERSALK9-M), Version 16.4.1, RELEASE SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2016 by Cisco Systems, Inc.
Compiled Sun 27-Nov-16 13:02 by mcpre
...
ROM: IOS-XE ROMMON
```
Available commands:
- `show version`
- `show ip interface brief`
- `show running-config`
Additional commands can be added by modifying `transcripts/transcript_map.yaml`.
## Advanced Usage
### Command Line Options
```text
-l, --listeners=50 How many listeners to spawn ($CISSHGO_LISTENERS).
-p, --starting-port=10000 Starting port ($CISSHGO_STARTING_PORT).
-t, --transcript-map="transcripts/transcript_map.yaml"
Path to transcript map YAML file
($CISSHGO_TRANSCRIPT_MAP).
-P, --platform="csr1000v" Platform to use when no inventory is provided
($CISSHGO_PLATFORM).
-i, --inventory=STRING Path to inventory YAML file ($CISSHGO_INVENTORY).
```
### Example: Single Listener
```bash
./cisshgo --listeners 1 --starting-port 10000
```
## Expanding Platform Support
cisshgo is built with modularity in mind to support easy expansion or customization.
### Customized Output in Command Transcripts
Transcripts support Go templating. For example, in `show_version.txt`:
```text
ROM: IOS-XE ROMMON
{{.Hostname}} uptime is 4 hours, 55 minutes
Uptime for this control processor is 4 hours, 56 minutes
```
Available template variables from `fakedevices.FakeDevice`:
```go
type FakeDevice struct {
Vendor string // Vendor of this fake device
Platform string // Platform of this fake device
Hostname string // Hostname of the fake device
Password string // Password of the fake device
SupportedCommands SupportedCommands // What commands this fake device supports
ContextSearch map[string]string // The available CLI prompt/contexts on this fake device
ContextHierarchy map[string]string // The hierarchy of the available contexts
}
```
### Adding Additional Command Transcripts
1. Create a plain text file in the appropriate `vendor/platform` folder
2. Add an entry in `transcripts/transcript_map.yaml`:
```yaml
---
platforms:
- csr1000v:
command_transcripts:
"my new fancy command": "transcripts/cisco/csr1000v/my_new_fancy_command.txt"
```
### Adding Additional "Cisco-style" Platforms
Supply additional device types and transcripts in `transcript_map.yaml`.
This works for devices with similar interaction patterns (e.g., `configure terminal` leading to `(config)#` mode).
### Adding Additional Non-"Cisco-style" Platforms
**NOTE:** This feature is not fully implemented yet!
For platforms with different interaction patterns (e.g., Juniper, F5):
1. Implement a new handler module under `ssh_server/handlers`
2. Add it to the device mapping in `cissh.go`
The handler controls SSH session emulation and provides conditional logic to simulate the device experience.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Disclaimer
Cisco IOS is the property/trademark of Cisco.