chore: merge develop into main (#1142)

.github/workflows/build-test-release.yml

@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: apache/skywalking-eyes@v0.5.0
+      - uses: apache/skywalking-eyes@v0.6.0
 
   build-ui:
     name: Build UCC UI
@@ -298,7 +298,7 @@ jobs:
           poetry install
           mkdir tests/packaged
           poetry run ucc-gen package --path tests/testdata/expected_addons/expected_output_global_config_everything/Splunk_TA_UCCExample -o tests/packaged
-      - uses: splunk/appinspect-cli-action@v2.5
+      - uses: splunk/appinspect-cli-action@v2.6
         with:
           app_path: tests/packaged
           included_tags: ${{ matrix.tags }}

docs/alert_actions/adaptive_response.md

@@ -0,0 +1,75 @@
+The Adaptive Response framework provides a mechanism for running preconfigured actions
+within the Splunk platform or by integrating with external applications. 
+These actions can be automatically triggered by correlation search results or manually
+run on an ad hoc basis from the Incident Review dashboard inside the Enterpise Security app. You can read more about this framework [here](https://docs.splunk.com/Documentation/ES/latest/Admin/Setupadaptiveresponse).
+
+In case your add-on is integrated with Enterprise Security, you can define the configurations in 
+the alert action details in your add-on's `globalConfig` and it will create the necessary triggers for it.
+
+
+### Adaptive Response Properties
+
+
+| Property                                                                  | Type   | Description                                                                                            |
+|---------------------------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------|
+| task<span class="required-asterisk">\*</span>    | string | The function or functions performed by the modular action.|
+| subject<span class="required-asterisk">\*</span>    | string | The object or objects that the modular action's task(s) can be performed on (i.e. "endpoint.file"). |
+| category<span class="required-asterisk">\*</span>    | array | The category or categories the modular action belongs to. |
+| technology<span class="required-asterisk">\*</span>    | string | The technology or technologies that the modular action supports. |
+| supportsAdhoc    | boolean | Specifies if the modular action supports adhoc invocations. Default: false |
+| supportsCloud    | boolean | Specifies if the modular actions supports the "cloud" model. Default: true |
+| drilldownUri    | string | Specifies a custom target for viewing the events outputted as a result of the action. Custom target can specify app and/or view depending on syntax. |
+| sourcetype    | string | The sourcetype in which the result of the AR alert action would be written to. The value is updated in the alert action script. If you don't specify any value you can update your alert action script manually once it is generated. |
+
+An example of adaptive response in globalConfig:
+
+```json
+"alerts": [
+    {
+        "name": "test_alert",
+        "label": "Test Alert",
+        "description": "Description for test Alert Action",
+        "iconFileName": "test icon.png",
+        "activeResponse": {
+            "task": [
+                "Create",
+                "Update"
+            ],
+            "supportsAdhoc": true,
+            "supportsCloud": true,
+            "subject": [
+                "endpoint"
+            ],
+            "category": [
+                "Information Conveyance",
+                "Information Portrayal"
+            ],
+            "technology": [
+                {
+                    "version": [
+                        "1.0.0"
+                    ],
+                    "product": "Test Incident Update",
+                    "vendor": "Splunk"
+                }
+            ],
+            "drilldownUri": "search?q=search%20index%3D\"_internal\"&earliest=0&latest=",
+            "sourcetype": "test:incident"
+        },
+        "entity": [ "..." ]
+    }
+]
+```
+
+The above would create an attribute in `output/<YOUR_ADDON_NAME>/default/alert_action.conf` as following:
+```conf
+[test_alert]
+label = Test Alert
+description = Description for test Alert Action
+icon_path = test icon.png
+is_custom = 1
+param._cam = {"task": ["Create", "Update"], "subject": ["endpoint"], "category": ["Information Conveyance", "Information Portrayal"], "technology": [{"version": ["1.0.0"], "product": "Test Incident Update", "vendor": "Splunk"}], "supports_adhoc": true, "supports_cloud": true, "drilldown_uri": "search?q=search%20index%3D\"_internal\"&earliest=0&latest="}
+# ... rest of the properties mentioned in the alert action configuration
+```
+
+You can refer this [dev documentation](https://dev.splunk.com/enterprise/docs/devtools/enterprisesecurity/adaptiveresponseframework) for details on updating alert action scripts such that they can be used in the Adaptive Response framework.

docs/alert_actions/alert_scripts.md

@@ -0,0 +1,113 @@
+The following files would be created/ updated in the output folder once you executed the `ucc-gen` command:
+
+| File Location | Content Description | Action |
+| ------ | ------ | -----|
+| output/<YOUR_ADD-ON_NAME>/bin/<NAME_OF_THE_ALERT>.py | The logic that will be executed when the alert action would be executed. | Created |
+| output/<YOUR_ADD-ON_NAME>/default/alert_actions.conf | Helps Splunk determine the parameters supported by the alert action when using `sendalert` Splunk command. | A stanza with the name as <NAME_OF_THE_ALERT> is created in this conf file.|
+| output/<YOUR_ADD-ON_NAME>/default/data/ui/alerts/<NAME_OF_THE_ALERT>.html | HTML page of the Alert Action that will be rendered in the UI. | Created |
+
+In the python file that is created, below are the methods that you can use or override for varying use cases:
+
+- `process_event()`
+    - This is the start point of where you require to write the logic of sending data from Splunk to any other 
+service via its APIs. Additionally, you can validate the parameters that are provided in the alert action 
+as client side validation (via JavaScript) isn't allowed in Splunk's alert action's HTML page for 
+security reasons. <br> Note: This method must be overwritten.
+- `get_events()` -> List[dict]
+    - Used to get the events that triggered the alert. It returns a list of dictionary. A dictionary points to an event that triggered the alert, and each dictionary has the fields extracted by Splunk.
+- `addevent(raw: str, sourcetype: str)`
+    - If you are bringing additional information from an outer service, you can write that information using this method. You write a single record using the method. This method will append all the records and will dump it to Splunk when `writeevents()` method is called.
+- `writeevents(index: str, host: str, source: str)`
+    - All the events added to the queue using `addevent()` method are written to Splunk with the details passed in the arguments.
+
+An example of a script with validations:
+
+```python
+import import_declare_test
+import sys
+
+from splunktaucclib.alert_actions_base import ModularAlertBase
+from splunk_ta_uccexample import modalert_test_alert_helper
+
+class AlertActionWorkertest_alert(ModularAlertBase):
+
+    def __init__(self, ta_name, alert_name):
+        super(AlertActionWorkertest_alert, self).__init__(ta_name, alert_name)
+
+    def validate_params(self):
+
+
+        if not self.get_param("name"):
+            self.log_error('name is a mandatory parameter, but its value is None.')
+            return False
+
+        if not self.get_param("action"):
+            self.log_error('action is a mandatory parameter, but its value is None.')
+            return False
+
+        if not self.get_param("account"):
+            self.log_error('account is a mandatory parameter, but its value is None.')
+            return False
+        return True
+
+    def process_event(self, *args, **kwargs):
+        status = 0
+        try:
+            if not self.validate_params():
+                return 3
+            status = modalert_test_alert_helper.process_event(self, *args, **kwargs)
+        except (AttributeError, TypeError) as ae:
+            self.log_error("Error: {}. Please double check spelling and also verify that a "
+                "compatible version of Splunk_SA_CIM is installed.".format(str(ae)))
+            return 4
+        except Exception as e:
+            msg = "Unexpected error: {}."
+            if str(e):
+                self.log_error(msg.format(str(e)))
+            else:
+                import traceback
+                self.log_error(msg.format(traceback.format_exc()))
+            return 5
+        return status
+
+if __name__ == "__main__":
+    exitcode = AlertActionWorkertest_alert("Splunk_TA_UCCExample", "test_alert").run(sys.argv)
+    sys.exit(exitcode)
+
+```
+
+In this example, `modalert_test_alert_helper`'s `process_event()` method contains the logic of the actions to be 
+performed when the alert is triggered. It could either be fetch additional information from a service 
+into Splunk or to send any data from Splunk to a service via its APIs.
+
+### Custom Script for Alert Action
+
+Alternatively, you can provide the `process_event()` and `validate_params()` in the script you mentioned in 
+the `customScript` parameter in the globalConfig. If the parameter isn't provided in the globalConfig, UCC framework would provide a boiler plate code that you can leverage in writing your logic for alert action.
+
+This script should be present at `<YOUR_ADD-ON_REPOSITORY_PACKAGE>/bin/` in your respository and it should 
+have `process_event()` function defined. An example declaration could be:
+
+```python
+
+def my_custom_validation(helper):
+    # custom validation logic for the params that are passed
+    return 0 # for successful custom validations
+
+def process_event(helper, *args, **kwargs):
+    if not my_custom_validation(helper):
+        return 3
+
+    helper.log_info("Alert action test_alert started.")
+    # TODO: Implement your alert action logic here
+
+
+    # if clean execution, return 0, 
+    # else non-zero number
+    return 0
+
+```
+
+This function then can have validations and the alert action logic required for your add-on. The preliminary check for required field validations is already provided by the UCC framework. However, if you have any other validations or pre-checks, you can call that function from `process_event()`.
+The `helper` variable would be an object of `splunktaucclib.alert_actions_base.ModularAlertBase` class. 
+This script would be then be copied to `output/` directory after you execute the `ucc-gen` command.

docs/alert_actions/index.md

@@ -0,0 +1,142 @@
+---
+title: Alert Actions
+---
+
+The alert action can help a user to take action on the alerts that have been triggered. The knowledge from Splunk can be sent to an outside service or to pull additional or detailed information related to the trigger details.
+An add-on can have multiple alert actions based on the use cases the add-on provides. You can know more about alert actions from [this documentation](https://docs.splunk.com/Documentation/Splunk/latest/Alert/Aboutalerts).
+
+Developers are required to add alerts in the global config file to create an Alert Action. All the alerts 
+(belonging to all the add-ons and apps) present on a Splunk instance would be shown in the "Trigger Actions" section when creating an alert.
+
+### Properties
+
+
+| Property                                                                  | Type   | Description                                                                                            |
+|---------------------------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------|
+| name<span class="required-asterisk">\*</span>                            | string | Alphanumeric name that would be used to generate the Python file for the alert action. |
+| label<span class="required-asterisk">\*</span>                            | string | User-friendly name of the alert action that would be seen in the Trigger Actions. |
+| entity<span class="required-asterisk">\*</span>                            | array | Array of inputs that would be available in the alert action. |
+| iconFileName                            | string | The name of the icon to be shown in the Alert Action UI. It has to be present in `<YOUR_ADD-ON_NAME>/appserver/static/` directory. Default file name (and icon): `alerticon.png` that comes with UCC framework. |
+| description<span class="required-asterisk">\*</span>                            | string | Description of the alert action. |
+| activeResponse                            | object | Define only if the alert action will be visible for AR in Splunk Enterprise Security app. Note: <strong>DEPRECATED. Use `adaptiveResponse` instead.</strong> |
+| adaptiveResponse                            | object | Define only if the alert action will be visible for AR in Splunk Enterprise Security app. Refer [this section](adaptive_response.md) for complete details. |
+| customScript | string | A Python script that would have validation and logic for alert action execution. The script should be present at `<YOUR_ADD-ON_NAME>/bin/`. Refer [this section](alert_scripts.md#custom-script-for-alert-action) for more information. |
+
+
+### Alert Properties
+
+
+| Property                                                                  | Type   | Description                                                                                            |
+|---------------------------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------|
+| type<span class="required-asterisk">\*</span>                            | string | The type of the user input in the alert. Available choices: "text", "checkbox", "singleSelect", "radio", "singleSelectSplunkSearch". |
+| label<span class="required-asterisk">\*</span>                            | string | The text that would be shown in the alert action UI. |
+| field<span class="required-asterisk">\*</span>                            | string | The field that would be used in the scripts to get the value from the user input. These are defined as `param.<field_mentioned>` in the `alert_actions.conf`. |
+| options                            | array | Static choices that a user can select in the alert action UI. |
+| required                            | boolean | Whether the mentioned field is required or not. Default: false |
+| help                            | string | Help text to be shown under the field of the alert. |
+| search                            | string | A Splunk SPL that would query and return some result. Query the REST API, a lookup table, or indexed data. |
+| valueField                            | string | Field name to use for drop-down option values that correspond to the option labels. In some cases, you can use the same results field for the label-field and value-field. In other cases, you might need to display human-readable labels from one field and use the corresponding values from another field. Note: Applicable when a `search` property is defined. |
+| labelField                            | string | Field name to use for drop-down option labels. Labels generated from this field are visible in the drop-down interface. Note: Applicable when a `search` property is defined. |
+
+
+### Usage
+
+
+This is how the global configuration looks like for an alert action:
+
+```json
+"alerts": [
+        {
+            "name": "test_alert",
+            "label": "Test Alert",
+            "description": "Description for your Alert Action",
+            "entity": [
+                {
+                    "type": "singleSelectSplunkSearch",
+                    "label": "Select Account",
+                    "field": "account",
+                    "search": "| rest /servicesNS/nobody/Splunk_TA_UCCExample/splunk_ta_uccexample_account splunk_server=local | dedup title",
+                    "options": {
+                        "items": [
+                            {
+                                "label": "earliest",
+                                "value": "-4@h"
+                            },
+                            {
+                                "label": "latest",
+                                "value": "now"
+                            }
+                        ]
+                    },
+                    "valueField": "title",
+                    "labelField": "title",
+                    "help": "Select an account from the dropdown",
+                    "required": true
+                },
+                {
+                    "type": "text",
+                    "label": "Name",
+                    "field": "name",
+                    "defaultValue": "my_name",
+                    "required": true,
+                    "help": "Please enter your Name"
+                },
+                {
+                    "type": "checkbox",
+                    "label": "Run for All",
+                    "field": "run_for_all",
+                    "defaultValue": 0,
+                    "required": false,
+                    "help": "Check if you want to run alert action for all "
+                },
+                {
+                    "type": "singleSelect",
+                    "label": "Item List",
+                    "field": "item_list",
+                    "options": {
+                        "items": [
+                            {
+                                "value": "option_1",
+                                "label": "Option 1"
+                            },
+                            {
+                                "value": "option_2",
+                                "label": "Option 2"
+                            }
+                        ]
+                    },
+                    "help": "Select any one option from the list",
+                    "required": false,
+                    "defaultValue": "option_1"
+                },
+                {
+                    "type": "radio",
+                    "label": "Action:",
+                    "field": "action",
+                    "options": {
+                        "items": [
+                            {
+                                "value": "update",
+                                "label": "Update"
+                            },
+                            {
+                                "value": "insert",
+                                "label": "Insert"
+                            }
+                        ]
+                    },
+                    "help": "Select the action you want to perform",
+                    "required": true,
+                    "defaultValue": "insert"
+                }
+            ]
+        }
+    ]
+```
+
+### Output
+
+This is how the alert action looks like in the UI:
+
+![image](../images/alert_actions/alert_output.png)
+Refer the [Alert Scripts](alert_scripts.md) section to know what all files are created and how they can be updated to achieve the use case of your add-on.

docs/custom_ui_extensions/custom_control.md

@@ -70,7 +70,9 @@ class CustomControl {
         this.setValue = setValue;
     }
 
-    _onSelectOptionChange() { }
+    onSelectOptionChange(event) {
+        this.setValue(event.target.value);
+    }
 
     validation(field, value) {
         // Validation logic for value. Return the error message if failed.
@@ -88,8 +90,8 @@ class CustomControl {
         `;
 
         this.el.innerHTML = content_html;
+        this.el.addEventListener('change', this.onSelectOptionChange);
 
-        $('select#custom_control').on('change', () => this._onSelectOptionChange());
         return this;
     }
 }