Splunk® Enterprise

Upgrade Readiness

Splunk Enterprise version 7.3 is no longer supported as of October 22, 2021. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

REST API reference for the Splunk Python Upgrade Readiness App

Use the REST API to run scans programmatically on your Splunk platform instance. For more information about how to use the Splunk REST API, see Basic concepts about the Splunk platform REST API in the REST API User Manual.

Authentication and Authorization
To use this REST API, you must have write permissions to the Splunk Platform Upgrade Readiness App.

/services/pura_app_list

https://<host>:<mPort>/services/pura_app_list?type={scan_type}

Lists the apps for a user by the scan type

Usage details
To use this endpoint, you must have permission to see the apps on your instance.

GET

Fetches the list of apps for a user by the scan type.

Request parameters
None.

Returned values

Name Description
200 
{
          "name": <folder_name_of_apps>,
          "label": <user_friendly_name_of_app>,
          "type": <type_of_app>,
          "link": <link_of_app_on_splunkbase>,
          "version": <version_of_app>,
          "app_path": <path_of_installed_application>"
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_app_list?type=splunkbase  -X GET

Response

{
    "name":"conf_editor",
    "label":"Conf Editor",
    "type":"Splunkbase-Dual",
    "link":"https://splunkbase.splunk.com/app/5393/",
    "visible":"ENABLED",
    "version":"0.1.1",
    "app_path":"/opt/splunk/etc/apps/conf_editor"
}

/services/pura_dismiss_app

https://<host>:<mPort>/services/pura_dismiss_app

Dismisses an application path.


Usage details
To use this endpoint, a previous scan must be available for this user.

POST

Writes an entry for a specified app path in the KV store for the user and updates the JSON report accordingly.

Request parameters
None.

Payload

Name Type Description
app String
Required. Folder name of the app containing the file path you want to dismiss.
app_path String
Required. The absolute app path in which the file is present.

Returned values

Name Description
200 
{
		"status": true,
		"message": <success_message>
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_dismiss_file -H 'Content-Type: application/json' -d '{"app": "conf_editor_private", "app_path": "/opt/splunk/etc/apps/conf_editor_private"}'  -X POST

Response

{
    "success": true,
    "message": "App: conf_editor_private successfully registered for dismissing the app for user: admin on host: so1. The periodic notification would skip this dismissed app."
}

/services/pura_export_report

https://<host>:<mPort>/services/pura_export_report?id={scan_id}&format={file_format}&app_name={app_name}&app_path={app_path}

Fetches a JSON or CSV report for a given scan_id and app path.

Usage details
to use this endpoint, a previous scan result must be available, and you must know its scan_id and app_path.

GET

Fetches the JSON or CSV report for a previous scan, given a scan_id.

Request parameters

Name Type Description
id String
Required. The scan id of a completed scan run by this user.
format String
Required. The format of the report.
app_name String
Required. Name of the app (folder name).
app_path String
Required. The absolute path of the installed app.

Returned values

Name Description
200 
{
		"apps": [ <list_of_apps> ],
		"summary": { <dict_of_summary_of_scan> },
		"scan_id": <id_of_the_scan_report>
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}


Example request and JSON response

Request

curl -k -u username:password https://localhost:8089/services/pura_export_report?id=admin_1615290732&format=JSON&app_name="conf_editor_private"&app_path="/opt/splunk/etc/apps/conf_editor_private"  -X GET

Response

{
  "apps": [
    {
      "name": "conf_editor_private",
      "label": "Conf Editor Private",
      "version": "1.0.0",
      "app_path": "/opt/splunk/etc/apps/conf_editor_private",
      "summary": {
        "Passed": 2,
        "Blocker": 0,
        "Warning": 1,
        "Skipped": 0,
        "type": "Private App",
        "app_link": "",
        "dismiss_app": 1,
        "dismiss_app_date": "1614862371",
        "Status": "WARNING"
      },
      "checks": [
        {
          "name": "Python in custom Mako templates",
          "result": "PASSED",
          "messages": [

          ],
          "required_action": "None"
        },
        {
          "description": "Check for the existence of Python scripts, which must be upgraded to be cross-compatible with Python 2 and 3 for the upcoming Splunk Enterprise Python 3 release. ",
          "name": "Python scripts",
          "result": "WARNING",
          "messages": [
            {
              "message_filename": "/opt/splunk/etc/apps/conf_editor_private/bin/report.py",
              "code": [
                "@@ -2,6 +2,7 @@\n import sys\n import requests\n import datetime\n+from io import open\n \n if __name__ == \"__main__\":\n   if len(sys.argv) > 1 and sys.argv[1] == \"--execute\":"
              ],
              "result": "warning",
              "message_line": null,
              "dismissed": 0,
              "message": "@@ -2,6 +2,7 @@\n import sys\n import requests\n import datetime\n+from io import open\n \n if __name__ == \"__main__\":\n   if len(sys.argv) > 1 and sys.argv[1] == \"--execute\":\nFile: /opt/splunk/etc/apps/abuseipdb_0/bin/report.py"
            }
          ],
          "required_action": "Update these Python scripts to be dual-compatible with Python 2 and 3."
        },
        {
          "description": "Splunk Python SDK Check",
          "name": "Splunk Python SDK Check",
          "result": "PASSED",
          "messages": [

          ],
          "required_action": "None"
        }
      ],
      "details": "This app is not compatible with Python 3.",
      "required_action": "Update this app or uninstall it. If you do nothing, the app will fail."
    }
  ],
  "scan_id": "admin_1615290732"
}

/services/pura_scan_deployment

https://<host>:<mPort>/services/pura_scan_deployment

Triggers a new scan of the apps installed on the Splunk Platform instance for which you have at least Read permission.

Usage details
To use this endpoint, a scan must not be running.

POST

Starts a scan and writes progress in KV store

Request parameters
None.

Payload

Name Type Description
apps String Required. List of apps to scan. Obtain this information from the /pura_app_list/ endpoint.
app.name String Required. Name of the app (folder_name).
app.label String Required. User-friendly name of the app.
app.type String Required. Type of the app.
app.link String Link to the app on Splunkbase.
app.version String Version of the app.
app.app_path String Path of the installed app.

Returned values

Name Description
200 
{
		"status": true,
		"message": <success_message>
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_scan_deployment -H 'Content-Type: application/json' -d '{"apps":[{"name": "conf_editor", "type": "Splunkbase-Dual", "label": "Conf Editor", "link": "https://splunkbase.splunk.com/app/5393/", "version": "0.1.1", "app_path": "/opt/splunk/etc/apps/conf_editor"}]} -X POST

Response

{
	"status": true,
	"message": "Scan called"
}

/services/pura_schedule_scan

https://<host>:<mPort>/services/pura_schedule_scan

Schedules a scan at a custom time or at the default time at 1:00 AM daily.

Returns the custom scan details from the KV store if stored.

Usage details
To use this endpoint, you must have permission to see the apps on your instance.

POST

Schedules a scan at the given time interval. By default, if no time is specified, the scan is scheduled for 1:00 AM daily.

Request parameters
None.

Payload

Name Type Description
schedule_scan_type String Required. Type of scan. Accepted values: "custom", "default"
day String Required. Day interval. For example, "2" runs the scan every 2 days.
hours String Required. Hours of the time at which the scan is to be run.
minutes String Required. Minutes of the time at which the scan is to be run.
am_pm String Required. AM or PM
time_offset String Required.The offset of the timezone. For example, "+5:30"

Returned values

Name Description
200 
{
		"status": true,
		"message": "Scan called"
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_schedule_scan -H 'Content-Type: application/json' -d '{"schedule_scan_type": "default"}' -X POST

Response

{
	"status": true,
	"message": "Schedule scan details saved"
}


GET

Returns the scan schedule details saved in the KV store.

Request parameters
None.

Returned values

Name Description
200 
{
          "user": <user>,
          "host": <hostname>,
          "day": <day_interval>,
          "minutes": <minutes_value_in_time>,
          "hours": <hours_value_in_time>,
          "am_pm": <am_or_pm>",
          "schedule_scan_type": <default_or_custom>,
          "timestamp": <timestamp_at_which_details_were_saved>"
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_schedule_scan -X GET

Response

{
"name":"conf_editor",
    "user":"admin",
    "host":"so1",
    "day":"1",
    "hours":"12",
    "minutes":"22",
    "am_pm":"AM"
    "schedule_scan_type": "custom",
    "timestamp": "1615286051",
    "_user": "nobody",
    "_key": "60474f23dbe8a80b2d1c22e0"
}

/services/pura_sendemail

https://<host>:<mPort>/services/pura_sendemail

Email a specific app report to the specified email addresses and app.

Usage details
To use this endpoint, you must complete a scan and correctly configure email details.


POST

Sends the app report as an email to the specified email addresses.

Request parameters
None.

Payload

Name Type Description
app_name String Required. Name of the app (folder name)"
app_path String Required. The absolute path to the application.
subject String Required. The subject of the email.
receiver String Required. A comma-separated list of email addresses to whom the report is to be mailed.
body String Required. Body of the email.

Returned values

Name Description
200 
{
		"status": true,
		"message": "Email sent"
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_sendemail -H 'Content-Type: application/json' -d '{"app_name": "conf_editor_private", "app_path": "/opt/splunk/etc/apps/conf_editor_private", "subject": "Subject of the email", "receiver": "email1@email.com, email2@email.com", "body": "Body of the email"}' -X POST

Response

{
	"status": true,
	"message": "Email sent"
}

/services/pura_read_progress

https://<host>:<mPort>/services/pura_read_progress

Reads current progress for an ongoing or completed scan.

Usage details
To use this endpoint, you must be running a scan or have completed a scan.

GET

Reads current progress of an ongoing scan on the instance from the KV store or fetches the previous scan results for the user.

Request parameters
None.

Returned values

Name Description
200 
{
		"status": <status_of_scan>,
		"message": <message_related_to_status>,
		"progress": <progress_percentage_value>,
		"results": { <dict_of_results_for scan> }
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_read_progress  -X GET

Response when scan is in progress

{
	"message": "1 apps out of 8 scanned. Scanning App: Splunk Add-on Example",
	"progress": 12,
	"results": {},
	"status": "IN_PROGRESS"
}

Response when scan is complete

{
	"status": "COMPMLETE",
	"progress": 100,
	"results": {
		"apps": [
			{
        "name": "conf_editor",
        "label": "Conf Editor",
        "version": "0.1.1",
        "app_path": "/opt/splunk/etc/apps/conf_editor",
        "summary": {
        "Passed": 0,
        "Blocker": 0,
        "Warning": 0,
        "Skipped": 0,
        "Status": "PASSED",
        "type": "Splunkbase-Dual",
        "app_link": "https://splunkbase.splunk.com/app/5393/",
        "dismiss_app": 0,
        "dismiss_app_date": ""
      },
      "details": "This app is compatible with Python 3.",
      "required_action": "None",
      "checks": [
      {
        "description": "Splunk Python SDK Check",
        "name": "Splunk Python SDK Check",
        "result": "success",
        "messages": [

        ]
      }
    ]
  }
],
"summary": {
"splunkbase": 1,
"splunk_supported": 0,
"private": 0,
"public_passed": 1,
"public_blocker": 0,
"public_warning": 0,
"public_unknown": 0,
"private_passed": 0,
"private_blocker": 0,
"private_warning": 0,
"private_unknown": 0,
"scan_completion_time": 1615289038
},
"scan_id": "admin_1615289038"
},
"message": "Deployment scanned successfully for user: admin",
"progress": 100,
"host_name": "so1"
}

/services/pura_cancel_scan

https://<host>:<mPort>/services/pura_cancel_scan

Cancels an ongoing scan for the user on the instance.

Usage details
To use this endpoint, you must be running a scan.

DELETE

Sets canceled flag for the ongoing scan which restricts the scan from writing further progress in the KV store and allows the thread to return.

Request parameters
None.

Returned values

Name Description
200 
{
		"status": COMPLETE,
		"message": <message_for_cancellation>,
		"progress": 100
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_cancel_scan  -X DELETE

Response

{
	"status": "COMPLETE",
	"message": "Scan for user: admin on host: localhost cancelled successfully",
	"progress": 100
}


/services/pura_dismiss_file

https://<host>:<mPort>/services/pura_dismiss_file

Dismisses a file path from the scan report and omits it from future scans.

Usage details
To use this endpoint, a previous scan must be available for this user.

POST

Writes an entry for a specified file path in the KV store for a user and updates the JSON report by removing the file path entry.

Request parameters
None.

Payload

Name Type Description
app String
Required. Folder name of the app containing the file path you want to dismiss.
check String
Required. The name of the check containing the file path you want to dismiss.
file_path String
Required. The file path you want to dismiss.
app_path String
Required. The absolute app path in which the file is present.

Returned values

Name Description
200 
{
		"status": true,
		"message": <success_message>
	}
400, 403, 404, or 500 
{
	"status": false,
	"message": <failure_cause>
}

Example request and response

Request

curl -k -u username:password https://localhost:8089/services/pura_dismiss_file -H 'Content-Type: application/json' -d '{"app": "conf_editor_private", "check": "All Python scripts", "file_path": "/opt/splunk/etc/apps/conf_editor_private/bin/__init__.py", "app_path": "/opt/splunk/etc/apps/conf_editor_private"}'  -X POST

Response

{
    "message": "File: /opt/splunk/etc/apps/conf_editor_private/bin/__init__.py for check: All Python scripts for app: Conf Editor Private successfully registered for dismissing for user: admin on host: cds.local. The fresh scan results would skip this file.",
    "success": true
}
Last modified on 21 January, 2022

This documentation applies to the following versions of Splunk® Enterprise: 7.3.0

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters