hckctl

The declarative Breach and Attack Simulation toolkit: one tool to rule 'em all
Quick start • Setup • Provider • 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

• tunnel multiple vpn connections through a high-available ssh proxy
• expose public endpoints
• pre-mount saved dumps (git, s3)
• load secrets from a vault
• save/restore workdir snapshots
• deploy custom labs

hckctl lab ctf-linux

Task

Run a single-stage task using pre-defined commands

# default commands
hckctl task gobuster --command help
hckctl task fuzzer/ffuf --command version

# uses the "default" preset 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

# uses the "full" preset arguments
hckctl task nmap --command full --input address=127.0.0.1 --input port=80

# invokes it with custom arguments
hckctl task nuclei --inline -- -u https://example.com

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

TryHackMe demo

TODO

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

Setup

Download the latest binaries

# TODO latest
HCKCTL_VERSION=???

curl -sSL https://github.com/hckops/hckctl/releases/download/${HCKCTL_VERSION}/hckctl_linux_x86_64.tar.gz | \
  tar -xzf - -C /usr/local/bin

Provider

Docker

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

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

Kubernetes

Use minikube or kind to setup a local cluster

provider:
  kube:
    # by default uses "~/.kube/config"
    configPath: ""
    namespace: hckops

Make sure you disable IPv6 in your cluster to use the --network-vpn flag

minikube start --extra-config="kubelet.allowed-unsafe-sysctls=net.ipv6.conf.all.disable_ipv6"

If you are looking for a simple way to get started with a remote cluster consider using kube-template

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

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

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

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!