hckctl

The declarative Breach and Attack Simulation toolkit: one tool to rule 'em all
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 your vulnerable target infrastructure or 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 known exploits to find weaknesses on authorized targets in a declarative way.

Designed to transparently run locally, remotely or integrated in pipelines and with guaranteed stability and backward compatibility over time. hckctl is free, open source and community driven, no vendor lock-in, extensible and built using native providers api.

Leverage the cloud platform or request a dedicated managed environment to:

• orchestrate complex attack scenarios
• constantly probe and monitor your security posture
• analyze, aggregate and export results via api
• trigger instant actions based on observed events and patterns

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

Lab (preview)

TODO video

Access your target from a managed lab to

• tunnel multiple vpn connections through a highly available ssh proxy
• expose public endpoints with custom domains
• mount and keep in sync dumps e.g. git, s3
• load secrets from a vault
• save/restore workdir snapshots
• deploy private templates and infrastructures e.g. Kompose, Helm

# starts demo lab (cloud only)
hckctl lab ctf-linux

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 loading 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-*

Flow (preview)

Run multistage tasks in parallel, collect and output the combined results

hckctl flow scan www.example.com
hckctl flow fuzz 127.0.0.1:8080
hckctl flow sql 127.0.0.1:3306
hckctl flow atomic-red-team 127.0.0.1 T1485
hckctl flow c2 ping
hckctl flow phishing @example.com

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}"

Inspired by GitOps, 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 is with the convenience script

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

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 .name | sed 's/v//')

# install or update
curl -sSL https://github.com/hckops/hckctl/releases/latest/download/hckctl-${HCKCTL_VERSION}-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>

Roadmap

• 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
  • 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!