Splunk® Platform Upgrade Readiness App

Use the Splunk Platform Upgrade Readiness App

Download manual as PDF

Download topic as PDF

REST API endpoint reference for the Splunk Platform Upgrade Readiness App

Use the REST API to run scans programmatically on your Splunk platform instance.

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

/services/scan_deployment

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

Triggers a new scan of the apps that you have at least Read access to on the Splunk platform instance.

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

GET

Starts a scan and writes progress in KV store

Request parameters
None.

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/scan_deployment -X GET

Response

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

/services/read_progress

https://<host>:<mPort>/services/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/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

{
	"message": "Deployment scanned successfully for user: admin", 
	"progress": 100, 
	"results": {
		"apps": [
			{
            "checks": [
                {
                    "description": "Check for Advanced XML <module> elements. The Module system was\n deprecated in Splunk 6.3 as part of the advanced XML deprecation. See:\n http://docs.splunk.com/Documentation/Splunk/latest/Module",
                    "messages": [],
                    "result": "PASSED",
                    "name": "Advanced XML",
                    "required_action": "No required action."
                },
                {
                    "description": "Detect the existence of CherryPy endpoints. With the upcoming Splunk Python 3 migration,\n Splunkweb will run entirely on Python 3. As custom CherryPy endpoints (AKA custom web controls) run on Splunkweb,\n Python code in custom CherryPy endpoints must be upgraded to be compatible with Python 3.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "Custom CherryPy endpoints",
                    "required_action": "No required action."
                },
                {
                    "description": "Check for the existence of Mako template. Mako template should be compatible with Python 3 in\n the upcoming Splunk Python 3 migration.",
                    "messages": [
                        {
                            "result": "warning",
                            "message_line": null,
                            "message": "With the upcoming Splunk Python 3 migration, Splunk Web will run entirely on Python 3. As custom Mako templates run on Splunk Web, Python code in Mako templates must be upgraded to be compatible with Python 3, and failing to upgrade it may cause breakage. Please ensure your Mako template is compatible with Python 3. If you've finished your upgrade, please disregard this message. File: appserver/static/js/templates/Dialogs/Error.html",
                            "message_filename": "appserver/static/js/templates/Dialogs/Error.html"
                        },
                        {
                            "result": "warning",
                            "message_line": null,
                            "message": "With the upcoming Splunk Python 3 migration, Splunk Web will run entirely on Python 3. As custom Mako templates run on Splunk Web, Python code in Mako templates must be upgraded to be compatible with Python 3, and failing to upgrade it may cause breakage. Please ensure your Mako template is compatible with Python 3. If you've finished your upgrade, please disregard this message. File: appserver/static/js/templates/Models/LoadingMsg.html",
                            "message_filename": "appserver/static/js/templates/Models/LoadingMsg.html"
                        },
                        {
                            "result": "warning",
                            "message_line": null,
                            "message": "With the upcoming Splunk Python 3 migration, Splunk Web will run entirely on Python 3. As custom Mako templates run on Splunk Web, Python code in Mako templates must be upgraded to be compatible with Python 3, and failing to upgrade it may cause breakage. Please ensure your Mako template is compatible with Python 3. If you've finished your upgrade, please disregard this message. File: appserver/templates/base.html",
                            "message_filename": "appserver/templates/base.html"
                        }
                    ],
                    "result": "BLOCKER",
                    "name": "Custom Mako templates",
                    "required_action": "Check to ensure that Mako templates are upgraded to be compatible with Python 3."
                },
                {
                    "description": "Check removed M2Crypto usages.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "M2Crypto module",
                    "required_action": "No required action."
                },
                {
                    "description": "Check reserved filename test.py.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "test.py",
                    "required_action": "No required action."
                },
                {
                    "description": "Check that the 'appServerPorts' property in the web.conf does not contain\n port 0.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "Splunkweb legacy mode",
                    "required_action": "No required action."
                },
                {
                    "description": "Check for existence of Python scripts. All Python scripts must be updated due to the upcoming Splunk Python 3 migration.",
                    "messages": [
                        {
                            "result": "warning",
                            "message_line": "N/A",
                            "message": "The file at path /opt/splunk/etc/apps/TA-example/bin/update_state.py needs to be checked for Splunk Python 3 migration",
                            "message_filename": "/opt/splunk/etc/apps/TA-example/bin/update_state.py"
                        },
                    ],
                    "result": "WARNING",
                    "name": "All Python scripts",
                    "required_action": "Update these Python scripts to be dual-compatible with Python 2 and 3."
                }
            ],
            "summary": {
                "type": "Splunkbase App",
                "Passed": 5,
                "Warning": 1,
                "Blocker": 1,
                "Skipped": 0,
                "checks_passed": 5,
                "checks_review": 2,
                "app_link": "https://splunkbase.splunk.com/app/0000/" 
            		},
           		 "name": "TA-example",
            		"label": "Technology Add-on Example"
       		 }
		], 
		"summary": {
			"splunkbase": 1,
			"splunk_supported": 0,
			"private": 0,
			"passed": 0,
			"review": 1,
			"scan_completion_time": 1565094900
		},
		"scan_id": "admin_1565094900"
	}, 
	"status": "COMPLETE"
}

/services/cancel_scan

https://<host>:<mPort>/services/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/cancel_scan  -X DELETE

Response

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

/services/export_report?id={scan_id}

https://<host>:<mPort>/export_report?id={scan_id}

Fetches a JSON report for a given scan_id.

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

GET

Fetches the JSON 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.

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 response

Request

curl -k -u username:password https://localhost:8089/services/export_report?id=admin_1565094900  -X GET

