diff --git a/README.md b/README.md index 69949dd..770f78f 100644 --- a/README.md +++ b/README.md @@ -275,6 +275,7 @@ the details about them follows in their own manual. Take a look at the ``Table 3 | **Sub-task** | **What does it perform?** | **Manual** | |:---------------------:|:------------------------------------------------------:|:--------------------------------------------------------------------------------------------------:| | ``pcap-import`` | Imports packet from a PCAP file into a pigsty file | [``cat doc/pcap-import.md``](https://github.com/rafael-santiago/pig/blob/master/doc/pcap-import.md)| +| ``shell`` | Executes pig on interactive mode | [``cat doc/shell.md``](https://github.com/rafael-santiago/pig/blob/master/doc/shell.md) | ## Pig tricks diff --git a/RELNOTES.md b/RELNOTES.md index 125b875..9f5d831 100644 --- a/RELNOTES.md +++ b/RELNOTES.md @@ -1,5 +1,15 @@ # pig - Release Notes +## Version: 0.0.5 + +### Features + +- Introducing the sub-task ``shell``, now is possible to use ``pig`` on interactive mode besides the default batch mode. + +### Bugfixes + +- None! :1st_place_medal: + ## Version: 0.0.4 ### Features diff --git a/doc/man/pig.1 b/doc/man/pig.1 index fb6de15..6f9e520 100644 --- a/doc/man/pig.1 +++ b/doc/man/pig.1 @@ -1,4 +1,4 @@ -.TH pig 1 "August 22, 2016" "version 0.0.4" "USER COMMANDS" +.TH pig 1 "March 30, 2017" "version 0.0.5" "USER COMMANDS" .SH NAME pig \- a packet crafting tool .SH SYNOPSIS @@ -43,9 +43,11 @@ Specifies the pigsty traverse mode. It can be \fIrandom\fR (the default) or \fIs Shows the application version. .TP -\-\-sub-task=\fI\fR +\-\-sub-task=\fI\fR Asks the execution of a specific task. Call it with the option \fI\-\-help\fR in order -to know more about the related task. +to know more about the related sub-task. + +Until now the implemented sub-tasks are: \fIpcap-import\fR, \fIshell\fR. .TP \-\-help diff --git a/doc/shell.md b/doc/shell.md new file mode 100644 index 0000000..ed69d88 --- /dev/null +++ b/doc/shell.md @@ -0,0 +1,265 @@ +# The shell sub-task + +This sub-task allows you to use ``pig`` on interactive mode. For doing this you should call the +application with the following arguments: + +``` +you@SOMEWHERE:~/over/the/rainbow# pig --sub-task=shell +``` + +Just after will be presented a very simple shell prompt: + +``` +you@SOMEWHERE:~/over/the/rainbow# pig --sub-task=shell +~ _ +``` + +With this shell you are able to do anything that you do on batch mode and also things that you do not. + +Even on interactive mode is necessary to indicate the options ``--gateway`` or ``--no-gateway``, ``--net-mask``, ``--lo-iface``. +Depending on the loaded signatures, you also need to specify some additional options related with your desired task. + +## Setting the pig options + +There are two ways for doing this. You can pass these options when starting ``pig`` on "shell mode" or into the ``shell`` +specify the options using the command ``set`` as follows: + +``` +~ set net-mask=255.255.255.0 +~ set gateway=10.0.2.2 +~ set lo-iface=eth0 +``` + +To probe any ``pig``'s option you should call ``set`` without arguments. + +``` +~ set + pig + --sub-task=shell + --net-mask=255.255.255.0 + --gateway=10.0.2.2 + --lo-iface=eth0 +~ +``` + +If due to some reason you want to remove an option you should use the command ``unset``: + +``` +~ unset net-mask +``` + +## Inline definition of pigsties + +The interactive mode allows us to use the shell prompt as a very simple text editor and define signatures on the fly. + +Any command started with ``[`` and ended with ``]`` is considered a pigsty. So: + +``` +~ [ ip.version = 4, ip.protocol = 6, signature = "silly-one" ] +1 signature was added. -- +``` + +All we should do is define a pigsty using the rules explained in the main [``README.md``](https://github.com/rafael-santiago/pig/blob/master/README.md). + +Sometimes a pigsty can be longer so a good way is to escape the line with a backslash to keep your sanity: + +``` +~ [ ip.version = 4,\ +... ip.protocol = 17,\ +... ip.src = user-defined-ip,\ +... ip.dst = 224.12.23.3,\ +... udp.src = 6,\ +... udp.dst = 20,\ +... udp.payload = "(null)",\ +... signature = "s1lly-t0o" ] +1 signature was added. -- +``` + +I find it good but only for minor tasks, things that you do not need to follow any method. + +## Manipulating your loaded pigsties + +When you have some specific routine task to perform, the best way is to save the related pigsties as files +and later load them all. When you use ``pig`` on standard ``batch-mode`` you can load previous pigsties with +the option ``--signatures``. On ``shell`` you can use the command ``pigsty`` with its ``sub-command`` called ``ld``: + +``` +~ pigsty ld /usr/local/pigsty/pentest-session-1.pigsty +``` + +If you have more than one file to load, you can pass them as a comma separated list. Take a look: + +``` +~ pigsty ld /usr/local/pigsty/pentest-session-1.pigsty, /usr/local/pigsty/pentest-session-2.pigsty,\ +... /usr/local/pigsty/snort-rules-test/worms.pigsty,\ +... /usr/local/pigsty/snort-rules-test/backdoors.pigsty,\ +... /usr/local/pigsty/snort-rules-test/ddos-from-last-3-weeks.pigsty +``` + +Once the signatures loaded you can probe what your ``pig`` has into his brain using the sub-command ``ls``: + +``` +~ pigsty ls +-- SIGNATURES + + * silly-one + * s1lly-t0o + +2 entries were found. -- +``` + +If you are looking for some specific pattern of signature name you can use the ``ls`` with a ``glob``: + +``` +~ pigsty ls *droids* +-- SIGNATURES + + * the-droids-that-we-are-looking-for + +1 entry was found. -- +``` + +We can also pass a comma separated list of patterns: + +``` +~ pigsty silly-one, *[Ss]ub?7*, *deep* +``` + +You can load a set of pigsties from a file with the sub-command ``ld``. In order to remove them from memory you should use the +sub-command ``rm``. + +``` +~ pigsty rm silly-one +``` + +The ``rm`` argument is taken as a glob, so: + +``` +~ pigsty rm * +``` + +Will remove every loaded pigsty from memory. + +Also is valid to call ``rm`` as follows: + +``` +~ pigsty rm silly-one, *[Ss]ub?7* +``` + +There is a synonym for ``pigsty rm *`` command that is ``pigsty clear``. + +## Sending packets without method, a.k.a flooding + +In order to do it you should use the command ``flood`` + +``` +~ flood +``` + +It will send random signatures based on the signatures previously read throught ``pigsty ld`` and/or ``--signatures=(...)``. +If you want to cancel this endless flood session you should press ``CTRL + c``. + +Is also possible to flood with just a specific amount of random signatures: + +``` +~ flood 15 +``` + +Again, if you want to cancel it, you should press ``CTRL + c``. + +## Sending packets with some method + +In ``shell`` mode ``pig`` allows you to do a more specific packet crafting. You can send a specific signature or still a +set of signatures based on a glob pattern. Besides the specification of signatures is also possible to indicate the +total of sendings for each found signature based on the supplied search pattern. + +The command that allows you do it is ``oink``. Look: + +``` +~ oink SpaceCadet, Catamaran +``` + +The command sample above will send the signatures "SpaceCadet" and "Catamaran". + +After the glob pattern, you can also specify the total of sendings: + +``` +~ oink "SpaceCadet", 10, Catamaran +``` + +This last shown command will send 10 packets of "SpaceCadet" signature and then 1 of "Catamaran". + +``` +~ oink "[sS]ub?7*", "NewApt*[Ww][Oo][Rr][Mm]*", 60 +``` + +Now all signatures named using the pattern ``[sS]ub?7`` will be sent. Also any signature that its name matches the +pattern ``NewApt*[Ww][Oo][Rr][Mm]*`` will be sent sixty times. + +## Executing external commands from the shell + +When you are doing some pentest session or anything related, sometimes you need to switch to other applications, maybe +a text editor to take some notes, etc. Being on ``shell`` mode you can use the "outsider marker" in order to execute the +supplied command outside from the pig's shell. + +The outsider marker is denoted by an exclamation symbol: + +``` +~ !ls /usr/local/report.txt +``` + +After the command execution you will back to the ``shell`` mode, so is possible to run programs that will hang the +prompt until their exit: + +``` +~ !mcedit /usr/local/report.txt +``` + +## Pig shell tricks + +If you really enjoy using ``pig`` on shell mode and the ``network mask``, ``gateway`` and ``lo-iface`` data +never changes, you can pass this data when starting ``pig``: + +``` +you@SOMEWHERE:~/over/the/rainbow# pig --sub-task=shell \ +> --net-mask=255.255.255.0 --gateway=10.0.2.2 --lo-iface=eth0 +``` + +Even better: you can create a shell script to automate this call... + +```bash +# pig-shell.sh +pig --sub-task=shell --net-mask=255.255.255.0 --gateway=10.0.2.2 --lo-iface=eth0 +``` + +...and then: + +``` +you@SOMEWHERE:~/over/the/rainbow# ./pig-shell.sh +``` + +Maybe change the script to read the network config data from ``$1``...``$n`` arguments. Anyway, it is up to you. + + +## Commands summary + +Well, now that you master all shell aspects present in ``pig`` here goes a short summary of all you have +been learning during this reading: + + +| **Command** | **What does it perform?** | +|:------------------------:|:-------------------------------------------------------------------------:| +| ``set