-
Notifications
You must be signed in to change notification settings - Fork 0
Usage
To run the tool simply run pentest_tool in your terminal.
The first screen will display the current settings loaded from the configuration file, and should list out the projects loaded from the projects.conf file.
Review the information to ensure its correct then press enter to drop into the CLI.
This tool is designed to help manage your notes, files, and custom distroboxes for pentest or CTF projects.
The main thought behind this is that you'd have a template distrobox created that would have all of your tools already installed on it, and all of the common configurations you do applied to it. For example I use arch linux as my attacking OS. I have a distrobox called atarchbox (attacking arch box) that has all my tools and configurations set up already. This tool will clone the template distrobox into a new distrobox for each project. Your tools and configurations will be cloned along with it.
By default all distroboxes share your home directory and mount them as the distrobox user's directory. I may change the creation command and install script to make a custom home directory for them to help keep data even more separated, but for the time being this seems to work well enough.
The installation function will ask you for a location that you store custom tools in. This is primarily meant for the tools that you git clone, or install manually outside of your attack platform's package manager.
Projects are organized by customer (or CTF platform) and project name (for example 2025_internal_pentest or permx).
For example if you're working on an internal pentest for a client named test the folder structure will start with client/2025_internal_pentest or if you're working on permx on HTB then it'll be htb/permx.
Creating a new project with the tool will by default create a default folder structure for your files that includes 3 sub directories in the files folder; working, writing, and deliver. For the above client example this will look like
client/2025_internal_pentest
/working- `/writing
/delivery
Project notes are expected to be in markdown. This tool works great along side Obsidian. Any markdown note editor should work just as well, but I have only tested Obsidian.
Creating a new project also sets up a default note structure that is similar to the files folder structures. For the same client example above the note structure will be:
client/2025_internal_pentest
loot/credsattackscleanupfindingsgeneralpasswordspraytodo
It will also populate these notes with the default templates I use for engagements. It only does these default templates for project types that I actively work on. For example if the work "internal" is in the project name it will auto populate with the internal pentest template notes. Currently I only have templates for
- internal pentests
- external pentests
- vishing tests
Projects have two stages they can be in, current and upcoming. Creating a new project with the create new project command will assume it is upcoming. Upcoming projects will have their file and note structure created, but will not spin up a distrobox for the project yet. I personally have separate folders for current and upcoming projects, but it should also work fine if these are the same folders.
To promote a project from upcoming stage to the current stage we can use the command promote project. This will automatically copy the folders from the upcoming folder to the current folder, and create a new distrobox for the engagement. The project files folder will be mounted at /pentest on the distrobox, and a folder with your custom tools will be mounted at /tools.
This makes interacting with your project files folder inside the distrobox as easy as cd /pentest/working.
Only one project can be "active" at a time. This does not mean that only one project's distrobox can be running at the same time. The Active project is simply the project that the commands run in this tool will be interacting with. You can switch active projects with the switch project command.
For example I have a terminal running in client1's project. This terminal is doing a portscan that will take a while. While I wait I want to do some work on client2's project. I can still switch project to activate project 2's project then run the new terminal command. This will not interrupt the terminal open in client1's project.
The CLI is the primary mode to run this tool in. The prompt will display the currently active customer name and project name separated by a : followed by Command? and a new line to enter the command on. EXAMPLE:
test_customer:2025_internal_pentest
Command?
Entering the command help will display all available commands and their aliases. different commands are separated by new lines, and aliases are separated by | characters. Entering an unknown command or a blank string will result in an unknown command error that will also print the default help message.
help $command will display more information about any specific command in the tool.
EXAMPLE:
test_customer:2025_internal_pentest
Command?
help sp
Command: save projects
Aliases: sp save
This command saves all project information to the ~/.config/pyro_pentest_tool/projects.conf file
None of the commands take arguments at the moment, they will prompt you for any additional information needed.
menu | main menu | mm
list projects | lp | listp | list p
switch project | sp | switch p | switchp
show active project | show active | sa | show a
create new project | cnp | new project | np
save projects | sp | save | s
import project | ip | import
remove project | rp | remove | rmp
show upcoming project | sup | show upcoming
promote project | pp | promote
new terminal | enter | enter terminal | nt | et
inline terminal | it | enter inline | ei
cobalt strike | cs
recreate distrobox | rdb | ndb | new distrobox
generate userpass | userpass | gup | up
inital enum | ie | enum
host discovery | build host discovery | hd | bhd
port scan | cs port scan | cobaltstrike port scan | csps | ps
parse port scan | pps | parse scan
stop boxes | stop distroboxes | sdb
password spray | pass spray | pas
bloodhound | bh
parse gather contacts | pgc | parse contacts | pc
prune distroboxes | pdb | prune
clear | clear screen | cls
parse nomral nmap file | pnnf | parse nmap | pn
show scope | ss | show s | s s | scope
sharpersist command | spc | sharp scheduled task
port scan | ps | nmap | nmap scan | ns | nm
port scan command | psc | nmap command | nmc
update git tools | ugt | update git | ug
dns records | dr
brute force subdomains| bsd | gobuster dns | gd
dns enumeration | de | all dns stuff | ads | dns stuff | ds
help | ? | -h
If the command line isn't your cup of tea, no worries! I have created a menu system as well! Simply enter the command menu when you get to the CLI and you'll be dropped into the main menu. This will show all available command (though some newer commands may be missing until I add them.) If the main menu seems too cluttered then there are specific menus for engagement types as well. I've created a menu for both external engagements and internal engagements that will filter out any commands that are not useful for those projects. These menus can be accessed by entering the number corresponding to their menu option displayed in the terminal.
The menu system just calls the run_command function within the cli, so you only need to define the function to do something once, then you call it from both the CLI or the menu in the same way.