Decker - Orchestrierungsframework für Penetrationstests

Zweck

Decker ist ein Orchestrierungsframework für Penetrationstests. Es nutzt HashiCorp Configuration Language 2 (die gleiche Konfigurationssprache wie Terraform), um deklaratives penetration testing as code zu ermöglichen, sodass Ihre Tests versioniert, geteilt, wiederverwendet und mit Ihrem Team oder der Community gemeinsam bearbeitet werden können.

Beispiel einer decker Konfigurationsdatei:

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

Führen Sie ein Plugin für jedes Element in einer Liste aus:

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

Komplexe Konfiguration, die for_each mit verschachtelten Werten kombiniert:

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

Ausgabeformate

Mehrere Ausgabeformate sind verfügbar und es können gleichzeitig mehr als eines ausgewählt werden.

Wenn DECKER_OUTPUTS_JSON oder DECKER_OUTPUTS_XML auf "true" gesetzt wird, werden entsprechend json- und xml-formatierte Dateien ausgegeben.

Geben Sie .json-Dateien zusätzlich zum Klartext aus: export DECKER_OUTPUTS_JSON="true"
Geben Sie .xml-Dateien zusätzlich zum Klartext aus: export DECKER_OUTPUTS_XML="true"

Warum der Name Decker?

Meine Freundin Courtney kam mir zu Hilfe, als ich Schwierigkeiten hatte, einen Namen zu finden, und fand decker in einem SciFi-Wortglossar... und es klang cool.

Ein zukünftiger Cracker; ein Software-Experte, der sich auf die Manipulation des Cyberspace versteht, insbesondere auf die Umgehung von Sicherheitsvorkehrungen.

Ausführen einer Beispielkonfiguration mit Docker

Es werden zwei Volumes eingebunden:

Ein Verzeichnis namens decker-reports, in das decker für jedes ausgeführte Plugin eine Datei ausgibt. Der Dateiname lautet {unique_resource_name}.report.txt.
Das Verzeichnis examples mit decker-Konfigurationsdateien. Durch das Einbinden dieses Volumes können Sie Konfigurationen lokal mit Ihrem bevorzugten Editor schreiben und sie dennoch im Container ausführen.

Eine Umgebungsvariable wird übergeben:

DECKER_TARGET_HOST

Diese wird in den Konfigurationsdateien als {var.target_host} referenziert. Decker durchläuft alle Umgebungsvariablen mit dem Namen DECKER_*, entfernt das Präfix und setzt den Rest in Kleinbuchstaben.

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

Wenn decker die Konfiguration ausgeführt hat, suchen Sie in ./decker-reports nach den Ausgaben.

Ausführen einer Beispielkonfiguration ohne Docker

Sie möchten wahrscheinlich das Verzeichnis, in das decker Berichte schreibt, mit der Umgebungsvariablen DECKER_REPORTS_DIR festlegen.

So etwas wäre angemessen. Stellen Sie einfach sicher, dass das, worauf Sie es setzen, ein vorhandenes Verzeichnis ist.

export DECKER_REPORTS_DIR="$HOME/decker-reports"

Sie müssen auch einen Zielhost setzen, wenn Sie eine der Beispielkonfigurationsdateien ausführen.

export DECKER_TARGET_HOST="<insert hostname here>"

Dann führen Sie einfach eine Konfigurationsdatei aus. Wechseln Sie in das Stammverzeichnis dieses Repositorys und führen Sie aus:

./decker ./examples/example.hcl

Mitwirken

Beiträge sind sehr willkommen und werden geschätzt. Siehe docs/contributions.md für Richtlinien.

Entwicklung

Die Verwendung von Docker für die Entwicklung wird für eine reibungslose Erfahrung empfohlen. Dadurch wird sichergestellt, dass alle Abhängigkeiten installiert und einsatzbereit sind.

Siehe Verzeichnisstruktur unten für einen Überblick über den Go-Code.

Quick Start

