Add RTR admin script management example.

faldridge · faldridge · commit 3aecaf3098ec · 2022-12-14T06:27:42.000-06:00
diff --git a/.github/wordlist.txt b/.github/wordlist.txt
@@ -38,3 +38,9 @@ pre
 stdout
 utilises
 zta
+RTR
+Responders
+linux
+macOS
+Zsh
+PowerShell
diff --git a/examples/falcon_rtr_admin_create_and_run_script/README.md b/examples/falcon_rtr_admin_create_and_run_script/README.md
@@ -0,0 +1,57 @@
+This is a working standalone example of a program to upload a stored script
+using the RTR Create Script API and then running it against an agent
+via the RTR Execute Admin Command API.
+
+Note that the API client key used for this example will need to be granted
+the RTR Administrator permission for this script to run successfully.
+
+For more information on managing RTR scripts as an Administrator, see the
+[Manage Real Time Response scripts](https://developer.crowdstrike.com/crowdstrike/docs/real-time-response-apis#manage-real-time-response-scripts)
+section of the Falcon developer API documentation.
+
+## Build
+```
+go get github.com/crowdstrike/gofalcon/examples/falcon_rtr_upload_and_run_script
+```
+
+## Setup Environment Variables
+```
+export FALCON_CLIENT_ID="your_falcon_id"
+export FALCON_CLIENT_SECRET="your_falcon_secret"
+export FALCON_CLOUD="us-1, us-2, eu-1, us-gov-1, etc"
+```
+
+## Usage
+```
+$ FALCON_CLIENT_ID="abc" FALCON_CLIENT_SECRET="XYZ" FALCON_CLOUD=us-1 \
+      falcon_rtr_admin_create_and_run_script --permtype group --platforms="linux,mac" \
+      --script="relative path to script file from current working directory" \
+      --name="name of the file to use when invoking runscript with the `-CloudFile` option" \
+      --aid="def"
+```
+
+## Notes
+
+### Script types by platform
+
+* Scripts targeting Windows will be interpreted with PowerShell
+* Scripts targeting Linux will be interpreted with bash
+* Scripts targeting macOS will be interpreted with Zsh
+
+### Permission Type
+
+Valid values for the `permtype` argument are:
+
+* private: script can only be invoked by the user who uploaded it
+* group: script can only be invoked by RTR Administrators
+* public: script can be invoked by RTR Administrators and RTR Active Responders
+
+Default value for `permtype` is `group`.
+
+### Platforms
+
+The `platforms` argument is a comma-delimited string of one or more of either
+"windows", "linux", or "mac".
+
+If not specified, the default for this example code is "linux", though when
+using the Falcon API or gofalcon SDK directly the default is "windows".
diff --git a/examples/falcon_rtr_admin_create_and_run_script/examplescript.sh b/examples/falcon_rtr_admin_create_and_run_script/examplescript.sh
@@ -0,0 +1,2 @@
+#!/bin/bash
+echo "Hello RTR!"
diff --git a/examples/falcon_rtr_admin_create_and_run_script/main.go b/examples/falcon_rtr_admin_create_and_run_script/main.go
@@ -0,0 +1,75 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/crowdstrike/gofalcon/falcon"
+	"github.com/crowdstrike/gofalcon/pkg/falcon_util"
+	"github.com/go-openapi/runtime"
+)
+
+func main() {
+	clientId := flag.String("client-id", os.Getenv("FALCON_CLIENT_ID"), "Client ID for accessing CrowdStrike Falcon Platform (default taken from FALCON_CLIENT_ID env)")
+	clientSecret := flag.String("client-secret", os.Getenv("FALCON_CLIENT_SECRET"), "Client Secret for accessing CrowdStrike Falcon Platform (default taken from FALCON_CLIENT_SECRET)")
+	clientCloud := flag.String("cloud", os.Getenv("FALCON_CLOUD"), "Falcon cloud abbreviation (us-1, us-2, eu-1, us-gov-1; default taken from FALCON_CLOUD)")
+	aid := flag.String("aid", os.Getenv("FALCON_AGENT_ID"), "Falcon agent ID on which to run the custom script (default taken from FALCON_AGENT_ID)")
+	permType := flag.String("permtype", "group", "Permission type (private, group, or public; default is group, which makes the script usable to all RTR Admins)")
+	platformString := flag.String("platforms", "linux", "The platform(s) the file supports. If specified, can be one or more of [windows, mac, linux] (default for this script is linux)")
+	script := flag.String("script", "examples/falcon_rtr_admin_create_and_run_script/examplescript.sh", "Relative path to the script to upload (defaults to the script included in this example, assuming cwd is the project root)")
+	name := flag.String("name", "examplescript.sh", "Name to give to the uploaded script for later invocation (default is examplescript.sh)")
+
+	flag.Parse()
+	if *clientId == "" {
+		*clientId = falcon_util.PromptUser(`Missing FALCON_CLIENT_ID environment variable. Please provide your OAuth2 API Client ID for authentication with CrowdStrike Falcon platform. Establishing and retrieving OAuth2 API credentials can be performed at https://falcon.crowdstrike.com/support/api-clients-and-keys.
+Falcon Client ID`)
+	}
+	if *clientSecret == "" {
+		*clientSecret = falcon_util.PromptUser(`Missing FALCON_CLIENT_SECRET environment variable. Please provide your OAuth2 API Client Secret for authentication with CrowdStrike Falcon platform. Establishing and retrieving OAuth2 API credentials can be performed at https://falcon.crowdstrike.com/support/api-clients-and-keys.
+Falcon Client Secret`)
+	}
+	if *aid == "" {
+		*aid = falcon_util.PromptUser(`Missing FALCON_AGENT_ID. Please provide the ID of the agent you would like to communicate with.
+Falcon agent ID`)
+	}
+	platforms := strings.Split(*platformString, ",")
+	scriptFile, err := os.Open(*script)
+	if err != nil {
+		panic(err)
+	}
+	scriptReadCloser := runtime.NamedReader(*name, scriptFile)
+
+	client, err := falcon.NewRTR(&falcon.ApiConfig{
+		ClientId:     *clientId,
+		ClientSecret: *clientSecret,
+		Cloud:        falcon.Cloud(*clientCloud),
+		Context:      context.Background(),
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	// First, create/upload the script for later use via the Create Script API.
+	err = client.CreateScript(context.Background(), nil, "An example script to demonstrate script management via the RTR Admin APIs.",
+		*permType, platforms, falcon_util.StrPtr("created example script with gofalcon SDK"), nil, scriptReadCloser)
+	if err != nil {
+		panic(falcon.ErrorExplain(err))
+	}
+
+	// Then invoke the script by sending the `runscript` command to the RTR Execute Admin Command API.
+	session, err := client.NewSession(context.Background(), *aid)
+	if err != nil {
+		panic(falcon.ErrorExplain(err))
+	}
+	result, err := session.AdminExecuteAndWait(
+		context.Background(), "runscript", fmt.Sprintf("runscript -CloudFile='%s'", *name))
+	if err != nil {
+		panic(falcon.ErrorExplain(err))
+	}
+
+	json, _ := falcon_util.PrettyJson(result)
+	fmt.Println(json)
+}
