GoNetSim

Go Network Simulator. A programmable network simulator for malware analysis that lets you simulate any network protocol with small, sandboxed, shareable Lua handlers. Explore the docs »

Contribute · Report a Bug · Request a Feature

Usage

Installation

Installation instructions can be found here.

Quick Start

Running gonetsim starts all services enabled in the configuration file:

gonetsim

Individual services and listeners can be selected as targets, as preset names, listener names from config, or inline handler@addr listeners:

gonetsim run http               # just the HTTP service
gonetsim run http dns           # multiple presets
gonetsim run irc                # a named [[listeners]] entry from config
gonetsim run echo@:7777         # inline echo listener, no config needed
gonetsim run sink@:9999/udp     # inline UDP sink
gonetsim run c2.lua@:8080       # inline Lua handler from a local script

Targets named explicitly run regardless of their enabled setting in config. Common settings are also available as flags which override the config file:

gonetsim run http --listen 127.0.0.1:8080
gonetsim run c2.lua@:8080 --tls --no-capture
gonetsim run http -s http.mode=real -s http.root_dir=/srv/www

A more detailed usage guide can be found here.

Configuration

GoNetSim uses a TOML configuration file for most configuration, rather than forcing the memorisation of many flags.

On first run, if no config file is found, GoNetSim generates a default commented config file in $XDG_CONFIG_HOME/gonetsim/config.toml and uses it.

Default search locations:

• ./gonetsim.toml
• $XDG_CONFIG_HOME/gonetsim/config.toml (usually ~/.config/gonetsim/config.toml)
• /etc/gonetsim/gonetsim.toml

To use a specific config file:

gonetsim --config /path/to/gonetsim.toml

For more information on configuration, please see the configuration reference

Custom Listeners

Beyond the built-in services, GoNetSim can simulate arbitrary TCP/UDP protocols through custom listeners. Listeners can either use basic builtins or fully custom Lua scripts:

[[listeners]]
name = "irc"
type = "tcp"
listen = ":6667"
handler = "lua:handlers/irc.lua" 

Run it with gonetsim run irc, or skip using a pre-defined config entirely with gonetsim run lua:handlers/irc.lua@:6667.

The examples/ directory has a full sample config plus example IRC and FTP handlers.

Docker

A lightweight distroless container setup lives in docker/ and is built/published with ko. This is the recommended installation method if you require long periods of uptime, or if your system is incompatible with the provided binaries.

For a full reference guide please see the Docker guide

Contributing

GoNetSim follows most standard conventions for contributing, and accepts any contributions from documentation improvements, bug triage / fixes, small features or any updates for issues in the backlog. For more information on contributing please see CONTRIBUTING.md and AI_USAGE.md

Codespaces

GoNetSim has full support for Github Codespaces. These are recommended for small changes or devices with no access to a development environment. You can use the buttons below to open the repository in a web-based editor and get started.

Dev Containers

We also have full support for Dev Containers. These provide a reproducible development environment that automatically isolates the project and installs the officially supported toolchain.

Clicking the below button will open up VS Code on your local machine, clone this repository and open it automatically inside a development container.

Local Development

For local development, please refer to CONTRIBUTING.md. Again, we follow most conventions so local development involves the standard flow of fork-PR-merge.

This project is licensed under the Apache 2.0 License. Please see LICENSE for more info.

Copyright (c) 2026 Lachlan Harris. All Rights Reserved.