Merge pull request #2 from JupiterOne/feature/initial

Initial Signal Science integration

.github/workflows/build.yml

@@ -1,5 +1,5 @@
 name: Build
-on: 
+on:
   pull_request:
   push:
     branches:
@@ -87,6 +87,7 @@ jobs:
           tag_name: ${{ steps.changelog_reader.outputs.version }}
           release_name: Release ${{ steps.changelog_reader.outputs.version }}
           body: ${{ steps.changelog_reader.outputs.changes }}
-          prerelease: ${{ steps.changelog_reader.outputs.status == 'prereleased' }}
+          prerelease:
+            ${{ steps.changelog_reader.outputs.status == 'prereleased' }}
           draft: ${{ steps.changelog_reader.outputs.status == 'unreleased' }}
         continue-on-error: true

.github/workflows/gitleaks.yml

@@ -1,5 +1,5 @@
 name: gitleaks
-on: 
+on:
   pull_request:
   push:
     branches:

.github/workflows/questions.yml

@@ -14,9 +14,9 @@ jobs:
 
       - name: Check out `main` branch
         uses: actions/checkout@v2
-        with: 
+        with:
           path: source
-      
+
       - name: Check out target branch questions
         uses: actions/checkout@v2
         with:
@@ -29,10 +29,12 @@ jobs:
 
       - name: Validate questions on target branch
         env:
-          MANAGED_QUESTIONS_JUPITERONE_ACCOUNT_ID: ${{ secrets.MANAGED_QUESTIONS_JUPITERONE_ACCOUNT_ID }}
-          MANAGED_QUESTIONS_JUPITERONE_API_KEY: ${{ secrets.MANAGED_QUESTIONS_JUPITERONE_API_KEY }}
-        run: yarn --cwd source 
-               j1-integration validate-question-file 
-                 -a $MANAGED_QUESTIONS_JUPITERONE_ACCOUNT_ID 
-                 -k $MANAGED_QUESTIONS_JUPITERONE_API_KEY 
-                 -p ../target/jupiterone/questions/questions.yaml
+          MANAGED_QUESTIONS_JUPITERONE_ACCOUNT_ID:
+            ${{ secrets.MANAGED_QUESTIONS_JUPITERONE_ACCOUNT_ID }}
+          MANAGED_QUESTIONS_JUPITERONE_API_KEY:
+            ${{ secrets.MANAGED_QUESTIONS_JUPITERONE_API_KEY }}
+        run:
+          yarn --cwd source j1-integration validate-question-file -a
+          $MANAGED_QUESTIONS_JUPITERONE_ACCOUNT_ID -k
+          $MANAGED_QUESTIONS_JUPITERONE_API_KEY -p
+          ../target/jupiterone/questions/questions.yaml

CHANGELOG.md

@@ -7,3 +7,6 @@ and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+Initial release of the Signal Sciences integration. Includes ingestion of users
+and corps (organizations).

README.md

@@ -75,9 +75,9 @@ git push --follow-tags -u origin release-<major>.<minor>.<patch>
 merging to main. If any commit is added _after_ the tagged commit, the project
 will not be published to NPM.
 
-**NOTE:** Make sure you select the _Create a merge commit_ option when 
-merging the PR for your release branch. Otherwise the publishing workflow 
-will error out.
+**NOTE:** Make sure you select the _Create a merge commit_ option when merging
+the PR for your release branch. Otherwise the publishing workflow will error
+out.
 
 **TIP:** We recommend updating your global `~/.gitconfig` with the
 `push.followTags = true` property. This will automatically add the

docs/development.md

@@ -1,28 +1,37 @@
 # 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.
