@contrast/common 1.7.0 → 1.9.0

package/src/signatures/mongodb.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright: 2022 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+const collectionSignatures: [string, any][] = [
+  'find',
+  'findOne',
+  'findAndModify',
+  'findOneAndDelete',
+  'findOneAndReplace',
+  'findOneAndUpdate',
+  'remove',
+  'removeOne',
+  'replaceOne',
+  'removeMany',
+  'save',
+  'update',
+  'updateOne',
+  'updateMany',
+  'deleteOne',
+  'deleteMany',
+].map((method) => [
+  `mongodb.Collection.prototype.${method}`,
+  {
+    moduleName: 'mongodb',
+    methodName: `Collection.prototype.${method}`,
+    isModule: true,
+  }
+]);
+
+const mongodb: Map<string, any> = new Map([
+  ...collectionSignatures,
+]);
+
+export default mongodb;

package/src/signatures/mssql.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright: 2022 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+import { Signature } from '../types';
+
+
+const mssql = new Map<string, Signature>([
+  [
+    'mssql/lib/base/prepared-statement.prototype.prepare',
+    {
+      moduleName: 'mssql',
+      version: '>=6.4.0',
+      fileName: 'lib/base/prepared-statement.js',
+      methodName: 'PreparedStatement.prototype.prepare',
+      isModule: true,
+    },
+  ],
+  [
+    'mssql/lib/base/request.prototype.batch',
+    {
+      moduleName: 'mssql',
+      version: '>=6.4.0',
+      fileName: 'lib/base/request.js',
+      methodName: 'Request.prototype.batch',
+      isModule: true,
+    },
+  ],
+  [
+    'mssql/lib/base/request.prototype.query',
+    {
+      moduleName: 'mssql',
+      version: '>=6.4.0',
+      fileName: 'lib/base/request.js',
+      methodName: 'Request.prototype.query',
+      isModule: true,
+    },
+  ],
+] as [string, Signature][]);
+
+export default mssql;

package/src/types.ts

@@ -13,8 +13,24 @@
  * way not consistent with the End User License Agreement.
  */
 
-import { Event, Rule, ProtectRuleMode } from './constants';
 import { EventEmitter } from 'events';
