Presentation

PacketWeaver (pw) is a Python script organization framework. It provides a nice development workflow for quickly creating re-usable Python scripts.

PacketWeaver is a Python framework, which helps build, organize and reuse your Python scripts. It is the most efficient when used in network script development projects.

It sets you up with a simple boilerplate to help building reusable scripts with a clear self-checked input interface and the ability for scripts to be chained between each others. These scripts can be organized into importable packages. This way they can be grouped by projects or topics and easily shared alongside the framework.

In addition to that, it provides a convenient interactive command line interface (CLI) to search, configure and run your scripts and a CLI to run your scripts from your favorite shell and other tools.

It’s all about abilities

When using PacketWeaver, your script source code is placed in an object inherinting from the AbilityBase class. Thus, your scripts are refered to as Abilities during the remaining of this documentation. Your scripts can be arbitrarily complex. They just all starts from the main() function that must be overidden. From there, you can import and run other abilities, build complex pipelines for information that goes through several abilities before rendering a result. That is completely up to you.

Every ability share at least a small common code structure. The first common element is metadata. These metadata uniquely identifies your ability within its package. They also provide additional information such as tags for search purposes, author contact info, and the list of the other abilities that might be invoked/imported from this one.

The second common element is the list of input parameters. These parameters, called options, can be any one from several high-level data types, like an IP address, a boolean, a network interface name or an enumeration.

Using these options offers several benefits. Firstly, you can assign them from the interactive CLI before running an Ability. The value assignment is eased thanks to smart autocompletion of the possible values, whenever possible. Also, values are automatically checked against a set of built-in or customizable constraints before their assignment. This alleviates the need for your script to perform the parsing and the verification of the input values.

For example, we could specify an option that must contain the file system path of a valid executable program:

PathOpt("cmd_name", default="/bin/ls", executable=True)

Also, some special keyword values can be assigned. These keyword values trigger special handlers that might generated random values for your script to use. Various random value generators are available, including the ability to generate randomly IP address within a network subnet without ever returning twice the same IP address. For instance, the following option might be assigned any integer, but by default, it will return a random integer between 0 and 255 when your script will ask for its value:

NumOpt("priority", default="RandByte")

Finally, the last common element of all Abilities is the main function, whose purpose is similar to that of the C main() function. Your script entry point is this function, and your script will end when this function returns or an unhandled exception bubbles up from it.

Within the main function and, in fact, anywhere within the object that contains it, you may take advantage of any of the helpers that are provided by PacketWeaver, including:

  • access to your input parameters as instance attributes, with self.cmd_name or self.priority.
  • use of the integrated display/log engine to organize and colorize your script outputs, e.g self._view.success('My log')
  • call other Abilities and orchestrate their collaboration using the pipe notation: ability1 | ablitiy2

As such, the boilerplate of your Abilities is as short as:

from packetweaver.core.ns import *

class Ability(AbilityBase):
    _info = AbilityInfo(name='Say hello')
    _option_list = []

    def main(self):
        self._view.success('Hello, world')

Developer oriented

PacketWeaver is a framework meant for you to develop new Abilities, build some from existing scripts and reuse them afterwards.

Thus the development workflow has been designed to ease the progressive writing and testing of your Abilities. As such, the PacketWeaver interactive CLI enables you to select any Ability, configure it with its input parameters and test the latest version of your code and parameters with the run command. If the source code changes while PacketWeaver is running, the latest version is automatically reloaded upon restart of the Ability, while keeping the Ability configuration across the reload. In fact, you can even edit your Ability source code right from the interactive CLI using the editor command.

A typical PacketWeaver could be as follows:

pw> list
1 Ping a target -- []
2 Ping a prefix -- []
pw> use 1
pw (Ping a target)> set ip_dst=192.0.2.1
pw (Ping a target)> run
192.0.2.1 is DOWN
pw (Ping a target)> editor
... edit the source code to write DOWN in lowercase ...
pw (Ping a target)> run
192.0.2.1 is down

During this session, we listed the available Abilities within the currently loaded packages. We then selected the first Ability listed. We set the IP address to ping to 192.0.2.1. We ran the Ability, and saw that the IP address did not answer to our ping. We launched the default text editor to change the source code of our Ability, and we ran the ability once more, automatically using the updated source code.

A generic tool

Thanks to its generic design, PacketWeaver is not restricted to a specific use case. Mainly used with Scapy hitherto, the framework features are built to be as generic as possible.

The package mechanism and the use of the Python programming language make it a good option to develop specific tools for a wide variety of use cases. Here are some usage examples where PacketWeaver could fit especially well:

  • In the educational/research field by:
    • building fill-in-the-blank autonomous exercises;
    • creating standalone demonstrations;
    • demonstrating some network protocol mechanisms;
    • automating network devices testing.
  • During a network security audit by:
    • building a bank of your favorite packages
    • taking advantage of advanced Abilities, developed in research phases
    • reuse content from one assignment to another, and progressively improve it

What’s next

You can start exploring the different parts of this documentation, and get started with the different aspects of the framework.

We hope PacketWeaver will make your future script development easier and help you enhance your existing Python scripts!