@jupiterone/integration-sdk-cli 6.17.0 → 6.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-cli",
-  "version": "6.17.0",
+  "version": "6.21.0",
   "description": "The SDK for developing JupiterOne integrations",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -22,20 +22,23 @@
     "prepack": "yarn build:dist"
   },
   "dependencies": {
-    "@jupiterone/integration-sdk-runtime": "^6.17.0",
+    "@jupiterone/integration-sdk-runtime": "^6.21.0",
     "commander": "^5.0.0",
     "globby": "^11.0.0",
+    "js-yaml": "^4.1.0",
     "json-diff": "^0.5.4",
     "lodash": "^4.17.19",
     "markdown-table": "^2.0.0",
+    "runtypes": "5.1.0",
     "upath": "^1.2.0",
     "vis": "^4.21.0-EOL"
   },
   "devDependencies": {
-    "@jupiterone/integration-sdk-private-test-utils": "^6.17.0",
+    "@jupiterone/integration-sdk-private-test-utils": "^6.21.0",
     "@pollyjs/adapter-node-http": "^4.0.4",
     "@pollyjs/core": "^4.0.4",
     "@pollyjs/persister-fs": "^4.0.4",
+    "@types/js-yaml": "^4.0.3",
     "@types/json-diff": "^0.5.1",
     "@types/lodash": "^4.14.158",
     "@types/pollyjs__adapter-node-http": "^2.0.0",
@@ -45,5 +48,5 @@
     "memfs": "^3.2.0",
     "uuid": "^8.2.0"
   },
-  "gitHead": "4be45cdd8f6bff0740e473ff1f682078fbc1b51a"
+  "gitHead": "ab626f6b32950e50ddcd19a05ff6318cda2e5a2e"
 }

package/src/__tests__/__snapshots__/cli.test.ts.snap

@@ -67,7 +67,7 @@ https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
 
 ### Relationships
 
-The following relationships are created/mapped:
+The following relationships are created:
 
 | Source Entity \`_type\` | Relationship \`_class\` | Target Entity \`_type\` |
 | --------------------- | --------------------- | --------------------- |
@@ -147,7 +147,7 @@ https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
 
 ### Relationships
 
-The following relationships are created/mapped:
+The following relationships are created:
 
 | Source Entity \`_type\` | Relationship \`_class\` | Target Entity \`_type\` |
 | --------------------- | --------------------- | --------------------- |
@@ -194,7 +194,7 @@ The following entities are created:
 
 ### Relationships
 
-The following relationships are created/mapped:
+The following relationships are created:
 
 | Source Entity \`_type\` | Relationship \`_class\` | Target Entity \`_type\` |
 | --------------------- | --------------------- | --------------------- |
@@ -282,7 +282,7 @@ The following entities are created:
 
 ### Relationships
 
-The following relationships are created/mapped:
+The following relationships are created:
 
 | Source Entity \`_type\` | Relationship \`_class\` | Target Entity \`_type\` |
 | --------------------- | --------------------- | --------------------- |
@@ -296,6 +296,53 @@ END OF GENERATED DOCUMENTATION AFTER BELOW MARKER
 <!-- {J1_DOCUMENTATION_MARKER_END} -->"
 `;
 
