Metadata-Version: 2.1
Name: pwnchain
Version: 0.2.0
Summary: Cascading different tools in automated fashion.
Home-page: https://github.com/nikolas-beisemann/pwnchain
Author: Nikolas Beisemann
Author-email: nikolas@disroot.org
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/nikolas-beisemann/pwnchain/issues
Description: # 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/
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
