guardrail-security 1.0.0

package/src/sbom/generator.ts

@@ -0,0 +1,355 @@
+/**
+ * SBOM (Software Bill of Materials) Generator
+ * 
+ * Generates SBOMs in CycloneDX and SPDX formats for compliance and security
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+
+export type SBOMFormat = 'cyclonedx' | 'spdx' | 'json';
+
+export interface SBOMComponent {
+  type: 'library' | 'framework' | 'application' | 'file' | 'container';
+  name: string;
+  version: string;
+  purl?: string;
+  licenses: string[];
+  hashes?: { algorithm: string; content: string }[];
+  description?: string;
+  author?: string;
+  supplier?: string;
+  externalReferences?: { type: string; url: string }[];
+}
+
+export interface SBOMDependency {
+  ref: string;
+  dependsOn: string[];
+}
+
+export interface SBOM {
+  format: SBOMFormat;
+  specVersion: string;
+  serialNumber: string;
+  version: number;
+  metadata: {
+    timestamp: string;
+    tools: { vendor: string; name: string; version: string }[];
+    component: {
+      type: string;
+      name: string;
+      version: string;
+    };
+    authors?: { name: string; email?: string }[];
+  };
+  components: SBOMComponent[];
+  dependencies: SBOMDependency[];
+}
+
+export interface SBOMGeneratorOptions {
+  format: SBOMFormat;
+  includeDevDependencies?: boolean;
+  includeLicenses?: boolean;
+  includeHashes?: boolean;
+  outputPath?: string;
+}
+
+export class SBOMGenerator {
+  private readonly toolInfo = {
+    vendor: 'Guardrail AI',
+    name: 'Guardrail-sbom-generator',
+    version: '1.0.0',
+  };
+
+  /**
+   * Generate SBOM for a project
+   */
+  async generate(projectPath: string, options: SBOMGeneratorOptions): Promise<SBOM> {
+    const packageJsonPath = join(projectPath, 'package.json');
+    
+    if (!existsSync(packageJsonPath)) {
+      throw new Error('package.json not found in project path');
+    }
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const components = await this.extractComponents(projectPath, packageJson, options);
+    const dependencies = this.buildDependencyGraph(packageJson, options);
+
+    const sbom: SBOM = {
+      format: options.format,
+      specVersion: options.format === 'cyclonedx' ? '1.5' : '2.3',
+      serialNumber: `urn:uuid:${this.generateUUID()}`,
+      version: 1,
+      metadata: {
+        timestamp: new Date().toISOString(),
+        tools: [this.toolInfo],
+        component: {
+          type: 'application',
+          name: packageJson.name || 'unknown',
+          version: packageJson.version || '0.0.0',
+        },
+        authors: packageJson.author ? [{ name: packageJson.author }] : undefined,
+      },
+      components,
+      dependencies,
+    };
+
+    if (options.outputPath) {
+      await this.writeSBOM(sbom, options.outputPath, options.format);
+    }
+
+    return sbom;
+  }
+
+  /**
+   * Extract components from package.json
+   */
+  private async extractComponents(
+    projectPath: string,
+    packageJson: any,
+    options: SBOMGeneratorOptions
+  ): Promise<SBOMComponent[]> {
+    const components: SBOMComponent[] = [];
+    const deps = { ...packageJson.dependencies };
+    
+    if (options.includeDevDependencies) {
+      Object.assign(deps, packageJson.devDependencies);
+    }
+
+    for (const [name, version] of Object.entries(deps)) {
+      const versionStr = String(version).replace(/^[\^~]/, '');
+      
+      const component: SBOMComponent = {
+        type: 'library',
+        name,
+        version: versionStr,
+        purl: `pkg:npm/${name}@${versionStr}`,
+        licenses: [],
+      };
+
+      // Try to get license info
+      if (options.includeLicenses) {
+        const license = await this.getLicenseForPackage(projectPath, name);
+        if (license) {
+          component.licenses = [license];
+        }
+      }
+
+      // Generate hashes if requested
+      if (options.includeHashes) {
+        const packagePath = join(projectPath, 'node_modules', name, 'package.json');
+        if (existsSync(packagePath)) {
+          const content = readFileSync(packagePath, 'utf-8');
+          component.hashes = [
+            { algorithm: 'SHA-256', content: this.hashContent(content, 'sha256') },
+            { algorithm: 'SHA-512', content: this.hashContent(content, 'sha512') },
+          ];
+        }
+      }
+
+      components.push(component);
+    }
+
+    return components;
+  }
+
+  /**
+   * Build dependency graph
+   */
+  private buildDependencyGraph(packageJson: any, options: SBOMGeneratorOptions): SBOMDependency[] {
+    const dependencies: SBOMDependency[] = [];
+    const rootRef = `pkg:npm/${packageJson.name}@${packageJson.version}`;
+    
+    const deps = Object.keys(packageJson.dependencies || {});
+    const devDeps = options.includeDevDependencies 
+      ? Object.keys(packageJson.devDependencies || {})
+      : [];
+
+    // Root dependency
+    dependencies.push({
+      ref: rootRef,
+      dependsOn: [...deps, ...devDeps].map(name => {
+        const version = packageJson.dependencies?.[name] || packageJson.devDependencies?.[name];
+        return `pkg:npm/${name}@${String(version).replace(/^[\^~]/, '')}`;
+      }),
+    });
+
+    return dependencies;
+  }
+
+  /**
+   * Get license for a package
+   */
+  private async getLicenseForPackage(projectPath: string, packageName: string): Promise<string | null> {
+    const packagePath = join(projectPath, 'node_modules', packageName, 'package.json');
+    
+    if (existsSync(packagePath)) {
+      try {
+        const pkgJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+        return pkgJson.license || null;
+      } catch {
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Hash content
+   */
+  private hashContent(content: string, algorithm: string): string {
+    return createHash(algorithm).update(content).digest('hex');
+  }
+
+  /**
+   * Generate UUID
+   */
+  private generateUUID(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === 'x' ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+
+  /**
+   * Write SBOM to file
+   */
+  private async writeSBOM(sbom: SBOM, outputPath: string, format: SBOMFormat): Promise<void> {
+    let content: string;
+    
+    switch (format) {
+      case 'cyclonedx':
+        content = this.toCycloneDXJSON(sbom);
+        break;
+      case 'spdx':
+        content = this.toSPDXJSON(sbom);
+        break;
+      default:
+        content = JSON.stringify(sbom, null, 2);
+    }
+
+    writeFileSync(outputPath, content, 'utf-8');
+  }
+
+  /**
+   * Convert to CycloneDX JSON format
+   */
+  toCycloneDXJSON(sbom: SBOM): string {
+    const cyclonedx = {
+      bomFormat: 'CycloneDX',
+      specVersion: '1.5',
+      serialNumber: sbom.serialNumber,
+      version: sbom.version,
+      metadata: {
+        timestamp: sbom.metadata.timestamp,
+        tools: sbom.metadata.tools.map(t => ({
+          vendor: t.vendor,
+          name: t.name,
+          version: t.version,
+        })),
+        component: {
+          type: sbom.metadata.component.type,
+          name: sbom.metadata.component.name,
+          version: sbom.metadata.component.version,
+          'bom-ref': `pkg:npm/${sbom.metadata.component.name}@${sbom.metadata.component.version}`,
+        },
+      },
+      components: sbom.components.map(c => ({
+        type: c.type,
+        name: c.name,
+        version: c.version,
+        purl: c.purl,
+        'bom-ref': c.purl,
+        licenses: c.licenses.map(l => ({ license: { id: l } })),
+        hashes: c.hashes?.map(h => ({ alg: h.algorithm, content: h.content })),
+      })),
+      dependencies: sbom.dependencies.map(d => ({
+        ref: d.ref,
+        dependsOn: d.dependsOn,
+      })),
+    };
+
+    return JSON.stringify(cyclonedx, null, 2);
+  }
+
+  /**
+   * Convert to SPDX JSON format
+   */
+  toSPDXJSON(sbom: SBOM): string {
+    const spdx = {
+      spdxVersion: 'SPDX-2.3',
+      dataLicense: 'CC0-1.0',
+      SPDXID: 'SPDXRef-DOCUMENT',
+      name: sbom.metadata.component.name,
+      documentNamespace: `https://Guardrail.ai/sbom/${sbom.serialNumber}`,
+      creationInfo: {
+        created: sbom.metadata.timestamp,
+        creators: [`Tool: ${sbom.metadata.tools[0]?.name}-${sbom.metadata.tools[0]?.version}`],
+      },
+      packages: sbom.components.map((c, i) => ({
+        SPDXID: `SPDXRef-Package-${i}`,
+        name: c.name,
+        versionInfo: c.version,
+        downloadLocation: `https://registry.npmjs.org/${c.name}/-/${c.name}-${c.version}.tgz`,
+        filesAnalyzed: false,
+        licenseConcluded: c.licenses[0] || 'NOASSERTION',
+        licenseDeclared: c.licenses[0] || 'NOASSERTION',
+        copyrightText: 'NOASSERTION',
+        externalRefs: c.purl ? [{
+          referenceCategory: 'PACKAGE-MANAGER',
+          referenceType: 'purl',
+          referenceLocator: c.purl,
+        }] : [],
+      })),
+      relationships: [
+        {
+          spdxElementId: 'SPDXRef-DOCUMENT',
+          relatedSpdxElement: 'SPDXRef-Package-0',
+          relationshipType: 'DESCRIBES',
+        },
+        ...sbom.components.slice(1).map((_, i) => ({
+          spdxElementId: 'SPDXRef-Package-0',
+          relatedSpdxElement: `SPDXRef-Package-${i + 1}`,
+          relationshipType: 'DEPENDS_ON',
+        })),
+      ],
+    };
+
+    return JSON.stringify(spdx, null, 2);
+  }
+
+  /**
+   * Validate SBOM structure
+   */
+  validateSBOM(sbom: SBOM): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    if (!sbom.metadata?.component?.name) {
+      errors.push('Missing component name in metadata');
+    }
+
+    if (!sbom.components || sbom.components.length === 0) {
+      errors.push('No components found in SBOM');
+    }
+
+    for (const component of sbom.components) {
+      if (!component.name) {
+        errors.push('Component missing name');
+      }
+      if (!component.version) {
+        errors.push(`Component ${component.name} missing version`);
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}
+
+// Export singleton
+export const sbomGenerator = new SBOMGenerator();

package/src/sbom/index.ts

@@ -0,0 +1,5 @@
+/**
+ * SBOM (Software Bill of Materials) Module
+ */
+
+export * from './generator';