PwnChain
Introduction and Goals
PwnChain is a tool for cascading different tools in an automated fashion. Modules with specified input and output domains are linked in a tree structure to fulfill a certain task.
The application is designed for the automatization of penetration testing sequences. Yet the application is aimed to be flexible enough to be used in any scenario where different interdependent CLI tools are processed in order.
PwnChain uses .json configuration files to determine which tools shall be executed in a certain way, using regular expressions to parse the output of a tool to be used as input for subsequent tools. Its goal is to be easily customizable to fulfill different repetitive tasks.
Warning
PwnChain executes shell commands as instructed by the configuration file.
You should never use configuration files that you do not fully understand.
Installation
PwnChain requires at least Python 3.8 to run.
pip (Recommended)
python3 -m pip install --upgrade pwnchain
Build Package
cd $PWNCHAIN_ROOT
python3 -m pip install --upgrade build
python3 -m build
python3 -m pip install --upgrade dist/pwnchain-*.tar.gz
Run Tests
pytest
or
cd src
python3 -m pytest ../tests
The latter is especially helpful during development.
Usage
python3 -m pwnchain
You can use the -h or --help option to display the various command line options available.
Example usage
python3 -m pwnchain cfg/enumerate.json -sserv:host:10.0.0.1
Configuration
Configuration files are composed in .json format. You can check out the cfg/ directory of this repository for some usage examples.
The configuration file uses nested module descriptions.
Using Variables
In the various configuration strings, variables can be used by {var_name}. All variables collected are carried into all subsequent tool executions, defined in the post attribute of a module. Redeclaring a variable will override its value for all subsequent tool executions.
Variables can either be declared explicitly using the vars attribute, or they can be captured from the tool execution output using the patterns attribute.
Attributes
Description of a module, identical for the root module, and any modules in the post list.
| Attribute | Description | Example |
|---|---|---|
name |
Used for output logging. Mandatory. | "name": "service-discovery" |
enabled |
A boolean value indicating whether a module is executed. Defaults to true. | "enabled": false |
condition |
Pre-condition which is evaluated to decide whether a module is executed. Can be any python expression. | "condition": "'{protocol}' == 'ssh'" |
files |
List of files embedded within the module configuration. | See separate description below |
cmd |
Command to be executed. Mandatory. | "cmd": "nmap -sV {host}" |
vars |
Dictionary of variables directly injected into a module. | "vars": { "host": "10.0.0.1" } |
patterns |
List of pattern dictionaries for capturing variables from module output. | See separate description below |
logfile |
Name of file to use if the -o option is used for saving tool output to files. |
"logfile": "nmap-{host}.log" |
submodules |
Dictionary of submodules to be executed after the command has run. | See separate description below |
The files list shall contain of dictionaries with the following attributes:
| Attribute | Description | Example |
|---|---|---|
name |
Name of the file, which can be used as a variable by the module and its submodules. Mandatory. | "name": "wordlist.txt" |
type |
One of text,base64,wget, for raw text, base64 encoded content, or URI of remote content. Mandatory. |
"type": "wget" |
content |
Content as specified by type. Mandatory. |
"content": "http://localhost/w.txt" |
The patterns list consists of dictionaries with the following attributes:
| Attribute | Description | Example |
|---|---|---|
pattern |
Regular expression using capture groups for variable extraction. Mandatory. | "pattern": "^(\\d+)" |
groups |
List of variable names for the capture groups in order of declaration in the regex. Mandatory. | "groups": [ "port" ] |
log |
Message format to output if a pattern was successfully matched. | "log": "Port {port} identified!" |
The submodules dictionary may consist of the following attributes:
| Attribute | Description | Example |
|---|---|---|
on_match |
List of modules to be run when matching a pattern from the patterns list. |
"on_match": []" |
always |
List of modules to always run after cmd has been executed. |
"always": []" |
License
PwnChain is available under the GPLv3 license. Please see the LICENSE file supplied with the software, or at https://www.gnu.org/licenses/
1 maintainer
Release files for pwnchain 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pwnchain-0.2.0.tar.gz | 21.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pwnchain-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 54.2 kB
Release files / pwnchain-0.2.0.tar.gz
| Download URL | pwnchain-0.2.0.tar.gz |
|---|---|
| Size | 21.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d916005dbecf9c2c745a750cdd3ae59371c0e5f823d8b62e3464a14f4ea2a50
|
|
BLAKE2b-256 checksum How to use checksums |
982f271d3ea76133ce0b86f88a7833c93889a9cb8cc476086b3a60f1f6355716
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2
|
Release files / pwnchain-0.2.0-py3-none-any.whl
| Download URL | pwnchain-0.2.0-py3-none-any.whl |
|---|---|
| Size | 33.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
73221f2e2cec5b58b2a5344dc3283f0531482bb7e70410bbc53ed979837b1b61
|
|
BLAKE2b-256 checksum How to use checksums |
ce6aedc21e2faf7138151e732570d5d0a0a8b4c77d2f22d5b8fec652a0b43beb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2
|
