@contrast/common 1.0.0

package/lib/constants.d.ts

@@ -0,0 +1,23 @@
+export declare enum Event {
+    ASSESS = "assess",
+    PROTECT = "protect"
+}
+export declare enum Rule {
+    BOT_BLOCKER = "bot-blocker",
+    CMD_INJECTION = "cmd-injection",
+    CMD_INJECTION_COMMAND_BACKDOORS = "cmd-injection-command-backdoors",
+    CMD_INJECTION_SEMANTIC_CHAINED_COMMANDS = "cmd-injection-semantic-chained-commands",
+    CMD_INJECTION_SEMANTIC_DANGEROUS_PATHS = "cmd-injection-semantic-dangerous-paths",
+    IP_DENYLIST = "ip-denylist",
+    METHOD_TAMPERING = "method-tampering",
+    NOSQL_INJECTION = "nosql-injection",
+    NOSQL_INJECTION_MONGO = "nosql-injection-mongo",
+    PATH_TRAVERSAL = "path-traversal",
+    REFLECTED_XSS = "reflected-xss",
+    SQL_INJECTION = "sql-injection",
+    SSJS_INJECTION = "ssjs-injection",
+    VIRTUAL_PATCH = "virtual-patch",
+    UNTRUSTED_DESERIALIZATION = "untrusted-deserialization",
+    UNSAFE_FILE_UPLOAD = "unsafe-file-upload",
+    XXE = "xxe"
+}

package/lib/constants.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rule = exports.Event = void 0;
+var Event;
+(function (Event) {
+    Event["ASSESS"] = "assess";
+    Event["PROTECT"] = "protect";
+})(Event = exports.Event || (exports.Event = {}));
+var Rule;
+(function (Rule) {
+    Rule["BOT_BLOCKER"] = "bot-blocker";
+    Rule["CMD_INJECTION"] = "cmd-injection";
+    Rule["CMD_INJECTION_COMMAND_BACKDOORS"] = "cmd-injection-command-backdoors";
+    Rule["CMD_INJECTION_SEMANTIC_CHAINED_COMMANDS"] = "cmd-injection-semantic-chained-commands";
+    Rule["CMD_INJECTION_SEMANTIC_DANGEROUS_PATHS"] = "cmd-injection-semantic-dangerous-paths";
+    Rule["IP_DENYLIST"] = "ip-denylist";
+    Rule["METHOD_TAMPERING"] = "method-tampering";
+    Rule["NOSQL_INJECTION"] = "nosql-injection";
+    Rule["NOSQL_INJECTION_MONGO"] = "nosql-injection-mongo";
+    Rule["PATH_TRAVERSAL"] = "path-traversal";
+    Rule["REFLECTED_XSS"] = "reflected-xss";
+    Rule["SQL_INJECTION"] = "sql-injection";
+    Rule["SSJS_INJECTION"] = "ssjs-injection";
+    Rule["VIRTUAL_PATCH"] = "virtual-patch";
+    Rule["UNTRUSTED_DESERIALIZATION"] = "untrusted-deserialization";
+    Rule["UNSAFE_FILE_UPLOAD"] = "unsafe-file-upload";
+    Rule["XXE"] = "xxe";
+})(Rule = exports.Rule || (exports.Rule = {}));
+//# sourceMappingURL=constants.js.map

package/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAA,IAAY,KAGX;AAHD,WAAY,KAAK;IACf,0BAAiB,CAAA;IACjB,4BAAmB,CAAA;AACrB,CAAC,EAHW,KAAK,GAAL,aAAK,KAAL,aAAK,QAGhB;AAED,IAAY,IAkBX;AAlBD,WAAY,IAAI;IACd,mCAA2B,CAAA;IAC3B,uCAA+B,CAAA;IAC/B,2EAAmE,CAAA;IACnE,2FAAmF,CAAA;IACnF,yFAAiF,CAAA;IACjF,mCAA2B,CAAA;IAC3B,6CAAqC,CAAA;IACrC,2CAAmC,CAAA;IACnC,uDAA+C,CAAA;IAC/C,yCAAiC,CAAA;IACjC,uCAA+B,CAAA;IAC/B,uCAA+B,CAAA;IAC/B,yCAAiC,CAAA;IACjC,uCAA+B,CAAA;IAC/B,+DAAuD,CAAA;IACvD,iDAAyC,CAAA;IACzC,mBAAW,CAAA;AACb,CAAC,EAlBW,IAAI,GAAJ,YAAI,KAAJ,YAAI,QAkBf"}

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants';
+export * from './types';
+/**
+ * Returns true if the value passed is either a primitive string or a
+ * String object.
+ */
+export declare function isString(value: unknown): value is string | String;
+export declare function encodeString(str: string): string;

