Introducing the Stellar Cyber API

Stellar Cyber provides a public API that lets you interact with the product programmatically, allowing you to write your own scripts to retrieve data from the product or create entities within it.

• Stellar Cyber is always adding new public APIs to the product. The Summary of Public APIs, below, shows you the types of information you can retrieve and create.

• Once you are ready to get started working with the API, use the following steps:

  1. Use the information in Configuring API Authentication to create a user with the necessary privileges and an API key.

  2. Use the detailed reference material from the API's swagger.json file to create your own scripts and API calls.

• Refer to the Stellar Cyber Public API Examples for a set of sample scripts and API calls that you can use as inspiration for your own work.

Access to the API is only available using local user accounts. Single-sign on (SSO) users cannot access the API with their SSO credentials.

The API replaces access to port 8889 on the DP.

Creating and Testing Public API Calls

You can create and test sample API calls on your Stellar Cyber Platform by clicking the ? | API Docs option, as shown below:

In response, a new browser tab appears with an interactive Swagger reference pre-populated to use the API on your Stellar Cyber Platform.

Authenticating with the API Test Page

Before you can test sample API calls, you'll need to obtain an API key from the Stellar Cyber user interface and use it to generate a JWT token in the Swagger reference. Then, you can use the generated JWT token to access all other parts of the API (only the /access_token API works with simple API key authentication; everything else requires a JWT token).

For most deployments, only user accounts with a Scope of root and a User Privilege of Super Admin can use the API Reference to test live API calls. The 5.4.1 release also introduces per-user API keys, scoped to a user's RBAC privileges and tenancy as an Early Access Program feature. If this feature is enabled in your deployment, you will see an API Keys tab in the Edit User and User Profile dialog boxes, as illustrated below. If this feature is enabled in your deployment, you can use the keys generated in these dialog boxes to access the endpoints in the API Test Page that are available to your account's RBAC privileges.

Generating an API Key

You generate an API key differently depending on whether per-user API keys are enabled as a Version 5.4.1 Early Access Program feature in your deployment:

• For most deployments, per-user keys will not be enabled in your deployment and the API Keys tab does not appear in the Edit User and User Profile dialog boxes. Use the following procedure to generate an API Key:

  1. Navigate to System | Users.

  2. Locate the user account to perform the API call and select Edit () in its row. You must select a Super Admin user with Root scope.

  3. Locate the API Access item in the dialog box that appears and select Generate New Token.

     The API Access option only appears for accounts with Root scope and Super Admin privileges.

  4. Copy and paste the API key into a text file to store it temporarily.

• If per-user keys are enabled in your 5.4.1 deployment, you will see an API Keys tab in both the Edit User and User Profile dialog boxes and can use either of those tabs to generate the key. The procedure for the Edit User dialog box is as follows:

  1. Navigate to System | Users.

  2. Locate the user account to perform the API call and select Edit () in its row.

     You can select any user account, regardless of its privileges or scope. However, the API endpoints available to the account depend on its RBAC privileges and tenancy.

  3. Click on the API Keys tab.

     

     Keep in mind that if you do not see the API Keys tab, per-user keys are not enabled as part of an Early Access Program and you must use the previous procedure to generate your API key.

  4. Click the Create API Key button to generate a new key for your account.

     The Create API Key button only appears if you are logged in to the account you are editing. You can't create API keys for other user accounts.

  5. Supply a name for your key in the window that appears and click Create. Choose a name that is short and memorable so you can easily identify the purpose of the key in Stellar Cyber displays.

  6. Use the Copy button to copy your API key now and store it somewhere safe. For security reasons, you will not be able to retrieve the key from within Stellar Cyber later on.

     If you do lose or forget your key, you can always revoke it and generate a new one. However, you'll also need to update any scripts that use the old key so that they'll continue to work with the new one.

  7. Click Close once you have copied the key.

Use the API Key in the API Test Page

1. Navigate to ? | API Docs and click the Authorize button at the top right, as illustrated below.

   

2. Locate the basic (http, Basic) fields at the bottom of the Available authorizations dialog box. Enter your username and paste in the API key you copied from the System | Users page in the corresponding fields here.

   

3. Click the Authorize button below the basic fields. You are now logged in using basic authentication, as illustrated below:

   

4. Click the x in the upper right hand corner of the Available authorizations dialog box to close it.

5. Cascade open the Access Token entry in the API Test Page. Then, click Try it out and Execute, as illustrated below:

   

6. In response, the /access_token API endpoint provides us with a JWT access token, as illustrated below. Use the Copy button in the Response body pane to copy the JWT token to the clipboard, as illustrated below.

   You can also copy the JWT token manually by selecting the green portion of the Response body between quotation marks. However, the Copy button is typically more reliable.

   

7. Click the Authorize button at the top right of the API Test Page again.

8. Paste the token you copied from the Response body pane into the jwt (http, Bearer) field and click Authorize, as illustrated below.

   

At this point, you are authorized to the API Test Page using a JWT token and can test out the other endpoints in the API Test Page.

About JWT Token Expiration

Keep in mind that JWT tokens are configured by default to expire ten minutes after they are generated. If this happens while you are using the API Test Page, you may notice that your test calls are no longer working. You can fix this by generating a new JWT token from the /access_token endpoint using the steps in the procedure above. Then, click Authorize, log out of the jwt (http, Bearer) section and log back in with your new JWT token.

Summary of Public APIs

As summarized in the interactive API Reference, Stellar Cyber provides public APIs for the following features:

• Create, delete, edit, and list connectors. You can also edit the checkpoint of a connector – the time from which it pulls data, which is useful in case of data loss.

  When numerous connectors roll back checkpoints during regular operating hours, it can lead to increased resource consumption and potential process interruption due to circuit breakers. Consult with Customer Support for considerations regarding off-peak execution of checkpoint rollback.

• Create, delete, update, and list queries with the /queries endpoint.

  The /queries endpoint is available as part of an Early Access Program and may not be available in your version of the Stellar Cyber Platform. It will be generally available in the 5.5.0 release.

• Add Tenants to a per-tenant ATH rule with the /alert_watchers endpoint.

  The /alert_watchers endpoint is available as part of an Early Access Program and may not be available in your version of the Stellar Cyber Platform. It will be generally available in the 5.5.0 release.

• Get alert types along with their key fields

• Retrieve phonehome logs

• Retrieve privilege profiles so they can be used with create/update user APIs

• Download sensor images

• Retrieve detailed sensor information

• Delete sensors

• Retrieve detailed case information

• Retrieve case observables

• Update case information

• Create cases

• Retrieve information on storage usage

• Retrieve ingestion statistics

• Retrieve information on the configuration and hits of log filters.

• Retrieve user activity logs for Stellar Cyber user accounts.

• Create, delete, update, and list tenants

• Create, Delete, Update, and List Tenant Groups

• Update Tags, Status, and Comments for Events

• Perform an ElasticSearch Query on a Specific Index

• Reset User Passwords

• Add events to the Security Index (bulk or standard)

• Create, Delete, and List Lookup Tables (by Tenant or by All Tenants)

• Create, Delete, and List Reports

• Create, Delete, and List Security Event Filters

• Create, Modify, and Delete Data Analyzer Profiles