Feature Request: Add Scripts and Script Jobs to API

Currently the "Scripts" and "Script Jobs" functionality is only supported when using the SimpleMDM web console via a browser.

• Scripts: https://a.simplemdm.com/admin/scripts
• Script Jobs: https://a.simplemdm.com/admin/script_jobs

With the goal to support custom advanced automation for our machine provisioning processes and integration with other configuration management systems, we need the ability to:

Requirements:

• Create/Update (Upload) and Delete Scripts
  • Support multipart/form-data by default (similar to other SimpleMDM APIs)
• List and Get Scripts, including:
  • Script ID
  • Script name
  • Full script contents
  • Created/Updated timestamps
• Create Script Jobs
• List Script Jobs
• Get Job Status
• Get Job Log / Results / Output

Desirable bells & whistles premium options:

• Query / Filter Script Jobs via Script Jobs List API. Available Filters might include:
  • Script Name
  • Script ID
  • Target ID(s) (Device ID(s), Device Group ID(s), Assignment Group ID(s))
  • Target Type(s) (Devices, Device Groups, Assignment Groups)
  • Created Timestamp
  • Updated/Modified Timestamp
  • Script Status (Pending, Completed, Failed)
• Support Base64 encoding for Script Content when Creating/Updating scripts
• API endpoint to get "raw" (application/octet-stream? Base64 encoded text/plain?) output of the script stdout/stderr Something like: GET https://a.simplemdm.com/api/v1/job/response/{job_id}
  • Currently the web console embeds the Script output as a JSON-escaped field in the "Metadata.job_response" field

Why we need this functionality:

We use SimpleMDM in addition to SaltProject for fleet management. Most of our fleet configuration is driven by Salt, however having the ability to use the native macOS MDM for management and automation will greatly benefit our ability to serve our users. The combination of Scripts (with Attribute Support!) and Jobs could be a game changer --if-- we could programatically interact with it. Some scenarios where this is valuable:

• Initial Device Provisioning: When a new Device is enrolled in SimpleMDM, we want to take additional actions via the "device_enrolled" webhook event with a Script Job to do just-in-time provisioning.
• Device Status Change Events: We already pull all SimpleMDM logs via API. We want to take advantage of

Example scenarios:

1. Upload A Bash Shell Script

Request (POST)
curl https://a.simplemdm.com/api/v1/scripts/ \
-F "[email protected];filename=myscript.sh" \
-F attributesupport=true \
-u {APIKEY}:

2.1. Execute myscript.sh against a single device

Request (POST):
curl https://a.simplemdm.com/api/v1/jobs/ \
-d scriptname=myscript.sh \
-d target={deviceid} \
-d target_type=device

Response:
HTTP/1.1 200
{
"data": {
"type": "job",
"id": "abcde123456",
"attributes": {
"scriptname": "myscript.sh",
"created": "2022-03-03T01:23:45Z",
"createdby": "[email protected]",
"target_type": "device",
"target": "device-id-xxxx1234",
"status": {
"pending": 1,
"completed": 0,
"failed": 0
},
"devices": [
{
"id": "device-id-xxxx1234",
"status": "pending"
}
]
}
}
}

2.2. Execute myscript.sh against a device group

Request (POST)
curl https://a.simplemdm.com/api/v1/jobs/ \
-d scriptname=myscript.sh \
-d target={devicegroupid} \
-d targettype=device_group

1. Get Job Status:

Request:
curl https://a.simplemdm.com/api/v1/job/{JOB_ID} \
-u {API_KEY}

Response:
HTTP/1.1 200
{
"data": {
"type": "job",
"id": "abcde123456",
"attributes": {
"scriptname": "myscript.sh",
"created": "2022-03-03T01:23:45Z",
"createdby": "[email protected]",
"targettype": "device",
"target": "device-id-xxxx1234",
"status: {
"pending": 0,
"completed": 1,
"failed": 0
},
"devices": [
{
"id": "device-id-xxxx1234",
"status": "completed",
"logid": "wxyz0987"
}
]
}
}
}

1. Get Job Output

Request:

curl https://a.simplemdm.com/api/v1/job/log/{LOG_ID} \
-u {API_KEY}

Response:

{
"data": {
"type": "log",
"id": "ec481e3a74a44f588f95bab03f9b76e5",
// ... standard job attributes?
"metadata": {
"name": "myscript.sh",
"job_status": "0",
"stdout": "<<Base64 Encoded stdout>>",
"stderr": "<<Base64 Encoded stderr>>"
}
}
}