INT-6697 - Initial implementation

.env.example

@@ -1,2 +1,3 @@
-CLIENT_ID=
-CLIENT_SECRET=
+BASE_URL=
+LOGIN=
+PASSWORD=

.github/workflows/questions.yml

@@ -24,9 +24,10 @@ jobs:
         with:
           node-version: 14.x
           cache: yarn
+          cache-dependency-path: '**/yarn.lock'
 
       - name: Install dependencies for `main` branch
-        run: yarn install --cwd source --frozen-lockfile
+        run: yarn install --cwd source
 
       - name: Validate questions on target branch
         env:

docs/development.md

@@ -1,28 +1,19 @@
 # Development
 
-Add details here to give a brief overview of how to work with the provider APIs.
-Please reference any SDKs or API docs used to help build the integration here.
-
-## Prerequisites
-
-Supply details about software or tooling (like maybe Docker or Terraform) that
-is needed for development here.
-
-Please supply references to documentation that details how to install those
-dependencies here.
-
-Tools like Node.js and NPM are already covered in the [README](../README.md) so
-don't bother documenting that here.
+This integration was developed primarily using the documentation provided by
+BigID at https://api.bigid.com/. Please reference it for questions specific to
+any of their endpoints.
 
 ## Provider account setup
 
-Please provide information about the steps needed to create an account with a
-provider. Images and references to a provider's documentation is very helpful
-for new developers picking up your work.
+BigID provides a sandbox at https://sandbox.bigid.tools/api/v1/ that can be used
+to test any changes to this integration.
 
 ## Authentication
 
-Supply details here for information on how to authenticate with a provider so
-that developers have an idea of what's needed to hit APIs. It may be useful to
-provide explanations for each value specified in the
-[`IntegrationInstanceConfigFieldMap`](../src/config.ts).
+We currently use session tokens for authentication using username and password
+for the initial authentication. The session lasts for 24 hours, so it should not
+need to be renewed unless we end up with very long running jobs.
+
+Documentation on session token authentication can be found at
+https://api.bigid.com/index-session-tokens.html#post-/sessions

docs/jupiterone.md

@@ -1,35 +1,29 @@
-# {{provider}}
+# BigID
 
 ## Integration Benefits
 
 TODO: Iterate the benefits of ingesting data from the provider into JupiterOne.
 Consider the following examples:
 
-- Visualize {{provider}} services, teams, and users in the JupiterOne graph.
-- Map {{provider}} users to employees in your JupiterOne account.
-- Monitor changes to {{provider}} users using JupiterOne alerts.
+- Visualize BigID data sources, finding objects, and users in the JupiterOne
+  graph.
+- Monitor changes to BigID finding counts per data source.
+- Map data source and finding owners to employees in your JupiterOne account.
 
 ## How it Works
 
-TODO: Iterate significant activities the integration enables. Consider the
-following examples:
-
-- JupiterOne periodically fetches services, teams, and users from {{provider}}
-  to update the graph.
+- JupiterOne periodically fetches data sources, finding objects, and users from
+  BigID to update the graph.
 - Write JupiterOne queries to review and monitor updates to the graph, or
   leverage existing queries.
 - Configure alerts to take action when JupiterOne graph changes, or leverage
   existing alerts.
 
 ## Prerequisites
 
-TODO: Iterate requirements for setting up the integration. Consider the
-following examples:
-
-- {{provider}} supports the OAuth2 Client Credential flow. You must have a
-  Administrator user account.
-- JupiterOne requires a REST API key. You need permission to create a user in
-  {{provider}} that is used to obtain the API key.
+- BigID supports token authentication using user credentials. You must use a
+  user account with access to read data source infomration, finding object
+  metadata, and BigID user data.
 - You must have permission in JupiterOne to install new integrations.
 
 ## Support
@@ -39,44 +33,36 @@ If you need help with this integration, contact
 
 ## How to Use This Integration
 
-### In {{provider}}
-
-TODO: List specific actions that must be taken in the provider. Remove this
-section when there are no actions to take in the provider.
+### In BigID
 
