HTB/CTF Container Environment

A comprehensive containerized environment for HackTheBox and CTF challenges that provides an ephemeral, consistent, and secure workspace with all necessary penetration testing tools.

Features

• Ephemeral containers: Each machine gets its own isolated container that's destroyed after use
• Persistent workspaces: Machine-specific directories that persist between sessions
• Pre-configured tools: Comprehensive suite of penetration testing tools from Kali repositories
• VPN support: Easy VPN connection management with OpenVPN
• Resource management: Configurable memory and CPU limits
• Extensible: Support for custom pip and apt packages

Project Showcase

Directory Structure

project/
├── penv                   # Main script
├── Dockerfile             # Container definition
├── .config                # Configuration file (auto-generated)
├── enviorment.log         # Activity logs
├── vpn/                   # OpenVPN configuration files
├── tools/                 # Shared tools directory
├── machines/              # Machine-specific workspaces
│   └── <machine_name>/
│       ├── notes.md       # Machine notes
│       ├── nmap/          # Nmap scan results
│       └── ...            # Other files
└── secLists/              # SecLists wordlists (optional)

Prerequisites

• Docker installed and running
• User must be in the docker group or run as root
• At least 1GB free disk space
• OpenVPN configuration files (for VPN connectivity) (This one is technically optional but would't make much sense if you don't use it)

Installation

1. Clone or download the project files
2. Make the script executable:

   chmod +x penv

3. Place your OpenVPN configuration files in the vpn/ directory
4. Run the script for the first time to build the image

Usage

Basic Usage

Start a container for a specific machine:

./penv <machine_name>

Example:

./penv horizontall

Available Commands

Container Management

• ./penv <machine_name> - Start/attach to a container for the specified machine
• ./penv build - Force rebuild of the Docker image
• ./penv clean - Remove Docker image and clean up containers

Install packages

• ./penv install - Configure additional APT packages interactively
• ./penv install <package> - Configure additional APT packages directly
• ./penv install pip - Configure additional Python packages interactively
• ./penv install pip <package> - Configure additional Python packages directly

Configuration

• ./penv config - Configure container resources (memory, CPU, packages)
• ./penv config show - Display current configuration

Workspace Management

• ./penv list - List all available machine workspaces
• ./penv remove <machine_name> - Remove a specific machine workspace

Monitoring

• ./penv status - Show system status and image information
• ./penv logs - Show recent activity logs
• ./penv help - Display help information

Container Environment

Once inside a container, you'll have access to:

• Workspace: /home/pentester/workspace (machine-specific files)
• VPN files: /home/pentester/vpn (read-only)
• Tools: /home/pentester/tools (shared tools directory)
• SecLists: /home/pentester/secLists (if installed)

VPN Connection

Connect to VPN from within the container:

sudo openvpn /home/pentester/vpn/<your_config>.ovpn

Or use the alias:

vpn /home/pentester/vpn/<your_config>.ovpn

Pre-installed Tools

Note

The tools are adjusted to what I use, this section will change relatively frequently.

Network Tools

• nmap - Network discovery and security auditing
• netcat-traditional - Networking utility
• tcpdump - Network packet analyzer
• whatweb - Web application fingerprinting

Web Application Testing

• gobuster - Directory/file enumeration
• wfuzz - Web application fuzzer
• sqlmap - SQL injection testing

System Tools

• neovim - Text editor
• git - Version control
• tmux - Terminal multiplexer
• jq - JSON processor

Python Packages

• requests - HTTP library
• beautifulsoup4 - HTML/XML parser
• pwntools - CTF framework

Configuration

Resource Configuration

Configure memory and CPU limits:

./penv config

Default settings:

• Memory: 2GB
• CPUs: 2 cores
• File descriptors: 65536
• Processes: 2048

Package Management

Add additional packages before image build:

Python packages:

./penv extra pip requests

APT packages:

./penv extra apt nmap

Or leave blank to modfiy your current installed packages and/or add new ones interactively

./penv extra apt

Security Features

• Non-root user execution
• Capability dropping (except NET_RAW/NET_ADMIN/NET_BIND_SERVICE for nmap, netcat and openvpn)
• Network security hardening
• Read-only VPN directory
• Secure file permissions

Troubleshooting

It takes too long

The first installation may take some time but after the first startup it should take just a few seconds. The way the Dockerfile is structured adding your extra packages should be quite fast since the base image is already cached in docker.

Common Issues

Docker daemon not running:

sudo systemctl start docker

Permission denied:

sudo usermod -aG docker $USER
# Log out and log back in

I added tools but I can't use them in the container:

./penv build
# Applies the changes to the config file

Image build failures: Check the logs:

./penv logs

My CLI got stuck after connecting to VPN If the last message in the VPN log is something like this:

Protocol options: explicit-exit-notify 1, protocol-flags cc-exit tls-ekm dyn-tls-crypt

You just need to press Enter to get back to your CLI.

Low disk space: Clean up Docker resources:

./penv clean
docker system prune -a

Log Files

Activity logs are stored in enviorment.log and automatically rotated when they exceed 10MB.

Advanced Usage

Custom Dockerfile Modifications

The image will not rebuilt automatically, it gives you a warning message when you start a machine if you want to rebuild. The script tracks Dockerfile and .config changes using SHA256 checksums.

Workspace Customization

Each machine workspace is isolated and can contain:

• Custom scripts and tools
• Enumeration results
• Exploit code
• Notes and documentation

Resource Monitoring

Monitor container resource usage:

docker stats htb-<machine_name>

Best Practices

1. Organization: Keep each machine in its own workspace
2. VPN Management: Keep VPN configs in the dedicated directory
3. Resource Limits: Adjust memory/CPU based on your system
4. Regular Cleanup: Remove old workspaces when no longer needed

Contributing

To extend the environment:

1. Modify the Dockerfile for additional tools
2. Update the configuration system for new options
3. Add new commands to the main script

License

This project is provided as-is for educational and authorized penetration testing purposes only. Users are responsible for compliance with applicable laws and regulations.

Support

For issues or questions:

1. Check the logs: ./penv logs
2. Verify system status: ./penv status
3. Review configuration: ./penv config show
4. Rebuild if necessary: ./penv build