Cloud-ready app guidelines for Splunk Cloud Platform
- Cloud-ready app guidelines for Splunk Cloud Platform
- About this document
- App packaging
- Packaging standards
- Directory file constraints
- app.conf standards
- App and knowledge object permissions
- Splunk Enterprise Security and Splunk built app integration
- Configuration
- Allowed configuration files with constraints
- Disallowed configuration files
- Custom configuration files
- Scripting
- Supported languages
- Architecture-specific scripts
- Supported data formats
- Environment variables
- Network communications
- Secrets
- Vulnerabilities
- Dashboards
- Splunk Web
- Python scripts
- App security
- File system restrictions
- Examples
- App package
- app.conf
- default.meta
- server.conf
- Cloud-ready app guidelines for Splunk Cloud Platform revision history
When developing apps for Splunk Cloud Platform, you must follow specific rules for app packaging, configuration, and scripting for compatibility and security. To prepare your app for Splunk Cloud Platform vetting, installation, and self-service updates, ensure that Splunk Cloud Platform apps follow these guidelines. For the latest updates to these guidelines, see the Cloud ready app guidelines for Splunk Cloud Platform revision history.
About this document
This document serves as a guideline to assist Splunk developers with building Splunk apps that are compatible for Splunk Cloud Platform. These guidelines are for informational purposes only, and shall not be incorporated into any contract or other commitment.
App packaging
Apps must adhere to criteria specific to Splunk Cloud Platform for file and directory structure, configuration file standards, naming conventions, and permissions. For general information about app structure, see The directory structure of a Splunk app.
Packaging standards
The general packaging criteria are:
File permissions:
600
File permissions for scripts within the bin directory may be set to
700
Directory permissions:
700
App package permissions:
400
Accepted app package compression formats: .tgz, .tar.gz.
Accepted app package extensions: .tgz, .tar.gz, .spl.
Must not include:
local directory.
metadata/local.meta file.
filename with spaces.
hidden files or directories, for example, files or directory names starting with a period (.).
symlink pointing to files outside the app.
nested archives.
extraneous, OS generated files or directories (for example, .DS_STORE, __MACOSX, thumbs.db).
nested Splunk apps within the app package.
For more information see the App package example.
Directory file constraints
Be aware of the following directory file constraints when structuring your app:
Directory | Requirements |
---|---|
default | - Must only contain allowed .conf files. For more information, see Configuration. |
default/data/models | - Allowed file type: .json. |
default/data/ui | - Allowed file types: .html, .xml. |
default/data/ui/nav | - Must only contain a default.xml file. |
lookups | - Allowed file types: .csv, .csv.gz, .csv.tgz, .kmz. - Allowed file formatted as valid .csv. |
metadata | - Must only contain a default.meta file. |
static | - Allowed file types: .css, .csv, .eot, .gif, .htm, .html, .ico, .jpeg, .jpg, .kmz, .less, .map, .md, .otf, .pdf, .png, .rst, .sass, .scss, .svg, .ttf, .txt, .woff, .woff2, .xcf, .xhtml, .xml. - Allowed file formats: valid ASCII, text or Unicode. - Reserved app icon related filenames: appIcon_2x.png, appIcon.png, appIconAlt_2x.png, appIconAlt.png, appLogo.png, appLogo_2x.png. |
app.conf standards
Every Splunk app package must include a default/app.conf file which maintains the state of the given app in the Splunk platform. This provides a reference for the Splunk Cloud Platform and Splunkbase. For more information, see app.conf example. The following app.conf stanzas and properties are mandatory:
Stanza | Property | Type | Description |
---|---|---|---|
[id] | name | string | - Must be the same as the directory name for the app in $SPLUNK_HOME/etc/apps. - Must be the same as [package]/id . - Must not start with a digit. - Must contain only letters, numbers, period (.), hyphen (-), or underscore (_) characters. - Must not end with a period (.) character. |
[id] | version | string | - Must be the same as [launcher]/version . - Must use three digits formatted as Major.Minor.Revision version numbers for releases. |
[launcher] | version | string | - Must be the same as [id]/version . - Must use three digits formatted as Major.Minor.Revision version numbers for releases. |
[launcher] | description | string | - Limit descriptions to 200 characters or less for user readability. |
[package] | id | string | - Must be the same as the directory for the in $SPLUNK_HOME/etc/apps. - Must be the same as [id]/name . - Must not start with a digit. - Must contain only letters, numbers, period (.), hyphen (-) or underscore (_) characters. - Must not end with a period (.) character. |
[install] | build | integer | - Must be a positive integer. - Must increment this whenever files are updated in appserver/static. - Must change both version and build settings for every new release. - Must be a single integer, unlike version which can be a complex string, such as 1.5.18. |
[triggers] | reload.<conf_file_name> | string | - Must be defined for every custom configuration .conf file that exists in the default directory. - Must not be set to rest_endpoints. |
[ui] | is_visible | boolean | - Must be set to 0 (app is not visible) or 1 (app is visible). |
[ui] | label | string | - Must be between 5 and 80 characters inclusive in length. |
App and knowledge object permissions
The app global access write permissions must include the sc_admin role at a minimum. Set the app global export to none
in the []
stanza and granularly export knowledge objects using the system
(global) level as needed to avoid the app interfering with other apps. For more information, see the default.meta example.
default.meta
Set the following default.meta stanza properties as needed:
Stanza | Property | Type | Description |
---|---|---|---|
[] | access | string | - Global access controls for the app. - Write access must include sc_admin at a minimum. |
[] | export | string | - Must be set to none at a minimum if there is no intent to make all the knowledge objects globally available to all apps. - Follow a granular access control strategy. |
[alert_actions] | export | string | - Can be set to system to make custom alert actions globally accessible to all apps. |
[alerts] | export | string | - Can be set to system to make alerts (saved searches or reports) globally accessible to all apps. |
[collections] | export | string | - Can be set to system to make kvstore collections globally accessible to all apps. |
[commands] | export | string | - Can be set to system to make custom search commands globally accessible to all apps. |
[datamodels] | export | string | - Can be set to system to make data models globally accessible to all apps. |
[eventtypes] | export | string | - Can be set to system to make eventtypes (search-time field) globally accessible to all apps. |
[html] | export | string | - Strongly recommended to set this to none - May be set to system to make HTML dashboards globally accessible to all apps. |
[lookups] | export | string | - Can be set to system to make lookups globally accessible to all apps. - May be required globally if there is an auto-lookup (search-time field) defined within a props/transforms that references a lookup definition. |
[macros] | export | string | - Can be set to system to make search macros globally accessible to all apps. |
[nav/default] | export | string | - Can be set to none to avoid the app navigation bar menu to interfere with other apps. |
[props] | export | string | - Can be set to system to make search-time field extractions globally accessible to all apps. |
[restmap] | export | string | - Can be set to system to make custom rest endpoints globally accessible to all apps. |
[savedsearches] | export | string | - Strongly recommended to set this to none - May be set to system to make saved searches or reports globally accessible to all apps. |
[searchbnf] | export | string | - Can be set to system to make the custom search command’s search assistant globally accessible to all apps. - Only applicable with custom search commands. |
[tags] | export | string | - Can be set to system to make tags (search-time fields) globally accessible to all apps. |
[transforms] | export | string | - Can be set to system to make search-time field extractions globally accessible to all apps. |
[views] | export | string | - Usually, set to none - Can be set to system to make SimpleXML/UDF dashboards globally accessible to all apps. |
[visualizations] | export | string | - Can be set to system to make custom visualizations globally accessible to all apps. |
Splunk Enterprise Security and Splunk built app integration
Apps must follow these rules to integrate with other Splunk built apps.
Naming conventions
To ensure the knowledge objects are imported into the Splunk Enterprise Security (ES) app, the app id must be prefixed with one of the following:
DA-ESS-
,SA-
, orTA-
.The following prefixes are reserved for Splunk built apps:
Splunk_SA_
,Splunk_TA_
, andSplunk_DA-ESS_
.
Configuration
All .conf files must parse cleanly with no duplicate stanzas, no duplicate properties within a stanza, and no trailing whitespaces after continuations. All standard .conf files must not point to files outside of the app or have any [default]
stanza defined. Only custom .conf files and savedsearches.conf can define a [default]
stanza.
Allowed configuration files with constraints
Set the following configuration file properties as needed:
File | Stanza/Property | Description |
---|---|---|
alert_actions.conf | [<alert_name>] alert.execute.cmd | - Must be set to a binary or script in the bin folder. - Path pointer file (*.path) is prohibited. For more information, see Scripting. |
app.conf | n/a | For more information, see app.conf standards and Reload Triggers. |
authentication.conf | [<script>] scriptPath | For more information, see Scripting. |
authentication.conf | [<saml-authSettings-key>] signedAssertion | - SAML stanzas must not turn off the signedAssertion property. |
authentication.conf | [roleMap_<authSettings-key>] [userToRoleMap_<saml-authSettings-key>] | - Roles must not be mapped to Splunk Cloud Platform system roles: admin, splunk-system-role, app-installer, index-manager, internal_ops_admin, and internal_monitoring. |
authorize.conf | [tokens_auth] | - Stanza must not be defined. |
authorize.conf | [role_<roleName>] | - No modifying of global roles. - The app cannot alter the following Splunk system user roles: admin, sc_admin, power, user, ess_admin, ess_analyst, ess_user, itoa_user, itoa_analyst, itoa_team_admin, itoa_admin, app-installer, index-manager, internal_ops_admin, or internal_monitoring. - Creation of new roles must not grant excessive administrative permissions to the user. The following capabilities are not permitted: admin_all_objects, change_authentication. - Creation of new roles must not import the following roles: admin, sc_admin, splunk-system-role, app-installer, index-manager, internal_ops_admin, or internal_monitoring. - No modifying existing roles created by another app. - Leverage a naming convention to uniquely distinguish the roles created for the app. |
authorize.conf | [capability::<capability>] | - Don't modify global capabilities. For the latest list, see the Table of Splunk platform capabilities in the Securing Splunk Cloud Platform manual. - Leverage a naming convention to uniquely distinguish the capabilities created for the app. |
collections.conf | n/a | No constraints. |
commands.conf | [<command_name>] filename | - For more information, see Scripting. |
datamodels.conf | [<datamodel_name>] acceleration | - Property must be set to false . - Data Model Accelerations (DMA) must be disabled by default. If Data Model Acceleration is required, developers must provide directions in documentation for how to accelerate data models from within Splunk Web. |
distsearch.conf | [replicationSettings] concerningReplicatedFileSize | - Must set a value lower than 50 MB. |
eventtypes.conf | n/a | No constraints. |
fields.conf | n/a | No constraints. |
indexes.conf | [<index>] homePath coldPath thawedPath frozenTimePeriodInSecs disabled datatype repFactor | - Only these index properties are allowed. - Must use relative paths that contain $SPLUNK_DB. - All other properties are prohibited. |
indexes.conf | [_audit] [_internal] [_introspection] [_metrics] [_metrics_rollup] [_telemetry] [_thefishbucket] [default] [history] [main] [provider-family:hadoop] [splunklogger] [summary] [volume:_splunk_summaries] | - No modification to the default Splunk indexes stanza. For more information, see Configure and deploy indexes in the Splunk Enterprise Security Installation and Upgrade manual and Overview of ITSI indexes in the Splunk IT Service Intelligence administration manual. |
indexes.conf | [<volume>] homePath coldPath thawedPath | - No volume declaration or reference in indexes.conf. |
inputs.conf | [default] [fifo://] [fschange:<path>] [http] [remote_queue:<name>] [splunktcp] [splunktcptoken://<token name>] [SSL] [tcp://<remote server>:<port>] [udp://<remote server>:<port>] | - The use of these stanzas is prohibited. |
inputs.conf | [monitor://<windows_path>] [script://<windows_path>] [perform://] [MonitorNoHandle://] [WinEventLog://] [admon://] [WinRegMon://] [WinHostMon://] [WinPrintMon://] [WinNetMon://] [powershell2://] [powershell://] | - Windows-related input stanzas are prohibited. |
inputs.conf | [batch://<path>] move_policy = sinkhole | - Must define move_policy = sinkhole when declaring batch inputs. - The file path must match a file in the directory $SPLUNK_HOME/var/spool/splunk/. - The file name must be application specific $SPLUNK_HOME/etc/apps/<my_app>. - The file name must not end with stash or stash_new . |
inputs.conf | [http://<name>] | - Must specify the name in the stanza for HTTP Event Collector (HEC) configurations. |
inputs.conf | [script://<cmd>] | - Must have a corresponding script file in the bin directory for each scripted input. - Must specify the cmd path in the stanza. - The use of a .path file pointer is prohibited. - Must not perform management tasks. For more information, see Scripting. |
inputs.conf | [<modular_input>] | - Must have a corresponding script file in the bin directory for each modular input. - Must define an input spec within README/inputs.conf.spec for every modular input. - Splunkd expects each modular input to print a description of itself in XML to STDOUT. - Must define a modular input scheme in either XML with <scheme> as root, or JSON format. - Must define modular input scheme arguments that match in README/inputs.conf.spec. For more information about arguments, see splunklib.modular input in the Splunk SDK for Python API Reference. - Must not perform management tasks. - For more information, see Scripting. |
macros.conf | [<macro>] definition | - Must not use index=* if defining index macros. It must be specific and managed during app setup. |
metric_alerts.conf | n/a | No constraints. |
multikv.conf | n/a | No constraints. |
props.conf | [<pretrained_sourcetype>] TRANSFORMS-<class> SEDCMD-<class> | - Pretrained source types can only have the host , source or sourcetype metadata modified. For more information, see List of pretrained source types in the Splunk Cloud Platform Getting Data In manual. For more information about TRANSFORMS-<class> , see transforms.conf in the Splunk Enterprise Admin manual. |
props.conf | [<default_sourcetypes>] | - Must not modify or overwrite default sources or source types in system/default/props.conf. |
restmap.conf | [script:<uniqueName>] [admin_external:<uniqueName>] handler handlerfile pythonHandlerPath python.version script scripttype | - Custom REST handler must be written in Python. For more information, see Use the script interface for custom REST endpoints. - Each stanza has a matching handler script within the bin directory. For more information, see Scripting. - Must expose the custom REST endpoints on Splunk Web server port via web.conf. For more information, see web.conf in the Splunk Enterprise Admin manual. |
savedsearches.conf | [<savedsearch_name>] cron_schedule | - Searches cannot be scheduled to run more than 12 times within a period of an hour. - Minimum scheduling interval is set to 5 minutes. |
savedsearches.conf | [<savedsearch_name>] dispatch.earliest_time dispatch.latest_time | - Real-time searches are not allowed. - No use of real-time modifier syntax rt in dispatch.earliest_time and dispatch.latest_time . For more information, see Specify time ranges for real-time searches in the Splunk Enterprise Search Manual. - Must specify dispatch.earliest_time . - Must specify dispatch.latest_time . |
savedsearches.conf | [<savedsearch_name>] search | - The tscollect SPL search command is prohibited. - Must not use index=* . Searches must be specific. |
savedsearches.conf | [default] | - Custom visualizations can define visualization property default values. |
searchbnf.conf | n/a | No constraints. |
server.conf | [shclustering] conf_replication_include .<custom_conf_files> | - Must define a reload trigger for every custom .conf file in the default directory. - Must be set to true for every custom .conf file in the default directory. - All other server.conf stanzas and properties are prohibited unless defined in this table. For more information, see Configuration Replication. |
server.conf | [diag] EXCLUDE-<class> | - Must specify a glob/shell pattern that matches the app only. - All other server.conf stanzas and properties are prohibited unless defined in this table. |
tags.conf | n/a | No constraints. |
transactiontypes.conf | n/a | No constraints. |
transforms.conf | [<lookup_stanza_name>] external_cmd | - The first argument is expected to be a Python script or executable file located in $SPLUNK_HOME/etc/apps/<app_name>/bin. For more information, see Scripting. |
transforms.conf | [<transforms_name]> DEST_KEY | - Pretrained source types can only have the host , source or sourcetype metadata modified. Only the following values are permitted: MetaData:Host , MetaData:Source , MetaData:Sourcetype . For more information, see List of pretrained source types in the Splunk Cloud Platform Getting Data In manual. |
visualizations.conf | n/a | No constraints. |
web.conf | [endpoint:<python_module_name>] [expose:<unique_name>] pattern method | - Must reference a custom REST endpoint within restmap.conf. - Must be set for every custom REST endpoints created within restmap.conf. - All other web.conf stanzas and properties are prohibited unless defined in this table. For more information, see Scripting. |
workflow_actions.conf | [<workflow_action_name>] link.uri | - Must use HTTPS protocol for external links. - Unencrypted HTTP is permitted for internal links. - Must start with: / , http://localhost , http://127.0.0.1 , localhost , 127.0.0.1 , or https:// . For more information, see Network communications. |
Disallowed configuration files
Do not include the following configuration files in your app:
- audit.conf
- bookmarks.conf
- checklist.conf
- crawl.conf
- datatypesbnf.conf
- default-mode.conf
- deployment.conf
- deploymentclient.conf
- eventdiscoverer.conf
- event_renderers.conf
- federated.conf
- global-banner.conf
- health.conf
- instance.conf
- limits.conf
- literals.conf
- messages.conf
- metric_rollups.conf
- outputs.conf
- passwords.conf
- procmon-filters.conf
- pubsub.conf
- segmenters.conf
- serverclass.conf
- serverclass.seed.xml
- splunk-launch.conf
- setup.xml
- source-classifier.conf
- sourcetypes.conf
- splunk-launch.conf
- telemetry.conf
- times.conf
- ui-prefs.conf
- ui-tours.conf
- user-prefs.conf
- user-seed.conf
- viewstates.conf
- wmi.conf
- workload_policy.conf
- workload_pools.conf
- workload_rules.conf
Including any of these disallowed files in your app will result in an automated AppInspect failure during the cloud vetting process.
Custom configuration files
Cloud-ready apps follow these .conf file customization rules.
Reload triggers
All components in the app must be reloadable and are not permitted to require a system-wide restart. If the app includes long-running extensions, such as modular inputs, code your extensions to handle restarts by using checkpoints or similar restart solutions. If the app uses custom .conf files, use the app.conf [triggers]
stanza to specify the simple
setting or an access_endpoint
handler to control updates. For more information, see app.conf standards and the app.conf example.
Configuration replication
All custom .conf files must be replicated within a search head cluster. This must be defined in default/server.conf as follows:
Stanza | Property | Type | Description |
---|---|---|---|
[shclustering] | conf_replication_include.<conf_file_name> | boolean | - Must be defined for every custom .conf file in the default directory - Must be set to true for every custom .conf file in the default directory |
For more information, see the server.conf example.
Scripting
For apps to be Cloud-ready, all scripts and code must adhere to specific rules for languages, data formats, and security constraints. Splunk Cloud Platform also requires specific rules for apps implementing dashboard and Splunk Web features.
The following Cloud Ready app guidelines for Splunk Cloud Platform apply to all app scripts.
Supported languages
The following languages are supported:
- Bash.
- CSS.
- HTML.
- Java.
- JavaScript.
- Python.
- Shell.
Architecture-specific scripts
Scripts must be built for Linux x86_64 architecture.
Supported data formats
The following data formats are supported:
- JSON.
- XML.
Environment variables
$SPLUNK_HOME can only be read, not modified, and your app must not manipulate OS environment variables.
Network communications
You must secure and encrypt all outgoing communication over HTTPS/TCP 443.
Do not complete any of the following actions due to security concerns:
UDP communication.
Insecure HTTP calls.
Communicate with the Splunk Cloud Metadata API (for example,
http://169.254.169.254
).
Secrets
Secrets may be stored using the Splunk storage/passwords endpoint. For more information, see storage/passwords in the REST API Reference Manual.
Apps must not:
Store secrets in plaintext files.
Log secrets or sensitive data.
Use weak cryptographic functions.
Vulnerabilities
Apps must not:
Access files or directories outside of the app directory.
Use stored or reflected cross-site scripting (XSS).
Use remote code execution.
Use destructive shell commands.
Use reverse shells.
Use root privilege escalation.
Unmarshal data from untrusted sources.
If your app fails to comply with these security policies, your app will fail the cloud vetting process and cannot be installed in Splunk Cloud Platform.
Dashboards
Use version 1.1 or higher Simple XML dashboards. For more information, see Editing Simple XML in the Splunk Enterprise Dashboards and Visualizations manual.
To specify version 1.1:
<dashboard version="1.1" script="myCustomJS.js"> ... </dashboard> <form version="1.1" script="myCustomJS.js"> ... </form>
Splunk Web
For Splunk Web apps, include all web dependencies in the appserver directory
Splunk Web apps must not:
Contain inline frames (iframes).
Import Splunk Web files directly.
Collect, use or send telemetry data.
Python scripts
Use Python version 3.6 or later, and Python scripts must use import
rather than the __import__
method.
Python scripts must not:
Use built in functions
open
,eval
,execfile
, orfile
.Include .pyc or .pyo compiled files in the app package.
Use a custom Python interpreter.
Manipulate system Python objects.
App security
Apps for Splunk Enterprise are highly portable to Splunk Cloud Platform, and introduce the same security concerns around confidentiality, integrity, and availability to Splunk Cloud Platform. These concerns can apply a much larger scale on Splunk Cloud Platform, and these risks are addressed but not eliminated in the Splunk General Terms for Third Party Products, Third-Party Extensions, Third-Party Content and Unsupported Splunk Extensions. For more information about portability and vetting, see Vet apps and add ons for Splunk Cloud Platform.
On Splunk Cloud Platform, your apps must follow specific constraints to read or write safely to directories and files.
File system restrictions
Apps and their respective extension points, including modular inputs, custom search commands, modular alerts, REST handlers, and so on, run in their own namespace on Splunk Cloud Platform. That namespace has access to specific paths of the file system and operates under the following constraints. Beyond the following exceptions, apps do not have access to the underlying file system.
Access | Description |
---|---|
No access | Apps have read-only access to the $SPLUNK_HOME directory, with the following exceptions: - $SPLUNK_HOME/etc/{passwd,opasswd,auth,users}. No access to these paths as they contain sensitive information. - No access to user-specific .conf files. Configuration should be done using the Splunk REST API. |
Write | Apps can generate diagnostic log in the following directories, which are also provided by the Splunk Enterprise SDK for Python: - $SPLUNK_HOME/var/log/splunk/<appName>/<logName>.log - $SPLUNK_HOME/var/log/splunk/<appName>.log Apps can write to their own app directories: - $SPLUNK_HOME/etc/<appName>/local - SPLUNK_HOME/etc/<appName>/lookup |
Read and write | Apps have restricted shared access to Splunk software and OS temporary file systems: - /tmp - $SPLUNK_HOME/var/run for Splunk-specific artifacts |
Read-only | Binary and library directories. Linux binary and library directories (such as /bin, /sbin, /usr/ and so on) are mounted read-only for apps if necessary. However, there are no guarantees that specific OS libraries are present for your use case in Splunk Cloud Platform. |
Examples
Follow these examples for Splunk Cloud Platform app directory structure, configuration, and metadata.
App package
Use the following directory structure for your app when developing for Splunk Cloud Platform:
my_app-1.0.0.tar.gz └── my_app ├── appserver │ └── static │ ├── myjavascript.js │ └── mystyle.css ├── bin │ └── mycustommodinput.py
...
app.conf
The following example shows the configuration for a simple Splunk Cloud Platform app:
[id] name = hello_world version = 1.0.0 [launcher] version = 1.0.0 description = This is a Splunk app that displays the message Hello World! author = my-splunk-dot-com@username.com
...
default.meta
The following example shows how to set up default metadata for a Splunk Cloud Platform app:
[] access = read : [ * ], write : [ sc_admin, power ] export = none [alert_actions] export = system [eventtypes]
...
server.conf
The following example shows how to enable the replication of a custom configuration file foo.conf within a search head cluster:
[shclustering] conf_replication_include.foo = true
Cloud-ready app guidelines for Splunk Cloud Platform revision history
Updates to the Cloud-ready app guidelines for Splunk Cloud Platform are tracked here:
Version | Date | Description |
---|---|---|
1.1 | 10/01/2021 | App security and File system restrictions. |
1.0 | 09/07/2021 | Initial release focusing on current state. |
For questions about the content of this document, contact devinfo@splunk.com.