+The Signal Science API docs can be found
+[here](https://docs.fastly.com/signalsciences/api/). Additional developer guides
+can be found [here](https://docs.fastly.com/signalsciences/developer/).
 
-## Prerequisites
-
-Supply details about software or tooling (like maybe Docker or Terraform) that
-is needed for development here.
+## Provider account setup
 
-Please supply references to documentation that details how to install those
-dependencies here.
+In order to use the Signal Science API, you will need to have a user account.
+Once invited, click on `My Profile` at the top right of page. Click
+[API Access Tokens](https://dashboard.signalsciences.net/corps/jupiterone/user/apitokens)
+from the drop down.
 
-Tools like Node.js and NPM are already covered in the [README](../README.md) so
-don't bother documenting that here.
+Click
+[Add API access token](https://dashboard.signalsciences.net/corps/jupiterone/user/apitokens#add)
+to add a new token, provide a name to identify this access token.
 
-## Provider account setup
+**Note:** The role of the user will be applied to the access token. Any role is
+sufficient but **Observer** is recommended.
 
-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.
+Copy the access token for use in the next step.
 
 ## 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).
+Here are
+[details](https://docs.fastly.com/signalsciences/developer/using-our-api/) about
+how to authenticate.
+
+In essence, include these two headers in every request:
+
+```
+ x-api-user: email@email.com
+ x-api-token: example-234d2-3ocke-vmeow-bcoiekw
+```
+
+Replacing `email@email.com` with your Signal Science username/email and the
+example token with the value copied from the previous step.

docs/jupiterone.md

@@ -1,35 +1,23 @@
 # Integration with JupiterOne
 
-## {{provider}} + JupiterOne Integration Benefits
+## Signal Sciences + JupiterOne 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 Signal Sciences corps and users in the JupiterOne graph.
+- Monitor changes to Signal Sciences users and corps using JupiterOne alerts.
 
 ## 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 users from Signal Sciences 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.
 
 ## Requirements
 
-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 will be used to obtain the API key.
+- JupiterOne requires an API access token. You need access to a user in Signal
+  Sciences that has permissions to create an access token.
 - You must have permission in JupiterOne to install new integrations.
 
 ## Support
@@ -39,42 +27,40 @@ If you need help with this integration, please contact
 
 ## Integration Walkthrough
 
-### In {{provider}}
+### In Signal Sciences
 
-TODO: List specific actions that must be taken in the provider. Remove this
-section when there are no actions to take in the provider.
-
-1. [Generate a REST API key](https://example.com/docs/generating-api-keys)
+1. [Add API access token](https://dashboard.signalsciences.net/corps/jupiterone/user/apitokens#add).
+   The access token generated will have the same role as the logged in user. The
+   role of **Observer** is sufficient for the ingestion of corps and users.
+2. Save the provided token in a secure location. You will need it to configure
+   Signal Sciences in JupiterOne.
 
 ### In JupiterOne
 
-TODO: List specific actions that must be taken in JupiterOne. Many of the
-following steps will be reusable; take care to be sure they remain accurate.
-
 1. From the configuration **Gear Icon**, select **Integrations**.
-2. Scroll to the **{{provider}}** integration tile and click it.
+2. Scroll to the **Signal Sciences** integration tile and click it.
 3. Click the **Add Configuration** button and configure the following settings:
 
-- Enter the **Account Name** by which you'd like to identify this {{provider}}
-  account in JupiterOne. Ingested entities will have this value stored in
-  `tag.AccountName` when **Tag with Account Name** is checked.
+- Enter the **Account Name** by which you'd like to identify this Signal
+  Sciences account in JupiterOne. Ingested entities will have this value stored
+  in `tag.AccountName` when **Tag with Account Name** is checked.
 - Enter a **Description** that will further assist your team when identifying
   the integration instance.
 - Select a **Polling Interval** that you feel is sufficient for your monitoring
   needs. You may 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 **Signal Sciences user** to be used by JupiterOne. This is most like
+  the email associated with the account that was used to generate the API access
+  token.
+- Enter the **Signal Sciences API access token** generated for use by
+  JupiterOne. This was created within the Signal Sciences web app in a previous
+  step (see above).
 
 4. Click **Create Configuration** once all values are provided.
 
 # 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 configuration **Gear Icon**, select **Integrations**.
-2. Scroll to the **{{provider}}** integration tile and click it.
+2. Scroll to the **Signal Sciences** integration tile and click it.
 3. Identify and click the **integration to delete**.
 4. Click the **trash can** icon.
 5. Click the **Remove** button to delete the integration.
@@ -96,21 +82,18 @@ 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` |
+| ------------ | -------------- | --------------- |
+| Organization | `sigsci_corp`  | `Organization`  |
+| User         | `sigsci_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`           |
+| `sigsci_corp`         | **HAS**               | `sigsci_user`         |
 
 <!--
 ********************************************************************************

docs/spec/src/index.ts

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

docs/spec/src/organization/index.ts

@@ -0,0 +1,22 @@
+import { StepSpec } from '@jupiterone/integration-sdk-core';
+import { IntegrationConfig } from '../../../../src/config';
+
+export const organizationSpec: StepSpec<IntegrationConfig>[] = [
+  {
+    /**
+     * ENDPOINT: /corps
+     */
+    id: 'fetch-organizations',
+    name: 'Fetch Corps',
+    entities: [
+      {
+        resourceName: 'Organization',
+        _type: 'sigsci_corp',
+        _class: ['Organization'],
+      },
+    ],
+    relationships: [],
+    dependsOn: [],
+    implemented: true,
+  },
+];