RocketCyber API PowerShell Wrapper

Celerium_RocketCyberAPI

Buy me a coffee

Whether you use this project, have learned something from it, or just like it, please consider supporting it by buying me a coffee, so I can dedicate more time on open-source projects like this :)

PowerShell Gallery · Report Bug · Request Feature

About The Project

The RocketCyberAPI offers users the ability to extract data from RocketCyber into third-party reporting tools and aims to abstract away the details of interacting with RocketCyber’s API endpoints in such a way that is consistent with PowerShell nomenclature. This gives system administrators and PowerShell developers a convenient and familiar way of using RocketCyber’s API to create documentation scripts, automation, and integrations.

:book: Project documentation can be found on Github Pages
:book: RocketCyber’s REST API documentation here.

RocketCyber features a REST API that makes use of common HTTPs GET actions. In order to maintain PowerShell best practices, only approved verbs are used.

GET -> Get-

Additionally, PowerShell’s verb-noun nomenclature is respected. Each noun is prefixed with RocketCyber in an attempt to prevent naming problems.

For example, one might access the /agent endpoint by running the following PowerShell command with the appropriate parameters:

Get-RocketCyberAgents -id e9487ac5443c1b514f8f2c7ca256bb46

(back to top)

Install

This module can be installed directly from the PowerShell Gallery with the following command:

Install-Module -Name RocketCyberAPI

:information_source: This module supports PowerShell 5.0+ and should work in PowerShell Core.
:information_source: If you are running an older version of PowerShell, or if PowerShellGet is unavailable, you can manually download the main branch and place the RocketCyberAPI folder into the (default) C:\Program Files\WindowsPowerShell\Modules folder.

Project documentation can be found on Github Pages

A full list of functions can be retrieved by running Get-Command -Module RocketCyberAPI.
Help info and a list of parameters can be found by running Get-Help <command name>, such as:

Get-Help Get-RocketCyberAgents
Get-Help Get-RocketCyberAgents -Full

(back to top)

Initial Setup

After installing this module, you will need to configure both the base URI & API key that are used to talk with the RocketCyber API.

Run Add-RocketCyberBaseURI
- By default, RocketCyber’s https://api-us.rocketcyber.com/v3 URI is used.
- If you have your own API gateway or proxy, you may put in your own custom URI by specifying the -base_uri parameter:
  - Add-RocketCyberBaseURI -base_uri http://myapi.gateway.celerium.org
Run Add-RocketCyberAPIKey -Api_Key '12345'
- It will prompt you to enter your API key if you do not specify it.
- RocketCyber API keys are generated via the RocketCyber portal under Provider settings > RocketCyber API
[optional] Run Export-RocketCyberModuleSettings
- This will create a config file at %UserProfile%\RocketCyberAPI that holds the base uri & API key information.
- Next time you run Import-Module -Name RocketCyberAPI, this configuration file will automatically be loaded.
- :warning: Exporting module settings encrypts your API keys in a format that can only be unencrypted by the user principal that encrypted the secret. It makes use of .NET DPAPI, which for Windows uses reversible encrypted tied to your user principal. This means that you cannot copy your configuration file to another computer or user account and expect it to work.
- :warning: However in Linux\Unix operating systems the secret keys are more obfuscated than encrypted so it is recommend to use a more secure & cross-platform storage method.

(back to top)

Usage

Calling an API resource is as simple as running Get-RocketCyber<resourceName>

The following is a table of supported functions and their corresponding API resources:
Table entries with [ - ] indicate that the functionality is NOT supported by the RocketCyber API at this time.

API Resource	Create	Read	Update	Delete
Account	-	`Get-RocketCyberAccounts`	-	-
Agents	-	`Get-RocketCyberAgents`	-	-
Apps	-	`Get-RocketCyberApps`	-	-
Defender	-	`Get-RocketCyberDefender`	-	-
Events	-	`Get-RocketCyberEvents`	-	-
EventSummary	-	`Get-RocketCyberEvents`	-	-
Firewalls	-	`Get-RocketCyberFirewalls`	-	-
Incidents	-	`Get-RocketCyberIncidents`	-	-
Office	-	`Get-RocketCyberOffice`	-	-

Each Get-RocketCyber* function will respond with the raw data that RocketCyber’s API provides.

:warning: Returned data is mostly structured the same but does vary between commands.

(back to top)

Roadmap

Add Changelog
Build more robust Pester & ScriptAnalyzer tests
Add example scripts & automation

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag “enhancement”. Don’t forget to give the project a star! Thanks again!

See the CONTRIBUTING guide for more information about contributing.

(back to top)