jupiterone-client-nodejs

A node.js client wrapper and CLI utility for JupiterOne public API.

This is currently an experimental project and subject to change.

Installation

To install the client local to the current project:

npm install @jupiterone/jupiterone-client-nodejs

To install the client globally:

npm install @jupiterone/jupiterone-client-nodejs -g

Using the Node.js client

const { JupiterOneClient } = require('@jupiterone/jupiterone-client-nodejs');

const j1Client = await new JupiterOneClient({
  account: 'my-account-id',
  accessToken: 'my-api-token',
  apiBaseUrl: 'https://api.us.jupiterone.io', // Optional parameter
}).init();
const integrationInstance = await j1Client.integrationInstances.get(
  'my-integration-instance-id',
);

Using the J1 CLI

Usage:

$ j1 --help
Usage: j1 [options]

Options:
  -v, --version             output the version number
  -a, --account <id>        JupiterOne account ID.
  -u, --user <email>        JupiterOne user email.
  -k, --key <apiToken>      JupiterOne API access token.
  -q, --query <j1ql>        Execute a query.
  -o, --operation <action>  Supported operations: create, update, upsert, delete, bulk-delete, provision-alert-rule-pack
  --entity                  Specifies entity operations.
  --relationship            Specifies relationship operations.
  --alert                   Specifies alert rule operations.
  -f, --file <dir>          Input JSON file. Or the filename of the alert rule pack.
  --api-base-url <url>      Optionally specify base URL to use during execution. (defaults to `https://api.us.jupiterone.io`)
  -h, --help                output usage information

Relevant Environment Variables

J1_API_TOKEN - Sets the JupiterOne API access token as environment variable instead of passing it through -k parameter

J1_DEV_ENABLED - Alters the base url. Valid values: 'true' | 'false' (string)

Examples

Run a J1QL query

j1 -a j1dev -q 'Find jupiterone_account'
Validating inputs...
Authenticating with JupiterOne... OK
[
  {
    "id": "06ab12cd-a402-406c-8582-abcdef001122",
    "entity": {
      "_beginOn": 1553777431867,
      "_createdOn": 1553366320704,
      "_deleted": false,
      "displayName": "YCO, Inc.",
      "_type": [
        "jupiterone_account"
      ],
      "_key": "1a2b3c4d-44ce-4a2f-8cd8-99dd88cc77bb",
      "_accountId": "j1dev",
      "_source": "api",
      "_id": "1a2b3c4d-44ce-4a2f-8cd8-99dd88cc77bb",
      "_class": [
        "Account"
      ],
      "_version": 6
    },
    "properties": {
      "emailDomain": "yourcompany.com",
      "phoneNumber": "877-555-4321",
      "webURL": "https://yourcompany.com/",
      "name": "YCO"
    }
  }
]
Done!

Advanced Node Usage

You are able to pass in Apollo Query Options into the queryV1 method. This is beneficial when you need to change how the cache behaves, for example. More information about what data you can provide found here: https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy

To do so:

  // Pass in options like shown below:

  const options = {
    'fetchPolicy': 'network-only'
  }

  j1.queryV1('FIND jupiterone_account', options)

Create or update entities from a JSON input file

j1 -o create --entity -a j1dev -f ./local/entities.json
Validating inputs...
Authenticating with JupiterOne... Authenticated!
Created entity 12345678-fe34-44ee-b3b0-abcdef123456.
Created entity 12345678-e75f-40d6-858e-123456abcdef.
Done!

j1 -o update --entity -a j1dev -f ./local/entities.json
Validating inputs...
Authenticating with JupiterOne... Authenticated!
Updated entity 12345678-fe34-44ee-b3b0-abcdef123456.
Updated entity 12345678-e75f-40d6-858e-123456abcdef.
Done!

NOTE: the create operation will also update an existing entity, if an entity matching the provided Key, Type, and Class already exists in JupiterOne. The update operation will fail unless that entity Id already exists.

The input JSON file is a single entity or an array of entities. For example:

[
  {
    "entityId": "12345678-fe34-44ee-b3b0-abcdef123456",
    "entityKey": "test:entity:1",
    "entityType": "generic_resource",
    "entityClass": "Resource",
    "properties": {
      "name": "Test Entity Resource 1",
      "displayName": "TER1"
    }
  },
  {
    "entityId": "12345678-e75f-40d6-858e-123456abcdef",
    "entityKey": "test:entity:3",
    "entityType": "generic_resource",
    "entityClass": "Resource",
    "properties": {
      "name": "Test Entity Resource 2",
      "displayName": "TER2"
    }
  }
]

The entityId property is only necessary for update operations.

Create or update alert rules from a JSON input file

j1 -o create --alert -a j1dev -f ./local/alerts.json
Validating inputs...
Authenticating with JupiterOne... OK
Created alert rule <uuid>.
Done!

The input JSON file is one or an array of alert rule instances. The following is an example of a single alert rule instance:

{
  "instance": {
    "name": "unencrypted-prod-data",
    "description": "Data stores in production tagged critical and unencrypted",
    "specVersion": 1,
    "pollingInterval": "ONE_DAY",
    "outputs": ["alertLevel"],
    "operations": [
      {
        "when": {
          "type": "FILTER",
          "specVersion": 1,
          "condition": [
            "AND",
            ["queries.unencryptedCriticalData.total", "!=", 0]
          ]
        },
        "actions": [
          {
            "type": "SET_PROPERTY",
            "targetProperty": "alertLevel",
            "targetValue": "CRITICAL"
          },
          {
            "type": "CREATE_ALERT"
          }
        ]
      }
    ],
    "question": {
      "queries": [
        {
          "query": "Find DataStore with (production=true or tag.Production=true) and classification='critical' and encrypted!=true as d return d.tag.AccountName as Account, d.displayName as UnencryptedDataStores, d._type as Type, d.encrypted as Encrypted",
          "version": "v1",
          "name": "unencryptedCriticalData"
        }
      ]
    }
  }
}

Add "id": "<uuid>" property to the instance JSON when updating an alert rule.

Bulk Delete

j1 -q 'Find SomeDataClass with someProp="some value"'
j1 -e -o bulk-delete -f ./results.json

The first CLI command queries data using a J1QL query and saves the data locally to results.json. The second CLI command takes results.json as input and bulk deletes all the entities in the file.

Provision Alert Rules from Rule Pack

The following command will provision all the default alert rules from jupiterone-alert-rules with the rule pack name aws-config:

j1 -a <j1AccountId> -u <j1Username> -o provision-alert-rule-pack --alert -f aws-config

You can specify your own rule pack to provision as well, by specifying the full file path to the rule-pack.json file:

j1 -a <j1AccountId> -u <j1Username> -o provision-alert-rule-pack --alert -f path/to/your/rule-pack.json

For more details about the rules and rule packs, see the jupiterone-alert-rules project.