Using the Script Native Action

11 min

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".

Example:

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.

Note: 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 Script Test use case 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:

Input Attachment

You can use an attachment input in a Python script using a Script native action.

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 Script Test use case for detailed examples.

Use Cases

For more examples and detailed use cases, see the Script Test use case.

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 will fail with the error message you provide.

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: For Boolean and Null data types, use json.loads() to ensure proper data loading:

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:

Use Default Values: Use .get() method with default values for optional inputs:

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.