+import { Event, ProtectRuleMode, Rule } from './constants';
+
+export interface Installable {
+  install(): void | Promise<void>;
+  uninstall?(): void | Promise<void>;
+}
+
+export interface Signature {
+  moduleName: string;
+  methodName: string;
+  fileName?: string;
+  version?: string;
+  isModule: boolean;
+  isConstructor?: boolean;
+  source?: 'O' | 'P' | 'R';
+  target?: 'O' | 'P' | 'R';
+}
 
 export interface AppInfo {
   os: {
@@ -147,6 +163,13 @@ export interface ProtectMessage {
   parsedQuery: any;
 }
 
+export interface SourceInfo {
+  serverType: string;
+  port: number;
+  protocol: string;
+  time: number;
+}
+
 /**
  * this is known as RequestStore even though, in the future, instrumentation
  * will exist for message buses or sources other than HTTP requests. "request"
@@ -158,22 +181,150 @@ export interface ProtectMessage {
  * with, requests, whether from HTTP or elsewhere.
  */
 export interface RequestStore {
+  // TODO: this shouldn't be optional but blows up
+  sourceInfo?: SourceInfo;
   protect?: ProtectMessage; // from protect/lib/make-source-context
-  assess?: any // TODO
+  assess?: any;
+  route?: any;
 }
 
-export interface Messages extends EventEmitter {
-  addListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
-  addListener(event: Event.SERVER_SETTINGS_UPDATE, listener: (msg: Record<string, any>) => void): this;
+/**
+ * Architecture Component registration event payload.
+ */
+export interface ArchitectureComponent {
+  /** The type of this component: database, ldap, or web server connection. */
+  type: 'db' | 'ldap' | 'ws',
+  /**
+   * The URL to which this component responds.
+   * @example "mysql://host:3306"
+   */
+  url: string;
+  /**
+   * Some indication of the subtype of the connection.
+   * @example "MySQL"
+   */
+  vendor?: string;
+}
+
+/**
+ * Library discovery event payload.
+ */
+export interface Library {
+  /**
+   * The time, in ms, that the library was last modified on the filesystem.
+   * Must be greater than 0 and less than 32503679999000 (Tuesday, 31 December 2999 23:59:59).
+   * @todo
+   */
+  externalDate: number;
+  /**
+   * The time, in ms, that the library was last modified on the filesystem.
+   * Must be greater than 0 and less than 32503679999000 (Tuesday, 31 December 2999 23:59:59).
+   * @todo
+   */
+  internalDate: number;
+  /**
+   * The version of the library.
+   * @example "2.18.1"
+   */
+  version: string;
+  /**
+   * Hash of the library. uses the provided SHA sum when present, or a generated
+   * identifer otherwise.
+   * @example "2254143855c5a8c73825e4522baf2ea021766717"
+   * @example "mysql:2.18.1"
+   */
+  hash: string;
+  /**
+   * Name of the library with version data
+   * @example "mysql-2.18.1"
+   */
+  file: string;
+  /**
+   * Homepage or source of the library.
+   * @example "https://github.com/mysqljs/mysql#readme"
+   * @example "https://registry.npmjs.org/mysql/-/mysql-2.18.1.tgz"
+   */
+  url?: string;
+  /**
+   * String describing the library, including name, description, license,
+   * dependencies and dependents.
+   */
+  manifest: string;
+  /**
+   * Library tags provided by the user to the agent.
+   */
+  tags: string;
+}
 
+/**
+ * Library usage update event payload.
+ */
+export interface LibraryUsage {
+  id: string;
+  names: string[];
+}
+
+/**
+ * Route discovery or observation event payload.
+ */
+export interface RouteInfo {
+  /**
+   * Language specific signature of the controller method.
+   * @example "Router.get('prefix/route/path', [Function])"
+   */
+  signature: string;
+  /**
+   * The HTTP method supported by the discovered route url, if one is reported.
+   * @example "get"
+   */
+  method?: string;
+  /**
+   * Normalized URL for a route.
+   * @example "prefix/route/path"
+   */
+  url: string;
+}
+
+/**
+ * Agent event emitter for messaging to/from external systems. Use cases are
+ * reporting agent findings and broadcasting settings updates.
+ *
+ * The final, generic, overloads for emit/on matches any calls that don't match
+ * one of the more specific definitions.
+ */
+export interface Messages extends EventEmitter {
+  emit(event: Event.ARCHITECTURE_COMPONENT, msg: ArchitectureComponent): boolean;
+  emit(event: Event.ASSESS_DATAFLOW_FINDING, msg: any): boolean;
+  emit(event: Event.LIBRARY, msg: Library): boolean;
+  emit(event: Event.LIBRARY_USAGE, msg: LibraryUsage): boolean;
   emit(event: Event.PROTECT, msg: RequestStore): boolean;
+  emit(event: Event.ROUTE_COVERAGE_DISCOVERY, route: RouteInfo): boolean;
+  emit(event: Event.ROUTE_COVERAGE_DISCOVERY_FINISHED, routes: RouteInfo[]): boolean;
+  emit(event: Event.ROUTE_COVERAGE_OBSERVATION, route: RouteInfo): boolean;
   emit(event: Event.SERVER_SETTINGS_UPDATE, msg: Record<string, any>): boolean;
+  emit(event: Event, ...args: any[]): boolean;
 
-  on(event: Event.ARCHITECTURE_COMPONENT, listener: (msg: Record<string, any>) => void): this;
+  on(event: Event.ARCHITECTURE_COMPONENT, listener: (msg: ArchitectureComponent) => void): this;
+  on(event: Event.ASSESS_DATAFLOW_FINDING, listenter: (msg: any) => void): this;
+  on(event: Event.LIBRARY, listener: (msg: Library) => void): this;
+  on(event: Event.LIBRARY_USAGE, listener: (msg: LibraryUsage) => void): this;
   on(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
-  on(event: Event.LIBRARY_USAGE, listener: (msg: Record<string, any>) => void): this
+  on(event: Event.ROUTE_COVERAGE_DISCOVERY, listener: (route: RouteInfo) => void): this;
+  on(event: Event.ROUTE_COVERAGE_DISCOVERY_FINISHED, listener: (routes: RouteInfo[]) => void): this;
+  on(event: Event.ROUTE_COVERAGE_OBSERVATION, listener: (route: RouteInfo) => void): this;
   on(event: Event.SERVER_SETTINGS_UPDATE, listener: (msg: Record<string, any>) => void): this;
+  on(event: Event, listener: (...args: any[]) => void): this;
+}
+
+/**
+ * Agent event emitter for broadcasting internal lifecycle events.
+ *
+ * The final, generic, overloads for emit/on matches any calls that don't match
+ * one of the more specific definitions.
+ */
+export interface Lifecycle extends EventEmitter {
+  emit(event: Event, ...args: any[]): boolean;
 
-  prependListener(event: Event.PROTECT, listener: (msg: RequestStore) => void,): this;
-  prependOnceListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+  on(event: Event.RESPONSE_FINISH, listener: (msg: RequestStore) => void): this;
+  on(event: Event, listener: (...args: any[]) => void): this;
 }