Skip to content

SOAR Playbooks: Variables and Functions (IN DEVELOPMENT)

Jump to bottom
Matt Taylor edited this page Oct 18, 2021 · 2 revisions

Common Variables in our SOAR playbooks

There are some variables that are set and are key for functions across the scripted SOAR playbooks in this repository, such as:

  • analyticEA
  • IRSupportDIR
  • artefactAcqusition
  • artefactBackup
  • moreJamfPro
  • notifyUser
  • AWS S3 Upload Variables

Please see below for a detailed breakdown of their purpose, their defaults and proposed configuration.

analyticEA

This variable is used to identify the file created by Jamf Protect as a result of the 'Add to Jamf Pro Smart Group' Analytic action.

  • The value of this variable must match the value specified in the field of this action in order for the workflow to reset successfully after running, otherwise the device will stay a member of the Jamf Pro Smart Group and the workflow is likely to execute again unexpectedly next time the integration is invoked.

IRSupportDIR

This variable is used to define the location of resources used for these incident response workflows. This includes:

  • resource files for the end-user notification function, such as the IBM Notifier.app and logo files
  • the parent directory for the artefact backup save location, created and/or used when artefact backups are enabled

The IRSupportDIR is defaulted to /Library/Application Support/IRSupport but may be specified to any location that is writeable through a Jamf Pro Policy and script.

  • If using either end-user notifications or artefact backups it is recommended to create this directory on endpoints ahead of time but if a workflow runs that requires the directory and it doesn't already exist, it will be created (although files such as those needed for end-user notification will not be created and must be pre-staged).

  • It is recommended to restrict access to this directory from end-users by default.

artefactAcqusition

This variable is used to enable or disable acquisition of artefacts (which differ per playbook) via upload to an AWS S3 bucket.

artefactBackup

This variable is used to enable or disable backing up of artefacts collected during the playbook in the event that a failed acquisition occurs, such as a failed upload or misconfiguration.

  • The variable backupDIR is dependent on the artefactBackup variable being enabled. The default directory specified is a sub-directory of that specified in the IRSupportDIR variable called ArtefactBackups but this may be altered as desired. If the backup operation runs and the directory does not exist it will be created.

moreJamfPro

This variable is used to enable or disable the execution of additional Jamf Pro Policies that may be called by a custom trigger. An example workflow may be running an additional Policy to perform more in-depth or general artefact collection in the event of a security event.

  • The variable customTrigger is dependent on the moreJamfPro variable being enabled. This variable is used to define a custom trigger that will be used to call the additional Policy(s) using the Jamf Pro management framework.

notifyUser

This variable is used to enable or disable an end-user notification popup using the Mac@IBM Notifications tool. Refer to the tool's Github repository for help with usage, configuration and deployment.

  • The location for the IBM Notifier.app tool used for the end-user communication is set with the dependent variable notificationApp, by default configured to be the directory specified in the IRSupportDIR variable but which may be altered.

  • The IBM Notifier.app tool must be pre-staged on devices prior to the scripted playbooks executing that use it. If found to be missing the end-user notification operation will not be executed.

  • This variable has various dependent variables that are required in order to configure and execute the IBM Notifier.app. Refer to the tool documentation linked above for full descriptions and image examples.

AWS S3 Upload Variables

These variables are used to perform an upload operation of artefacts from the endpoint to a specified AWS S3 bucket whereby they can be quickly accessed shortly afterwards.

  • The AWS CLI must be installed and available on the endpoint at the default location: /usr/local/bin/aws
    • Documentation, installation instructions and download links for the AWS CLI can be found here
  • The required S3 bucket information and authorisation key data for the upload must be specified in the configuration area of the playbook script
    • $s3Bucket = S3 bucket name
    • $s3BucketRegion = S3 bucket region (e.g., us-east-1)
    • $s3AccessKeyID = IAM User Access Key ID
    • $s3SecretKey = IAM User Secret Key

Because these values are provided down to the endpoint as part of a Jamf Pro Policy and Script object it is absolutely recommended to implement appropriate security controls made available with IAM and documented by the vendor. An extensive list of these recommendations can be found here.

Some recommended security controls include but are not limited to:

An example IAM managed policy for permitting only upload actions with specified file types to a specific S3 bucket can be found here.

Common Functions in our SOAR Playbooks

There are many functions that are commonplace in the scripted SOAR playbooks in this repository, such as:

  • Artefact acquisition (uploading of files to an AWS S3 bucket)
  • Artefact backup
  • End-user notification
  • Call additional Jamf Pro Policy

Please see below for a detailed breakdown of each function's expected behaviour and required configuration.

AcquireArtefacts

The default method of artefact acquisition from endpoints used in these playbooks is an upload mechanism to an AWS S3 bucket using the AWS CLI. This was chosen due to simplicity, security in function as well as the prevalence of this service within business environments.

Requirements:

  • The AWS CLI tool must be installed on the endpoint and available at the default path (or at a custom path configured in the variables mentioned above)
  • The required variables for a successful upload must be configured
  • Network availability to the S3 service (s3.amazonaws.com:443)
Clone this wiki locally