Decker - 侵入テストオーケストレーションフレームワーク

目的

Deckerは侵入テストのオーケストレーションフレームワークです。HashiCorp Configuration Language 2（Terraformと同じ設定言語）を活用し、宣言的な侵入テスト as Codeを実現します。これにより、テストをバージョン管理、共有、再利用、そしてチームやコミュニティと共同作業できます。

decker設定ファイルの例：

// 変数は環境から取得されます
//   例: DECKER_TARGET_HOST
// これらは設定ファイル全体で var.* として利用可能になります
//   例: ${var.target_host}
variable "target_host" {
  type = "string"
}

// リソースはプラグインを参照します
// リソースは一意な名前が必要で、プラグインを複数回使用できます
// 形式: 'resource "plugin_name" "unique_name" {}'
// その出力は unique_name.* の形式で他のプラグインから利用可能になります
//   例: 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"
  }
}

for_eachとネストされた値を組み合わせた複雑な設定：

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}"
}
// 各IPに対して、nmapがポート25が開いているか確認します。
// 開いている場合、metasploitのsmtp_enumスキャナーを実行します
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"}"
}

出力形式

複数の出力形式が利用可能で、同時に複数を選択できます。

DECKER_OUTPUTS_JSONまたはDECKER_OUTPUTS_XMLを"true"に設定すると、それぞれjsonおよびxml形式のファイルが出力されます。

1. プレーンテキストに加えて.jsonファイルを出力する: export DECKER_OUTPUTS_JSON="true"
2. プレーンテキストに加えて.xmlファイルを出力する: export DECKER_OUTPUTS_XML="true"

なぜdeckerという名前なのか？

名前を考えあぐねていたとき、友人のCourtneyが助けに来て、SciFi用語集からdeckerを見つけてくれました...そしてかっこよかったのです。

未来のクラッカー。サイバースペースを操作すること、特にセキュリティ対策を回避することに長けたソフトウェアのエキスパート。

Dockerでサンプル設定を実行する

2つのボリュームがマウントされます:

1. decker-reportsという名前のディレクトリ。deckerは実行された各プラグインのファイルをここに出力します。ファイル名は{unique_resource_name}.report.txtとなります。
2. decker設定ファイルを含むexamplesディレクトリ。このボリュームをマウントすることで、お気に入りのエディタでローカルに設定を書き、コンテナ内で実行できます。

1つの環境変数が渡されます:

1. DECKER_TARGET_HOST

これは設定ファイル内で{var.target_host}として参照されます。DeckerはDECKER_*という名前のすべての環境変数をループし、プレフィックスを削除して残りを小文字に設定します。

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

deckerが設定の実行を終了したら、./decker-reports内の出力を確認してください。

Dockerなしでサンプル設定を実行する

deckerがレポートを書き込むディレクトリを、環境変数DECKER_REPORTS_DIRで設定することをお勧めします。

次のような設定が適切でしょう。設定したディレクトリが既に存在していることを確認してください。

export DECKER_REPORTS_DIR="$HOME/decker-reports"

また、サンプル設定ファイルを実行する場合はターゲットホストも設定する必要があります。

export DECKER_TARGET_HOST="<ホスト名を挿入>"

次に、設定ファイルを実行します。このリポジトリのルートディレクトリに移動し、次のコマンドを実行します:

./decker ./examples/example.hcl

コントリビューション

コントリビューションは大歓迎です。ガイドラインについてはdocs/contributions.mdを参照してください。

開発

スムーズな開発体験のために、Dockerを使用することをお勧めします。これにより、すべての依存関係がインストールされ、すぐに使用できる状態になります。

Goコードの概要については、以下の「ディレクトリ構造」を参照してください。

クイックスタート

1. (ホストマシン上): make docker_build
2. (ホストマシン上): make docker_run (Dockerコンテナを起動し、インタラクティブなbashセッションを開きます)
3. (コンテナ内): dep ensure -v
4. (コンテナ内): make build_all
5. (コンテナ内): make run

Gitフックの初期化

make initを実行すると、各コミットでlintingとテストを実行するpre-commitスクリプトが追加されます。

プラグイン開発

Decker自体は、設定ファイルを読み取り、依存関係を特定し、プラグインを適切な順序（あるプラグインの出力が別のプラグインの入力になる場合、依存先の後に実行される）で実行するフレームワークです。

deckerの真の力はプラグインにあります。プラグインの開発は、最終結果がコンパイルされたプラグインコードを含む.soファイルと、ユーザーが設定する入力を宣言する同じディレクトリ内の.hclファイルである限り、単純にも複雑にもできます。

最初のプラグインを始めるには、docs/building_plugins.mdをチェックしてください。「Hello World」のdeckerプラグインを実行するのに数分しかかからないはずです。

プラグインのインストール

デフォルトでは、プラグインはdeckerバイナリからの相対パス、<decker binary>/internal/app/decker/plugins/<plugin name>/<plugin name>.soにあることが期待されます。環境変数DECKER_PLUGIN_DIRSを設定することで、追加のパスを追加できます。DECKER_PLUGIN_DIRSが設定されている場合でも、デフォルトのプラグインパスは引き続き使用されます。

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

.soファイルと同じディレクトリに、その入力と出力を定義するHCLファイルが存在する必要があります。現在、string、list、mapの入力のみがサポートされています。各入力は、次のようなinputブロックを持つ必要があります:

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はドライバーです。その役割は、指定された設定ファイルを解析し、ファイルのresourceブロックに基づいて適切なプラグインをロードし、指定された入力でプラグインを実行することです。
• examplesには、deckerを始めるためのいくつかのサンプル設定があります。kaliのdockerイメージ（stevenaldinger/decker:kali）を使用する場合、すべての設定ファイルの依存関係がインストールされており、スムーズに動作するはずです。
• internal/pkgには、実際のコードの大部分が含まれています。main.goによってインポートされるすべてのパッケージが含まれています。
  • dependenciesは、プラグインの依存関係グラフを構築し、プラグインが適切な順序で実行されるようにトポロジカルソートされた配列を返す責任があります。
  • goctyは、動的な入力型を扱うために使用されるgo-cty値のエンコードとデコードのためのヘルパーを提供します。
  • hclは、HCLファイルの解析を担当し、他のプラグインブロックに依存するブロックが正しくデコードできるようにする評価コンテキストの作成も含みます。
  • pathsは、deckerバイナリ、設定ファイル、プラグイン設定ファイル、生成されたレポートのファイルパスを返す責任があります。
  • pluginsは、プラグインが有効かどうかを判断し、それらを実行する責任があります。
  • reportsは、レポートをファイルシステムに書き込む責任があります。