(auf dem Host-Rechner): make docker_build
(auf dem Host-Rechner): make docker_run (startet einen Docker-Container und öffnet eine interaktive Bash-Sitzung)
(im Container): dep ensure -v
(im Container): make build_all
(im Container): make run

Git-Hooks initialisieren

Führen Sie make init aus, um ein pre-commit-Skript hinzuzufügen, das bei jedem Commit Linting und Tests ausführt.

Plugin-Entwicklung

Decker selbst ist nur ein Framework, das Konfigurationsdateien liest, Abhängigkeiten in den Konfigurationsdateien ermittelt und Plugins in einer Reihenfolge ausführt, die sicherstellt, dass Plugins mit Abhängigkeiten von anderen Plugins (Ausgabe eines Plugins als Eingabe für ein anderes) nach denjenigen ausgeführt werden, von denen sie abhängen.

Die wahre Stärke von decker liegt in den Plugins. Die Entwicklung eines Plugins kann so einfach oder komplex sein, wie Sie möchten, solange das Endergebnis eine .so-Datei mit dem kompilierten Plugin-Code und eine .hcl-Datei im selben Verzeichnis ist, die die vom Plugin erwarteten Eingaben deklariert.

Schauen Sie sich docs/building_plugins.md an, um mit Ihrem ersten Plugin zu beginnen. Es sollte nur ein paar Minuten dauern, bis ein "Hello World" decker-Plugin läuft.

Plugins installieren

Standardmäßig werden Plugins in einem Verzeichnis relativ zum Speicherort der decker-Binärdatei erwartet, und zwar unter <decker binary>/internal/app/decker/plugins/<Pluginname>/<Pluginname>.so. Zusätzliche Pfade können durch Setzen der Umgebungsvariablen DECKER_PLUGIN_DIRS hinzugefügt werden. Der Standard-Plugin-Pfad wird weiterhin verwendet, wenn DECKER_PLUGIN_DIRS gesetzt ist.

Beispiel: export DECKER_PLUGIN_DIRS="/path/to/my/plugins:/additional/path/to/plugins"

Es sollte eine HCL-Datei neben der .so-Datei unter <decker binary>/internal/app/decker/plugins/<Pluginname>/<Pluginname>.hcl geben, die seine Ein- und Ausgaben definiert. Derzeit werden nur Eingaben vom Typ string, list und map unterstützt. Jede Eingabe sollte einen input-Block haben, der wie folgt aussieht:

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

Verzeichnisstruktur

.
├── 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 ist der Treiber. Seine Aufgabe ist es, eine angegebene Konfigurationsdatei zu parsen, die entsprechenden Plugins basierend auf den resource-Blöcken der Datei zu laden und die Plugins mit den angegebenen Eingaben auszuführen.
examples enthält ein paar Beispielkonfigurationen, um mit decker zu beginnen. Wenn Sie das Kali Docker-Image (stevenaldinger/decker:kali) verwenden, sollten alle Abhängigkeiten für alle Konfigurationsdateien installiert sein und alles reibungslos laufen.
internal/pkg ist der Ort, an dem sich der meiste tatsächliche Code befindet. Es enthält alle Pakete, die von main.go importiert werden.
- dependencies ist für die Erstellung des Plugin-Abhängigkeitsgraphen und die Rückgabe eines topologisch sortierten Arrays verantwortlich, das sicherstellt, dass Plugins in einer funktionierenden Reihenfolge ausgeführt werden.
- gocty bietet Hilfsfunktionen zum Codieren und Decodieren von go-cty-Werten, die zur Handhabung dynamischer Eingabetypen verwendet werden.
- hcl ist für das Parsen von HCL-Dateien verantwortlich, einschließlich der Erstellung von Auswertungskontexten, die es Blöcken ermöglichen, korrekt zu decodieren, wenn sie von anderen Plugin-Blöcken abhängen.
- paths ist für die Rückgabe von Dateipfaden für die -Binärdatei, Konfigurationsdateien, Plugin-Konfigurationsdateien und generierte Berichte verantwortlich.

decker

Beliebteste