Manage SPL2-based apps

To modify an SPL2-based app, you need to use a version of the Splunk platform that supports SPL2-based apps:

• Splunk Cloud Platform version 9.3.2408 or higher
• Splunk Enterprise version 9.4.0 or higher

For information about SPL2-based applications, see:

• Install SPL2-based apps
• Create SPL2-based apps in the Splunk Developer Guide on dev.splunk.com

Modify an SPL2-based application

To make changes to an SPL2-based application, other than just updating module permissions, you must modify the app contents in the local directory and completely reinstall the app to ensure the changes to be implemented.

Complete the following steps to change an SPL2-based app:

1. Copy the modules that you want to change into a local directory under the <app_name> directory. The local directory structure must be /local/data/spl2. The following image shows the sample_data and masked_view modules copied into the local directory path:
   
2. Modify the files in the local directory. The local directory takes precedence over the default directory. Note that the default module must be named _default to provide implicit SPL2 imports to the app's search interface.
3. Reinstall the app.

When you reinstall an app, modules with the exact same name are overwritten.

To make changes to the modules directly in the environment, use the modules endpoints to modify a module. For examples of how to use these endpoints to modify a module, see Endpoints for SPL2-based application in the REST API Reference Manual.

To fully customize an SPL2-based app, you must download the app modules, edit the modules, and re-package the modules by using the same steps as the application developer. See Package your SPL2-based application in the Splunk Developer Guide on the Splunk Developer Portal.

Modify permissions for modules

Permissions for SPL2-based apps are set by role and module:

• Module-level permissions are set by using the Splunk REST API endpoints.
• App-level permissions are set in Splunk Web.

By default, the admin and power roles have execute, read, and write permissions on all modules.

Module owners, regardless of their role, are automatically given read and write permissions to modules that they create.

Users

• The execute permission enables the role to run a search.
• The read permission enables the role to run a search and to see a module definition. The read permission supersedes the execute permission.
• The write permission enables the role to perform create, update, and delete operations.

Adding the @run_as_owner; annotation to a module changes the module permissions. For more information, see the "Enable users to run a module as its owner" section later in this topic.

You can modify role-based permissions for SPL2-based apps at the module level by using the permissions API endpoints. For details on the permissions endpoints, see Search endpoint descriptions in the REST API Reference Manual.

Calls to the permissions endpoints must specify all of the operations, even if you are only changing one of the operations.

Example of setting role based permissions

Suppose an SPL2-based app contains a module called "masked_data" that takes events from an index and uses a search to return the same set of events with the email addresses masked out. The search that masks the events is exported as a view which can be used in other modules in the app. While you can't set permissions on the masked view itself, you can set permissions on the "masked_data" module.

Here's an example of the permissions endpoint that you use to add the user role to the execute operation for the masked_data module. The other permissions remain unchanged from the default permissions:

curl -k -u admin:pass https://localhost:8089/services/spl2/permissions \
--data '{
  "resourceType": "modules",
  "resourceName": "masked_data",
  "permissions": [
     {
      "operation": "execute",
      "roles": [
        "admin",
        "power",
        "user"
      ]
    },
    {
      "operation": "read",
      "roles": [
        "admin",
        "power"
      ]
    },
    {
      "operation": "write",
      "roles": [
        "admin",
        "power"
      ]
    }
  ]
}'

Limit access to sensitive data by enabling run-as-owner views

When a dataset, such as an index, contains some sensitive or personal data, you can enable users to search the non-sensitive portions of the dataset without granting them permissions on the dataset itself.

You do this by creating a module that contains views which either mask or filter out sensitive and personal data. You then grant users permissions on that specific module without giving users access to the underlying dataset. You grant users permissions by adding the @run_as_owner; annotation to the module and granting execute permissions to that module .

• The @run_as_owner; annotation enables users to run searches using the views in the module with the same permissions as the owner of the module.
• The execute permissions enables the users to run searches using the views, without being able to read or edit the module or the view definition itself.

Only private apps can be marked with the @run_as_owner; annotation.

This annotation gives users permissions to any of the items exported by the module, including any datasets that are exported. It is important that you export only the masked views - and not any of the imported datasets - from a module that includes the @run_as_owner; annotation.

Users will access the views in the module and the views will access the underlying datasets.

For more information, see:

• Modules and SPL2 statements
• Datasets
• SPL2 views

Scenario: Implementing run as owner feature

Here is a scenario that explains how the run as owner feature works:

Sasha, a Splunk administrator, creates or installs an application that contains a module called masked. The masked module imports the main index, which contains sensitive data that should not be accessed by all users. However, Sasha wants all users to access a filtered subset or view of the same data, without double-indexing the masked or filtered data into a separate index.

