guardrail-security 1.0.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "guardrail-security",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "files": ["dist/**/*", "src/**/*"],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --skipLibCheck",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@guardrail/core": "workspace:*",
+    "@guardrail/database": "workspace:*",
+    "@aws-sdk/client-secrets-manager": "^3.490.0",
+    "@azure/keyvault-secrets": "^4.8.0",
+    "@azure/identity": "^4.0.0",
+    "@google-cloud/secret-manager": "^5.0.0",
+    "node-vault": "^0.10.2",
+    "glob": "^10.3.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  }
+}

package/src/__tests__/license/engine.test.ts

@@ -0,0 +1,250 @@
+/**
+ * License Compliance Engine Tests
+ *
+ * Test suite for the LicenseComplianceEngine class
+ */
+
+import { describe, it, expect, beforeEach, jest } from "@jest/globals";
+import { LicenseComplianceEngine } from "../../license/engine";
+
+// Import ResponseType
+type ResponseType =
+  | "basic"
+  | "cors"
+  | "default"
+  | "error"
+  | "opaque"
+  | "opaqueredirect";
+
+// Mock fs
+jest.mock("fs", () => ({
+  readFileSync: jest.fn<(path: string) => string>().mockReturnValue(""),
+  existsSync: jest.fn<(path: string) => boolean>(() => true),
+}));
+
+// Mock prisma
+jest.mock("@guardrail/database", () => ({
+  prisma: {
+    licenseAnalysis: {
+      findMany: jest.fn<() => Promise<any[]>>().mockResolvedValue([]),
+      create: jest.fn<() => Promise<any>>().mockResolvedValue({}),
+      update: jest.fn<() => Promise<any>>().mockResolvedValue({}),
+      delete: jest.fn<() => Promise<any>>().mockResolvedValue({}),
+      findUnique: jest.fn<() => Promise<any>>().mockResolvedValue(null),
+    },
+  },
+}));
+
+// Mock fetch
+const mockFetch = jest.fn<() => Promise<Response>>();
+global.fetch = mockFetch;
+
+describe("LicenseComplianceEngine", () => {
+  let engine: LicenseComplianceEngine;
+
+  beforeEach(() => {
+    engine = new LicenseComplianceEngine();
+    jest.clearAllMocks();
+  });
+
+  describe("license fetching", () => {
+    it("should fetch license from npm registry", async () => {
+      const mockResponse = {
+        ok: true,
+        json: jest.fn<() => Promise<any>>().mockResolvedValue({
+          "dist-tags": { latest: "1.0.0" },
+          versions: {
+            "1.0.0": {
+              license: "MIT",
+            },
+          },
+        }),
+        headers: new Headers(),
+        status: 200,
+        statusText: "OK",
+        type: "basic" as ResponseType,
+        url: "",
+        redirected: false,
+        clone: jest.fn<() => Response>(),
+        body: null,
+        bodyUsed: false,
+        bytes: jest.fn<() => Promise<Uint8Array<ArrayBufferLike>>>(),
+        text: jest.fn<() => Promise<string>>(),
+        blob: jest.fn<() => Promise<Blob>>(),
+        formData: jest.fn<() => Promise<FormData>>(),
+        arrayBuffer: jest.fn<() => Promise<ArrayBuffer>>(),
+      };
+
+      mockFetch.mockResolvedValue(mockResponse);
+
+      // Access private method through type assertion
+      const result = await (engine as any).fetchLicenseFromRegistry(
+        "test-package",
+      );
+
+      expect(result.license).toBe("MIT");
+      expect(result.category).toBe("permissive");
+    });
+
+    it("should handle SPDX expressions", async () => {
+      const mockResponse = {
+        ok: true,
+        json: jest.fn<() => Promise<any>>().mockResolvedValue({
+          "dist-tags": { latest: "1.0.0" },
+          versions: {
+            "1.0.0": {
+              license: {
+                type: "MIT",
+              },
+            },
+          },
+        }),
+        headers: new Headers(),
+        status: 200,
+        statusText: "OK",
+        type: "basic" as ResponseType,
+        url: "",
+        redirected: false,
+        clone: jest.fn<() => Response>(),
+        body: null,
+        bodyUsed: false,
+        bytes: jest.fn<() => Promise<Uint8Array<ArrayBufferLike>>>(),
+        text: jest.fn<() => Promise<string>>(),
+        blob: jest.fn<() => Promise<Blob>>(),
+        formData: jest.fn<() => Promise<FormData>>(),
+        arrayBuffer: jest.fn<() => Promise<ArrayBuffer>>(),
+      };
+
+      mockFetch.mockResolvedValue(mockResponse);
+
+      const result = await (engine as any).fetchLicenseFromRegistry(
+        "test-package",
+      );
+
+      expect(result.license).toBe("MIT");
+    });
+
+    it("should normalize license names", async () => {
+      // Test the normalizeLicenseName method directly
+      const result = (engine as any).normalizeLicenseName("Apache 2.0");
+      expect(result).toBe("Apache-2.0");
+    });
+
+    it("should use fallback on network error", async () => {
+      mockFetch.mockRejectedValue(new Error("Network error"));
+
+      const result = await (engine as any).fetchLicenseFromRegistry(
+        "private-package",
+      );
+
+      expect(result.license).toBe("UNKNOWN");
+      expect(result.category).toBe("unknown");
+    });
+  });
+
+  describe("license categorization", () => {
+    it("should categorize MIT as permissive", () => {
+      const result = (engine as any).categorizeLicense("MIT");
+      expect(result).toBe("permissive");
+    });
+
+    it("should categorize GPL as copyleft", () => {
+      const result = (engine as any).categorizeLicense("GPL-3.0");
+      expect(result).toBe("copyleft");
+    });
+
+    it("should categorize LGPL as weak-copyleft", () => {
+      const result = (engine as any).categorizeLicense("LGPL-3.0");
+      expect(result).toBe("weak-copyleft");
+    });
+
+    it("should categorize unknown licenses", () => {
+      const result = (engine as any).categorizeLicense("UNKNOWN-LICENSE");
+      expect(result).toBe("unknown");
+    });
+  });
+
+  describe("conflict detection", () => {
+    it("should detect GPL contamination in proprietary project", () => {
+      const dependencies = [
+        { name: "dep1", license: "MIT", category: "permissive" },
+        { name: "dep2", license: "GPL-3.0", category: "copyleft" },
+      ];
+
+      const conflicts = (engine as any).detectGPLContamination(
+        dependencies,
+        "Proprietary",
+      );
+
+      expect(conflicts).toHaveLength(2);
+      expect(conflicts[0].dependency).toBe("dep1");
+      expect(conflicts[0].severity).toBe("warning");
+      expect(conflicts[1].dependency).toBe("dep2");
+      expect(conflicts[1].severity).toBe("error");
+    });
+
+    it("should allow LGPL in Apache project", () => {
+      const dependencies = [
+        { name: "dep1", license: "Apache-2.0", category: "permissive" },
+        { name: "dep2", license: "LGPL-3.0", category: "weak-copyleft" },
+      ];
+
+      const conflicts = (engine as any).detectGPLContamination(
+        dependencies,
+        "Apache-2.0",
+      );
+
+      expect(conflicts).toHaveLength(0);
+    });
+  });
+
+  describe("project analysis", () => {
+    it("should analyze simple project", async () => {
+      const mockFs = await import("fs");
+      jest.mocked(mockFs.readFileSync).mockReturnValue(
+        JSON.stringify({
+          dependencies: {
+            express: "^4.18.0",
+            lodash: "^4.17.21",
+          },
+        }),
+      );
+
+      // Mock fetch responses
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: jest.fn<() => Promise<any>>().mockResolvedValue({
+          "dist-tags": { latest: "1.0.0" },
+          versions: {
+            "1.0.0": { license: "MIT" },
+          },
+        }),
+        headers: new Headers(),
+        status: 200,
+        statusText: "OK",
+        type: "basic" as ResponseType,
+        url: "",
+        redirected: false,
+        clone: jest.fn<() => Response>(),
+        body: null,
+        bodyUsed: false,
+        bytes: jest.fn<() => Promise<Uint8Array<ArrayBufferLike>>>(),
+        text: jest.fn<() => Promise<string>>(),
+        blob: jest.fn<() => Promise<Blob>>(),
+        formData: jest.fn<() => Promise<FormData>>(),
+        arrayBuffer: jest.fn<() => Promise<ArrayBuffer>>(),
+      });
+
+      const result = await engine.analyzeProject(
+        "/test/path",
+        "test-project",
+        "MIT",
+      );
+
+      expect(result.projectId).toBe("test-project");
+      expect(result.projectLicense).toBe("MIT");
+      expect(result.dependencies).toHaveLength(2);
+      expect(result.overallStatus).toBe("compliant");
+    });
+  });
+});

