cisshgo

Simple, small, fast, concurrent SSH server to emulate network equipment (i.e. Cisco IOS) for testing purposes.

Quick Start

Using Pre-built Binaries

Download the latest release from GitHub Releases and run:

./cisshgo

Building from Source

Quick Run

go run cissh.go

Build and Run

go build -o cisshgo cissh.go
./cisshgo

Using Docker

Pull and run the latest release:

docker run -d -p 10000-10049:10000-10049 ghcr.io/tbotnz/cisshgo:latest

Or run with custom options:

docker run -d -p 10000:10000 ghcr.io/tbotnz/cisshgo:latest --listeners 1 --starting-port 10000

Or build locally:

docker build -t cisshgo .
docker run -d -p 10000-10049:10000-10049 cisshgo

Using GoReleaser (for maintainers)

Build a local snapshot release:

goreleaser release --snapshot --clean --skip=publish

Releasing

Releases are automated via GitHub Actions. To create a new release:

1. Update the changelog and tag:

   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:

ssh -p 10000 admin@localhost

Default password: admin

Example Session

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

  -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

./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:

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:

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:

---
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 file for details.

Disclaimer

Cisco IOS is the property/trademark of Cisco.