Network attack simulation for security education

A unified matcha CLI for running network-layer, application-layer, and replay attacks in controlled lab environments — built to teach how attacks work, not just that they exist.

Get Started | Playbook | Web Demo

How It Works

graph LR
    Install["pip install -e ."] --> CLI["matcha <attack>"]
    CLI --> Registry["Attack Registry"]
    Registry --> Validate["Validate args"]
    Validate --> Execute["Execute attack"]
    Execute --> Target["Lab Target"]
    Execute --> Log["Structured logs"]

Each attack inherits from AttackBase, which enforces argument parsing, input validation, and structured logging. The registry auto-discovers modules — adding a new attack requires only a class and a one-line registration.

Attack Coverage

Key Features

Quick Start

Prerequisites: Python 3.8+ and root/sudo privileges (required for raw socket attacks)

pip:

pip install mmt-attacker

One-line install (Linux / macOS — installs system deps automatically):

curl -sSL https://raw.githubusercontent.com/Montimage/mmt-attacker/main/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/Montimage/mmt-attacker/main/install.sh | bash

Docker — two-container lab (recommended, no host setup required):

git clone https://github.com/Montimage/mmt-attacker.git
cd mmt-attacker
docker compose up --build -d
docker compose exec attacker matcha syn-flood --target-ip target --target-port 80 --count 200
docker compose down

Starts an isolated lab with an attacker container (matcha CLI) and a target container (nginx + SSH + FTP). Attacks stay contained to the lab bridge network.

Docker — CLI-only (run against your own lab target):

docker build -t matcha .
docker run --rm --cap-add NET_ADMIN --cap-add NET_RAW matcha --help

See docs/DEMO.md for the full two-container guide. See docs/DOCKER.md for the CLI-only Docker guide (PCAP replay, JSON output, etc.).

From source:

git clone https://github.com/Montimage/mmt-attacker.git
cd mmt-attacker
pip install -e .

Verify:

matcha --help

List all available attacks:

matcha list

Launch an attack (in a controlled lab environment):

matcha http-dos --target-url http://example.com --threads 10

Shell Completions

# bash (~/.bashrc)
eval "$(_MATCHA_COMPLETE=bash_source matcha)"

# zsh (~/.zshrc)
eval "$(_MATCHA_COMPLETE=zsh_source matcha)"

# fish (~/.config/fish/config.fish)
_MATCHA_COMPLETE=fish_source matcha | source

Or print the activation command:

matcha completions bash   # or zsh / fish

Usage Examples

PCAP Replay

matcha pcap-replay \
    --pcap-file capture.pcap \
    --interface eth0 \
    --speed 2.0

ARP Spoofing

matcha arp-spoof \
    --target-ip 192.168.1.100 \
    --gateway-ip 192.168.1.1

HTTP DoS

matcha http-dos \
    --target-url http://example.com \
    --threads 10

Attack Info

matcha info arp-spoof

Web Interface

Install frontend dependencies:

cd frontend && npm install

Start the dev server:

npm run dev

Opens at http://localhost:3000 — interactive attack walkthroughs, Mermaid flow diagrams, command generation with validation, and simulated execution results.

Educational Use

MMT-Attacker is built for security courses, CTF preparation, and lab-based research. The web demo explains each attack's mechanism without executing real traffic. The CLI is for hands-on practice in isolated, authorized environments.

Use cases:

• University network security courses
• Cybersecurity workshop labs
• IDS/IPS detection research (generate known attack traffic)
• Personal study in a home lab

Security Warning

This tool is for authorized security testing and education only. Before use:

• Obtain written authorization from the system owner
• Test only in controlled, isolated environments
• Follow responsible disclosure practices
• Comply with all applicable laws

Unauthorized use may be illegal. See PLAYBOOK for detailed ethical guidelines.

Roadmap

• GUI interface
• Cloud deployment (Netlify)
• CLI tool (matcha)
• Shell completions
• CI/CD pipeline
• Additional attack vectors
• Enhanced reporting
• Docker containerization (CLI-only image)
• Two-container attack simulation demo (attacker + target via docker compose)
• API integration

Get Started

pip install -e .

Read the Playbook | Try the Web Demo | Contributing | Apache 2.0 Licensed

mmt-attacker/
├── matcha/                        # CLI package
│   ├── cli.py                    # Click-based CLI entry point
│   ├── commands/                 # CLI commands
│   │   └── completions_cmd.py   # Shell completion support
│   └── attacks/                  # Attack implementations (auto-discovered)
├── src/
│   ├── attacks/                  # Attack implementations
│   │   ├── base.py              # Base attack class (AttackBase)
│   │   ├── arp_spoof.py         # ARP spoofing
│   │   ├── syn_flood.py         # SYN flood
│   │   ├── dns_amplification.py # DNS amplification
│   │   ├── http_dos.py          # HTTP DoS
│   │   ├── slowloris.py         # Slowloris
│   │   ├── ssh_brute_force.py   # SSH brute force
│   │   ├── sql_injection.py     # SQL injection
│   │   ├── pcap_replay.py       # PCAP replay
│   │   ├── ping_of_death.py     # Ping of Death
│   │   └── credential_harvester.py
│   └── utils/                   # Validators, network utils, logger
├── frontend/                     # React + Vite web demo
├── docs/                         # Documentation + playbook
├── pyproject.toml               # Package config (matcha entry point)
└── README.md

from .base import AttackBase
from argparse import ArgumentParser
import logging

logger = logging.getLogger(__name__)

class NewAttack(AttackBase):
    name = "new-attack"
    description = "Description of the new attack type"

    def add_arguments(self, parser: ArgumentParser) -> None:
        parser.add_argument('--target', required=True, help='Target IP or hostname')
        parser.add_argument('--port', type=int, default=80, help='Target port')

    def validate(self, args) -> bool:
        if not self.validator.validate_ip(args.target):
            logger.error(f"Invalid target: {args.target}")
            return False
        return True

    def run(self, args) -> None:
        logger.info(f"Starting {self.name} against {args.target}:{args.port}")
        # Attack logic here

from .new_attack import NewAttack

ATTACKS = {
    # ... existing attacks ...
    "new-attack": NewAttack,
}

Built by Montimage