hckctl

README

hckctl

The Security Automation Toolkit
Quick start • Provider • Setup • Development • Roadmap • Contribute

Launch manual and automated attacks with pre-defined and always up-to-date templates of your favourite tools.

Attack a vulnerable infrastructure and connect to your training platform (HTB, TryHackMe, Vulnlab, etc.) without wasting anymore time on boring installations, environment setup and network configurations.

Package, distribute and run local or remote boxes and workflows to find weaknesses on authorized targets in a declarative way. hckctl is free, open source and community driven, no vendor lock-in, extensible and built using native providers api.

Quick start

Box

Spin-up a box and access all port-forwarded ports locally

# spawns a temporary docker box locally
hckctl box alpine
#[box-alpine-<RANDOM>][tty] tunnel (remote) 7681 -> (local) 7681
#[box-alpine-<RANDOM>] TTYD_USERNAME=root
#[box-alpine-<RANDOM>] TTYD_PASSWORD=alpine

# deploys a detached box to a kubernetes cluster
hckctl box start arch --provider kube
# tunnels tty port only
hckctl box open box-arch-<RANDOM> --no-exec

# creates a pwnbox box connected to your hack the box account
hckctl box preview/parrot-sec --network-vpn htb
# connects to vnc
vncviewer localhost:5900

# starts a background box to attack locally
hckctl box start vulnerable/owasp-juice-shop

parrot-sec box screenshots

Task

Run a single-stage task using pre-defined commands

# shows the "help" command
hckctl task nuclei --command help

# uses the "default" preset command and arguments
hckctl task rustscan
# equivalent of
hckctl task rustscan --input address=127.0.0.1
hckctl task scanner/rustscan --command default --input address=127.0.0.1

# runs the "full" preset command against the retired "Lame" machine (with docker)
# see https://app.hackthebox.com/machines/Lame
hckctl task nmap --network-vpn htb --command full --input address=10.10.10.3 
# equivalent of (with kube)
hckctl task nmap --network-vpn htb --provider kube --inline -- nmap 10.10.10.3 -sC -sV

# downloads common wordlists
git clone --depth 1 https://github.com/danielmiessler/SecLists.git \
  ${HOME}/.local/state/hck/share/wordlists/SecLists
# fuzzing using a local template against the retired "Knife" machine (with kube)
# see https://app.hackthebox.com/machines/Knife
hckctl task \
  --local ../megalopolis/task/fuzzer/gobuster.yml \
  --network-vpn htb \
  --provider kube \
  --input address=10.10.10.242 \
  --input wordlist=wordlists/SecLists/Discovery/Web-Content/Apache.fuzz.txt

# monitors the logs
tail -F ${HOME}/.local/state/hck/task/log/task-*

Output command examples

Template

Explore all available templates or write your own and validate it locally

# lists all templates
hckctl template list

# validates all templates
hckctl template validate "../megalopolis/**/*.{yml,yaml}"

The whole project is centered around git as source of truth, schema validation and versioning. Pin a revision (branch, tag, or sha) if you need to ensure long term stability

# uses template "megalopolis/task/scanner/trivy" @ commit hash "12e7599"
hckctl task trivy --revision v0.1.0

Config

Override the default configurations

# prints path and current configs
hckctl config

# resets default configs
hckctl config --reset

How to configure vpn networks

# edits config file
vim ${HOME}/.config/hck/config.yml

# example
network:
  vpn:
  - name: htb
    path: /home/demo/ctf/openvpn/htb_demo_eu_vip_28.ovpn
  - name: thm
    path: /home/demo/ctf/openvpn/thm_demo_us_regular_3.ovpn

Provider

Docker

Follow the official instructions to install Docker Engine. The fastest way to get started on Linux is with the convenience script

# downloads and runs script
curl -fsSL https://get.docker.com -o get-docker.sh
./sudo sh get-docker.sh

or on macOS with Docker Desktop

brew install homebrew/cask/docker

lazydocker is the recommended tool to watch and monitor containers

Kubernetes

Remote

If you are looking for a simple and cheap way to get started with a remote cluster use kube-template on DigitalOcean

provider:
  kube:
    configPath: "/PATH/TO/kube-template/clusters/do-template-kubeconfig.yaml"

Local

Use minikube, kind or k3s to setup a local cluster

provider:
  kube:
    # absolute path, empty by default uses "${HOME}/.kube/config"
    configPath: ""
    namespace: hckops

Troubleshooting

Useful dev tools, see hckops/kube-base

# starts tmp container
docker run --rm --name hck-tmp-local --network host -it \
  -v ${HOME}/.kube/config:/root/.kube/config hckops/kube-base

# watches pods
kubectl klock -n hckops pods

Depending on your local environment, you might need to override IPv6 config in the local cluster to use the --network-vpn flag. Set also --embed-certs if you need to use the dev tools

# starts local cluster
minikube start --embed-certs \
  --extra-config="kubelet.allowed-unsafe-sysctls=net.ipv6.conf.all.disable_ipv6"

# runs with temporary privileges to connect to a vpn
env HCK_CONFIG_NETWORK.PRIVILEGED=true hckctl box alpine --provider kube --network-vpn htb
# equivalent of
network:
  # default is false, override for local clusters
  privileged: true

Cloud

Access to the platform is limited and in private preview. If you are interested, please leave a comment or a 👍 to this issue and we'll reach out with more details

provider:
  cloud:
    host: <ADDRESS>
    port: 2222
    username: <USERNAME>
    token: <TOKEN>

Podman (coming soon)

Follow the official instructions to install Podman

Setup

Linux

# latest release
HCKCTL_VERSION=$(curl -sS https://api.github.com/repos/hckops/hckctl/releases/latest | jq -r .tag_name)

# install or update
curl -sSL https://github.com/hckops/hckctl/releases/latest/download/hckctl-${HCKCTL_VERSION#"v"}-linux-x86_64.tar.gz | \
  sudo tar -xzf - -C /usr/local/bin

# verify
hckctl version

# uninstall
sudo rm /usr/local/bin/hckctl

MacOS

• Homebrew

# install
brew install hckops/tap/hckctl

# update
brew upgrade hckctl

Development

• just

# run
go run internal/main.go

# debug
go run internal/main.go task test/debug --provider kube --inline -- tree /hck/share

# build
just
./build/hckctl

# logs
tail -F ${HOME}/.local/state/hck/log/hckctl-*.log

# publish (without "v" prefix)
just publish <MAJOR.MINOR.PATCH>

Known issues

• Most of the images are built by default only for linux/amd64, but they should work also on linux/arm64

Roadmap

• flow orchestrate and schedule multistage tasks, collect and output the combined results in multiple formats
• lab simulate attacks and scenarios against vulnerable targets on a managed platform
• machine create and access VMs e.g. DigitalOcean Droplet, AWS EC2, Azure Virtual Machines, QEMU etc.
• tui similar to lazydocker and k9s together
• network support WireGuard, Tor, ProxyChains, etc.
• plugin add custom cli commands in any language
  • man combine tldr and cheat with task commands
  • htb and thm api to start/stop/list machines and submit flags
  • mitm hook to intercept network traffic of boxes and tasks
  • prompt ChatGPT prompt style

Contribute

Create your custom template and test it locally

# loads local template
hckctl box --local ../megalopolis/box/preview/powershell.yml

Please, feel free to contribute to the companion repository and add more community templates to the catalog. Credit should go to all the authors and maintainers for their open source tools, without them this project wouldn't exist!