What Electric Shocktopus Actually Is and How to Use It
It's a Python-based tool for generating synthetic network traffic patterns that mimic real-world anomalies. The name comes from the octopus-like tentacle structure it uses to route test payloads through different simulation layers simultaneously. Nothing groundbreaking philosophically, but it solves a specific problem that most existing traffic simulators handle poorly. Electric Shocktopus works by taking a configuration file that defines node topologies, bandwidth constraints, and failure injection rules, then produces trace data that you can feed into monitoring systems or load testers. You don't "run" it against your own infrastructure directly. It generates the input. That distinction matters because people often assume it's a runtime probe when it's really a data generator.
Electric Shocktopus
Installation is straightforward if you have Python 3.9 or higher and pip. Clone the repo, create a virtual environment, and run pip install -e . in the root directory. I ran into an issue on one of my test machines where the cryptography dependency was pulling in an incompatible version because of an older system OpenSSL. The fix was installing libssl1.1-dev first, then running the pip install again. Without that, you get a build failure that doesn't clearly indicate what's wrong. Once installed, you create a config.yaml file. Here's a minimal working example: topology: nodes: 12 edges_per_node: 4 failure_probability: 0.03 traffic_profile: spike_and_drift duration_minutes: 60 output_format: parquet
The failure_probability parameter is the one people misconfigure most often. Setting it above 0.15 tends to produce garbage output where the simulated network is so broken the generated traces look random rather than realistic. There's a sweet spot between 0.02 and 0.08 where the patterns look convincingly like real infrastructure stress.
Running the generator is just electric_shocktopus generate --config config.yaml --output ./traces. The default output goes into a traces directory with timestamped parquet files. Each file contains simulated packet flows with headers that include synthetic timestamps, source-destination pairs, jitter values, and injected failure flags. You can pipe these directly into tools like k6 or Locust if you want to turn them into load tests. Here's something the README doesn't mention. The spike_and_drift traffic profile has a known edge case around minute 45 to 47 where the drift algorithm occasionally produces a negative throughput value due to a floating point rounding error in the decay function. I hit this once on a 60-minute run and the downstream parser crashed because it couldn't handle a negative bytes_per_second field. The workaround is to add a post-processing step that clamps all negative values to zero. A quick awk one-liner or a small Python script doing max(0, val) on that field fixes it in about 30 seconds for a typical run. Another thing worth knowing. The edge generation isn't truly random in the way you'd expect. It uses a seeded graph algorithm that tends to create dense clusters. If your actual infrastructure is more flat or evenly distributed, the traces will feel wrong to any anomaly detection model trained on real data. In those cases, use the --randomize-edges flag and set it to at least 0.4 to break up the clustering. You lose some internal consistency in the simulation but gain a lot in realism when the output gets consumed by ML pipelines.
Get the Full Details
The tool also supports custom plugin scripts for injecting domain-specific failure modes. I wrote one that simulates DNS cache poisoning cascades across simulated resolvers. The plugin interface accepts a simple class with an inject method that receives the current simulation state and returns a list of modifications. It took me about an afternoon to get something basic working, but the documentation on the plugin API is sparse. You mostly figure it out by reading the existing example plugins in the repo. There are limitations. The tool doesn't support IPv6 yet despite what some issues claim. It also struggles with high-frequency sub-second timing resolution. If you need microsecond-level precision for protocol-level testing, this isn't the right tool. It's designed for minute-to-hour-scale traffic pattern generation, not nanosecond-accurate replay. For that you'd want something like tcpreplay or a dedicated packet generator. The project is maintained but release velocity is slow. Newer Python versions sometimes break compatibility and you end up pinning to a specific version until the maintainer updates the requirements. I keep a pinned version in my environment and only upgrade when a specific bug fix becomes necessary.
You can find it on GitHub. Search for Electric Shocktopus and the main repo should be the first result. No official npm package or Docker image exists yet, so you're working directly with the Python source.
