topic Orbital Scripts API in Integrated Security Platform

Orbital Scripts API

Flint — Wed, 25 Oct 2023 10:48:01 GMT

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?

Re: Orbital Scripts API

Ken Stieers — Wed, 25 Oct 2023 11:39:48 GMT

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.

Re: Orbital Scripts API

Flint — Wed, 25 Oct 2023 11:43:11 GMT

Thanks for the info, Ken!

Re: Orbital Scripts API

eugechan — Tue, 21 Nov 2023 16:16:56 GMT

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!

Re: Orbital Scripts API

Flint — Mon, 27 Nov 2023 10:41:08 GMT

Thank you, eugechan!

Re: Orbital Scripts API

TomML — Fri, 10 May 2024 20:35:36 GMT

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!

Re: Orbital Scripts API

eugechan — Mon, 13 May 2024 16:39:49 GMT

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.

Re: Orbital Scripts API

TomML — Mon, 13 May 2024 23:29:15 GMT

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).

Re: Orbital Scripts API

TomML — Mon, 13 May 2024 23:44:41 GMT

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)