Shell and interactive command line¶
PacketWeaver gives you two ways of interacting with your Abilities (see Introduction for explanations).
The pw interactive CLI¶
The interactive CLI is the main way of interacting with the framework. It is composed of two levels: one that enables you to browse and to select available Abilities, and another one to configure and run a selected Ability.
The interactive CLI offers command history features similar to that of usual
shells, such as history search and command recall, using ctrl+p
, ctrl+n
and ctrl+r
.
To cancel a command, you may use ctrl+c
. ctrl+d
and exit
may be
used to return to unselect an Ability, or exit the framework. Finally, tab
can be used to trigger autocompletion of the current command line, whenever
available.
Ability browsing and selection¶
To launch the interactive CLI, you may run the run_pw
script located at the
root of the PacketWeaver git repository:
./run_pw
This CLI understands a bunch of commands whose list you can obtain by typing
the help
command or ?
for short. Help of any of the listed commands can
be obtained by using the help
command followed by the name of a command:
pw> help list
For instance, the list
command displays a list of all the available standalone
Abilities that are loaded from the configured packages.
Each list entry is indexed by a number, so that you can refer to this Ability
by its associated number. For instance, to use the Ping a target
Ability,
you would type list
and then use 1
to select the Ability for use,
because it is the first listed:
pw> list
1 Ping a target -- []
2 Ping a prefix -- []
3 DNSProxy -- ['Application_Layer', 'Threaded', 'DNS']
pw> use 1
pw (Ping a target)>
While list
enumerates all loaded standalone Abilities, this might not be
convient if you loaded a very large package containing tons of abilities. You
may use the search
command to find any Ability that would be listed by
list
. Search results are indexed, just like listed Abilities are.
search
matches Ability names by default, using a case-insensitive
comparison:
pw> search ping
1 ping a target --
2 ping a prefix --
pw> search dns
1 dnsProxy -- Application_Layer, Threaded, DNS
You can also search by tags:
pw> search app
No matching ability found.
pw> search -a application_layer
1 DNSProxy -- application_layer, Threaded, DNS
Searching by tags is eased by autocompletion that will provide you with a list of all the tags that are registered by currently available Abilities.
Searches for tags may use multiple tags simultaneously. When multiple tags using a logical operation
between tags (and or or) may be specified with flags. The -o
flag
indicates an OR, while -a
indicates an AND.
For instance, you could search for all Abilities that are related to DNS and to MITM:
pw> search -a dns mitm
No matching ability found.
You may also want to list all Abilities that are either related to DNS or to HTTP:
pw> search -o dns http
1 DNSProxy -- application_layer, Threaded, DNS
Any of these flags can be used if you are filtering with only one tag.
Note
A default index is built when the framework starts. You can quickly re-open you current in-development Ability across
framework restart by recalling the last use
command to access it directly.
After selecting an index, if no errors are displayed, you now are interacting with a CLI specific to the selected Ability. This CLI is described in details in the next chapter.
Configuring, editing and running an Ability¶
Once more, the help
command is available to list the commands that are
available with this new interactive CLI, and the help
command may be used
to obtain further details about the listed commands.
You may also get more details about the selected Ability, with the info
command:
pw (DNSProxy)> info
------------------------------ [ DNSProxy ] -------------------------------
type: Standalone
description: Replacement for DNSProxy
authors: Florian Maury
tags: Application_Layer, Threaded, DNS
reliability: Incomplete
---------------------------------------------------------------------------
Details about the role and the usage of the selected Ability may also be
obtained with the howto
command:
pw (DNSProxy)> howto
This DNS proxy intercepts DNS requests at OSI layer 2.
...
the real DNS server is connected to a different card than the victim.
The options
command (or its alias ls
) lists the Ability parameters that may be set before
running that Ability:
pw (DNSProxy)> options
------------------------------- [ Options ] -------------------------------
fake_zone = /bin/true
policy_zone = /bin/true
ip_src (Optional) = None
ip_dst (Optional) = None
port_dst (Optional) = 53
interface = None
outerface (Optional) = None
quiet = True
---------------------------------------------------------------------------
Options may be set to user values or reset to their default values using the
set
and clear
commands. For instance, let’s set some option value:
pw (DNSProxy)> set ip_dst=8.8.8.8
pw (DNSProxy)> set interface=eth0
pw (DNSProxy)> set ip_src=192.0.2.1
pw (DNSProxy)> options
------------------------------- [ Options ] -------------------------------
fake_zone = /bin/true
policy_zone = /bin/true
ip_src (Optional) = 192.0.2.1
ip_dst (Optional) = 8.8.8.8
port_dst (Optional) = 53
interface = eth0
outerface (Optional) = None
quiet = True
---------------------------------------------------------------------------
Note
Some input parameters (such as IpOpt) support value generators. You can get
a list of them using the autocompletion when trying to set a new value
(set ip_dst=
+ Tab Tab
) to them.
For instance, you may set an IP address to the special value RandIP4
. A
new IP address will be generated each time the Abliity is run:
pw (DNSProxy)> set ip_dst=RandIP4
pw (DNSProxy)> options
------------------------------- [ Options ] -------------------------------
fake_zone = /bin/true
policy_zone = /bin/true
ip_src (Optional) = 192.0.2.1
ip_dst (Optional) = RandIP4
port_dst (Optional) = 53
interface = eth0
outerface (Optional) = None
quiet = True
---------------------------------------------------------------------------
You may also use this special keyword as a function, to set a random value to the variable. This random value won’t change across runs:
pw (DNSProxy)> set ip_dst=RandIP4()
pw (DNSProxy)> options
------------------------------- [ Options ] -------------------------------
fake_zone = /bin/true
policy_zone = /bin/true
ip_src (Optional) = 192.0.2.1
ip_dst (Optional) = 198.51.100.42
port_dst (Optional) = 53
interface = eth0
outerface (Optional) = None
quiet = True
---------------------------------------------------------------------------
Note
If you try to set a invalid value for an option, you will receive an error message and the stored option value will remain unchanged. Each type of options is designed with a set of constraints, including some customizable ones, to validate the values that may be assigned to it.
Now let’s reset the source IP address to its default value:
pw (DNSProxy)> clear ip_src
pw (DNSProxy)> options
------------------------------- [ Options ] -------------------------------
fake_zone = /bin/true
policy_zone = /bin/true
ip_src (Optional) = None
ip_dst (Optional) = 8.8.8.8
port_dst (Optional) = 53
interface = eth0
outerface (Optional) = None
quiet = True
---------------------------------------------------------------------------
Now let’s reset all options to their default value:
pw (DNSProxy)> clear
pw (DNSProxy)> options
------------------------------- [ Options ] -------------------------------
fake_zone = /bin/true
policy_zone = /bin/true
ip_src (Optional) = None
ip_dst (Optional) = None
port_dst (Optional) = 53
interface = None
outerface (Optional) = None
quiet = True
---------------------------------------------------------------------------
Once you and your options are all set, you may run the Ability with the run
command:
pw (DNSProxy)> run
Abilities may run until they are done with their tasks. In that case, they will give back control to the CLI once they terminated. Other Abilities may start some services and are designed to run until interrupted by the SIGINT signal (ctrl+c). Of course, you may interrupt any running Ability, in case it went into an infinite loop of sorts, with the same key sequence.
If you are satisfied by the results of the Ability that you just run, you may want to save the parameter values that you used. This enables you to reload them, during a future session of PacketWeaver, or to back them up for a future audit report, for instance.
To save the current parameter values, you may use the save
command:
pw (DNSProxy)> save /path/to/file.ini
To reload them, you may use the load
command:
pw (DNSProxy)> load /path/to/file.ini
At some point, you may feel the need to make some minor code adjustments in the
Ability you are about to run (e.g. a bug fix…). You don’t need to exit
PacketWeaver for this. The editor
command will open the source code file
of the selected Ability and of all other Abilities that take part in the
selected Ability operations. Which source code editor is run is configured
within PacketWeaver configuration file.
Finally, once configured you may ask of PacketWeaver to automatically generate a shell command line that will run this Ability with the current configuration from shell:
pw (DNSProxy)> cmd
export PW_OPT_FAKE_ZONE='/bin/true'
export PW_OPT_POLICY_ZONE='/bin/true'
export PW_OPT_IP_SRC='None'
export PW_OPT_IP_DST='None'
export PW_OPT_PORT_DST='53'
export PW_OPT_INTERFACE='None'
export PW_OPT_OUTERFACE='None'
export PW_OPT_QUIET='True'
export PYTHONPATH='/opt/pw/pw/packetweaver:/usr/local/lib/python2.7/dist-packages/python_twitter-1.0-py2.7.egg:/usr/local/lib/python2.7/dist-packages/oauth2-1.5.211-py2.7.egg:/usr/local/lib/python2.7/dist-packages/pympress-0.3-py2.7.egg:/opt/pw/pw:/usr/lib/python2.7:/usr/lib/python2.7/plat-x86_64-linux-gnu:/usr/lib/python2.7/lib-tk:/usr/lib/python2.7/lib-old:/usr/lib/python2.7/lib-dynload:/usr/local/lib/python2.7/dist-packages:/usr/lib/python2.7/dist-packages:/usr/lib/python2.7/dist-packages/PILcompat:/usr/lib/python2.7/dist-packages/gst-0.10:/usr/lib/python2.7/dist-packages/gtk-2.0:/usr/lib/python2.7/dist-packages/ubuntu-sso-client:/usr/lib/python2.7/dist-packages/ubuntuone-client:/usr/lib/python2.7/dist-packages/ubuntuone-couch:/usr/lib/python2.7/dist-packages/ubuntuone-storage-protocol:/opt/pw/scapy'
python /opt/pw/pw/packetweaver/pw.py use -p base -a DNSProxy --fake_zone=${PW_OPT_FAKE_ZONE} --policy_zone=${PW_OPT_POLICY_ZONE} --ip_src=${PW_OPT_IP_SRC} --ip_dst=${PW_OPT_IP_DST} --port_dst=${PW_OPT_PORT_DST} --interface=${PW_OPT_INTERFACE} --outerface=${PW_OPT_OUTERFACE} --quiet=${PW_OPT_QUIET}
This command line can be copy/pasted in a shell console to start the ability with these options.
Warning
This command line generation is experimental and might quickly evolve.
Note
You can also use the cmd oneline
option to get a bash oneline command that can be directly tested.