Using the Script Native Action

overview the script native action executes python code within a sandboxed environment it provides access to standard python libraries and pre configured global variables for accessing inputs, setting outputs, and handling errors scripts run in isolated containers to ensure security and resource management key benefits of the script action flexibility with python leverage python 3 to manipulate data and handle edge cases efficiency reduces complexity compared to jsonata for simpler tasks preloaded libraries access standard python libraries including json , datetime , math , csv , base64 , hashlib , itertools , statistics , and more sandboxed execution scripts run in isolated containers for security and resource management global variables pre configured variables ( action inputs , action outputs , action error ) simplify script development attachment support built in support for handling file attachments as inputs and outputs available global variables the script native action provides three global variables action inputs a dictionary containing all input values passed to the script access inputs using action inputs\["propertyname"] or action inputs get("propertyname") action outputs a dictionary used to set output values assign values using action outputs\["outputname"] = value action error a dictionary that, when populated, will fail the action with the corresponding error payload set error information using action error\["message"] = "error description" output attachment a pre injected global object used to create and return file attachments from a script call output attachment open("filename ext") to open a writable file handle, then assign the handle to action outputs example \# read an input value score = action inputs\["last malicious score"] # perform logic and write to outputs if score > 0 9 action outputs\["verdict"] = "malicious" action outputs\["score"] = score else action outputs\["verdict"] = "clean" action outputs\["score"] = score setting up the script native action here’s how to configure a script action in your playbook from the add panel, drag and drop the script action onto the playbook canvas click configure , then add property to define input data types (string, number, boolean, object, array, or attachment) write your python script in the provided field or select upstream playbook inputs using the property drawer script inputs define static and dynamic inputs using the following supported types string text values number numeric values (integers or floats) boolean true/false values object json objects/dictionaries array json arrays/lists attachment file attachments configuring script inputs follow these steps to set up your inputs click add property in the inputs pane to define your inputs rename properties as needed using the pencil icon set input values by entering static values directly selecting properties from upstream actions using the property drawer using expressions to reference playbook data write or paste your python code in the script pane access inputs in your script using action inputs\["propertyname"] example in this example, a script evaluates a last malicious score to determine if it meets the malicious score threshold outputs tab the outputs tab enables promotion of action outputs for downstream use view outputs see all outputs provided by the script action promote outputs select outputs to make them available to downstream actions in the playbook mark sensitive click the ellipsis button (⋯) next to an output and select mark sensitive to mark sensitive data delete outputs remove outputs that are not needed outputs are set in your python script using action outputs\["outputname"] = value the outputs tab allows you to manage which outputs are promoted and marked as sensitive script testing want to test your script action before continuing to build your playbook? in the script action, from the test tab view inputs see all configured inputs on the left side of the test panel view script see your python code on the right side of the test panel modify test inputs change input values to test different scenarios run test execute the script with the test inputs view results see the output in the results pane at the bottom important notes attachment limitations attachment fields are not shown in the test tab inputs attachments cannot be used in test runs of the action you must perform a full playbook test to test attachment inputs discovered outputs just like discovered outputs in an http action, results vary in addition to the base property types, depending on the inputs you select, the action outputs may return additional properties these are the discovered outputs, which you can promote and/or delete from the outputs tab error handling if your script encounters an error during testing, error details will be displayed in the results pane see a docid\ zrzcp0gr12dfzzkb risd for an example on testing the script native action handling attachments in scripts if you need to return an attachment or use an attachment as an input in the script native action, follow the instructions below output attachment in your playbook, follow the instructions below to configure an output attachment add a script action to your playbook, title it (for example, return attachment ), and click configure in the script pane, use the output attachment global to create and return a file there are two equivalent styles context manager style (recommended) with output attachment open("report txt") as f f write("this is the attachment content ") action outputs\["my file"] = f direct open/close style my file = output attachment open("report txt") my file write("this is the attachment content ") action outputs\["my file"] = my file the string passed to output attachment open() becomes the filename of the returned attachment assign the file handle to action outputs to make it available to downstream actions click apply to save changes input attachment you can use an attachment input in a python script using a script native action attachment inputs in action inputs are custom objects — call open() on them to get a readable file handle and use the methods described below add a script action and click configure in the inputs pane, click add property and select attachment rename the property (for example, file1 ) using the pencil icon click select a property and select the upstream attachment from the playbook property drawer in the script pane, read the attachment using one of the following styles context manager style (recommended) with action inputs\["file1"] open() as file1 action outputs\["file1 text"] = file1 read() action outputs\["file1 size"] = file1 size() action outputs\["file1 mimetype"] = file1 mimetype() direct open/close style file2 = action inputs\["file2"] open() action outputs\["file2 text"] = file2 read() file2 close() available methods on an opened attachment handle true 153,508left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type click apply to save changes attachment inputs are not shown in the test tab you must run a full playbook test to verify attachment input handling testing the script test your script in the test tab before full integration the results appear in the results pane this is useful for debugging and validating output see the docid\ zrzcp0gr12dfzzkb risd for detailed examples available python libraries the script native action provides access to standard python libraries some commonly used libraries include json json encoding and decoding datetime date and time manipulation math mathematical functions csv csv file processing base64 base64 encoding/decoding hashlib hash algorithms (md5, sha256, etc ) itertools iterator functions statistics statistical functions string string utilities time time related functions decimal decimal arithmetic fractions rational numbers ipaddress ip address manipulation html html utilities email email parsing zlib compression note custom package imports are not allowed only preloaded standard python libraries are available error handling you can handle errors in your script using the action error global variable when action error is populated, the action fails with the error payload you provide use a try/except block to catch exceptions and surface meaningful messages to the playbook import json try # validate that a required input is present if "target ip" not in action inputs action error\["message"] = "missing required input target ip" else target ip = action inputs\["target ip"] # perform processing action outputs\["result"] = f"processed {target ip}" except exception as e action error\["message"] = f"script failed with error once action error is populated, the action stops and the on failure path (if configured) is taken do not set both action outputs and action error in the same code path troubleshooting script fails with import error custom package imports are not allowed use only standard python libraries that are preloaded input not found use action inputs get("propertyname", default value) to provide default values for optional inputs, or check if keys exist before accessing them output not appearing ensure you're setting outputs using action outputs\["outputname"] = value outputs must be set before the script completes attachment not working attachments cannot be tested in the test tab use a full playbook test to verify attachment handling boolean/null values all playbook data is json python does not natively support all json types (for example, true / false / null vs python's true / false / none ) use json loads() to parse json strings containing boolean or null values import json # if the input arrives as a json string (e g , "true" or "null") raw value = action inputs get("is malicious", "false") is malicious = json loads(raw value) # converts "true" → true, "null" → none type errors ensure you're using the correct data types use type conversion functions (int(), str(), float(), bool()) when needed best practices start simple begin with straightforward scripts before moving to more complex logic use comments comment your code for clarity and easier debugging the script editor includes helpful comments about available global variables test frequently use the test tab to validate your script iteratively with different input values handle errors gracefully use try except blocks to catch and handle errors use action error to provide meaningful error messages validate inputs before processing them validate inputs check that required inputs exist and have valid values before using them if "severity" not in action inputs action error\["message"] = "missing required input severity" elif not isinstance(action inputs\["severity"], (int, float)) action error\["message"] = "input 'severity' must be a number" else action outputs\["level"] = "high" if action inputs\["severity"] > 7 else "low" use default values use get() method with default values for optional inputs threshold = action inputs get("threshold", 0 9) description = action inputs get("description", "no description provided") keep scripts focused write scripts that do one thing well break complex logic into multiple script actions if needed document your scripts add comments explaining what the script does, especially for complex logic or business rules