@ampsec/platform-client 47.2.0 → 47.4.0

package/src/services/entity.service.ts

@@ -1,9 +1,12 @@
 import _ from 'lodash';
-import {BaseDto, BaseUpsertDto, ExtKeyMap, Page} from '../dto';
-import {TargetApi, TARGET_API_AGENT, ErrorHandler} from './constants';
+import {AssetIdDto, BaseDto, BaseUpsertDto, ExtKeyMap, Page, PlatformAssetDto, PlatformAssetUpsertDto, PlatformUserDto, PlatformUserUpsertDto, UserIdDto} from '../dto';
+import {TargetApi, TARGET_API_AGENT, ErrorHandler, KIND} from './constants';
 import {AmpDataService, AmpDataServiceImpl} from './data.service';
 import {RestClient, RestRequest} from './rest';
 import {QueryMap} from './rest/utils';
+import {AssetLookupService, UserLookupService} from './lookup.service';
+
+const LOOKUP_ID_PAGE_SIZE = 50;
 
 export type EntityCallOptions = {
   params: unknown;
@@ -20,18 +23,13 @@ export interface AmpSdkTenantService<WriteT extends BaseUpsertDto, ReadT extends
   update(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
   delete(_id: string, _options?: EntityCallOptions): Promise<Page<ReadT>>;
 }
+
 export interface AmpGlobalEntityService<WriteT extends BaseUpsertDto, ReadT extends BaseDto> extends AmpDataService<ReadT> {
   create(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
   update(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
   delete(_id: string, _options?: EntityCallOptions): Promise<Page<ReadT>>;
   getLookupIds(_tid: string, _options?: EntityCallOptions): Promise<ExtKeyMap>;
 }
-export interface AmpSaaSEntityService<WriteT extends BaseUpsertDto, ReadT extends BaseDto> extends AmpDataService<ReadT> {
-  create(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
-  update(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
-  delete(_id: string, _options?: EntityCallOptions): Promise<Page<ReadT>>;
-  getLookupIds(_cid: string, _options?: EntityCallOptions): Promise<ExtKeyMap>;
-}
 
 export class AmpEntityServiceImpl<WriteT extends BaseUpsertDto, ReadT extends BaseDto> extends AmpDataServiceImpl<ReadT> implements AmpEntityService<WriteT, ReadT> {
   constructor(rest: RestClient, kind: string, targetApi: TargetApi = TARGET_API_AGENT) {
@@ -93,6 +91,8 @@ export class AmpGlobalEntityServiceImpl<WriteT extends BaseUpsertDto, ReadT exte
   constructor(rest: RestClient, kind: string, targetApi: TargetApi = TARGET_API_AGENT) {
     super(rest, kind, targetApi);
   }
+
+  /** @deprecated */
   getLookupIds = (tid: string, options?: EntityCallOptions): Promise<ExtKeyMap> => {
     const req: RestRequest = {
       url: `/${this.targetApi}/v1/${this.kind}/ext_key_map`,
@@ -106,22 +106,85 @@ export class AmpGlobalEntityServiceImpl<WriteT extends BaseUpsertDto, ReadT exte
   };
 }
 
-export class AmpSaaSEntityServiceImpl<WriteT extends BaseUpsertDto, ReadT extends BaseDto>
-  extends AmpEntityServiceImpl<WriteT, ReadT>
-  implements AmpSaaSEntityService<WriteT, ReadT>
-{
-  constructor(rest: RestClient, kind: string, targetApi: TargetApi = TARGET_API_AGENT) {
-    super(rest, kind, targetApi);
+const errorHandler = (error: unknown) => {
+  if (error instanceof Error) {
+    console.error(error.message);
   }
-  getLookupIds = (cid: string, options?: EntityCallOptions): Promise<ExtKeyMap> => {
-    const req: RestRequest = {
-      url: `/${this.targetApi}/v1/${this.kind}/ext_key_map`,
-      method: 'GET',
-      params: {
-        ...((options?.params as QueryMap) ?? {}),
-        cid,
-      },
-    };
-    return this.call(req, extIdMapErrorHandler);
+  throw error;
+};
+
+export class AmpSdkUserService extends AmpGlobalEntityServiceImpl<PlatformUserUpsertDto, PlatformUserDto> {
+  constructor(rest: RestClient, targetApi: TargetApi = TARGET_API_AGENT) {
+    super(rest, KIND.USERS, targetApi);
+  }
+
+  getLookup = async (tid: string, options?: EntityCallOptions): Promise<UserLookupService> => {
+    const lookup = new UserLookupService();
+    return this.refreshLookup(lookup, tid, options);
+  };
+
+  refreshLookup = async (lookup: UserLookupService, tid: string, options?: EntityCallOptions): Promise<UserLookupService> => {
+    const limit = LOOKUP_ID_PAGE_SIZE;
+    let offset = 0;
+    let hasMore = true;
+    if (!options) {
+      options = {params: {}};
+    }
+    _.set(options, 'params.updatedAt', {$gt: lookup.getLastUpdated()});
+    while (hasMore) {
+      const req: RestRequest = {
+        url: `/${this.targetApi}/v1/${this.kind}/id_summary`,
+        method: 'GET',
+        params: {
+          ...((options?.params as QueryMap) ?? {}),
+          tid,
+          limit,
+          offset,
+        },
+      };
+      const page = await this.call(req, errorHandler as ErrorHandler<Page<UserIdDto>>);
+      page.data.forEach(ids => lookup.add(ids));
+      offset = (page.hints.offset ?? offset) + limit;
+      hasMore = page.hints.hasMore ?? false;
+    }
+    return lookup;
+  };
+}
+
+export class AmpSdkAssetService extends AmpGlobalEntityServiceImpl<PlatformAssetUpsertDto, PlatformAssetDto> {
+  constructor(rest: RestClient, targetApi: TargetApi = TARGET_API_AGENT) {
+    super(rest, KIND.ASSETS, targetApi);
+  }
+
+  getLookup = async (tid: string, options?: EntityCallOptions): Promise<AssetLookupService> => {
+    const lookup = new AssetLookupService();
+    return this.refreshLookup(lookup, tid, options);
+  };
+
+  refreshLookup = async (lookup: AssetLookupService, tid: string, options?: EntityCallOptions): Promise<AssetLookupService> => {
+    const limit = LOOKUP_ID_PAGE_SIZE;
+    let offset = 0;
+    let hasMore = true;
+    if (!options) {
+      options = {params: {}};
+    }
+    _.set(options, 'params.updatedAt', {$gt: lookup.getLastUpdated()});
+    while (hasMore) {
+      const req: RestRequest = {
+        url: `/${this.targetApi}/v1/${this.kind}/id_summary`,
+        method: 'GET',
+        params: {
+          ...((options?.params as QueryMap) ?? {}),
+          tid,
+          limit,
+          offset,
+        },
+      };
+      const page = await this.call(req, errorHandler as ErrorHandler<Page<AssetIdDto>>);
+      page.data.forEach(ids => lookup.add(ids));
+      offset = (page.hints.offset ?? offset) + limit;
+      hasMore = page.hints.hasMore ?? false;
+    }
+    return lookup;
   };
 }

package/src/services/index.ts

@@ -5,5 +5,8 @@ export * from './constants';
 export * from './data.service';
 export * from './entity.service';
 export * from './findings.service';
+export * from './lookup.service';
 export * from './rest';
+export * from './saasEntity.service';
 export * from './settings.service';
+export * from './utils';

package/src/services/lookup.service.ts

@@ -0,0 +1,176 @@
+import _ from 'lodash';
+import {AssetIdDto, AssetKeys, RawUserIds, SaasComponentIdDto, UserIdDto} from '../dto';
+import {formatMacAddress} from './utils';
+
+export class UserLookupService {
+  private readonly emailLookupMap = new Map<string, UserIdDto>();
+  private readonly extIdLookupMap = new Map<string, UserIdDto>();
+  private lastUpdated = new Date('2023-04-17T13:00:00.000Z');
+
+  getLastUpdated(): string {
+    return this.lastUpdated.toISOString();
+  }
+
+  // TODO throw errors if conflicts are found
+  /**
+   * Emails are normalized to lower case but external IDs are case sensitive
+   */
+  add(user: UserIdDto) {
+    user.emails.forEach(email => this.emailLookupMap.set(email.toLowerCase(), user));
+    if (user.extId) {
+      this.extIdLookupMap.set(user.extId, user);
+    }
+    this.lastUpdated = new Date();
+  }
+
+  // TODO throw errors if conflicts are found
+  /**
+   * Calls through to `byEmails` and `byExtId`
+   */
+  lookup(userIds?: RawUserIds): UserIdDto[] {
+    if (!userIds) {
+      return [];
+    }
+    const matches = [] as UserIdDto[];
+    const emails = [];
+    if (userIds.primaryEmail) {
+      emails.push(userIds.primaryEmail);
+    }
+    if (Array.isArray(userIds.emails)) {
+      emails.push(...userIds.emails);
+    }
+    matches.push(...this.byEmails(emails));
+    if (userIds.extId) {
+      const match = this.byExtId(userIds.extId);
+      if (match) {
+        matches.push(match);
+      }
+    }
+    return _.uniqBy(matches, 'id');
+  }
+
+  /**
+   * Emails are normalized to lower case
+   */
+  byEmails(emails: string[]): UserIdDto[] {
+    const matches = [] as UserIdDto[];
+    if (!Array.isArray(emails)) {
+      emails = [emails];
+    }
+
+    emails = _.uniq(emails);
+
+    for (const email of emails) {
+      const match = this.emailLookupMap.get(email.toLocaleLowerCase());
+      if (match) {
+        matches.push(match);
+      }
+    }
+    return _.uniqBy(matches, 'id');
+  }
+  /**
+   * Emails are normalized to lower case
+   */
+  byEmail(email: string): UserIdDto | undefined {
+    return this.emailLookupMap.get(email.toLocaleLowerCase());
+  }
+
+  /**
+   * External IDs are case sensitive
+   */
+  byExtId(extId: string): UserIdDto | undefined {
+    return this.extIdLookupMap.get(extId);
+  }
+}
+
+export class AssetLookupService {
+  private readonly macsLookupMap = new Map<string, AssetIdDto>();
+  private readonly snLookupMap = new Map<string, AssetIdDto>();
+  private readonly extIdLookupMap = new Map<string, AssetIdDto>();
+  private lastUpdated = new Date('2023-04-17T13:00:00.000Z');
+
+  getLastUpdated(): string {
+    return this.lastUpdated.toISOString();
+  }
+
+  // TODO throw errors if conflicts are found
+  /**
+   * Macs are normalized to standard format using `formatMacAddress` but serial numbers and external IDs are case sensitive
+   */
+  add(asset: AssetIdDto) {
+    asset.macs?.forEach(mac => this.macsLookupMap.set(formatMacAddress(mac), asset));
+    if (asset.sn) {
+      this.snLookupMap.set(asset.sn, asset);
+    }
+    if (asset.extId) {
+      this.extIdLookupMap.set(asset.extId, asset);
+    }
+    this.lastUpdated = new Date();
+  }
+
+  // TODO throw errors if conflicts are found
+  lookup(keys: AssetKeys): AssetIdDto[] {
+    const matches = [] as AssetIdDto[];
+    matches.push(...this.byMacs(keys.macs));
+    if (keys.sn) {
+      const ids = this.bySn(keys.sn);
+      if (ids) {
+        matches.push(ids);
+      }
+    }
+    if (keys.extId) {
+      const match = this.byExtId(keys.extId);
+      if (match) {
+        matches.push(match);
+      }
+    }
+    return _.uniqBy(matches, 'id');
+  }
+
+  /**
+   * Macs are normalized to standard format using `formatMacAddress`
+   */
+  byMacs(macs: string | string[]): AssetIdDto[] {
+    const matches = [] as AssetIdDto[];
+    if (!Array.isArray(macs)) {
+      macs = [macs];
+    }
+    for (const mac of macs) {
+      const match = this.macsLookupMap.get(formatMacAddress(mac));
+      if (match) {
+        matches.push(match);
+      }
+    }
+    return _.uniqBy(matches, 'id');
+  }
+
+  bySn(sn?: string): AssetIdDto | undefined {
+    return sn ? this.snLookupMap.get(sn) : undefined;
+  }
+
+  /**
+   * External IDs are case sensitive
+   */
+  byExtId(extId: string): AssetIdDto | undefined {
+    return this.extIdLookupMap.get(extId);
+  }
+}
+
+export class SaasComponentLookupService {
+  private readonly extIdLookupMap = new Map<string, SaasComponentIdDto>();
+  private lastUpdated = new Date('2023-04-17T13:00:00.000Z');
+
+  getLastUpdated(): string {
+    return this.lastUpdated.toISOString();
+  }
+
+  // TODO throw errors if conflicts are found
+  add(sc: SaasComponentIdDto) {
+    this.extIdLookupMap.set(sc.extId, sc);
+    this.lastUpdated = new Date();
+  }
+
+  byExtId(extId: string): SaasComponentIdDto | undefined {
+    return this.extIdLookupMap.get(extId);
+  }
+}

package/src/services/saasEntity.service.ts

@@ -0,0 +1,181 @@
+import _ from 'lodash';
+import {
+  AssetIdDto,
+  BaseDto,
+  BaseUpsertDto,
+  ExtKeyMap,
+  Page,
+  PlatformSaasAssetDto,
+  PlatformSaasAssetUpsertDto,
+  PlatformSaasComponentDto,
+  PlatformSaasComponentUpsertDto,
+  PlatformSaasUserDto,
+  PlatformSaasUserUpsertDto,
+  SaasComponentIdDto,
+  UserIdDto,
+} from '../dto';
+import {TargetApi, TARGET_API_AGENT, ErrorHandler, KIND} from './constants';
+import {AmpDataService} from './data.service';
+import {RestClient, RestRequest} from './rest';
+import {QueryMap} from './rest/utils';
+import {AssetLookupService, SaasComponentLookupService, UserLookupService} from './lookup.service';
+import {AmpEntityServiceImpl, EntityCallOptions} from './entity.service';
+
+const LOOKUP_ID_PAGE_SIZE = 50;
+
+export interface AmpSaaSEntityService<WriteT extends BaseUpsertDto, ReadT extends BaseDto> extends AmpDataService<ReadT> {
+  create(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
+  update(_model: WriteT | WriteT[], _options?: EntityCallOptions): Promise<Page<ReadT>>;
+  delete(_id: string, _options?: EntityCallOptions): Promise<Page<ReadT>>;
+  getLookupIds(_cid: string, _options?: EntityCallOptions): Promise<ExtKeyMap>;
+}
+
+const extIdMapErrorHandler: ErrorHandler<ExtKeyMap> = (error: unknown) => {
+  if (error instanceof Error) {
+    console.error(error.message);
+  }
+  return {};
+};
+
+export class AmpSaaSEntityServiceImpl<WriteT extends BaseUpsertDto, ReadT extends BaseDto>
+  extends AmpEntityServiceImpl<WriteT, ReadT>
+  implements AmpSaaSEntityService<WriteT, ReadT>
+{
+  constructor(rest: RestClient, kind: string, targetApi: TargetApi = TARGET_API_AGENT) {
+    super(rest, kind, targetApi);
+  }
+
+  /** @deprecated */
+  getLookupIds = (cid: string, options?: EntityCallOptions): Promise<ExtKeyMap> => {
+    const req: RestRequest = {
+      url: `/${this.targetApi}/v1/${this.kind}/ext_key_map`,
+      method: 'GET',
+      params: {
+        ...((options?.params as QueryMap) ?? {}),
+        cid,
+      },
+    };
+    return this.call(req, extIdMapErrorHandler);
+  };
+}
+
+const errorHandler = (error: unknown) => {
+  if (error instanceof Error) {
+    console.error(error.message);
+  }
+  throw error;
+};
+
+export class AmpSdkSaasUserService extends AmpSaaSEntityServiceImpl<PlatformSaasUserUpsertDto, PlatformSaasUserDto> {
+  constructor(rest: RestClient, targetApi: TargetApi = TARGET_API_AGENT) {
+    super(rest, KIND.SAAS_USERS, targetApi);
+  }
+
+  getLookup = async (cid: string, options?: EntityCallOptions): Promise<UserLookupService> => {
+    const lookup = new UserLookupService();
+    return this.refreshLookup(lookup, cid, options);
+  };
+
+  refreshLookup = async (lookup: UserLookupService, cid: string, options?: EntityCallOptions): Promise<UserLookupService> => {
+    const limit = LOOKUP_ID_PAGE_SIZE;
+    let offset = 0;
+    let hasMore = true;
+    if (!options) {
+      options = {params: {}};
+    }
+    _.set(options, 'params.updatedAt', {$gt: lookup.getLastUpdated()});
+    while (hasMore) {
+      const req: RestRequest = {
+        url: `/${this.targetApi}/v1/${this.kind}/id_summary`,
+        method: 'GET',
+        params: {
+          ...((options?.params as QueryMap) ?? {}),
+          cid,
+          limit,
+          offset,
+        },
+      };
+      const page = await this.call(req, errorHandler as ErrorHandler<Page<UserIdDto>>);
+      page.data.forEach(ids => lookup.add(ids));
+      offset = (page.hints.offset ?? offset) + limit;
+      hasMore = page.hints.hasMore ?? false;
+    }
+    return lookup;
+  };
+}
+
+export class AmpSdkSaasAssetService extends AmpSaaSEntityServiceImpl<PlatformSaasAssetUpsertDto, PlatformSaasAssetDto> {
+  constructor(rest: RestClient, targetApi: TargetApi = TARGET_API_AGENT) {
+    super(rest, KIND.SAAS_ASSETS, targetApi);
+  }
+
+  getLookup = async (cid: string, options?: EntityCallOptions): Promise<AssetLookupService> => {
+    const lookup = new AssetLookupService();
+    return this.refreshLookup(lookup, cid, options);
+  };
+
+  refreshLookup = async (lookup: AssetLookupService, cid: string, options?: EntityCallOptions): Promise<AssetLookupService> => {
+    const limit = LOOKUP_ID_PAGE_SIZE;
+    let offset = 0;
+    let hasMore = true;
+    if (!options) {
+      options = {params: {}};
+    }
+    _.set(options, 'params.updatedAt', {$gt: lookup.getLastUpdated()});
+    while (hasMore) {
+      const req: RestRequest = {
+        url: `/${this.targetApi}/v1/${this.kind}/id_summary`,
+        method: 'GET',
+        params: {
+          ...((options?.params as QueryMap) ?? {}),
+          cid,
+          limit,
+          offset,
+        },
+      };
+      const page = await this.call(req, errorHandler as ErrorHandler<Page<AssetIdDto>>);
+      page.data.forEach(ids => lookup.add(ids));
+      offset = (page.hints.offset ?? offset) + limit;
+      hasMore = page.hints.hasMore ?? false;
+    }
+    return lookup;
+  };
+}
+
+export class AmpSdkSaasComponentService extends AmpSaaSEntityServiceImpl<PlatformSaasComponentUpsertDto, PlatformSaasComponentDto> {
+  constructor(rest: RestClient, targetApi: TargetApi = TARGET_API_AGENT) {
+    super(rest, KIND.SAAS_COMPONENTS, targetApi);
+  }
+
+  getLookup = async (cid: string, options?: EntityCallOptions): Promise<SaasComponentLookupService> => {
+    const lookup = new SaasComponentLookupService();
+    return this.refreshLookup(lookup, cid, options);
+  };
+
+  refreshLookup = async (lookup: SaasComponentLookupService, cid: string, options?: EntityCallOptions): Promise<SaasComponentLookupService> => {
+    const limit = LOOKUP_ID_PAGE_SIZE;
+    let offset = 0;
+    let hasMore = true;
+    if (!options) {
+      options = {params: {}};
+    }
+    _.set(options, 'params.updatedAt', {$gt: lookup.getLastUpdated()});
+    while (hasMore) {
+      const req: RestRequest = {
+        url: `/${this.targetApi}/v1/${this.kind}/id_summary`,
+        method: 'GET',
+        params: {
+          ...((options?.params as QueryMap) ?? {}),
+          cid,
+          limit,
+          offset,
+        },
+      };
+      const page = await this.call(req, errorHandler as ErrorHandler<Page<SaasComponentIdDto>>);
+      page.data.forEach(ids => lookup.add(ids));
+      offset = (page.hints.offset ?? offset) + limit;
+      hasMore = page.hints.hasMore ?? false;
+    }
+    return lookup;
+  };
+}

package/src/services/utils.ts

@@ -0,0 +1,8 @@
+import _ from 'lodash';
+
+export function formatMacAddress(raw: string): string {
+  const lower = raw.toLowerCase().replace(/[^a-f0-9]/g, '');
+  return _.chunk(lower.split(''), 2)
+    .map(chunk => chunk.join(''))
+    .join(':');
+}