Unified Network Disturbance Simulator (Eris)

Eris is a easy-to-use BASH script for chaos engineering and resilience testing. It helps to introduce controlled network disturbances to test how applications handle adverse conditions. It uses iptables to precisely simulate connection drops, rejections, flapping, and packet loss for specific TCP connections.

---

Key Features

• Command-Based Interface: Simple and intuitive commands (drop, reject, flap, loss).
• Targeted Disturbances: Isolate failures to specific connections using IP addresses and ports.
• Directional Control: Affect incoming, outgoing, or all (bidirectional) traffic.
• Multiple Modes:
  • Progressive: Outages that grow in duration based on a Fibonacci sequence.
  • Static: Disturbances that last for a fixed duration.
• Dry-Run: A --dry-run mode shows which iptables commands would be run without actually executing them.
• Logging: All actions are logged to both the console and a file (/var/log/eris.log by default). Optional packet logging for deep dives.
• Automatic Cleanup: A trap ensures iptables rules are removed on script exit, and a manual eris cleanup command is available for any leftovers.

---

Requirements

• A Linux-based operating system.
• iptables installed on the system.
• root or sudo privileges to modify iptables rules.

---

Installation

For easy, system-wide access, place eris.sh in a directory within your system's PATH.

1. Download the script:

   curl -o eris.sh https://raw.githubusercontent.com/SergiyBabenkov/eris/main/eris.sh

2. Make it executable:

   chmod +x eris.sh

3. Move it into your path (recommended):

   sudo mv eris.sh /usr/local/bin/eris

   Now you can run the script from anywhere by simply typing eris.

---

Usage

The script must be run with sudo or as the root user. The basic structure is:

sudo eris [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]

Global Options

These flags can be used before any command.

Flag	Description
--dry-run	Show iptables commands without executing them.
--verbose, -v	Enable detailed debug output.
--log-file <path>	Specify a custom log file location.
--help, -h	Display the main help message.

---

Commands

Eris is organized into clear commands. Run eris <command> --help for details on any command.

Command	Description
drop	Simulate TCP drops (progressive or static)
reject	Simulate TCP rejects (progressive or static)
flap	Simulate connection flapping
loss	Simulate probabilistic packet loss
cleanup	Remove any lingering iptables rules

drop

Simulates a connection drop by silently discarding packets.

• Modes: progressive (default) or static.
• Example: Drop all traffic to 10.0.0.20:443 for a static duration of 90 seconds.

  sudo eris drop \
    --direction all \
    --local-ip 192.168.1.100 \
    --local-port 54321 \
    --remote-ip 10.0.0.20 \
    --remote-port 443 \
    --mode static \
    --duration 90

reject

Simulates a connection rejection by actively sending a TCP RST packet back. This provides an immediate failure notice to the client.

• Modes: progressive (default) or static.
• Example: Progressively reject outgoing traffic to 10.0.0.20:80.

  sudo eris reject \
    --direction out \
    --local-ip 192.168.1.100 \
    --local-port 12345 \
    --remote-ip 10.0.0.20 \
    --remote-port 80

flap

Simulates an unstable network by repeatedly dropping and restoring a connection.

• Example: Flap the incoming connection from 10.0.0.20 10 times, with each drop lasting 3 seconds.

  sudo eris flap \
    --direction in \
    --local-ip 192.168.1.100 \
    --local-port 8080 \
    --remote-ip 10.0.0.20 \
    --count 10 \
    --duration 3

loss

Simulates an unreliable network by dropping packets based on a random probability. This affects all TCP traffic between the specified IPs, not specific ports.

• Example: Introduce 25% packet loss on all traffic to and from 10.0.0.20 for 2 minutes.

  sudo eris loss \
    --direction all \
    --local-ip 192.168.1.100 \
    --remote-ip 10.0.0.20 \
    --probability 0.25 \
    --duration 120

cleanup

Manually removes any lingering iptables rules that Eris may have left behind if it was terminated improperly.

• Example:

  sudo eris cleanup

---

🔍 Validation

Always check the state of iptables chains to see the rules Eris has applied.

# View INPUT chain rules
sudo iptables -L INPUT --line-numbers -n

# View OUTPUT chain rules
sudo iptables -L OUTPUT --line-numbers -n

# Delete a specific rule by its chain and line number
# Example: Delete rule number 1 from the OUTPUT chain
sudo iptables -D OUTPUT 1

---