Metadata-Version: 2.4
Name: evillimiter-ng
Version: 3.0.3
Summary: Monitors, analyzes and limits the bandwidth of devices on the local network (Next Generation).
Project-URL: Homepage, https://github.com/KevinCrrl/evillimiter-ng
Project-URL: Bug Tracker, https://github.com/KevinCrrl/evillimiter-ng/issues
Author: KevinCrrl
License-Expression: GPL-2.0-only
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: netaddr>=1.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: psutil>=5.6.7
Requires-Dist: rich>=13.9.2
Requires-Dist: scapy>2.5.0
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center"><img src="https://github.com/KevinCrrl/evillimiter-ng/blob/main/evillimiter_ng_screenshot.png?raw=true"/></p>

# Evil Limiter Next Generation

[![License Badge](https://shields.io/badge/license-GPLv2%20only-blue)](LICENSE)
[![Compatibility](https://img.shields.io/badge/python-3-brightgreen.svg)](pyproject.toml)
[![Hatch project](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pypa/hatch/master/docs/assets/badge/v0.json)](https://github.com/pypa/hatch)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/KevinCrrl/evillimiter-ng/graphs/commit-activity)
[![Free Software](https://shields.io/badge/Free_(Libre)_Software-blue)](LICENSE)

A tool to monitor, analyze and limit the bandwidth (upload/download) of devices on your local network without physical or administrative access.

`evillimiter-ng` employs [ARP spoofing](https://en.wikipedia.org/wiki/ARP_spoofing) and [traffic shaping](https://en.wikipedia.org/wiki/Traffic_shaping) to throttle the bandwidth of hosts on the network.

> [New in version 3.0: Use the code as a library instead of a CLI](#library-api)

## Requirements
- Linux distribution with nftables
- Python 3.10 or greater

Possibly missing python packages will be installed during the installation process.

## Installation

### Pypi + Pip

```bash
pip install evillimiter-ng
```

### AUR

[EvilLimiter-NG AUR page](https://aur.archlinux.org/packages/evillimiter-ng)

Using the AUR, the package can be installed manually:

```bash
git clone https://aur.archlinux.org/evillimiter-ng.git

cd evillimiter-ng

makepkg -si
```

Or using AUR helpers:

```bash
# Using KPA (https://github.com/KevinCrrl/kpa)
kpa Ins evillimiter-ng

# Or using yay (https://github.com/Jguer/yay)
yay -S evillimiter-ng
```

## Library API

Learn how to use the library API for your own projects, write less code, take advantage of the architecture based on lists of IPs with assigned IDs, and find more uses for the code beyond the terminal program: [Library docs](https://kevincrrl.github.io/evillimiter-ng/apilib)

## Quick Start Example

After installation, you can start using the tool with the following basic workflow.

1. Start the program and specify your network interface:

```bash
evillimiter-ng -i wlan0
```

2. Scan the network for connected hosts:

```bash
scan
```

3. Limit bandwidth of a device (example: device ID 3 to 200kbit):

```bash
limit 3 200kbit
```

### Example of a single-use command in the shell

```bash
# Scan the network, list hosts, block everyone for 20 seconds, and then restore connection.
echo "scan && hosts && block all && sleep 20 && free all && exit" | evillimiter-ng
```

### Exporting/Importing a JSON file to save scans

```bash
# Scan the network, and save the results in a JSON file encoded in base64
scan && export-json my_network.json
```

With it, you can restore these results without a new scan in a future session:

```bash
import-json my_network.json
```

> 🛑 **CRITICAL SECURITY WARNING**
> 
> **Base64 is NOT encryption (like PGP).** It only obfuscates sensitive data (local IPs, MAC addresses) so they aren't visible to the naked eye. **Any user or program can easily decode this file.**
> 
> * **Permissions:** The file is read-proctected and write-protected (root only) to prevent corruption. 
> * **Risk:** Even if a malicious user obtains root access, they cannot decrypt what was never encrypted, but they *can* read, corrupt or destroy the information. Do not rely on this file for confidentiality.

#### Command-Line Arguments

| Argument | Explanation |
| -------- | ----------- |
| `-h` | Displays help message listing all command-line arguments |
| `-s` | Enables a shell mode for typing commands and hides banners and flashy elements |
| `-i [Interface Name]` | Specifies network interface (resolved if not specified) |
| `-g [Gateway IP Address]` | Specifies gateway IP address (resolved if not specified) |
| `-m [Gateway MAC Address]` | Specifies gateway MAC address (resolved if not specified) |
| `-n [Netmask Address]` | Specifies netmask (resolved if not specified)

#### `evillimiter-ng` Commands

You can use the command `-h` to see the general help menu, also, each command has a submenu generated by argparse, you can view the help for these by typing:

```bash
>>> <COMMAND_NAME> -h
```

For example:

```bash
>>> scan -h

usage:  scan [-h] [-r RANGE] [-i INTENSITY]

options:
-h, --help            show this help message and exit
-r, --range RANGE
-i, --intensity INTENSITY

# Another example:

>>> watch --help

usage:  watch [-h] {add,remove,set} ...

positional arguments:
{add,remove,set}
add             Adds host to the reconnection watchlist. e.g.: watch add 3,4
remove          Removes host from the reconnection watchlist. e.g.: watch remove all
set             Changes reconnect watch settings. e.g.: watch set interval 120 watch set intensity 1

options:
-h, --help        show this help message and exit

```

#### Commands Table

This table shows all the available commands:

| Command | Explanation |
| ------- | ----------- |
| `scan (--range [IP Range]) (--intensity [(1,2,3)])` | Scans your network for online hosts. One of the first things to do after start.<br>`--range` lets you specify a custom IP range.<br>`--intensity` lets you specify the scan intensity / speed (`1` = quick, `2` = normal (standard), `3` = intense).<br>Example: `scan --range 192.168.178.1-192.168.178.40 --intensity 1` or just `scan`. |
| `hosts` | Displays all scanned hosts and basic information. |
| `limit [ID1,ID2,...] [Rate] (--upload) (--download)` | Limits bandwidth of host(s) associated with specified ID. |
| `block [ID1,ID2,...] (--upload) (--download)` | Blocks internet connection of host(s). |
| `free [ID1,ID2,...]` | Removes bandwidth restrictions. |
| `add [IP] (--mac [MAC])` | Adds custom host manually. |
| `monitor (--with-id [ID1,ID2,...]) (--interval [time in ms])` | Monitor bandwidth usage of host(s). |
| `analyze [ID1,ID2,...] (--duration [time in s])` | Analyze traffic usage. |
| `watch` | Shows current watch status. |
| `watch add [ID1,ID2,...]` | Adds host(s) to watchlist. |
| `watch remove [ID1,ID2,...]` | Removes host(s) from watchlist. |
| `watch set [Attribute] [Value]` | Changes watch settings. |
| `clear` | Clears terminal window. |
| `exit` | Quits the application. |
| `sleep` | Waits for <n> seconds. |
| `-h`, `--help` | Displays command help. |
| `import-json, export-json [JSON_FILE_PATH]` | Import/Export a JSON file containing IP addresses and MAC addresses encoded in base64. |

## Restrictions

- **Limits IPv4 connections only**, since [ARP spoofing](https://en.wikipedia.org/wiki/ARP_spoofing) requires ARP packets which exist only in IPv4 networks.

## Legal Disclaimer

Please read the full legal disclaimer here:

[LEGAL.md](https://github.com/KevinCrrl/evillimiter-ng/blob/main/LEGAL.md)

## License

Copyright (c) 2026 by [KevinCrrl](https://github.com/KevinCrrl).

Licensed under the **GPL-2.0-only License**.

For a detailed list of original authors, dependencies, and their respective licenses, see the [CREDITS](https://github.com/KevinCrrl/evillimiter-ng/blob/main/CREDITS.md) file.
