Decker - Declarative Penetration Testing Orchestration Framework

// variables are pulled from environment
//   ex: DECKER_TARGET_HOST
// they will be available throughout the config files as var.*
//   ex: ${var.target_host}
variable "target_host" {
  type = "string"
}

// resources refer to plugins
// resources need unique names so plugins can be used more than once
// they are declared with the form: 'resource "plugin_name" "unique_name" {}'
// their outputs will be available to others using the form unique_name.*
//   ex: nmap.443
resource "nmap" "nmap" {
  host = "${var.target_host}"
  plugin_enabled = "true"
}
resource "sslscan" "sslscan" {
  host = "${var.target_host}"
  plugin_enabled = "${nmap.443 == "open"}"
}

variable "target_host" {
  type = "string"
}
resource "nslookup" "nslookup" {
  dns_server = "8.8.4.4"
  host = "${var.target_host}"
}
resource "metasploit" "metasploit" {
  for_each = "${nslookup.ip_address}"
  exploit = "auxiliary/scanner/portscan/tcp"
  options = {
    RHOSTS = "${each.key}/32"
    INTERFACE = "eth0"
  }
}

variable "target_host" {
  type = "string"
}
resource "nslookup" "nslookup" {
  dns_server = "8.8.4.4"
  host = "${var.target_host}"
}
resource "nmap" "nmap" {
  for_each = "${nslookup.ip_address}"
  host = "${each.key}"
}
// for each IP, check if nmap found port 25 open.
// if yes, run metasploit's smtp_enum scanner
resource "metasploit" "metasploit" {
  for_each = "${nslookup.ip_address}"
  exploit = "auxiliary/scanner/smtp/smtp_enum"
  options = {
    RHOSTS = "${each.key}"
  }
  plugin_enabled = "${nmap["${each.key}"].25 == "open"}"
}

1. Output .json files in addition to plain text: export DECKER_OUTPUTS_JSON="true"
2. Output .xml files in addition to plain text: export DECKER_OUTPUTS_XML="true"

A future cracker; a software expert skilled at manipulating cyberspace, especially at circumventing security precautions.

1. Directory named decker-reports where decker will output a file for each plugin executed. The file's name will be {unique_resource_name}.report.txt.
2. examples directory containing decker config files. Mounting this volume allows you to write configs locally using your favorite editor and still run them within the container.

1. DECKER_TARGET_HOST

docker run -it --rm \
  -v "$(pwd)/decker-reports/":/tmp/reports/ \
  -v "$(pwd)/examples/":/decker-config/ \
  -e DECKER_TARGET_HOST=example.com \
 stevenaldinger/decker:kali decker ./decker-config/example.hcl

export DECKER_REPORTS_DIR="$HOME/decker-reports"

export DECKER_TARGET_HOST="<insert hostname here>"

./decker ./examples/example.hcl

1. (on host machine): make docker_build
2. (on host machine): make docker_run (will start docker container and open an interactive bash session)
3. (inside container): dep ensure -v
4. (inside container): make build_all
5. (inside container): make run

input "my_input" {
  type = "string"
  default = "some default value"
}

.
├── build
│   ├── ci/
│   └── package/
├── cmd
│   ├── decker
│   │   └── main.go
│   └── README.md
├── deployments/
├── docs/
├── examples
│   └── example.hcl
├── githooks
│   ├── pre-commit
├── Gopkg.toml
├── internal
│   ├── app
│   │   └── decker
│   │       └── plugins
│   │           ├── a2sv
│   │           │   ├── a2sv.hcl
│   │           │   ├── main.go
│   │           │   └── README.md
│   │           └── ...
│   │               ├── main.go
│   │               ├── README.md
│   │               └── xxx.hcl
│   ├── pkg
│   │   ├── dependencies/
│   │   ├── gocty/
│   │   ├── hcl/
│   │   ├── paths/
│   │   ├── plugins/
│   │   └── reports/
│   └── README.md
├── LICENSE
├── Makefile
├── README.md
└── scripts
├── build-plugins.sh
└── README.md

• cmd/decker/main.go is the driver. Its job is to parse a given config file, load the appropriate plugins based on the file's resource blocks, and run the plugins with the specified inputs.
• examples has a couple example configurations to get you started with decker. If you use the kali docker image (stevenaldinger/decker:kali), all dependencies should be installed for all config files and things should run smoothly.
• internal/pkg is where most of the actual code is. It contains all the packages imported by main.go.
  • dependencies is responsible for building the plugin dependency graph and returning a topologically sorted array that ensures plugins are run in a working order.
  • gocty offers helpers for encoding and decoding go-cty values which are used to handle dynamic input types.
  • hcl is responsible for parsing HCL files, including creating evaluation contexts that let blocks properly decode when they depend on other plugin blocks.
  • paths is responsible for returning file paths for the decker binary, config files, plugin config files, and generated reports.
  • plugins is responsible for determining if plugins are enabled and running them.
  • reports is responsible for writing reports to the file system.
• internal/app/decker/plugins are modular pieces of code written as Golang plugins, implementing a simple interface that allows them to be loaded and called at run-time with inputs and outputs specified in the plugin's config file (also in HCL). An example can be found at internal/app/decker/plugins/nslookup/nslookup.hcl.
• decker config files offer a declarative way to write penetration tests. The manifests are written in HashiCorp Configuration Language 2) and describe the set of plugins to be used in the test as well as their inputs.