Response

{
    "apps": [
        {
            "checks": [
                {
                    "description": "Check for Advanced XML <module> elements. The Module system was\n deprecated in Splunk 6.3 as part of the advanced XML deprecation. See:\n http://docs.splunk.com/Documentation/Splunk/latest/Module",
                    "messages": [],
                    "result": "PASSED",
                    "name": "Advanced XML",
                    "required_action": "No required action."
                },
                {
                    "description": "Detect the existence of CherryPy endpoints. With the upcoming Splunk Python 3 migration,\n Splunkweb will run entirely on Python 3. As custom CherryPy endpoints (AKA custom web controls) run on Splunkweb,\n Python code in custom CherryPy endpoints must be upgraded to be compatible with Python 3.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "Custom CherryPy endpoints",
                    "required_action": "No required action."
                },
                {
                    "description": "Check for the existence of Mako template. Mako template should be compatible with Python 3 in\n the upcoming Splunk Python 3 migration.",
                    "messages": [
                        {
                            "result": "warning",
                            "message_line": null,
                            "message": "With the upcoming Splunk Python 3 migration, Splunk Web will run entirely on Python 3. As custom Mako templates run on Splunk Web, Python code in Mako templates must be upgraded to be compatible with Python 3, and failing to upgrade it may cause breakage. Please ensure your Mako template is compatible with Python 3. If you've finished your upgrade, please disregard this message. File: appserver/static/js/templates/Dialogs/Error.html",
                            "message_filename": "appserver/static/js/templates/Dialogs/Error.html"
                        },
                        {
                            "result": "warning",
                            "message_line": null,
                            "message": "With the upcoming Splunk Python 3 migration, Splunk Web will run entirely on Python 3. As custom Mako templates run on Splunk Web, Python code in Mako templates must be upgraded to be compatible with Python 3, and failing to upgrade it may cause breakage. Please ensure your Mako template is compatible with Python 3. If you've finished your upgrade, please disregard this message. File: appserver/static/js/templates/Models/LoadingMsg.html",
                            "message_filename": "appserver/static/js/templates/Models/LoadingMsg.html"
                        },
                        {
                            "result": "warning",
                            "message_line": null,
                            "message": "With the upcoming Splunk Python 3 migration, Splunk Web will run entirely on Python 3. As custom Mako templates run on Splunk Web, Python code in Mako templates must be upgraded to be compatible with Python 3, and failing to upgrade it may cause breakage. Please ensure your Mako template is compatible with Python 3. If you've finished your upgrade, please disregard this message. File: appserver/templates/base.html",
                            "message_filename": "appserver/templates/base.html"
                        }
                    ],
                    "result": "BLOCKER",
                    "name": "Custom Mako templates",
                    "required_action": "Check to ensure that Mako templates are upgraded to be compatible with Python 3."
                },
                {
                    "description": "Check removed M2Crypto usages.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "M2Crypto module",
                    "required_action": "No required action."
                },
                {
                    "description": "Check reserved filename test.py.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "test.py",
                    "required_action": "No required action."
                },
                {
                    "description": "Check that the 'appServerPorts' property in the web.conf does not contain\n port 0.",
                    "messages": [],
                    "result": "PASSED",
                    "name": "Splunkweb legacy mode",
                    "required_action": "No required action."
                },
                {
                    "description": "Check for existence of Python scripts. All Python scripts must be updated due to the upcoming Splunk Python 3 migration.",
                    "messages": [
                        {
                            "result": "warning",
                            "message_line": "N/A",
                            "message": "The file at path /opt/splunk/etc/apps/TA-example/bin/update_state.py needs to be checked for Splunk Python 3 migration",
                            "message_filename": "/opt/splunk/etc/apps/TA-example/bin/update_state.py"
                        },
                    ],
                    "result": "WARNING",
                    "name": "All Python scripts",
                    "required_action": "Update these Python scripts to be dual-compatible with Python 2 and 3."
                }
            ],
            "summary": {
                "type": "Splunkbase App",
                "Passed": 5,
                "Warning": 1,
                "Blocker": 1,
                "Skipped": 0,
                "checks_passed": 5,
                "checks_review": 2,
                "app_link": "https://splunkbase.splunk.com/app/0000/"
                
            },
            "name": "TA-example",
            "label": "Technology Add-on Example"
        }
    ],
    "summary": {
        "splunkbase": 1,
        "splunk_supported": 0,
        "private": 0,
        "passed": 0,
        "review": 1,
        "scan_completion_time": 1565094900
    },
    "scan_id": "admin_1565094900"
}

/services/dismiss_file

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

Dismisses a file path from the scan report and skip 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 the user and update 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. Acceptable values:
Custom Mako templates | Custom CherryPy endpoints | Python scripts
file_path String
Required. The file path you want to dismiss.

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/dismiss_file -H 'Content-Type: application/json' -d '{"app": "TA-example", "check": "All Python scripts", "file_path": "/opt/splunk/etc/apps/TA-example/bin/ta_example/__init__.py"}'  -X POST

Response

{
    "message": "File: /opt/splunk/etc/apps/TA-example/bin/ta_example/__init__.py for check: All Python scripts for app: TA-example successfully registered for dismissing for user: admin on host: cds.local. The fresh scan results would skip this file.",
    "success": true
}
PREVIOUS
Scan a Splunk platform instance with the Splunk Platform Upgrade Readiness App
  NEXT
Release notes for the Splunk Platform Upgrade Readiness App

This documentation applies to the following versions of Splunk® Platform Upgrade Readiness App: 0.1.0, 1.0.0, 2.0.0


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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