Skip to content

Commit cf75271

Browse files
dev195dev195
authored
Update README
Updated README file with new requirements, information, and example output
1 parent 7aa565b commit cf75271

File tree

1 file changed

+14
-38
lines changed

1 file changed

+14
-38
lines changed

‎README‎

Lines changed: 14 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,16 @@ Key features:
55
* Deep packet analysis using specialized plugins
66
* Robust stream reassembly
77
* IPv4 and IPv6 support
8-
* Custom output handlers
8+
* Multiple user-selectable output formats and the ability to create custom output handlers
99
* Chainable plugins
10+
* Parallel processing option to divide the handling of data source into separate Python processes
11+
* Enables development of external plugin packs to share and install new externally developed plugins without overlapping the core Dshell plugin directories
1012

1113
## Requirements
12-
* Linux (developed on Red Hat Enterprise Linux 6.7)
13-
* Python 3 (developed with Python 3.6.2)
14+
* Linux (developed on Ubuntu 20.04 LTS)
15+
* Python 3 (developed with Python 3.8.10)
1416
* [pypacker](https://gitlab.com/mike01/pypacker)
15-
* [pcapy](https://github.com/helpsystems/pcapy)
17+
* [pcapy-ng](https://github.com/stamparm/pcapy-ng/)
1618
* [pyOpenSSL](https://github.com/pyca/pyopenssl)
1719
* [geoip2](https://github.com/maxmind/GeoIP2-python)
1820
* [MaxMind GeoIP2 datasets](https://dev.maxmind.com/geoip/geoip2/geolite2/)
@@ -27,37 +29,11 @@ Key features:
2729
* [pyJA3](https://github.com/salesforce/ja3/tree/master/python)
2830
* used in the tls plugin
2931

30-
## Major Changes Since Previous Release
31-
* This is a major framework update to Dshell. Plugins written for the previous version are not compatible with this version, and vice versa.
32-
* Uses Python 3
33-
* Rewritten in Python 3 from the ground up. Python 2 language deprecated on [1 JAN 2020](https://www.python.org/doc/sunset-python-2/)
34-
* By extension, dpkt and pypcap have been replaced with Python3-friendly pypacker and pcapy (respectively).
35-
* Is a Python package
36-
* Converted into a single package, removing the need for the shell to set several environment variables.
37-
* Allows easier use of Dshell plugins in other Python scripts
38-
* Changed "decoders" to "plugins"
39-
* Primarily a word-swap, to clarify that "decoders" can do more than simply decode traffic, and to put Dshell more in line with the terminology of other frameworks.
40-
* Significant reduction in camelCase functions, replaced with more Pythonic snake\_case functions.
41-
* Notable examples include blobHandler->blob\_handler, rawHandler->raw\_handler, connectionInitHandler->connection\_init\_handler, etc.
42-
* All plugins are now chainable
43-
* To accommodate this, handler functions in plugins must now use return statements indicating whether a packet, connection, or similar will continue to the next plugin. The type of object(s) to return depends on the type of handler, but will generally match the types of the handler's input. Dshell will display a warning if it's not the right type.
44-
* Plugins can now use all output modules<sup>\*</sup> available to the command line switch, -O
45-
* That does not mean every output module will be _useful_ to every plugin (e.g. using netflow output for a plugin that looks at individual packets), but they are available.
46-
* alert(), write(), and dump() are now the same function: write()
47-
* Output modules can be listed with a new flag in decode.py, --list-output or --lo
48-
* Arguments for output modules are now passed with the --oargs command-line argument
49-
* \* pcapout is (currently) the exception to this rule. A method has yet to arise that allows it to work with connection-based plugins
50-
* No more dObj declaration
51-
* decode.py just looks for the class named DshellPlugin and creates an instance of that
52-
* Improved error handling
53-
* Dshell handles more of the most common exceptions during everyday use
54-
* Enables development of external plugin packs, allowing the sharing and installation of new, externally-developed plugins without overlapping the core Dshell libraries.
55-
5632
## Installation
5733

5834
1. Install Dshell with pip
59-
* `sudo python3 -m pip install Dshell/` OR `sudo python3 -m pip install <Dshell-tarball>`
60-
2. Configure geoip2 by moving the MaxMind data files (GeoLite2-ASN.mmdb, GeoLite2-City.mmdb, GeoLite2-Country.mmdb) to &lt;install-location&gt;/data/GeoIP/
35+
* `python3 -m pip install Dshell/` OR `python3 -m pip install <Dshell-tarball>`
36+
2. Configure geoip2 by moving the MaxMind data files (GeoLite2-ASN.mmdb, GeoLite2-City.mmdb, GeoLite2-Country.mmdb) to [...]/site-packages/dshell/data/GeoIP/
6137
3. Run `dshell`. This should drop you into a `Dshell> ` prompt.
6238

6339
## Basic Usage
@@ -69,7 +45,7 @@ Key features:
6945
* `decode -p <plugin>`
7046
* Display information about a plugin, including available command line flags
7147
* `decode -p <plugin> <pcap>`
72-
* Run the selected plugin on a pcap file
48+
* Run the selected plugin on a pcap or pcapng file
7349
* `decode -p <plugin1>+<plugin2> <pcap>`
7450
* Chain two (or more) plugins together and run them on a pcap file
7551
* `decode -p <plugin> -i <interface>`
@@ -79,7 +55,7 @@ Key features:
7955
Showing DNS lookups in [sample traffic](http://wiki.wireshark.org/SampleCaptures#General_.2F_Unsorted)
8056

8157
```
82-
Dshell> decode -p dns ~/pcap/dns.cap |sort
58+
Dshell> decode -p dns ~/pcap/dns.cap | sort
8359
[DNS] 2005-03-30 03:47:46 192.168.170.8:32795 -- 192.168.170.20:53 ** ID: 4146, TXT? google.com., TXT: b'\x0fv=spf1 ptr ?all' **
8460
[DNS] 2005-03-30 03:47:50 192.168.170.8:32795 -- 192.168.170.20:53 ** ID: 63343, MX? google.com., MX: b'\x00(\x05smtp4\xc0\x0c', MX: b'\x00\n\x05smtp5\xc0\x0c', MX: b'\x00\n\x05smtp6\xc0\x0c', MX: b'\x00\n\x05smtp1\xc0\x0c', MX: b'\x00\n\x05smtp2\xc0\x0c', MX: b'\x00(\x05smtp3\xc0\x0c' **
8561
[DNS] 2005-03-30 03:47:59 192.168.170.8:32795 -- 192.168.170.20:53 ** ID: 18849, LOC? google.com. **
@@ -165,8 +141,8 @@ Dshell> decode -p country+netflow --country_code=JP ~/pcap/SkypeIRC.cap
165141
Collecting DNS traffic from several files and storing it in a new pcap file.
166142

167143
```
168-
Dshell> decode -p dns+pcapwriter --pcapwriter_outfile=test.pcap ~/pcap/*.cap >/dev/null
169-
Dshell> tcpdump -nnr test.pcap |head
144+
Dshell> decode -p dns+pcapwriter --pcapwriter_outfile=test.pcap ~/pcap/*.cap > /dev/null
145+
Dshell> tcpdump -nnr test.pcap | head
170146
reading from file test.pcap, link-type EN10MB (Ethernet)
171147
15:36:08.670569 IP 192.168.1.2.2131 > 192.168.1.1.53: 40209+ A? ui.skype.com. (30)
172148
15:36:08.670687 IP 192.168.1.2.2131 > 192.168.1.1.53: 40210+ AAAA? ui.skype.com. (30)
@@ -184,8 +160,8 @@ Collecting TFTP data and converting alerts to JSON format using [sample traffic]
184160

185161
```
186162
Dshell> decode -p tftp -O jsonout ~/pcap/tftp_*.pcap
187-
{"dport": 3445, "dip": "192.168.0.10", "data": "read rfc1350.txt (24599 bytes) ", "sport": 50618, "readwrite": "read", "sip": "192.168.0.253", "plugin": "tftp", "ts": 1367411051.972852, "filename": "rfc1350.txt"}
188-
{"dport": 2087, "dip": "192.168.0.13", "data": "write rfc1350.txt (24599 bytes) ", "sport": 57509, "readwrite": "write", "sip": "192.168.0.1", "plugin": "tftp", "ts": 1367053679.45274, "filename": "rfc1350.txt"}
163+
{"ts": 1367411051.972852, "sip": "192.168.0.253", "sport": 50618, "dip": "192.168.0.10", "dport": 3445, "readwrite": "read", "filename": "rfc1350.txt", "plugin": "tftp", "pcapfile": "/home/pcap/tftp_rrq.pcap", "data": "read rfc1350.txt (24599 bytes) "}
164+
{"ts": 1367053679.45274, "sip": "192.168.0.1", "sport": 57509, "dip": "192.168.0.13", "dport": 2087, "readwrite": "write", "filename": "rfc1350.txt", "plugin": "tftp", "pcapfile": "/home/pcap/tftp_wrq.pcap", "data": "write rfc1350.txt (24599 bytes) "}
189165
```
190166

191167
Running a plugin within a separate Python script using [sample traffic](https://wiki.wireshark.org/SampleCaptures#TFTP)

0 commit comments

Comments
 (0)