package/src/__tests__/supply-chain/typosquat.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Typosquat Detector Tests
+ *
+ * Test suite for the TyposquatDetector class
+ */
+
+import { describe, it, expect, beforeEach } from "@jest/globals";
+import { TyposquatDetector } from "../../supply-chain/typosquat";
+
+describe("TyposquatDetector", () => {
+  let detector: TyposquatDetector;
+
+  beforeEach(() => {
+    detector = new TyposquatDetector();
+  });
+
+  describe("Exact Match Detection", () => {
+    const legitimatePackages = [
+      "react",
+      "vue",
+      "express",
+      "lodash",
+      "typescript",
+      "axios",
+      "webpack",
+      "jest",
+    ];
+
+    it.each(legitimatePackages)(
+      "should NOT flag legitimate package: %s",
+      async (pkg) => {
+        const result = await detector.detectTyposquatting(pkg);
+        expect(result.isTyposquat).toBe(false);
+      },
+    );
+  });
+
+  describe("Character Swap Detection", () => {
+    const swapAttempts = [
+      { input: "raect", target: "react" },
+      { input: "exrpess", target: "express" },
+      { input: "loadsh", target: "lodash" },
+      { input: "axois", target: "axios" },
+    ];
+
+    it.each(swapAttempts)(
+      "should detect character swap: $input -> $target",
+      async ({ input, target }) => {
+        const result = await detector.detectTyposquatting(input);
+        expect(result.isTyposquat).toBe(true);
+        expect(result.targetPackage).toBe(target);
+        expect(result.patterns).toContain("character_swap");
+      },
+    );
+  });
+
+  describe("Missing Character Detection", () => {
+    const missingCharAttempts = [
+      { input: "rect", target: "react" },
+      { input: "expres", target: "express" },
+      { input: "lodas", target: "lodash" },
+      { input: "webpck", target: "webpack" },
+    ];
+
+    it.each(missingCharAttempts)(
+      "should detect missing character: $input -> $target",
+      async ({ input, target }) => {
+        const result = await detector.detectTyposquatting(input);
+        expect(result.isTyposquat).toBe(true);
+        expect(result.targetPackage).toBe(target);
+        expect(result.patterns).toContain("missing_character");
+      },
+    );
+  });
+
+  describe("Extra Character Detection", () => {
+    const extraCharAttempts = [
+      { input: "reactt", target: "react" },
+      { input: "expresss", target: "express" },
+      { input: "lodassh", target: "lodash" },
+      { input: "axioss", target: "axios" },
+    ];
+
+    it.each(extraCharAttempts)(
+      "should detect extra character: $input -> $target",
+      async ({ input, target }) => {
+        const result = await detector.detectTyposquatting(input);
+        expect(result.isTyposquat).toBe(true);
+        expect(result.targetPackage).toBe(target);
+        expect(result.patterns).toContain("extra_character");
+      },
+    );
+  });
+
+  describe("Homoglyph Detection", () => {
+    const homoglyphAttempts = [
+      { input: "reаct", description: "cyrillic a" },
+      { input: "exprеss", description: "cyrillic e" },
+      { input: "l0dash", description: "zero for o" },
+      { input: "ax1os", description: "one for i" },
+    ];
+
+    it.each(homoglyphAttempts)(
+      "should detect homoglyph attack: $input ($description)",
+      async ({ input }) => {
+        const result = await detector.detectTyposquatting(input);
+        // Homoglyph detection may vary based on implementation
+        expect(result.similarity).toBeGreaterThan(0);
+      },
+    );
+  });
+
+  describe("Combosquatting Detection", () => {
+    const comboAttempts = [
+      { input: "react-native-helper", target: "react" },
+      { input: "express-security", target: "express" },
+      { input: "lodash-utils", target: "lodash" },
+      { input: "axios-wrapper", target: "axios" },
+    ];
+
+    it.each(comboAttempts)(
+      "should detect combosquatting: $input -> $target",
+      async ({ input }) => {
+        const result = await detector.detectTyposquatting(input);
+        if (result.isTyposquat) {
+          expect(result.patterns).toContain("combosquatting");
+        }
+      },
+    );
+  });
+
+  describe("Levenshtein Distance", () => {
+    it("should calculate similarity based on Levenshtein distance", async () => {
+      const result = await detector.detectTyposquatting("reakt");
+      expect(result.similarity).toBeGreaterThan(0.7);
+    });
+
+    it("should have low similarity for unrelated packages", async () => {
+      const result = await detector.detectTyposquatting(
+        "completely-different-package",
+      );
+      expect(result.similarity).toBeLessThan(0.5);
+    });
+  });
+
+  describe("Result Structure", () => {
+    it("should return complete result structure", async () => {
+      const result = await detector.detectTyposquatting("reakt");
+
+      expect(result).toHaveProperty("isTyposquat");
+      expect(result).toHaveProperty("suspiciousPackage");
+      expect(result).toHaveProperty("similarity");
+      expect(result).toHaveProperty("patterns");
+      expect(Array.isArray(result.patterns)).toBe(true);
+    });
+
+    it("should include target package when typosquat detected", async () => {
+      const result = await detector.detectTyposquatting("reakt");
+
+      if (result.isTyposquat) {
+        expect(result.targetPackage).toBeDefined();
+      }
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle empty string", async () => {
+      const result = await detector.detectTyposquatting("");
+      expect(result.isTyposquat).toBe(false);
+    });
+
+    it("should handle very long package names", async () => {
+      const longName = "a".repeat(100);
+      const result = await detector.detectTyposquatting(longName);
+      expect(result).toBeDefined();
+    });
+
+    it("should handle special characters", async () => {
+      const result = await detector.detectTyposquatting("@scope/react");
+      expect(result).toBeDefined();
+    });
+
+    it("should be case insensitive", async () => {
+      const result1 = await detector.detectTyposquatting("REACT");
+      const result2 = await detector.detectTyposquatting("React");
+      // Both should handle case variations
+      expect(result1).toBeDefined();
+      expect(result2).toBeDefined();
+    });
+  });
+});

