scapy-helper


Namescapy-helper JSON
Version 0.10.2 PyPI version JSON
download
home_pagehttps://github.com/NexSabre/scapy_helper
SummarySeveral features that should help you use Scapy
upload_time2021-05-04 18:59:50
maintainer
docs_urlNone
authorNex Sabre
requires_python
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ![Test](https://github.com/NexSabre/scapy_helper/workflows/Test/badge.svg?branch=master)
![CodeQL](https://github.com/NexSabre/scapy_helper/workflows/CodeQL/badge.svg?branch=master)
[![PyPI version](https://badge.fury.io/py/scapy-helper.svg)](https://badge.fury.io/py/scapy-helper)

# Scapy helper (aka. Packet Helper) 
This micro library popularizes some handy tricks that make it easy usage of Scapy.

## TL;DR
```python
from scapy_helper import *

# Dump frame hex
hex_value = get_hex(Ether())
# hex_value: 
'ff ff ff ff ff ff 00 00 00 00 00 00 90 00'

# Convert and print 
show_hex(Ether())
# output: 
# ff ff ff ff ff ff 00 00 00 00 00 00 90 00

# Show the differences
#   can be result of get_hex() or string or frame
second_ether = "ff ff fc ff ff fa 00 00 00 00 00 00 90 00 11 11 00 22" 
show_diff(Ether(), second_ether)
# output: 
# WARN:: Frame len is not the same
# WARN:: Second row is longer by the 4B
#
# __ __ ff __ __ ff __ 00 00 00 00 00 __ __ XX XX XX XX | len: 14B
# __ __ fc __ __ fa __ 11 11 11 11 11 __ __ 11 11 00 22 | len: 18B
#
# Not equal at 11B

# You can add a index to it
show_diff(Ether(), second_ether, index=True)
# output: 
# __ __ ff __ __ ff __ 00 00 00 00 00 __ __ XX XX XX XX | len: 14B
# __ __ fc __ __ fa __ 11 11 11 11 11 __ __ 11 11 00 22 | len: 18B
#                                                       |
#       ^2       ^5    ^7 ^8 ^9 10 11       14 15 16 17 | position
#
# Not equal at 11B

# You can add a custom char to mark a missing elements
show_diff(Ether(), second_ether, index=True, empty_char="+")
# output: 
# __ __ ff __ __ ff __ 00 00 00 00 00 __ __ ++ ++ ++ ++ | len: 14B
# __ __ fc __ __ fa __ 11 11 11 11 11 __ __ 11 11 00 22 | len: 18B
#                                                       |
#       ^2       ^5    ^7 ^8 ^9 10 11       14 15 16 17 | position
```

## Addons
Since version v0.5.1, to the _scapy_helper_ was added `chexdump` and `hexdump`. 
With v0.7.1 we introduce a `mac2int` and `int2mac`. Version v0.10 bring `hstrip`.

### hstrip
Since v0.10, allows to convert a Scapies hexdump into clean string-hex format.
Select a hexdump and copy into clipboard.

```text
>>> f = Ether()/IP()/TCP()
>>> hexdump(f)
0000  FF FF FF FF FF FF 00 00 00 00 00 00 08 00 45 00  ..............E.
0010  00 28 00 01 00 00 40 06 7C CD 7F 00 00 01 7F 00  .(....@.|.......
0020  00 01 00 14 00 50 00 00 00 00 00 00 00 00 50 02  .....P........P.
0030  20 00 91 7C 00 00                                 ..|..
>>> 
```
In command line type `hstrip`

```text
FF FF FF FF FF FF 00 00 00 00 00 00 08 00 45 00
00 28 00 01 00 00 40 06 7C CD 7F 00 00 01 7F 00
00 01 00 14 00 50 00 00 00 00 00 00 00 00 50 02
20 00 91 7C 00 00
```

VoilĂ ! You have in your clipboard striped version of hexdump. Now you can paste it into [packetor.com](http://packetor.com)

### chexdump
```python
from scapy_helper import chexdump

packet = "\x00\x01".encode()

# chexdump as we know 
chexdump(packet)
# 0x00, 0x01

# with return 
val = chexdump("\x00\x01".encode(), dump=True)
# or if you need a list
val = chexdump("\x00\x01".encode(), dump=True, to_list=True)
```

### hexdump
```python
from scapy_helper import hexdump

packet = Ether(dst="ff:ff:ff:ff:ff:ff",
               src="00:00:00:00:00:00")

# chexdump as we know 
hexdump(packet)
# 0000   ff ff ff ff ff ff 00 00 00 00 00 00 08 00 45 00   ..............E.
# 0010   00 14 00 01 00 00 40 00 fb e8 00 00 00 00 7f 00   ......@.........
# 0020   00 01                                             ..

# with return 
val = hexdump(packet, dump=True)
# or if you need a list
val = hexdump(packet, dump=True, to_list=True)
```

### int2mac
Convert an integer value into mac address. Letters by the default are lower case. 
```python
from scapy_helper import int2mac

int2mac(73596036829, upper=True)
# "00:11:22:AA:66:DD"
```

### mac2int
Convert a mac address into integer value 
```python
from scapy_helper import mac2int

mac2int("00:11:22:AA:66:DD")
# 73596036829
```

### ip2int
Convert IP address string into int value
```python
from scapy_helper import ip2int

ip2int("0.0.0.0")
# 0
```

### int2mac
Convert an int value into IP address string
```python
from scapy_helper import int2ip

int2ip(0)
# 0.0.0.0
```

## Test case usage
### Extends test class using PacketAssert (since v0.3.1)
__Note: In the v0.3.0 this class was called HexEqual__

You can use assertHexEqual/assertHexNotEqual and assertBytesEqual/assertBytesNotEqual in the tests.
When the assertion fails, wrapper produces information about the frames (in hex).

```python
import unittest
from scapy_helper.test_case_extensions.packet_assert import PacketAssert

class TestExample(unittest.TestCase, PacketAssert):
    def test_example(self):
        self.assertHexEqual(Ether(), Ether("10.10.10.10"), "Frame should be the same")

    def text_example_negative(self):
        self.assertNotEqual(Ether(), Ether(), "Frame should be diffrent")

    def test_example_bytes(self):
        self.assertBytesEqual(Ether(), Ether(), "Bytes should be equal")
```


### hex_equal (since v0.1.11)
Return bool status of equality and print status if there is a difference between objects
```python
from scapy_helper import hex_equal

# hex_equal(first, second, show_inequalities=True, **options_for_show_diff):
assert hex_equal(Ether(), second_ether)
```

## Compare
### table_diff (tdiff as shortcut)
```text
from scapy_helper.compare import Compare
Compare(frame_1, frame_2).table_diff()

| Diff or header              | Element   | First             | Second            |
|-----------------------------|-----------|-------------------|-------------------|
| ###[ Ethernet ]###          |           |                   |                   |
|                             | dst       | 00:00:00:00:00:00 | 00:00:00:00:00:00 |
|                             | src       | 00:00:00:00:00:00 | 00:00:00:00:00:00 |
|                             | type      | IPv4              | IPv4              |
| ###[ IP ]###                |           |                   |                   |
|                             | version   | 4                 | 4                 |
|                             | ihl       | None              | None              |
|                             | tos       | 0x0               | 0x0               |
|                             | len       | None              | None              |
|                             | id        | 1                 | 1                 |
|                             | flags     |                   |                   |
|                             | frag      | 0                 | 0                 |
| 15 !=  20                   | ttl       | 15                | 20                |
|                             | proto     | udp               | udp               |
|                             | chksum    | None              | None              |
| 192.168.1.1 !=  192.168.1.2 | src       | 192.168.1.1       | 192.168.1.2       |
|                             | dst       | 192.168.1.20      | 192.168.1.20      |
| \options   \                |           |                   |                   |
| ###[ UDP ]###               |           |                   |                   |
|                             | sport     | domain            | domain            |
|                             | dport     | domain            | domain            |
|                             | len       | None              | None              |
|                             | chksum    | None              | None              |
|                             |           |                   |                   |

```



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/NexSabre/scapy_helper",
    "name": "scapy-helper",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Nex Sabre",
    "author_email": "nexsabre@protonmail.com",
    "download_url": "https://files.pythonhosted.org/packages/e7/4d/ee92f1aad75d6e21098b4225cb8f62317bdc51fb10566e008854a4534713/scapy_helper-0.10.2.tar.gz",
    "platform": "",
    "description": "![Test](https://github.com/NexSabre/scapy_helper/workflows/Test/badge.svg?branch=master)\n![CodeQL](https://github.com/NexSabre/scapy_helper/workflows/CodeQL/badge.svg?branch=master)\n[![PyPI version](https://badge.fury.io/py/scapy-helper.svg)](https://badge.fury.io/py/scapy-helper)\n\n# Scapy helper (aka. Packet Helper) \nThis micro library popularizes some handy tricks that make it easy usage of Scapy.\n\n## TL;DR\n```python\nfrom scapy_helper import *\n\n# Dump frame hex\nhex_value = get_hex(Ether())\n# hex_value: \n'ff ff ff ff ff ff 00 00 00 00 00 00 90 00'\n\n# Convert and print \nshow_hex(Ether())\n# output: \n# ff ff ff ff ff ff 00 00 00 00 00 00 90 00\n\n# Show the differences\n#   can be result of get_hex() or string or frame\nsecond_ether = \"ff ff fc ff ff fa 00 00 00 00 00 00 90 00 11 11 00 22\" \nshow_diff(Ether(), second_ether)\n# output: \n# WARN:: Frame len is not the same\n# WARN:: Second row is longer by the 4B\n#\n# __ __ ff __ __ ff __ 00 00 00 00 00 __ __ XX XX XX XX | len: 14B\n# __ __ fc __ __ fa __ 11 11 11 11 11 __ __ 11 11 00 22 | len: 18B\n#\n# Not equal at 11B\n\n# You can add a index to it\nshow_diff(Ether(), second_ether, index=True)\n# output: \n# __ __ ff __ __ ff __ 00 00 00 00 00 __ __ XX XX XX XX | len: 14B\n# __ __ fc __ __ fa __ 11 11 11 11 11 __ __ 11 11 00 22 | len: 18B\n#                                                       |\n#       ^2       ^5    ^7 ^8 ^9 10 11       14 15 16 17 | position\n#\n# Not equal at 11B\n\n# You can add a custom char to mark a missing elements\nshow_diff(Ether(), second_ether, index=True, empty_char=\"+\")\n# output: \n# __ __ ff __ __ ff __ 00 00 00 00 00 __ __ ++ ++ ++ ++ | len: 14B\n# __ __ fc __ __ fa __ 11 11 11 11 11 __ __ 11 11 00 22 | len: 18B\n#                                                       |\n#       ^2       ^5    ^7 ^8 ^9 10 11       14 15 16 17 | position\n```\n\n## Addons\nSince version v0.5.1, to the _scapy_helper_ was added `chexdump` and `hexdump`. \nWith v0.7.1 we introduce a `mac2int` and `int2mac`. Version v0.10 bring `hstrip`.\n\n### hstrip\nSince v0.10, allows to convert a Scapies hexdump into clean string-hex format.\nSelect a hexdump and copy into clipboard.\n\n```text\n>>> f = Ether()/IP()/TCP()\n>>> hexdump(f)\n0000  FF FF FF FF FF FF 00 00 00 00 00 00 08 00 45 00  ..............E.\n0010  00 28 00 01 00 00 40 06 7C CD 7F 00 00 01 7F 00  .(....@.|.......\n0020  00 01 00 14 00 50 00 00 00 00 00 00 00 00 50 02  .....P........P.\n0030  20 00 91 7C 00 00                                 ..|..\n>>> \n```\nIn command line type `hstrip`\n\n```text\nFF FF FF FF FF FF 00 00 00 00 00 00 08 00 45 00\n00 28 00 01 00 00 40 06 7C CD 7F 00 00 01 7F 00\n00 01 00 14 00 50 00 00 00 00 00 00 00 00 50 02\n20 00 91 7C 00 00\n```\n\nVoil\u00e0! You have in your clipboard striped version of hexdump. Now you can paste it into [packetor.com](http://packetor.com)\n\n### chexdump\n```python\nfrom scapy_helper import chexdump\n\npacket = \"\\x00\\x01\".encode()\n\n# chexdump as we know \nchexdump(packet)\n# 0x00, 0x01\n\n# with return \nval = chexdump(\"\\x00\\x01\".encode(), dump=True)\n# or if you need a list\nval = chexdump(\"\\x00\\x01\".encode(), dump=True, to_list=True)\n```\n\n### hexdump\n```python\nfrom scapy_helper import hexdump\n\npacket = Ether(dst=\"ff:ff:ff:ff:ff:ff\",\n               src=\"00:00:00:00:00:00\")\n\n# chexdump as we know \nhexdump(packet)\n# 0000   ff ff ff ff ff ff 00 00 00 00 00 00 08 00 45 00   ..............E.\n# 0010   00 14 00 01 00 00 40 00 fb e8 00 00 00 00 7f 00   ......@.........\n# 0020   00 01                                             ..\n\n# with return \nval = hexdump(packet, dump=True)\n# or if you need a list\nval = hexdump(packet, dump=True, to_list=True)\n```\n\n### int2mac\nConvert an integer value into mac address. Letters by the default are lower case. \n```python\nfrom scapy_helper import int2mac\n\nint2mac(73596036829, upper=True)\n# \"00:11:22:AA:66:DD\"\n```\n\n### mac2int\nConvert a mac address into integer value \n```python\nfrom scapy_helper import mac2int\n\nmac2int(\"00:11:22:AA:66:DD\")\n# 73596036829\n```\n\n### ip2int\nConvert IP address string into int value\n```python\nfrom scapy_helper import ip2int\n\nip2int(\"0.0.0.0\")\n# 0\n```\n\n### int2mac\nConvert an int value into IP address string\n```python\nfrom scapy_helper import int2ip\n\nint2ip(0)\n# 0.0.0.0\n```\n\n## Test case usage\n### Extends test class using PacketAssert (since v0.3.1)\n__Note: In the v0.3.0 this class was called HexEqual__\n\nYou can use assertHexEqual/assertHexNotEqual and assertBytesEqual/assertBytesNotEqual in the tests.\nWhen the assertion fails, wrapper produces information about the frames (in hex).\n\n```python\nimport unittest\nfrom scapy_helper.test_case_extensions.packet_assert import PacketAssert\n\nclass TestExample(unittest.TestCase, PacketAssert):\n    def test_example(self):\n        self.assertHexEqual(Ether(), Ether(\"10.10.10.10\"), \"Frame should be the same\")\n\n    def text_example_negative(self):\n        self.assertNotEqual(Ether(), Ether(), \"Frame should be diffrent\")\n\n    def test_example_bytes(self):\n        self.assertBytesEqual(Ether(), Ether(), \"Bytes should be equal\")\n```\n\n\n### hex_equal (since v0.1.11)\nReturn bool status of equality and print status if there is a difference between objects\n```python\nfrom scapy_helper import hex_equal\n\n# hex_equal(first, second, show_inequalities=True, **options_for_show_diff):\nassert hex_equal(Ether(), second_ether)\n```\n\n## Compare\n### table_diff (tdiff as shortcut)\n```text\nfrom scapy_helper.compare import Compare\nCompare(frame_1, frame_2).table_diff()\n\n| Diff or header              | Element   | First             | Second            |\n|-----------------------------|-----------|-------------------|-------------------|\n| ###[ Ethernet ]###          |           |                   |                   |\n|                             | dst       | 00:00:00:00:00:00 | 00:00:00:00:00:00 |\n|                             | src       | 00:00:00:00:00:00 | 00:00:00:00:00:00 |\n|                             | type      | IPv4              | IPv4              |\n| ###[ IP ]###                |           |                   |                   |\n|                             | version   | 4                 | 4                 |\n|                             | ihl       | None              | None              |\n|                             | tos       | 0x0               | 0x0               |\n|                             | len       | None              | None              |\n|                             | id        | 1                 | 1                 |\n|                             | flags     |                   |                   |\n|                             | frag      | 0                 | 0                 |\n| 15 !=  20                   | ttl       | 15                | 20                |\n|                             | proto     | udp               | udp               |\n|                             | chksum    | None              | None              |\n| 192.168.1.1 !=  192.168.1.2 | src       | 192.168.1.1       | 192.168.1.2       |\n|                             | dst       | 192.168.1.20      | 192.168.1.20      |\n| \\options   \\                |           |                   |                   |\n| ###[ UDP ]###               |           |                   |                   |\n|                             | sport     | domain            | domain            |\n|                             | dport     | domain            | domain            |\n|                             | len       | None              | None              |\n|                             | chksum    | None              | None              |\n|                             |           |                   |                   |\n\n```\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Several features that should help you use Scapy",
    "version": "0.10.2",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "02785c6a7038230451c0d4ecaa49e4b0",
                "sha256": "859d2e7183554a2ec0383848afc81fb38c277f9a739652b227839c32efa447ef"
            },
            "downloads": -1,
            "filename": "scapy_helper-0.10.2-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "02785c6a7038230451c0d4ecaa49e4b0",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 20189,
            "upload_time": "2021-05-04T18:59:47",
            "upload_time_iso_8601": "2021-05-04T18:59:47.826818Z",
            "url": "https://files.pythonhosted.org/packages/d1/56/cf9d34eb0efbbffed52b1b402de9bebe29865f7c25788f79d54f257bb537/scapy_helper-0.10.2-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "b0c45a7da82e24348f60feaf8bad9aaa",
                "sha256": "9e1ad9bfa8e0db4c8c881af3bbab7c2b06e7443828c4d1ba23545e92d38ff308"
            },
            "downloads": -1,
            "filename": "scapy_helper-0.10.2.tar.gz",
            "has_sig": false,
            "md5_digest": "b0c45a7da82e24348f60feaf8bad9aaa",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 16112,
            "upload_time": "2021-05-04T18:59:50",
            "upload_time_iso_8601": "2021-05-04T18:59:50.123383Z",
            "url": "https://files.pythonhosted.org/packages/e7/4d/ee92f1aad75d6e21098b4225cb8f62317bdc51fb10566e008854a4534713/scapy_helper-0.10.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-05-04 18:59:50",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "NexSabre",
    "error": "Could not fetch GitHub repository",
    "lcname": "scapy-helper"
}
        
Elapsed time: 0.24884s