Decker - Cadre d'orchestration de tests d'intrusion

Objectif

Decker est un cadre d'orchestration de tests d'intrusion. Il exploite HashiCorp Configuration Language 2 (le même langage de configuration que Terraform) pour permettre la déclaration de tests d'intrusion en tant que code, afin que vos tests puissent être versionnés, partagés, réutilisés et collaborés avec votre équipe ou la communauté.

Exemple d'un fichier de configuration decker :

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

Exécuter un plugin pour chaque élément d'une liste :

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

Configuration complexe combinant for_each avec des valeurs imbriquées :

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

Formats de sortie

Plusieurs formats de sortie sont disponibles et plusieurs peuvent être sélectionnés en même temps.

Définir DECKER_OUTPUTS_JSON ou DECKER_OUTPUTS_XML à "true" générera respectivement des fichiers au format json et xml.

1. Générer des fichiers .json en plus du texte brut : export DECKER_OUTPUTS_JSON="true"
2. Générer des fichiers .xml en plus du texte brut : export DECKER_OUTPUTS_XML="true"

Pourquoi le nom decker ?

Mon ami Courtney est venu à la rescousse quand je peinais à trouver un nom et a trouvé decker dans un glossaire de mots de science-fiction... et ça sonnait cool.

Un futur cracker ; un expert en logiciel habile à manipuler le cyberespace, surtout à contourner les mesures de sécurité.

Exécution d'un exemple de configuration avec Docker

Deux volumes sont montés :

1. Un répertoire nommé decker-reports où decker écrira un fichier pour chaque plugin exécuté. Le nom du fichier sera {unique_resource_name}.report.txt.
2. Le répertoire examples contenant les fichiers de configuration decker. Monter ce volume vous permet d'écrire des configurations localement avec votre éditeur préféré tout en les exécutant dans le conteneur.

Une variable d'environnement est passée :

1. DECKER_TARGET_HOST

Elle est référencée dans les fichiers de configuration sous la forme {var.target_host}. Decker parcourt toutes les variables d'environnement nommées DECKER_*, supprime le préfixe et met le reste en minuscules.

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

Lorsque decker a fini d'exécuter la configuration, cherchez les sorties dans ./decker-reports.

Exécution d'un exemple de configuration sans Docker

Vous voudrez probablement définir le répertoire dans lequel decker écrit les rapports avec la variable d'environnement DECKER_REPORTS_DIR.

Quelque chose comme ceci serait approprié. Assurez-vous simplement que ce que vous définissez est un répertoire existant.

export DECKER_REPORTS_DIR="$HOME/decker-reports"

Vous aurez aussi besoin de définir un hôte cible si vous exécutez un des exemples de fichiers de configuration.

export DECKER_TARGET_HOST="<insérer nom d'hôte ici>"

Ensuite, exécutez simplement un fichier de configuration. Placez-vous dans le répertoire racine de ce dépôt et exécutez :

./decker ./examples/example.hcl

Contribuer

Les contributions sont les bienvenues et appréciées. Voir docs/contributions.md pour les directives.

Développement

L'utilisation de Docker pour le développement est recommandée pour une expérience fluide. Cela garantit que toutes les dépendances seront installées et prêtes à l'emploi.

Référez-vous à Structure du répertoire ci-dessous pour un aperçu du code Go.

Démarrage rapide

1. (sur la machine hôte) : make docker_build
2. (sur la machine hôte) : make docker_run (démarrera le conteneur Docker et ouvrira une session bash interactive)
3. (à l'intérieur du conteneur) : dep ensure -v
4. (à l'intérieur du conteneur) : make build_all
5. (à l'intérieur du conteneur) : make run

Initialiser les hooks Git

Exécutez make init pour ajouter un script pre-commit qui exécutera le linting et les tests à chaque commit.

Développement de plugins

Decker lui-même n'est qu'un cadre qui lit les fichiers de configuration, détermine les dépendances dans les fichiers de configuration et exécute les plugins dans un ordre qui garantit que les plugins ayant des dépendances sur d'autres plugins (sortie d'un plugin étant une entrée pour un autre) s'exécutent après ceux dont ils dépendent.

La vraie puissance de decker vient des plugins. Développer un plugin peut être aussi simple ou complexe que vous le souhaitez, tant que le résultat final est un fichier .so contenant le code compilé du plugin et un fichier .hcl dans le même répertoire déclarant les entrées que le plugin attend de l'utilisateur.

Consultez docs/building_plugins.md pour commencer avec votre premier plugin. Cela ne devrait vous prendre que quelques minutes pour faire fonctionner un plugin decker "Hello World".

Installation des plugins

Par défaut, les plugins sont attendus dans un répertoire relatif à l'emplacement du binaire decker, à <binaire decker>/internal/app/decker/plugins/<nom du plugin>/<nom du plugin>.so. Des chemins supplémentaires peuvent être ajoutés en définissant la variable d'environnement DECKER_PLUGIN_DIRS. Le chemin par défaut du plugin sera toujours utilisé si DECKER_PLUGIN_DIRS est défini.

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

Il devrait y avoir un fichier HCL à côté du fichier .so à <binaire decker>/internal/app/decker/plugins/<nom du plugin>/<nom du plugin>.hcl qui définit ses entrées et sorties. Actuellement, seules les entrées de type string, list et map sont prises en charge. Chaque entrée doit avoir un bloc input qui ressemble à ceci :

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

Structure du répertoire

.
├── 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 est le pilote. Son travail est d'analyser un fichier de configuration donné, de charger les plugins appropriés en fonction des blocs resource du fichier, et d'exécuter les plugins avec les entrées spécifiées.
• examples contient quelques exemples de configurations pour vous aider à démarrer avec decker. Si vous utilisez l'image docker kali (stevenaldinger/decker:kali), toutes les dépendances devraient être installées pour tous les fichiers de configuration et tout devrait fonctionner sans problème.
• internal/pkg est l'endroit où se trouve la plupart du code réel. Il contient tous les packages importés par main.go.
  • dependencies est chargé de construire le graphe de dépendances des plugins et de retourner un tableau trié topologiquement qui garantit que les plugins sont exécutés dans un ordre fonctionnel.
  • gocty offre des assistants pour encoder et décoder les valeurs go-cty qui sont utilisées pour gérer les types d'entrée dynamiques.
  • hcl est chargé d'analyser les fichiers HCL, y compris la création de contextes d'évaluation qui permettent aux blocs de se décoder correctement lorsqu'ils dépendent d'autres blocs de plugins.
  • paths est chargé de retourner les chemins de fichiers pour le binaire , les fichiers de configuration, les fichiers de configuration des plugins et les rapports générés.