A tmux plugin that supports penetration testing.
This plugin is by no means any competitor to existing exploit frameworks like metasploit, etc. It is meant to be a helping hand for pentest sessions including stuff like session management snippets, reuse, etc. pp.
It is inspired from metasploit's modules and can be extended by modules.
This is early WIP and the plugin API could change breaking everything ;)
Follow this chapter to install tmux-penmux
The following tools are required by the core:
The following tools are used by the standard modules. They are used to provide the core functionality for the modules. The modules will provide further features, that needs additional tools but these are for the pentesting itself and therefore not included here:
Installation with Tmux Plugin Manager (recommended)
Add plugin to the list of TPM plugins in .tmux.conf:
set -g @plugin 'mfulz/tmux-penmux'
Hit prefix + I to fetch the plugin and source it.
You should now have all tmux-penmux key bindings defined.
Clone the repo:
$ git clone https://github.com/mfulz/tmux-penmux ~/clone/path
Add this line to the bottom of .tmux.conf:
run-shell ~/clone/path/penmux.tmux
Reload TMUX environment:
# type this in terminal
$ tmux source-file ~/.tmux.conf
You should now have all tmux-penmux key bindings defined.
This chapter describes how to use this plugin and it's modules. It will give an overview of the standard modules that are included and how to use them.
This plugin is basically just an API to provide features via modules. The main features are just loading, unloading, running modules and changing their options.
prefix + P + l- load moduleprefix + P + u- unload moduleprefix + P + c- change module optionsprefix + P + r- run module
| Config | Default | Description |
|---|---|---|
set -g @penmux-custom-keytables-dir "$HOME/.tmux/penmux/keytables" |
$HOME/.tmux/penmux/keytables | This directory can hold keytable definitions for modules to override the defaults |
set -g @penmux-custom-module-options-dir "$HOME/.tmux/penmux/options" |
$HOME/.tmux/penmux/options | This directory can hold option definitions for modules to override the defaults |
| Config | Default | Description |
|---|---|---|
set -g @penmux-keytable-key "P" |
P | This is the prefix key for penmux |
set -g @penmux-load-module-key "l" |
l | Load module |
set -g @penmux-unload-module-key "u" |
u | Unload module |
set -g @penmux-change-option-key "c" |
c | Change module options |
set -g @penmux-run-key "r" |
r | Run module |
The modules are providing the functionality for penmux. Therefore the core is providing a basic API / Guideline to let the modules work in a cooperative way to hopefully provide usable features to other users and not only myself ;)
The modules can have two type of files, that let the user configure them.
The first type are the general options, that a module has. If you want to adjust the default values for a module, you copy the module's options xml from options/moduleName.xml to the penmux-custom-module-options-dir (default: $HOME/.tmux/penmux/options) and adjust them to your needs.
As an example if you want to change the default directory to store sessions for the Session module, you would do the following:
mkdir -p $HOME/.tmux/penmux/options
cp $HOME/.tmux/plugins/tmux-penmux/options/Session.xml $HOME/.tmux/penmux/options/
Then change the line for the "SessionDirBase" from:
<Option>
<Name>SessionDirBase</Name>
<DefaultValue>$HOME/.tmux/penmux/sessions</DefaultValue>
</Option>
to your likes:
<Option>
<Name>SessionDirBase</Name>
<DefaultValue>$HOME/my/new/penmux/session/folder</DefaultValue>
</Option>
If a module has some functions that are bound to keys it has a file under keytables/moduleName.xml. To adjust the default keys for the module you have to copy the keytable xml to the penmux-custom-keytables-dir (default: $HOME/.tmux/penmux/keytables).
Not all modules are using keytables
As an example if you want to change the default keys for creating a new session for the Session module, you would do the following:
mkdir -p $HOME/.tmux/penmux/keytables
cp $HOME/.tmux/plugins/tmux-penmux/keytables/Session.xml $HOME/.tmux/penmux/keytables/
Then change the key for 'new' from:
<Key>
<Key>n</Key>
<Func>new</Func>
<Description>Creates a new session</Description>
</Key>
to your likes:
<Key>
<Key>t</Key>
<Func>new</Func>
<Description>Creates a new session</Description>
</Key>
The 'PrefixKey' is used as a module prefix. It can be changed to your likes, too. That means that if you want to run any module functions you would need to use the tmux prefix + penmux prefix + module prefix + module function key.
As example to create a new session with all defaults you would press: prefix + P + s + n
| Module | Path | Runnable | Description |
|---|---|---|---|
| Session | auxilliary | No | Module to handle penmux sessions (persisting options, etc.) |
| Commander | auxilliary | Yes | Module to run commands that are read from csv files |
| Snipper | auxilliary | Yes | Module to copy snippets to clipboard that are read from csv files |
| ScriptLog | reporting | No | Module to log all terminal input / output via script |
| HttpExchange | comm | Yes | Module to provide a python webserver including predifined fetch commands |
Here you can find the guides for developing modules.
- The Penmux Module Library should be used to interact with Options and other penmux modules.
- The Penmux Schemas are describing what a module is made from
- The Module Development Guide teaches how to write modules
- Migrate Repo
- Installation / Usage Documentation
- Core configuration Documentation
- Module usage Documentation
- Module configuration Documentation
- Stabilizing API
- Development Info
- Module development Guide
- Contribution Guide