package/lib/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeString = exports.isString = void 0;
+__exportStar(require("./constants"), exports);
+__exportStar(require("./types"), exports);
+/**
+ * Returns true if the value passed is either a primitive string or a
+ * String object.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isString(value) {
+    return typeof value === 'string' || value instanceof String;
+}
+exports.isString = isString;
+function encodeString(str) {
+    return Buffer.from(str).toString('base64');
+}
+exports.encodeString = encodeString;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,0CAAwB;AAExB;;;GAGG;AACH,wDAAwD;AACxD,SAAgB,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,YAAY,MAAM,CAAC;AAC9D,CAAC;AAFD,4BAEC;AAED,SAAgB,YAAY,CAAC,GAAW;IACtC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC7C,CAAC;AAFD,oCAEC"}

package/lib/types/index.d.ts

@@ -0,0 +1,50 @@
+/// <reference types="node" />
+import { Event, Rule } from '../constants';
+import { EventEmitter } from 'events';
+export interface RuleConfig {
+    mode: 'monitor' | 'block' | 'block_at_perimeter' | 'off';
+}
+export interface RulesConfig extends Record<Rule, RuleConfig> {
+}
+export interface Result {
+    ruleId: Rule;
+    inputType: string;
+    path: string[];
+    key: string;
+    value: string;
+    details?: any[];
+}
+export interface RequestStore {
+    protect?: {
+        reqData: {
+            method: string;
+            headers: string[];
+            uriPath: string;
+            queries: string;
+            contentType?: string;
+            standardUrlParsing: boolean;
+        };
+        block: (mode: string, ruleId: string) => void;
+        rules: {
+            agentLibRules: RulesConfig;
+            agentLibRulesMask: number;
+            agentRules: RulesConfig;
+        };
+        exclusions: any[];
+        virtualPatches: any[];
+        findings: {
+            trackRequest: boolean;
+            securityException?: [mode: string, ruleId: string];
+            bodyType?: 'json' | 'urlencoded';
+            resultsMap: Record<Rule, Result[]>;
+        };
+    };
+}
+export interface Messages extends EventEmitter {
+    addListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+    emit(event: Event.PROTECT, msg: RequestStore): boolean;
+    on(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+    once(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+    prependListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+    prependOnceListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+}

package/lib/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/lib/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@contrast/common",
+  "version": "1.0.0",
+  "description": "Shared constants and utilities for all Contrast Agent modules",
+  "license": "UNLICENSED",
+  "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "npm": ">= 8.4.0",
+    "node": ">= 14.15.0"
+  },
+  "scripts": {
+    "build": "tsc --build src/",
+    "test": "../scripts/test.sh"
+  },
+  "dependencies": {}
+}

package/src/constants.ts

@@ -0,0 +1,24 @@
+export enum Event {
+  ASSESS = 'assess',
+  PROTECT = 'protect',
+}
+
+export enum Rule {
+  BOT_BLOCKER = 'bot-blocker',
+  CMD_INJECTION = 'cmd-injection',
+  CMD_INJECTION_COMMAND_BACKDOORS = 'cmd-injection-command-backdoors',
+  CMD_INJECTION_SEMANTIC_CHAINED_COMMANDS = 'cmd-injection-semantic-chained-commands',
+  CMD_INJECTION_SEMANTIC_DANGEROUS_PATHS = 'cmd-injection-semantic-dangerous-paths',
+  IP_DENYLIST = 'ip-denylist',
+  METHOD_TAMPERING = 'method-tampering',
+  NOSQL_INJECTION = 'nosql-injection',
+  NOSQL_INJECTION_MONGO = 'nosql-injection-mongo',
+  PATH_TRAVERSAL = 'path-traversal',
+  REFLECTED_XSS = 'reflected-xss',
+  SQL_INJECTION = 'sql-injection',
+  SSJS_INJECTION = 'ssjs-injection',
+  VIRTUAL_PATCH = 'virtual-patch',
+  UNTRUSTED_DESERIALIZATION = 'untrusted-deserialization',
+  UNSAFE_FILE_UPLOAD = 'unsafe-file-upload',
+  XXE = 'xxe',
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './constants';
+export * from './types';
+
+/**
+ * Returns true if the value passed is either a primitive string or a
+ * String object.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function isString(value: unknown): value is string | String {
+  return typeof value === 'string' || value instanceof String;
+}
+
+export function encodeString(str: string): string {
+  return Buffer.from(str).toString('base64');
+}

package/src/types/index.ts

@@ -0,0 +1,64 @@
+import { Event, Rule } from '../constants';
+import { EventEmitter } from 'events';
+
+export interface RuleConfig {
+  mode: 'monitor' | 'block' | 'block_at_perimeter' | 'off';
+}
+
+export interface RulesConfig extends Record<Rule, RuleConfig> {}
+
+export interface Result {
+  ruleId: Rule,
+  inputType: string, // TODO
+  path: string[],
+  key: string,
+  value: string,
+  details?: any[],
+}
+
+//
+// this is known as RequestStore even though, in the future, instrumentation
+// will exist for message buses or sources other than HTTP requests. "request"
+// seems generic enough that it's not hard to understand that request can mean
+// an amqp message or other request to perform work that might get user input.
+// additionally, at this time, the only things instrumented are HTTP requests,
+// and other things are only possible extensions to the core facility. it seems
+// reasonable that they will fit into the primary concept that the agent deals
+// with, requests, whether from HTTP or elsewhere.
+//
+export interface RequestStore {
+  // TODO: from protect/lib/make-source-context
+  protect?: {
+    reqData: {
+      method: string;
+      headers: string[];
+      uriPath: string;
+      queries: string;
+      contentType?: string;
+      standardUrlParsing: boolean;
+    };
+    block: (mode: string, ruleId: string) => void;
+    rules: {
+      agentLibRules: RulesConfig;
+      agentLibRulesMask: number;
+      agentRules: RulesConfig;
+    };
+    exclusions: any[]; // TODO
+    virtualPatches: any[]; // TODO
+    findings: {
+      trackRequest: boolean;
+      securityException?: [mode: string, ruleId: string];
+      bodyType?: 'json' | 'urlencoded';
+      resultsMap: Record<Rule, Result[]>
+    };
+  };
+}
+
+export interface Messages extends EventEmitter {
+  addListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+  emit(event: Event.PROTECT, msg: RequestStore): boolean;
+  on(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+  once(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+  prependListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+  prependOnceListener(event: Event.PROTECT, listener: (msg: RequestStore) => void): this;
+}