mmt-attacker 0.2.1

MMT Attack Toolkit - 26 network attacks from one CLI for authorized security testing and education

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

Layer	Attacks
Network	ARP Spoofing, BGP Hijacking, DHCP Starvation, DNS Amplification, ICMP Flood, MAC Flooding, MITM, NTP Amplification, Ping of Death, Smurf, SYN Flood, UDP Flood
Application	Credential Harvester, Directory Traversal, FTP Brute Force, HTTP DoS, HTTP Flood, RDP Brute Force, Slowloris, SQL Injection, SSH Brute Force, SSL Strip, VLAN Hopping, XSS, XXE
Replay	PCAP Replay

Key Features

Feature	What you get
Single CLI	All attacks through matcha — one interface for the entire curriculum
PCAP replay	Replay captured traffic with speed control and interface selection
Built-in validation	IP, port, interface, and parameter checks before execution
Structured logging	Every attack logs events for post-analysis and review
Pluggable architecture	Add an attack by subclassing AttackBase and registering it
Web demo	React-based interactive walkthroughs with Mermaid flow diagrams
Shell completions	Tab-completion for bash, zsh, and fish

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

---

Project Structure

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

Adding New Attacks

1. Create a new module in src/attacks/
2. Inherit from AttackBase
3. Implement add_arguments(), validate(), and run()
4. Register in src/attacks/__init__.py

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

Register it:

from .new_attack import NewAttack

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Code requirements:

• PEP 8 style
• Include tests
• Update docs as needed
• Maintain backward compatibility

Support

1. Check the documentation
2. Search existing issues
3. Email [e-mail]
4. Create a new issue if needed

---

Built by Montimage