+exports[`document loads the integration with entity and mapped relationship and writes documentation results 1`] = `
+"# Integration with JupiterOne
+
+## Setup
+
+In this section, please provide details about how to set up the integration with
+JupiterOne. This may require provisioning some resources on the provider's side
+(perhaps a role, app, or api key) and passing information over to JupiterOne.
+
+
+<!-- {J1_DOCUMENTATION_MARKER_START} -->
+<!--
+********************************************************************************
+NOTE: ALL OF THE FOLLOWING DOCUMENTATION IS GENERATED USING THE
+\\"j1-integration document\\" COMMAND. DO NOT EDIT BY HAND! PLEASE SEE THE DEVELOPER
+DOCUMENTATION FOR USAGE INFORMATION:
+
+https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
+********************************************************************************
+-->
+
+## Data Model
+
+### Entities
+
+The following entities are created:
+
+| Resources | Entity \`_type\` | Entity \`_class\` |
+| --------- | -------------- | --------------- |
+| The Group | \`my_group\`     | \`Group\`         |
+
+### Mapped Relationships
+
+The following mapped relationships are created:
+
+| Source Entity \`_type\` | Relationship \`_class\` | Target Entity \`_type\` | Direction |
+| --------------------- | --------------------- | --------------------- | --------- |
+| \`my_group\`            | **HAS**               | \`*your_user*\`         | FORWARD   |
+
+<!--
+********************************************************************************
+END OF GENERATED DOCUMENTATION AFTER BELOW MARKER
+********************************************************************************
+-->
+<!-- {J1_DOCUMENTATION_MARKER_END} -->"
+`;
+
 exports[`document loads the integration without entities and writes documentation results 1`] = `
 "# Integration with JupiterOne
 
@@ -321,7 +368,7 @@ https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
 
 ### Relationships
 
-The following relationships are created/mapped:
+The following relationships are created:
 
 | Source Entity \`_type\` | Relationship \`_class\` | Target Entity \`_type\` |
 | --------------------- | --------------------- | --------------------- |

package/src/__tests__/cli/validate-question-file.test.ts

@@ -0,0 +1,24 @@
+import * as path from 'path';
+import { createCli } from '../..';
+import { getDefaultQuestionFilePath } from '../../commands';
+
+describe('j1-integration validate-question-file --dry-run', () => {
+  test('should validate a provided question file', async () => {
+    await createCli().parseAsync([
+      'node',
+      'j1-integration',
+      'validate-question-file',
+      '--dry-run',
+      '--file-path',
+      path.join(__dirname, '../../questions/__fixtures__/questions/basic.yaml'),
+    ]);
+  });
+});
+
+describe('#getDefaultQuestionFilePath', () => {
+  test('should return expected directory', () => {
+    expect(getDefaultQuestionFilePath()).toEqual(
+      path.join(process.cwd(), './jupiterone/questions/questions.yaml'),
+    );
+  });
+});

package/src/__tests__/cli.test.ts

@@ -443,6 +443,10 @@ describe('document', () => {
     await documentCommandSnapshotTest('docsInstanceRelationshipsAlphabetize');
   });
 
+  test('loads the integration with entity and mapped relationship and writes documentation results', async () => {
+    await documentCommandSnapshotTest('docsInstanceWithMappedRelationships');
+  });
+
   test('should allow passing a file path for the generated documentation', async () => {
     loadProjectStructure('docsInstanceCustomDocLoc');
 

package/src/commands/document.ts

@@ -6,6 +6,7 @@ import {
   StepEntityMetadata,
   StepGraphObjectMetadataProperties,
   StepRelationshipMetadata,
+  StepMappedRelationshipMetadata,
 } from '@jupiterone/integration-sdk-core';
 
 import * as log from '../log';
@@ -142,11 +143,33 @@ function generateRelationshipTableFromAllStepEntityMetadata(
   return generated;
 }
 
+function generateMappedRelationshipTableFromAllStepEntityMetadata(
+  metadata: StepMappedRelationshipMetadata[],
+): string {
+  const generated = table([
+    [
+      'Source Entity `_type`',
+      'Relationship `_class`',
+      'Target Entity `_type`',
+      'Direction',
+    ],
+    ...metadata.map((v) => [
+      `\`${v.sourceType}\``,
+      `**${v._class}**`,
+      `\`*${v.targetType}*\``,
+      `${v.direction}`,
+    ]),
+  ]);
+
+  return generated;
+}
+
 function generateGraphObjectDocumentationFromStepsMetadata(
   metadata: StepGraphObjectMetadataProperties,
 ): string {
   let entitySection = '';
   let relationshipSection = '';
+  let mappedRelationshipSection = '';
 
   if (metadata.entities.length) {
     const generatedEntityTable = generateEntityTableFromAllStepEntityMetadata(
@@ -171,11 +194,25 @@ ${generatedEntityTable}`;
 
 ### Relationships
 
-The following relationships are created/mapped:
+The following relationships are created:
 
 ${generatedRelationshipTable}`;
   }
 
+  if (metadata.mappedRelationships?.length) {
+    const generatedMappedRelationshipTable = generateMappedRelationshipTableFromAllStepEntityMetadata(
+      metadata.mappedRelationships,
+    );
+
+    mappedRelationshipSection += `
+
+### Mapped Relationships
+
+The following mapped relationships are created:
+
+${generatedMappedRelationshipTable}`;
+  }
+
   return `${J1_DOCUMENTATION_MARKER_START}
 <!--
 ********************************************************************************
@@ -187,7 +224,7 @@ https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
 ********************************************************************************
 -->
 
-## Data Model${entitySection}${relationshipSection}
+## Data Model${entitySection}${relationshipSection}${mappedRelationshipSection}
 
 <!--
 ********************************************************************************

package/src/commands/index.ts

@@ -5,3 +5,4 @@ export * from './sync';
 export * from './run';
 export * from './document';
 export * from './visualize-types';
+export * from './validate-question-file';

package/src/commands/validate-question-file.ts

@@ -0,0 +1,82 @@
+import { createCommand } from 'commander';
+import * as log from '../log';
+import { TypesCommandArgs } from '../utils/getSortedJupiterOneTypes';
+import { validateManagedQuestionFile } from '../questions/managedQuestionFileValidator';
+import {
+  ApiClient,
+  createApiClient,
+  getApiBaseUrl,
+} from '@jupiterone/integration-sdk-runtime';
+import * as path from 'path';
+
+interface ValidateQuestionFileCommandArgs extends TypesCommandArgs {
+  filePath: string;
+  jupiteroneAccountId?: string;
+  jupiteroneApiKey?: string;
+  dryRun?: boolean;
+}
+
+export function getDefaultQuestionFilePath() {
+  return path.join(process.cwd(), './jupiterone/questions/questions.yaml');
+}
+
+export function validateQuestionFile() {
+  return createCommand('validate-question-file')
+    .description('validates an integration questions file')
+    .requiredOption(
+      '-p, --file-path <filePath>',
+      'absolute path to managed question file',
+      getDefaultQuestionFilePath(),
+    )
+    .option(
+      '-a, --jupiterone-account-id <jupiteroneAccountId>',
+      'J1 account ID used to validate J1QL queries',
+    )
+    .option(
+      '-k, --jupiterone-api-key <jupiteroneApiKey>',
+      'J1 API key used to validate J1QL queries',
+    )
+    .option(
+      '-d, --dry-run',
+      'skip making HTTP requests to validate J1QL queries',
+    )
+    .action(executeValidateQuestionFileAction);
+}
+
+async function executeValidateQuestionFileAction(
+  options: ValidateQuestionFileCommandArgs,
+): Promise<void> {
+  const { filePath, jupiteroneAccountId, jupiteroneApiKey, dryRun } = options;
+
+  log.info(
+    `\nRunning validate-question-file action (path=${filePath}, accountId=${jupiteroneAccountId}, dryRun=${dryRun})...\n`,
+  );
+
+  let apiClient: ApiClient | undefined;
+
+  if (!dryRun && (!jupiteroneAccountId || !jupiteroneApiKey)) {
+    throw new Error(
+      'Must provide J1 account ID and API key (except for --dry-run)',
+    );
+  } else if (!dryRun && jupiteroneAccountId && jupiteroneApiKey) {
+    apiClient = createApiClient({
+      apiBaseUrl: getApiBaseUrl({
+        dev: !!process.env.JUPITERONE_DEV,
+      }),
+      account: jupiteroneAccountId,
+      accessToken: jupiteroneApiKey,
+    });
+  }
+
+  try {
+    await validateManagedQuestionFile({
+      filePath,
+      apiClient,
+    });
+  } catch (err) {
+    log.error('Failed to validate managed question file!');
+    throw err;
+  }
+
+  log.info('Successfully validated managed question file!');
+}

package/src/index.ts

@@ -8,6 +8,7 @@ import {
   sync,
   visualize,
   visualizeTypes,
+  validateQuestionFile,
 } from './commands';
 
 export function createCli() {
@@ -18,5 +19,6 @@ export function createCli() {
     .addCommand(sync())
     .addCommand(run())
     .addCommand(visualizeTypes())
-    .addCommand(document());
+    .addCommand(document())
+    .addCommand(validateQuestionFile());
 }

package/src/questions/__fixtures__/questions/basic.yaml

@@ -0,0 +1,15 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-disabled-project-services
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Finds all disabled Google Cloud API services in a specified project
+  queries:
+  - query: |
+      FIND google_cloud_api_service WITH projectId = '{{projectId}}' AND enabled = false
+  tags:
+  - google-cloud
+  - service
+  - api

package/src/questions/__fixtures__/questions/compliance.yaml

@@ -0,0 +1,41 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-iam-not-assigned-user-token-roles-project-level
+  title: Ensure that IAM users are not assigned the Service Account User or Service Account Token Creator roles at project level
+  description: >
+    It is recommended to assign the Service Account User (iam.serviceAccountUser)
+    and Service Account Token Creator (iam.serviceAccountTokenCreator) roles to
+    a user for a specific service account rather than assigning the role to a
+    user at project level.
+  queries:
+  - name: good
+    query: |
+      find google_iam_service_account as user
+        that ASSIGNED google_iam_role as role
+        where
+          role.name!="roles/iam.serviceAccountUser" and
+          role.name!="roles/iam.serviceAccountTokenCreator"
+      return
+        user.name,
+        role.name
+  - name: bad
+    query: |
+      find google_iam_service_account as user
+        that ASSIGNED google_iam_role as role
+        where
+          role.name="roles/iam.serviceAccountUser" or
+          role.name="roles/iam.serviceAccountTokenCreator"
+      return
+        user.name,
+        role.name
+  tags:
+  - google-cloud
+  - service-account
+  - access
+  - iam
+  compliance:
+  - standard: CIS Google Cloud Foundations
+    requirements:
+      - '1.6'

package/src/questions/__fixtures__/questions/empty-questions.yaml

@@ -0,0 +1,4 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions: []

package/src/questions/__fixtures__/questions/invalid-yaml.yaml

@@ -0,0 +1,16 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+### The following is invalid!
+questions
+- id: integration-question-google-cloud-disabled-project-services
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Finds all disabled Google Cloud API services in a specified project
+  queries:
+  - query: |
+      FIND google_cloud_api_service WITH projectId = '{{projectId}}' AND enabled = false
+  tags:
+  - google-cloud
+  - service
+  - api

package/src/questions/__fixtures__/questions/multiple-queries.yaml

@@ -0,0 +1,17 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-corporate-login-credentials
+  title: Ensure that corporate login credentials are used
+  description:
+    Use corporate login credentials instead of personal accounts, such as Gmail accounts.
+  queries:
+  - name: good
+    query: find google_user with email $="@{{domain}}"
+  - name: bad
+    query: find google_user with email !$="@{{domain}}"
+  tags:
+  - google-cloud
+  - user
+  - access

package/src/questions/__fixtures__/questions/multiple-questions.yaml

@@ -0,0 +1,27 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-disabled-project-services
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Finds all disabled Google Cloud API services in a specified project
+  queries:
+  - query: |
+      FIND google_cloud_api_service WITH projectId = '{{projectId}}' AND enabled = false
+  tags:
+  - google-cloud
+  - service
+  - api
+
+- id: integration-question-google-cloud-corporate-login-credentials
+  title: Ensure that corporate login credentials are used
+  description:
+    Use corporate login credentials instead of personal accounts, such as Gmail accounts.
+  queries:
+  - query: |
+      FIND google_user WITH email $="@{{domain}}"
+  tags:
+  - google-cloud
+  - user
+  - access

package/src/questions/__fixtures__/questions/non-unique-question-id.yaml

@@ -0,0 +1,28 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-disabled-project-services
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Finds all disabled Google Cloud API services in a specified project
+  queries:
+  - query: |
+      FIND google_cloud_api_service WITH projectId = '{{projectId}}' AND enabled = false
+  tags:
+  - google-cloud
+  - service
+  - api
+
+### NOTE: This ID is _not_ unique and will cause an error to be thrown!
+- id: integration-question-google-cloud-disabled-project-services
+  title: Ensure that corporate login credentials are used
+  description:
+    Use corporate login credentials instead of personal accounts, such as Gmail accounts.
+  queries:
+  - query: |
+      FIND google_user WITH email $="@{{domain}}"
+  tags:
+  - google-cloud
+  - user
+  - access

package/src/questions/__fixtures__/questions/non-unique-question-name.yaml

@@ -0,0 +1,18 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-corporate-login-credentials
+  title: Ensure that corporate login credentials are used
+  description:
+    Use corporate login credentials instead of personal accounts, such as Gmail accounts.
+  queries:
+  - name: good
+    query: find google_user with email $="@{{domain}}"
+  ### NOTE: This name is _not_ unique and will cause an error to be thrown!
+  - name: good
+    query: find google_user with email !$="@{{domain}}"
+  tags:
+  - google-cloud
+  - user
+  - access

package/src/questions/__fixtures__/questions/non-unique-question-tag.yaml

@@ -0,0 +1,17 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-disabled-project-services
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Finds all disabled Google Cloud API services in a specified project
+  queries:
+  - query: |
+      FIND google_cloud_api_service WITH projectId = '{{projectId}}' AND enabled = false
+  tags:
+  - google-cloud
+  - service
+  ### NOTE: This tag is _not_ unique and will cause an error to be thrown!
+  - google-cloud
+  - api

package/src/questions/__fixtures__/questions/non-unique-question-title.yaml

@@ -0,0 +1,28 @@
+---
+sourceId: managed:google_cloud
+integrationDefinitionId: "${integration_definition_id}"
+questions:
+- id: integration-question-google-cloud-disabled-project-services
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Finds all disabled Google Cloud API services in a specified project
+  queries:
+  - query: |
+      FIND google_cloud_api_service WITH projectId = '{{projectId}}' AND enabled = false
+  tags:
+  - google-cloud
+  - service
+  - api
+
+- id: integration-question-google-cloud-corporate-login-credentials
+  ### NOTE: This title is _not_ unique and will cause an error to be thrown!
+  title: Which Google Cloud API services are disabled for my project?
+  description:
+    Use corporate login credentials instead of personal accounts, such as Gmail accounts.
+  queries:
+  - query: |
+      FIND google_user WITH email $="@{{domain}}"
+  tags:
+  - google-cloud
+  - user
+  - access