Alex is a user who doesn't have permissions on the main index. Alex needs access to some of the data on the index, but not to the sensitive data.

Sasha creates an SPL2 search to mask out PII information, such as email addresses, creating a masked view of the data. The view is called masked_main.

Sasha grants Alex execute permission on the masked module. The searches run by Alex using the masked_main view fail because Alex doesn't have permissions on the main index. Even if Sasha grants Alex read and write permission on the masked module, the searches run by Alex will still fail because Alex doesn't have permissions on the underlying dataset, the main index.

To enable Alex to run searches using the views in the masked module, Sasha can enable the run as owner feature. As the owner of the module, Sasha is the only user who can add the @run_as_owner; annotation to the module.

When Sasha adds the @run_as_owner; annotation to the module, Alex can run searches using any of the views in the masked module. Alex can only run searches using Sasha's permissions for the views in the maskedmodule.

Alex can't access the underlying datasets. The views access the underlying datasets.

As the owner of the module, Sasha is also the only user who can delete the module.

Steps: Enable run as owner permissions

By default, the run_as_owner feature is turned off. You can enable users, other than the module owner, to run searches using the views in an SPL2 module.

Splunk Cloud Platform

For Splunk Cloud Platform, the run_as_owner_enabled setting cannot be changed by sc_admin users. The run_as_owner feature is not supported in Splunk Cloud Platform.

Splunk Enterprise

To turn on the run_as_owner feature, follow these steps.

Prerequisites

• Only users with file system access, such as system administrators, can turn on the run_as_owner feature.
• Review the steps in How to edit a configuration file in the Admin Manual.

Never change or copy the configuration files in the default directory. The files in the default directory must remain intact and in their original location. Make the changes in the local directory.

Steps

1. Open the local server.conf file for the Search app. For example, $SPLUNK_HOME/etc/apps/<app_name>/local. If a local server.conf file doesn't exist, create the file.
2. Under the [spl2] stanza, set the run_as_owner_enabled to true.
3. For the module you want to add the annotation to, copy or create the module in the local directory of the application.
4. Edit the module in the app local directory and add @run_as_owner; to the first line in the module.
5. Create the searches to mask or filter out the data you don't want users to access.
6. Save the module and re-install the app. See Install SPL2-based apps.
7. Grant the roles execute permission on the module so that the users can run searches using the views in the module.
8. Ensure the users do not have permissions on the underlying dataset, such as an index. The users will see only the data that is filtered by the view that they use in their search.

How permissions change when run as owner is enabled

When a Splunk administrator installs or creates an SPL2-based application, the administrator becomes the owner of the modules in that application. As the module owner, you have execute, read, and write permissions on the module.

When the @run_as_owner; annotation is added to a module, any user with execute permission can run a search using any item exported by the module. Therefore it is important that the only items exported from the module are the masked or filtered views.

If a user imports a module with this annotation and runs a search, then search quotas are also calculated on the owner's behalf.

Modules marked with the @run_as_owner; annotation can import other modules marked with the annotation only if the modules have the same owner. Imported modules can have a different owner as long as the modules are not marked with the @run_as_owner; annotation.

Only the views exported from the module can be run as the owner of the module. Exported functions are run as the user who imported the function.

Limitations of the run as owner feature

• Splunk Cloud Platform: The sc_admin role does not have the ability to change the run_as_owner_enabled setting in the server.conf file. Additionally, there is no REST API endpoint to change this setting.
• Module permissions: The default module permissions assigned to the admin and power roles do not apply to modules that are marked with the @run_as_owner; annotation. For security reasons, only the owner of those modules retains write permission on the modules. When a module owner adds the @run_as_owner; annotation to a module, the data orchestrator adjusts the permissions on the module. Other users who were granted write permission on that module no longer have that permission on that module. This change in permissions is handled internally by the data orchestrator. Calls to the SPL2 REST endpoints still reflect the permissions granted to users before the @run_as_owner; annotation was added to the module.
• Module ownership inheritance: If a Splunk administrator is removed from the system, there is no ownership inheritance on any of the modules that that administrator owns.

The @run_as_owner; annotation can pose security risks or cause data loss if a module uses any risky commands from SPL, or uses the into command in SPL2. If the module owner does not have safeguards enabled, safeguards for risky commands are not applied when a user runs a module as the owner.

For more information about risky commands:

Splunk Cloud Platform

See SPL safeguards for risky commands in the Securing Splunk Cloud Platform manual.

Splunk Enterprise

See SPL safeguards for risky commands in the Securing Splunk Enterprise manual.

See also

• To learn how to install an SPL2-based app, see Install SPL2-based apps.
• To learn how to create an SPL2-based app, see Create a SPL2-based app in the Developer Guide for Splunk Cloud Platform and Splunk Enterprise on the Splunk Developer Portal.