-1. [Generate a REST API key](https://example.com/docs/generating-api-keys)
+1. Identify an existing user or create a new user for use with the integration.
+   A non-administrative role such as Inventory Analyst should have sufficient
+   access.
 
 ### In JupiterOne
 
-TODO: List specific actions that the user must take in JupiterOne. Many of the
-following steps will be reusable; take care to be sure they remain accurate.
-
 1. From the top navigation of the J1 Search homepage, select **Integrations**.
-2. Scroll down to **{{provider}}** and click it.
+2. Scroll down to **BigID** and click it.
 3. Click **Add Configuration** and configure the following settings:
 
-- Enter the account name by which you want to identify this {{provider}} account
-  in JupiterOne. Select **Tag with Account Name** to store this value in
+- Enter the account name by which you want to identify this BigID account in
+  JupiterOne. Select **Tag with Account Name** to store this value in
   `tag.AccountName` of the ingested assets.
 - Enter a description to help your team identify the integration.
 - Select a polling interval that is sufficient for your monitoring requirements.
   You can leave this as `DISABLED` and manually execute the integration.
-- {{additional provider-specific settings}} Enter the {{provider}} API key
-  generated for use by JupiterOne.
+- Enter the BigID URL, username, and password for use by JupiterOne.
 
 4. Click **Create Configuration** after you have entered all the values.
 
 ## How to Uninstall
 
-TODO: List specific actions that must be taken to uninstall the integration.
-Many of the following steps will be reusable; take care to be sure they remain
-accurate.
-
 1. From the top navigation of the J1 Search homepage, select **Integrations**.
-2. Scroll down to **{{provider}}** and click it.
+2. Scroll down to **BigID** and click it.
 3. Identify and click the **integration to delete**.
 4. Click the trash can icon.
 5. Click **Remove** to delete the integration.
+6. In BigID delete any no longer needed user accounts as needed.
 
 <!-- {J1_DOCUMENTATION_MARKER_START} -->
 <!--
@@ -95,21 +81,22 @@ https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
 
 The following entities are created:
 
-| Resources | Entity `_type` | Entity `_class` |
-| --------- | -------------- | --------------- |
-| Account   | `acme_account` | `Account`       |
-| User      | `acme_user`    | `User`          |
-| UserGroup | `acme_group`   | `UserGroup`     |
+| Resources   | Entity `_type`     | Entity `_class`  |
+| ----------- | ------------------ | ---------------- |
+| Account     | `bigid_account`    | `Account`        |
+| Data Source | `bigid_datasource` | `DataCollection` |
+| PII Object  | `bigid_pii_object` | `Record`         |
+| User        | `bigid_user`       | `User`           |
 
 ### Relationships
 
 The following relationships are created:
 
 | Source Entity `_type` | Relationship `_class` | Target Entity `_type` |
 | --------------------- | --------------------- | --------------------- |
-| `acme_account`        | **HAS**               | `acme_group`          |
-| `acme_account`        | **HAS**               | `acme_user`           |
-| `acme_group`          | **HAS**               | `acme_user`           |
+| `bigid_account`       | **HAS**               | `bigid_user`          |
+| `bigid_account`       | **SCANS**             | `bigid_datasource`    |
+| `bigid_datasource`    | **HAS**               | `bigid_pii_object`    |
 
 <!--
 ********************************************************************************

docs/spec/src/account/index.ts

@@ -12,7 +12,7 @@ export const accountSpec: StepSpec<IntegrationConfig>[] = [
     entities: [
       {
         resourceName: 'Account',
-        _type: 'acme_account',
+        _type: 'bigid_account',
         _class: ['Account'],
       },
     ],

docs/spec/src/dataSource/index.ts

@@ -0,0 +1,30 @@
+import { RelationshipClass, StepSpec } from '@jupiterone/integration-sdk-core';
+import { IntegrationConfig } from '../../../../src/config';
+
+export const dataSourceSpec: StepSpec<IntegrationConfig>[] = [
+  {
+    /**
+     * ENDPOINT: https://sandbox.bigid.tools/api/v1/ds-connections
+     * PATTERN: Fetch Entities
+     */
+    id: 'fetch-data-sources',
+    name: 'Fetch Sources',
+    entities: [
+      {
+        resourceName: 'Data Source',
+        _type: 'bigid_datasource',
+        _class: ['DataCollection'],
+      },
+    ],
+    relationships: [
+      {
+        _type: 'bigid_account_scans_datasource',
+        sourceType: 'bigid_account',
+        _class: RelationshipClass.SCANS,
+        targetType: 'bigid_datasource',
+      },
+    ],
+    dependsOn: ['fetch-account'],
+    implemented: true,
+  },
+];

docs/spec/src/findings/index.ts

@@ -0,0 +1,30 @@
+import { RelationshipClass, StepSpec } from '@jupiterone/integration-sdk-core';
+import { IntegrationConfig } from '../../../../src/config';
+
+export const findingSpec: StepSpec<IntegrationConfig>[] = [
+  {
+    /**
+     * ENDPOINT: https://sandbox.bigid.tools/api/v1/piiRecords/objects/file-download/export
+     * PATTERN: Fetch Entities
+     */
+    id: 'fetch-pii-findings',
+    name: 'Fetch Findings',
+    entities: [
+      {
+        resourceName: 'PII Object',
+        _type: 'bigid_pii_object',
+        _class: ['Record'],
+      },
+    ],
+    relationships: [
+      {
+        _type: 'bigid_datasource_has_pii_object',
+        sourceType: 'bigid_datasource',
+        _class: RelationshipClass.HAS,
+        targetType: 'bigid_pii_object',
+      },
+    ],
+    dependsOn: ['fetch-data-sources'],
+    implemented: true,
+  },
+];

docs/spec/src/index.ts

@@ -1,9 +1,16 @@
 import { IntegrationSpecConfig } from '@jupiterone/integration-sdk-core';
 
 import { IntegrationConfig } from '../../../src/config';
-import { accessSpec } from './access';
+import { dataSourceSpec } from './dataSource';
 import { accountSpec } from './account';
+import { findingSpec } from './findings';
+import { userSpec } from './users';
 
 export const invocationConfig: IntegrationSpecConfig<IntegrationConfig> = {
-  integrationSteps: [...accountSpec, ...accessSpec],
+  integrationSteps: [
+    ...accountSpec,
+    ...dataSourceSpec,
+    ...findingSpec,
+    ...userSpec,
+  ],
 };

docs/spec/src/users/index.ts

@@ -0,0 +1,30 @@
+import { RelationshipClass, StepSpec } from '@jupiterone/integration-sdk-core';
+import { IntegrationConfig } from '../../../../src/config';
+
+export const userSpec: StepSpec<IntegrationConfig>[] = [
+  {
+    /**
+     * ENDPOINT: https://sandbox.bigid.tools/api/v1/access-management/users
+     * PATTERN: Fetch Entities
+     */
+    id: 'fetch-users',
+    name: 'Fetch Users',
+    entities: [
+      {
+        resourceName: 'User',
+        _type: 'bigid_user',
+        _class: ['User'],
+      },
+    ],
+    relationships: [
+      {
+        _type: 'bigid_account_has_user',
+        sourceType: 'bigid_account',
+        _class: RelationshipClass.HAS,
+        targetType: 'bigid_user',
+      },
+    ],
+    dependsOn: ['fetch-account'],
+    implemented: true,
+  },
+];