Decker - Framework di Orchestrazione per Penetration Testing

Scopo

Decker è un framework di orchestrazione per penetration testing. Sfrutta HashiCorp Configuration Language 2 (lo stesso linguaggio di configurazione di Terraform) per consentire la dichiarazione di penetration testing as code, in modo che i tuoi test possano essere versionati, condivisi, riutilizzati e su cui collaborare con il tuo team o la community.

Esempio di file di configurazione decker:

// le variabili vengono estratte dall'ambiente
//   es: DECKER_TARGET_HOST
// saranno disponibili in tutto il file di configurazione come var.*
//   es: ${var.target_host}
variable "target_host" {
  type = "string"
}

// le risorse si riferiscono ai plugin
// le risorse necessitano di nomi univoci in modo che i plugin possano essere usati più volte
// vengono dichiarate con la forma: 'resource "nome_plugin" "nome_univoco" {}'
// i loro output saranno disponibili per altri utilizzando la forma nome_univoco.*
//   es: nmap.443
resource "nmap" "nmap" {
  host = "${var.target_host}"
  plugin_enabled = "true"
}
resource "sslscan" "sslscan" {
  host = "${var.target_host}"
  plugin_enabled = "${nmap.443 == "open"}"
}

Esegui un plugin per ogni elemento di una lista:

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

Configurazione complessa che combina for_each con valori annidati:

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}"
}
// per ogni IP, verifica se nmap ha trovato la porta 25 aperta.
// se sì, esegui lo scanner smtp_enum di metasploit
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"}"
}

Formati di output

Sono disponibili diversi formati di output e se ne possono selezionare più di uno contemporaneamente.

Impostando DECKER_OUTPUTS_JSON o DECKER_OUTPUTS_XML a "true" verranno generati rispettivamente file formattati in json e xml.

Output di file .json oltre al testo semplice: export DECKER_OUTPUTS_JSON="true"
Output di file .xml oltre al testo semplice: export DECKER_OUTPUTS_XML="true"

Perché il nome decker?

La mia amica Courtney è venuta in mio soccorso quando facevo fatica a trovare un nome e ha trovato decker in un glossario di parole di fantascienza... e sembrava figo.

Un cracker futuro; un esperto di software abile nel manipolare il cyberspazio, specialmente nell'eludere le precauzioni di sicurezza.

Esecuzione di una configurazione di esempio con docker

Vengono montati due volumi:

Una directory denominata decker-reports dove decker scriverà un file per ogni plugin eseguito. Il nome del file sarà {unique_resource_name}.report.txt.
La directory examples contenente i file di configurazione di decker. Montare questo volume ti permette di scrivere configurazioni localmente usando il tuo editor preferito e comunque eseguirle all'interno del container.

Viene passata una variabile d'ambiente:

DECKER_TARGET_HOST

Questa viene referenziata nei file di configurazione come {var.target_host}. Decker itera su tutte le variabili d'ambiente con nome DECKER_*, rimuovendo il prefisso e impostando il resto in minuscolo.

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

Al termine dell'esecuzione di decker, cerca i risultati in ./decker-reports.

Esecuzione di una configurazione di esempio senza docker

Probabilmente vorrai impostare la directory in cui decker scrive i report utilizzando la variabile d'ambiente DECKER_REPORTS_DIR.

Qualcosa di simile a questo sarebbe appropriato. Assicurati solo che ciò che imposti sia una directory esistente.

export DECKER_REPORTS_DIR="$HOME/decker-reports"

Dovrai anche impostare un host target se stai eseguendo uno dei file di configurazione di esempio.

export DECKER_TARGET_HOST="<inserisci hostname qui>"

Poi esegui semplicemente un file di configurazione. Spostati nella directory principale di questo repository ed esegui:

./decker ./examples/example.hcl

Contribuire

I contributi sono benvenuti e apprezzati. Vedi docs/contributions.md per le linee guida.

Sviluppo

L'uso di docker per lo sviluppo è consigliato per un'esperienza fluida. Ciò garantisce che tutte le dipendenze siano installate e pronte all'uso.

Fai riferimento a Struttura delle Directory qui sotto per una panoramica del codice go.

Avvio Rapido

(sulla macchina host): make docker_build
(sulla macchina host): make docker_run (avvia il container docker e apre una sessione bash interattiva)
(all'interno del container): dep ensure -v
(all'interno del container): make build_all
(all'interno del container): make run

Inizializzare i git hooks

Esegui make init per aggiungere uno script pre-commit che eseguirà linting e test ad ogni commit.

Sviluppo di Plugin

Decker stesso è solo un framework che legge file di configurazione, determina le dipendenze nei file di configurazione ed esegue i plugin in un ordine che garantisca che i plugin con dipendenze da altri plugin (output di un plugin come input per un altro) vengano eseguiti dopo quelli da cui dipendono.

Il vero potere di decker deriva dai plugin. Sviluppare un plugin può essere semplice o complesso quanto desideri, purché il risultato finale sia un file .so contenente il codice del plugin compilato e un file .hcl nella stessa directory che dichiari gli input che il plugin si aspetta che l'utente configuri.

Dai un'occhiata a docs/building_plugins.md per iniziare con il tuo primo plugin. Dovrebbero bastarti pochi minuti per far funzionare un plugin "Hello World" di decker.

Installazione dei plugin

Per impostazione predefinita, i plugin devono trovarsi in una directory relativa a dove si trova il binario di decker, in <decker binary>/internal/app/decker/plugins/<plugin name>/<plugin name>.so. È possibile aggiungere percorsi aggiuntivi impostando la variabile d'ambiente DECKER_PLUGIN_DIRS. Il percorso predefinito dei plugin verrà comunque utilizzato se DECKER_PLUGIN_DIRS è impostato.

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

Dovrebbe esserci un file HCL accanto al file .so in <decker binary>/internal/app/decker/plugins/<plugin name>/<plugin name>.hcl che definisce i suoi input e output. Attualmente sono supportati solo input di tipo string, list e map. Ogni input dovrebbe avere un blocco input che assomiglia a questo:

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

Struttura delle Directory

.
├── 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 è il driver. Il suo compito è analizzare un dato file di configurazione, caricare i plugin appropriati in base ai blocchi resource del file ed eseguire i plugin con gli input specificati.
examples contiene un paio di configurazioni di esempio per iniziare con decker. Se usi l'immagine docker kali (stevenaldinger/decker:kali), tutte le dipendenze dovrebbero essere installate per tutti i file di configurazione e tutto dovrebbe funzionare senza intoppi.
internal/pkg è dove risiede la maggior parte del codice effettivo. Contiene tutti i pacchetti importati da main.go.
- dependencies è responsabile della costruzione del grafo delle dipendenze dei plugin e del ritorno di un array ordinato topologicamente che garantisce che i plugin vengano eseguiti in un ordine funzionante.
- gocty offre helper per codificare e decodificare i valori go-cty che vengono utilizzati per gestire tipi di input dinamici.
- hcl è responsabile dell'analisi dei file HCL, inclusa la creazione di contesti di valutazione che consentano ai blocchi di decodificare correttamente quando dipendono da altri blocchi plugin.
- paths è responsabile della restituzione dei percorsi dei file per il binario di , i file di configurazione, i file di configurazione dei plugin e i report generati.

decker

Più Popolari