feat(INT-6599): create document permissions script

commands/documentPermissions.ts

@@ -0,0 +1,107 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import { invocationConfig } from '../src';
+import { GoogleCloudIntegrationStep } from '../src/types';
+
+const table = require('markdown-table');
+
+const documentPermissionsCommand = new Command();
+
+interface DocumentCommandArgs {
+  outputFile: string;
+}
+
+const J1_PERMISSIONS_DOCUMENTATION_MARKER_START =
+  '<!-- {J1_PERMISSIONS_DOCUMENTATION_MARKER_START} -->';
+const J1_PERMISSIONS_DOCUMENTATION_MARKER_END =
+  '<!-- {J1_PERMISSIONS_DOCUMENTATION_MARKER_END} -->';
+
+documentPermissionsCommand
+  .command('documentPermissions')
+  .description('Generate GCP permissions list')
+  .option(
+    '-o, --output-file <path>',
+    'project relative path to generated Markdown file',
+    path.join('docs', 'jupiterone.md'),
+  )
+  .action(executeDocumentPermissionsAction);
+
+documentPermissionsCommand.parse();
+
+async function executeDocumentPermissionsAction(options: DocumentCommandArgs) {
+  const { outputFile } = options;
+  const documentationFilePath = path.join(process.cwd(), outputFile);
+  const oldDocumentationFile = await getDocumentationFile(
+    documentationFilePath,
+  );
+
+  const newGeneratedDocumentationSection = getNewDocumentationVersion();
+
+  if (!newGeneratedDocumentationSection) return;
+
+  const newDocumentationFile = replaceBetweenDocumentMarkers(
+    oldDocumentationFile,
+    newGeneratedDocumentationSection,
+  );
+
+  await fs.writeFile(documentationFilePath, newDocumentationFile, {
+    encoding: 'utf-8',
+  });
+}
+
+function getDocumentationFile(documentationFilePath: string): Promise<string> {
+  return fs.readFile(documentationFilePath, {
+    encoding: 'utf-8',
+  });
+}
+
+function getNewDocumentationVersion(): string | undefined {
+  const { integrationSteps } = invocationConfig;
+
+  const permissionsList = integrationSteps.reduce(
+    (accumulatedPermissions, step) => {
+      const googleCloudIntegrationStep = step as GoogleCloudIntegrationStep;
+      return googleCloudIntegrationStep.permissions
+        ? [...accumulatedPermissions, ...googleCloudIntegrationStep.permissions]
+        : accumulatedPermissions;
+    },
+    [] as string[],
+  );
+
+  const tableMarkdown = getTableMarkdown(permissionsList);
+
+  return `${J1_PERMISSIONS_DOCUMENTATION_MARKER_START}\n${tableMarkdown}\n${J1_PERMISSIONS_DOCUMENTATION_MARKER_END}`;
+}
+
+function getTableMarkdown(permissionsList: string[]): string {
+  return table([
+    ['Permissions List'],
+    ...permissionsList.map((permission) => [`\`${permission}\``]),
+  ]);
+}
+
+function replaceBetweenDocumentMarkers(
+  oldDocumentationFile: string,
+  newGeneratedDocumentationSection: string,
+): string {
+  const startIndex = oldDocumentationFile.indexOf(
+    J1_PERMISSIONS_DOCUMENTATION_MARKER_START,
+  );
+
+  if (startIndex === -1) {
+    return `${oldDocumentationFile}\n\n${newGeneratedDocumentationSection}`;
+  }
+
+  const endIndex = oldDocumentationFile.indexOf(
+    J1_PERMISSIONS_DOCUMENTATION_MARKER_END,
+  );
+
+  return (
+    oldDocumentationFile.substring(0, startIndex) +
+    newGeneratedDocumentationSection +
+    oldDocumentationFile.substring(
+      endIndex + J1_PERMISSIONS_DOCUMENTATION_MARKER_END.length,
+    )
+  );
+}

docs/jupiterone.md

@@ -563,3 +563,12 @@ END OF GENERATED DOCUMENTATION AFTER BELOW MARKER
 <!-- {J1_DOCUMENTATION_MARKER_END} -->
 
 <!--  jupiterOneDocVersion=2-15-2-beta-4 -->
+
+#### Google Cloud Specific Permissions List
+
+If you prefer not to use Google managed roles, the following list of specific
+permissions can be used to provision only the required ones:
+
+<!-- {J1_PERMISSIONS_DOCUMENTATION_MARKER_START} -->
+
+<!-- {J1_PERMISSIONS_DOCUMENTATION_MARKER_END} -->

package.json

