Orbital Scripts API

[Flint]

I'm looking for documentation on using the Orbital API to run Orbital scripts.  I find plenty of documentation on querying the Orbital API, but I'm not finding anything on using the new Orbital scripts feature.  I see some indications that it may be accessible using GraphQL, but I don't see any documentation on it and I haven't been able to locate the GraphQL endpoint for Orbital.

The purpose of this is to eventually add this to an existing SecureX orchestration we have that posts information in a Webex space when a machine is isolated.  I have an Orbital script that splashes a nice notification on an endpoint letting the user know that their PC has been isolated, etc. and this works well, however, I am not able to run the script through orchestration.

Am I missing something obvious?

[Ken Stieers · Accepted solution]

No.

Pretty sure that specific piece hasn't been released yet. The API docs were not ready during the beta, and there were some discussions of tweaking the API some more before releasing it.

[Flint]

Thanks for the info, Ken!

[eugechan · Accepted solution]

Hi Flint (and Ken),

Apologies for the delay while we sorted some technical issues, but we've just recently moved our API documentation to https://developer.cisco.com/docs/orbital/  and also added the documentation for the new Orbital Script APIs there as well. Please take a look!

[Flint]

Thank you, eugechan!

[TomML]

I am a bit confused on the Orbital Script API document.  I am hoping it is like using the Query body syntax where I can give it the name of the Script ("windows_exec_powershell_cmdlets" in this case) along with its arguments.

import requests
import json

url = "https://orbital.amp.cisco.com/v0/script/run"

payload = json.dumps({
  "name": "Execute Powershell Cmdlet",
  "nodes": [
    "amp:235bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  ],
  "expiry": 1715368484,
  "interval": 0,
  "stock": "windows_exec_powershell_cmdlets",
  "stockArgs": {
    "cmdlet": [
      "Get-Date"
    ]
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <token>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

{
    "errors": [
        "access to this feature is not permitted"
    ]
}

 Thanks!

[eugechan]

Hi TomML,

Thanks for the post. 

As a security measure, Orbital scripts are only able to be executed by users and API clients that have the Admin role.

Unfortunately, you cannot modify API clients in SecureX after they have been created, so you will need to generate a new one in order to execute Scripts via API. Please ensure that you have both the "Admin" and "Orbital" options selected when generating the new API client.

Once you have the new API client generated please try your API call again and see if it works!

Reviewing the documentation, I see that this isn't clearly explained, so I'll look to get that added so that others don't encounter the same issue.

[TomML]

Thanks @eugechan ,  I created a new API client with Admin and Orbital options.  I think I am making progress - I'll further review the API documentation.  Appreciate your feedback!

import requests
import json

url = "https://orbital.amp.cisco.com/v0/script/run"
payload = json.dumps({
  "name": "Execute Powershell Cmdlet",
  "nodes": [
    "amp:235bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  ],
  "expiry": 1715642962,
  "interval": 0,
  "stock": "windows_exec_powershell_cmdlets",
  "stockArgs": {
    "cmdlet": [
      "Get-Date"
    ]
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <token>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

{
    "errors": [
        "neither field for scriptContent and catalog_id exists"
    ]
}

I did swap out scriptContent for catalog_id but same error (400 Bad Request).

[TomML]

Nevermind - I got it

import requests
import json

url = "https://orbital.amp.cisco.com/v0/script/run"

payload = json.dumps({
  "name": "Execute Powershell Cmdlet via API",
  "nodes": [
    "amp:235xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  ],
  "expiry": 1715643679,
  "interval": 0,
  "script": {
    "args": [
      {
        "Name": "cmdlet",
        "Value": "Get-Date"
      }
    ],
    "catalog_id": "windows_exec_powershell_cmdlets"
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <token>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)