package/src/attack-surface/analyzer.ts

@@ -0,0 +1,152 @@
+import { prisma } from "@guardrail/database";
+
+export interface EntryPoint {
+  type: "http" | "graphql" | "websocket" | "grpc";
+  path: string;
+  method?: string;
+  file: string;
+  line: number;
+  authentication?: string;
+  rateLimit?: string;
+  parameters: ParameterInfo[];
+}
+
+export interface ParameterInfo {
+  name: string;
+  type: string;
+  required: boolean;
+  validated: boolean;
+}
+
+export interface APISecurityFinding {
+  category: string;
+  severity: "low" | "medium" | "high" | "critical";
+  endpoint: string;
+  description: string;
+  recommendation: string;
+}
+
+export interface AttackPath {
+  id: string;
+  entry: string;
+  steps: string[];
+  impact: string;
+  likelihood: "low" | "medium" | "high";
+}
+
+export interface AttackSurfaceAnalysisResult {
+  projectId: string;
+  summary: {
+    totalEntryPoints: number;
+    byType: Record<string, number>;
+    risksByLevel: Record<string, number>;
+  };
+  entryPoints: EntryPoint[];
+  attackPaths: AttackPath[];
+  apiFindings: APISecurityFinding[];
+}
+
+export class AttackSurfaceAnalyzer {
+  async analyzeProject(
+    projectPath: string,
+    projectId: string,
+  ): Promise<AttackSurfaceAnalysisResult> {
+    const entryPoints = await this.scanHTTPEndpoints(projectPath);
+    const apiFindings = await this.analyzeEndpoints(entryPoints);
+    const attackPaths = await this.buildAttackPaths(entryPoints, apiFindings);
+
+    const byType: Record<string, number> = {};
+    const risksByLevel: Record<string, number> = {};
+
+    for (const ep of entryPoints) {
+      byType[ep.type] = (byType[ep.type] || 0) + 1;
+    }
+
+    for (const finding of apiFindings) {
+      risksByLevel[finding.severity] =
+        (risksByLevel[finding.severity] || 0) + 1;
+    }
+
+    const result: AttackSurfaceAnalysisResult = {
+      projectId,
+      summary: {
+        totalEntryPoints: entryPoints.length,
+        byType,
+        risksByLevel,
+      },
+      entryPoints,
+      attackPaths,
+      apiFindings,
+    };
+
+    await prisma.attackSurfaceAnalysis.create({
+      data: {
+        projectId,
+        summary: JSON.parse(JSON.stringify(result.summary)),
+        endpoints: JSON.parse(JSON.stringify(entryPoints)),
+        attackPaths: JSON.parse(JSON.stringify(attackPaths)),
+        apiFindings: JSON.parse(JSON.stringify(apiFindings)),
+      },
+    });
+
+    return result;
+  }
+
+  private async scanHTTPEndpoints(_projectPath: string): Promise<EntryPoint[]> {
+    // In production, would use AST parsing to find routes
+    return [];
+  }
+
+  private async analyzeEndpoints(
+    entryPoints: EntryPoint[],
+  ): Promise<APISecurityFinding[]> {
+    const findings: APISecurityFinding[] = [];
+
+    for (const ep of entryPoints) {
+      if (!ep.authentication) {
+        findings.push({
+          category: "Broken Authentication",
+          severity: "high",
+          endpoint: ep.path,
+          description: "No authentication detected",
+          recommendation: "Add authentication middleware",
+        });
+      }
+
+      if (!ep.rateLimit) {
+        findings.push({
+          category: "Unrestricted Resource Consumption",
+          severity: "medium",
+          endpoint: ep.path,
+          description: "No rate limiting detected",
+          recommendation: "Add rate limiting middleware",
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  private async buildAttackPaths(
+    _entryPoints: EntryPoint[],
+    _findings: APISecurityFinding[],
+  ): Promise<AttackPath[]> {
+    return [];
+  }
+
+  async generateVisualization(
+    analysis: AttackSurfaceAnalysisResult,
+  ): Promise<string> {
+    let mermaid = "graph TD\n";
+    mermaid += "  Start[External User]\n";
+
+    for (const ep of analysis.entryPoints) {
+      const epId = ep.path.replace(/[^a-zA-Z0-9]/g, "_");
+      mermaid += `  Start --> ${epId}[${ep.method} ${ep.path}]\n`;
+    }
+
+    return mermaid;
+  }
+}
+
+export const attackSurfaceAnalyzer = new AttackSurfaceAnalyzer();

package/src/attack-surface/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Attack Surface Analyzer
+ */
+
+export * from './analyzer';

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Guardrail Security Package
+ *
+ * Comprehensive security layer including:
+ * - Secrets & Credential Guardian
+ * - Supply Chain Attack Detection
+ * - License Compliance Engine
+ * - Attack Surface Analyzer
+ */
+
+export * from './secrets';
+export * from './supply-chain';
+export * from './license';
+export * from './attack-surface';
+export { 
+  SBOMGenerator, 
+  sbomGenerator,
+  type SBOMFormat,
+  type SBOMGeneratorOptions,
+  type SBOMDependency,
+} from './sbom';