@@ -29,7 +29,8 @@
     "prepush": "yarn lint && yarn type-check && jest --changedSince main",
     "postversion": "cp package.json ./dist/package.json",
     "tf": "cd terraform && env `grep -v '^#' .env` terraform $1",
-    "create-env-file": "yarn ts-node ./scripts/createEnvFile $1"
+    "create-env-file": "yarn ts-node ./scripts/createEnvFile $1",
+    "document:permissions": " yarn ts-node commands/documentPermissions.ts documentPermissions"
   },
   "peerDependencies": {
     "@jupiterone/integration-sdk-core": "^8.24.1"
@@ -55,7 +56,8 @@
     "gaxios": "^4.2.1",
     "google-auth-library": "^7.1.0",
     "googleapis": "94.0.0",
-    "lodash.get": "^4.4.2"
+    "lodash.get": "^4.4.2",
+    "commander": "^9.4.1"
   },
   "auto": {
     "plugins": [

src/steps/access-context-manager/index.ts

@@ -2,12 +2,14 @@ import {
   createDirectRelationship,
   createMappedRelationship,
   Entity,
-  IntegrationStep,
   JobState,
   RelationshipClass,
   RelationshipDirection,
 } from '@jupiterone/integration-sdk-core';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { AccessContextManagerClient } from './client';
 import {
   STEP_ACCESS_CONTEXT_MANAGER_ACCESS_POLICIES,
@@ -383,7 +385,7 @@ export async function fetchServicePerimeters(
   );
 }
 
-export const accessPoliciesSteps: IntegrationStep<IntegrationConfig>[] = [
+export const accessPoliciesSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_ACCESS_CONTEXT_MANAGER_ACCESS_POLICIES,
     name: 'Access Context Manager Access Policies',

src/steps/api-gateway/index.ts

@@ -1,10 +1,12 @@
 import {
   createDirectRelationship,
-  IntegrationStep,
   RelationshipClass,
 } from '@jupiterone/integration-sdk-core';
 import { apigateway_v1 } from 'googleapis';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { isMemberPublic } from '../../utils/iam';
 import { ApiGatewayClient } from './client';
 import {
@@ -181,7 +183,7 @@ export async function fetchApiGatewayGateways(
   });
 }
 
-export const apiGatewaySteps: IntegrationStep<IntegrationConfig>[] = [
+export const apiGatewaySteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_API_GATEWAY_APIS,
     name: 'Api Gateway APIs',

src/steps/app-engine/index.ts

@@ -4,12 +4,14 @@ import {
   Entity,
   getRawData,
   IntegrationLogger,
-  IntegrationStep,
   RelationshipClass,
   RelationshipDirection,
 } from '@jupiterone/integration-sdk-core';
 import { appengine_v1 } from 'googleapis';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { publishMissingPermissionEvent } from '../../utils/events';
 import { AppEngineClient } from './client';
 import {
@@ -377,7 +379,7 @@ export async function fetchAppEngineVersionInstances(
   );
 }
 
-export const appEngineSteps: IntegrationStep<IntegrationConfig>[] = [
+export const appEngineSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_APP_ENGINE_APPLICATION,
     name: 'AppEngine Application',

src/steps/big-query/index.ts

@@ -1,12 +1,14 @@
 import {
   createDirectRelationship,
   createMappedRelationship,
-  IntegrationStep,
   RelationshipClass,
   RelationshipDirection,
 } from '@jupiterone/integration-sdk-core';
 import { bigquery_v2 } from 'googleapis';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { isMemberPublic } from '../../utils/iam';
 import { getKmsGraphObjectKeyFromKmsKeyName } from '../../utils/kms';
 import { ENTITY_TYPE_KMS_KEY, STEP_CLOUD_KMS_KEYS } from '../kms';
@@ -220,7 +222,7 @@ export async function fetchBigQueryTables(
   );
 }
 
-export const bigQuerySteps: IntegrationStep<IntegrationConfig>[] = [
+export const bigQuerySteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_BIG_QUERY_DATASETS,
     name: 'Big Query Datasets',

src/steps/big-table/index.ts

@@ -1,9 +1,11 @@
 import {
   createDirectRelationship,
-  IntegrationStep,
   RelationshipClass,
 } from '@jupiterone/integration-sdk-core';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { getKmsGraphObjectKeyFromKmsKeyName } from '../../utils/kms';
 import { ENTITY_TYPE_KMS_KEY, STEP_CLOUD_KMS_KEYS } from '../kms';
 import { BigTableClient } from './client';
@@ -219,7 +221,7 @@ export async function fetchTables(
   );
 }
 
-export const bigTableSteps: IntegrationStep<IntegrationConfig>[] = [
+export const bigTableSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_BIG_TABLE_INSTANCES,
     name: 'Bigtable Instances',

src/steps/billing-budgets/index.ts

@@ -1,11 +1,13 @@
 import {
   createDirectRelationship,
   createMappedRelationship,
-  IntegrationStep,
   RelationshipClass,
   RelationshipDirection,
 } from '@jupiterone/integration-sdk-core';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import {
   PROJECT_ENTITY_TYPE,
   STEP_RESOURCE_MANAGER_ORGANIZATION,
@@ -199,7 +201,7 @@ export async function buildAdditionalProjectBudgetRelationships(
   );
 }
 
-export const billingBudgetsSteps: IntegrationStep<IntegrationConfig>[] = [
+export const billingBudgetsSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_BILLING_BUDGETS,
     name: 'Billing Budgets',

src/steps/binary-authorization/index.ts

@@ -1,10 +1,12 @@
 import {
   createDirectRelationship,
-  IntegrationStep,
   RelationshipClass,
 } from '@jupiterone/integration-sdk-core';
 import { binaryauthorization_v1 } from 'googleapis';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import {
   PROJECT_ENTITY_TYPE,
   STEP_RESOURCE_MANAGER_PROJECT,
@@ -72,7 +74,7 @@ export async function fetchBinaryAuthorizationPolicy(
   }
 }
 
-export const binaryAuthorizationSteps: IntegrationStep<IntegrationConfig>[] = [
+export const binaryAuthorizationSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_BINARY_AUTHORIZATION_POLICY,
     name: 'Binary Authorization Policy',

src/steps/cloud-asset/index.ts

@@ -7,7 +7,6 @@ import {
   getRawData,
   IntegrationError,
   IntegrationLogger,
-  IntegrationStep,
   JobState,
   MappedRelationship,
   PrimitiveEntity,
@@ -16,8 +15,10 @@ import {
   RelationshipDirection,
 } from '@jupiterone/integration-sdk-core';
 import { cloudasset_v1, cloudresourcemanager_v3 } from 'googleapis';
-import { IntegrationConfig } from '../..';
-import { IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { publishMissingPermissionEvent } from '../../utils/events';
 import { getProjectIdFromName } from '../../utils/jobState';
 import { IAM_ROLE_ENTITY_CLASS, IAM_ROLE_ENTITY_TYPE } from '../iam';
@@ -792,7 +793,7 @@ export async function createApiServiceToAnyResourceRelationships(
   );
 }
 
-export const cloudAssetSteps: IntegrationStep<IntegrationConfig>[] = [
+export const cloudAssetSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_IAM_BINDINGS,
     name: 'IAM Bindings',

src/steps/cloud-billing/index.ts

@@ -1,5 +1,7 @@
-import { IntegrationStep } from '@jupiterone/integration-sdk-core';
-import { IntegrationConfig, IntegrationStepContext } from '../../types';
+import {
+  GoogleCloudIntegrationStep,
+  IntegrationStepContext,
+} from '../../types';
 import { CloudBillingClient } from './client';
 import {
   STEP_BILLING_ACCOUNTS,
@@ -22,7 +24,7 @@ export async function fetchBillingAccounts(
   });
 }
 
-export const cloudBillingSteps: IntegrationStep<IntegrationConfig>[] = [
+export const cloudBillingSteps: GoogleCloudIntegrationStep[] = [
   {
     id: STEP_BILLING_ACCOUNTS,
     name: 'Billing Accounts',

src/steps/cloud-build/index.ts

@@ -1,5 +1,4 @@
-import { IntegrationStep } from '@jupiterone/integration-sdk-core';
-import { IntegrationConfig } from '../../types';
+import { GoogleCloudIntegrationStep } from '../../types';
 import { buildCloudBuildTriggerTriggersBuildRelationshipsStep } from './steps/build-cloud-build-trigger-triggers-build-relationships';
 import { buildCloudBuildTriggerUsesGithubRepositoryStep } from './steps/build-cloud-build-trigger-uses-github-repo-relationships';
 import { buildCloudBuildUsesSourceRepositoryRelationshipsStep } from './steps/build-cloud-build-uses-source-repo-relationships';
@@ -11,7 +10,7 @@ import { fetchCloudBuildTriggerStep } from './steps/fetch-cloud-build-triggers';
 import { fetchCloudBuildWorkerPoolsStep } from './steps/fetch-cloud-build-worker-pools';
 import { fetchCloudBuildStep } from './steps/fetch-cloud-builds';
 
-export const cloudBuildSteps: IntegrationStep<IntegrationConfig>[] = [
+export const cloudBuildSteps: GoogleCloudIntegrationStep[] = [
   fetchCloudBuildStep,
   fetchCloudBuildTriggerStep,
   fetchCloudBuildWorkerPoolsStep,