guardrail-core 1.0.0

package/src/ci/github-actions.ts

@@ -0,0 +1,335 @@
+/**
+ * GitHub Actions Integration
+ * 
+ * Provides integration with GitHub Actions for automated security scanning
+ */
+
+export interface GitHubActionsConfig {
+  workflowName: string;
+  triggers: {
+    push?: { branches: string[] };
+    pullRequest?: { branches: string[] };
+    schedule?: { cron: string }[];
+    workflowDispatch?: boolean;
+  };
+  scanTypes: ('security' | 'secrets' | 'vulnerabilities' | 'compliance' | 'sbom')[];
+  failOnCritical: boolean;
+  failOnHigh: boolean;
+  uploadArtifacts: boolean;
+  createPRComments: boolean;
+}
+
+export interface WorkflowStep {
+  name: string;
+  uses?: string;
+  run?: string;
+  with?: Record<string, string | boolean | number>;
+  env?: Record<string, string>;
+  if?: string;
+}
+
+export interface WorkflowJob {
+  name: string;
+  runsOn: string;
+  permissions?: Record<string, string>;
+  steps: WorkflowStep[];
+}
+
+export interface GitHubWorkflow {
+  name: string;
+  on: Record<string, any>;
+  permissions?: Record<string, string>;
+  jobs: Record<string, WorkflowJob>;
+}
+
+export class GitHubActionsGenerator {
+  /**
+   * Generate a complete GitHub Actions workflow
+   */
+  generateWorkflow(config: GitHubActionsConfig): string {
+    const workflow: GitHubWorkflow = {
+      name: config.workflowName,
+      on: this.buildTriggers(config.triggers),
+      permissions: {
+        contents: 'read',
+        'security-events': 'write',
+        'pull-requests': config.createPRComments ? 'write' : 'read',
+      },
+      jobs: {
+        'Guardrail-scan': this.buildScanJob(config),
+      },
+    };
+
+    return this.toYAML(workflow);
+  }
+
+  /**
+   * Build workflow triggers
+   */
+  private buildTriggers(triggers: GitHubActionsConfig['triggers']): Record<string, any> {
+    const on: Record<string, any> = {};
+
+    if (triggers.push) {
+      on['push'] = { branches: triggers.push.branches };
+    }
+
+    if (triggers.pullRequest) {
+      on['pull_request'] = { branches: triggers.pullRequest.branches };
+    }
+
+    if (triggers.schedule) {
+      on['schedule'] = triggers.schedule.map(s => ({ cron: s.cron }));
+    }
+
+    if (triggers.workflowDispatch) {
+      on['workflow_dispatch'] = {};
+    }
+
+    return on;
+  }
+
+  /**
+   * Build the main scan job
+   */
+  private buildScanJob(config: GitHubActionsConfig): WorkflowJob {
+    const steps: WorkflowStep[] = [
+      {
+        name: 'Checkout code',
+        uses: 'actions/checkout@v4',
+        with: { 'fetch-depth': 0 },
+      },
+      {
+        name: 'Setup Node.js',
+        uses: 'actions/setup-node@v4',
+        with: { 'node-version': '20' },
+      },
+      {
+        name: 'Install dependencies',
+        run: 'npm ci',
+      },
+    ];
+
+    // Add scan steps based on config
+    if (config.scanTypes.includes('secrets')) {
+      steps.push({
+        name: 'Scan for secrets',
+        run: 'npx Guardrail scan:secrets --format sarif --output secrets-results.sarif',
+        env: { Guardrail_CI: 'true' },
+      });
+    }
+
+    if (config.scanTypes.includes('vulnerabilities')) {
+      steps.push({
+        name: 'Scan for vulnerabilities',
+        run: 'npx Guardrail scan:vulnerabilities --format sarif --output vuln-results.sarif',
+        env: { Guardrail_CI: 'true' },
+      });
+    }
+
+    if (config.scanTypes.includes('security')) {
+      steps.push({
+        name: 'Security scan',
+        run: 'npx Guardrail scan:security --format sarif --output security-results.sarif',
+        env: { Guardrail_CI: 'true' },
+      });
+    }
+
+    if (config.scanTypes.includes('compliance')) {
+      steps.push({
+        name: 'Compliance check',
+        run: 'npx Guardrail scan:compliance --format json --output compliance-results.json',
+        env: { Guardrail_CI: 'true' },
+      });
+    }
+
+    if (config.scanTypes.includes('sbom')) {
+      steps.push({
+        name: 'Generate SBOM',
+        run: 'npx Guardrail sbom:generate --format cyclonedx --output sbom.json',
+        env: { Guardrail_CI: 'true' },
+      });
+    }
+
+    // Upload SARIF results
+    steps.push({
+      name: 'Upload SARIF results',
+      uses: 'github/codeql-action/upload-sarif@v3',
+      with: {
+        'sarif_file': '.',
+        'category': 'Guardrail-security',
+      },
+      if: 'always()',
+    });
+
+    // Upload artifacts
+    if (config.uploadArtifacts) {
+      steps.push({
+        name: 'Upload scan artifacts',
+        uses: 'actions/upload-artifact@v4',
+        with: {
+          name: 'Guardrail-results',
+          path: '*.sarif\n*.json',
+          'retention-days': 30,
+        },
+        if: 'always()',
+      });
+    }
+
+    // Check results and fail if needed
+    steps.push({
+      name: 'Check scan results',
+      run: this.buildCheckScript(config),
+      env: { 
+        FAIL_ON_CRITICAL: String(config.failOnCritical),
+        FAIL_ON_HIGH: String(config.failOnHigh),
+      },
+    });
+
+    return {
+      name: 'Guardrail Security Scan',
+      runsOn: 'ubuntu-latest',
+      steps,
+    };
+  }
+
+  /**
+   * Build result check script
+   */
+  private buildCheckScript(config: GitHubActionsConfig): string {
+    return `
+npx Guardrail results:check \\
+  --fail-on-critical=${config.failOnCritical} \\
+  --fail-on-high=${config.failOnHigh}
+`.trim();
+  }
+
+  /**
+   * Convert workflow object to YAML
+   */
+  private toYAML(workflow: GitHubWorkflow): string {
+    const lines: string[] = [];
+
+    lines.push(`name: ${workflow.name}`);
+    lines.push('');
+    lines.push('on:');
+    lines.push(this.objectToYAML(workflow.on, 2));
+    lines.push('');
+
+    if (workflow.permissions) {
+      lines.push('permissions:');
+      for (const [key, value] of Object.entries(workflow.permissions)) {
+        lines.push(`  ${key}: ${value}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('jobs:');
+    for (const [jobId, job] of Object.entries(workflow.jobs)) {
+      lines.push(`  ${jobId}:`);
+      lines.push(`    name: ${job.name}`);
+      lines.push(`    runs-on: ${job.runsOn}`);
+      lines.push('    steps:');
+      
+      for (const step of job.steps) {
+        lines.push(`      - name: ${step.name}`);
+        if (step.uses) {
+          lines.push(`        uses: ${step.uses}`);
+        }
+        if (step.run) {
+          if (step.run.includes('\n')) {
+            lines.push('        run: |');
+            for (const line of step.run.split('\n')) {
+              lines.push(`          ${line}`);
+            }
+          } else {
+            lines.push(`        run: ${step.run}`);
+          }
+        }
+        if (step.with) {
+          lines.push('        with:');
+          for (const [key, value] of Object.entries(step.with)) {
+            if (typeof value === 'string' && value.includes('\n')) {
+              lines.push(`          ${key}: |`);
+              for (const line of value.split('\n')) {
+                lines.push(`            ${line}`);
+              }
+            } else {
+              lines.push(`          ${key}: ${value}`);
+            }
+          }
+        }
+        if (step.env) {
+          lines.push('        env:');
+          for (const [key, value] of Object.entries(step.env)) {
+            lines.push(`          ${key}: ${value}`);
+          }
+        }
+        if (step.if) {
+          lines.push(`        if: ${step.if}`);
+        }
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Convert object to YAML with indentation
+   */
+  private objectToYAML(obj: Record<string, any>, indent: number): string {
+    const lines: string[] = [];
+    const prefix = ' '.repeat(indent);
+
+    for (const [key, value] of Object.entries(obj)) {
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        lines.push(`${prefix}${key}:`);
+        lines.push(this.objectToYAML(value, indent + 2));
+      } else if (Array.isArray(value)) {
+        lines.push(`${prefix}${key}:`);
+        for (const item of value) {
+          if (typeof item === 'object') {
+            const entries = Object.entries(item);
+            if (entries.length > 0) {
+              const firstEntry = entries[0];
+              if (!firstEntry) continue;
+              const [firstKey, firstValue] = firstEntry;
+              lines.push(`${prefix}  - ${firstKey}: ${firstValue}`);
+              for (const [k, v] of entries.slice(1)) {
+                lines.push(`${prefix}    ${k}: ${v}`);
+              }
+            }
+          } else {
+            lines.push(`${prefix}  - ${item}`);
+          }
+        }
+      } else {
+        lines.push(`${prefix}${key}: ${value}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate default workflow for quick setup
+   */
+  generateDefaultWorkflow(): string {
+    return this.generateWorkflow({
+      workflowName: 'Guardrail Security Scan',
+      triggers: {
+        push: { branches: ['main', 'master'] },
+        pullRequest: { branches: ['main', 'master'] },
+        schedule: [{ cron: '0 0 * * 0' }], // Weekly on Sunday
+        workflowDispatch: true,
+      },
+      scanTypes: ['security', 'secrets', 'vulnerabilities', 'sbom'],
+      failOnCritical: true,
+      failOnHigh: false,
+      uploadArtifacts: true,
+      createPRComments: true,
+    });
+  }
+}
+
+// Export singleton
+export const githubActionsGenerator = new GitHubActionsGenerator();

package/src/ci/index.ts

@@ -0,0 +1,12 @@
+/**
+ * CI/CD Integration Module
+ * 
+ * Provides integrations for:
+ * - GitHub Actions
+ * - GitLab CI (future)
+ * - Jenkins (future)
+ * - Azure DevOps (future)
+ */
+
+export * from './github-actions';
+export * from './pre-commit';

package/src/ci/pre-commit.ts

@@ -0,0 +1,338 @@
+/**
+ * Pre-commit Hooks Integration
+ * 
+ * Generates pre-commit hook configurations for local validation
+ * before commits are pushed to the repository
+ */
+
+export interface PreCommitConfig {
+  scanSecrets: boolean;
+  scanVulnerabilities: boolean;
+  checkCompliance: boolean;
+  validateTypes: boolean;
+  runLint: boolean;
+  runTests: boolean;
+  blockOnCritical: boolean;
+  blockOnHigh: boolean;
+  maxFileSize: number; // in KB
+  excludePatterns: string[];
+}
+
+export interface HuskyConfig {
+  hooks: {
+    'pre-commit'?: string;
+    'pre-push'?: string;
+    'commit-msg'?: string;
+  };
+}
+
+export class PreCommitGenerator {
+  /**
+   * Generate Husky pre-commit configuration
+   */
+  generateHuskyConfig(config: PreCommitConfig): HuskyConfig {
+    const commands: string[] = [];
+
+    if (config.runLint) {
+      commands.push('npx lint-staged');
+    }
+
+    if (config.scanSecrets) {
+      commands.push('npx Guardrail scan:secrets --staged --fail-on-detection');
+    }
+
+    if (config.validateTypes) {
+      commands.push('npx tsc --noEmit');
+    }
+
+    return {
+      hooks: {
+        'pre-commit': commands.join(' && '),
+        'pre-push': this.generatePrePushCommands(config),
+        'commit-msg': 'npx commitlint --edit $1',
+      },
+    };
+  }
+
+  /**
+   * Generate pre-push commands
+   */
+  private generatePrePushCommands(config: PreCommitConfig): string {
+    const commands: string[] = [];
+
+    if (config.scanVulnerabilities) {
+      commands.push('npx Guardrail scan:vulnerabilities');
+    }
+
+    if (config.checkCompliance) {
+      commands.push('npx Guardrail scan:compliance');
+    }
+
+    if (config.runTests) {
+      commands.push('npm test');
+    }
+
+    return commands.join(' && ');
+  }
+
+  /**
+   * Generate .husky/pre-commit script
+   */
+  generatePreCommitScript(config: PreCommitConfig): string {
+    const lines: string[] = [
+      '#!/usr/bin/env sh',
+      '. "$(dirname -- "$0")/_/husky.sh"',
+      '',
+      '# Guardrail Pre-commit Hook',
+      '# Generated by Guardrail AI',
+      '',
+    ];
+
+    if (config.runLint) {
+      lines.push('echo "Running lint-staged..."');
+      lines.push('npx lint-staged || exit 1');
+      lines.push('');
+    }
+
+    if (config.scanSecrets) {
+      lines.push('echo "Scanning for secrets..."');
+      lines.push('npx Guardrail scan:secrets --staged --fail-on-detection || {');
+      lines.push('  echo "ERROR: Secrets detected in staged files!"');
+      lines.push('  echo "Please remove secrets before committing."');
+      lines.push('  exit 1');
+      lines.push('}');
+      lines.push('');
+    }
+
+    if (config.validateTypes) {
+      lines.push('echo "Checking TypeScript types..."');
+      lines.push('npx tsc --noEmit || exit 1');
+      lines.push('');
+    }
+
+    if (config.maxFileSize > 0) {
+      lines.push(`echo "Checking file sizes (max ${config.maxFileSize}KB)..."`);
+      lines.push(`MAX_SIZE=${config.maxFileSize * 1024}`);
+      lines.push('for file in $(git diff --cached --name-only); do');
+      lines.push('  if [ -f "$file" ]; then');
+      lines.push('    size=$(wc -c < "$file")');
+      lines.push('    if [ $size -gt $MAX_SIZE ]; then');
+      lines.push('      echo "ERROR: $file exceeds maximum file size"');
+      lines.push('      exit 1');
+      lines.push('    fi');
+      lines.push('  fi');
+      lines.push('done');
+      lines.push('');
+    }
+
+    lines.push('echo "Pre-commit checks passed!"');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate .husky/pre-push script
+   */
+  generatePrePushScript(config: PreCommitConfig): string {
+    const lines: string[] = [
+      '#!/usr/bin/env sh',
+      '. "$(dirname -- "$0")/_/husky.sh"',
+      '',
+      '# Guardrail Pre-push Hook',
+      '# Generated by Guardrail AI',
+      '',
+    ];
+
+    if (config.scanVulnerabilities) {
+      lines.push('echo "Scanning for vulnerabilities..."');
+      const failCondition = config.blockOnCritical 
+        ? (config.blockOnHigh ? '--fail-on-high' : '--fail-on-critical')
+        : '';
+      lines.push(`npx Guardrail scan:vulnerabilities ${failCondition} || {`);
+      lines.push('  echo "ERROR: Vulnerabilities detected!"');
+      lines.push('  exit 1');
+      lines.push('}');
+      lines.push('');
+    }
+
+    if (config.checkCompliance) {
+      lines.push('echo "Checking compliance..."');
+      lines.push('npx Guardrail scan:compliance || {');
+      lines.push('  echo "WARNING: Compliance issues detected"');
+      lines.push('}');
+      lines.push('');
+    }
+
+    if (config.runTests) {
+      lines.push('echo "Running tests..."');
+      lines.push('npm test || {');
+      lines.push('  echo "ERROR: Tests failed!"');
+      lines.push('  exit 1');
+      lines.push('}');
+      lines.push('');
+    }
+
+    lines.push('echo "Pre-push checks passed!"');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate lint-staged configuration
+   */
+  generateLintStagedConfig(config: PreCommitConfig): Record<string, string[]> {
+    const lintStaged: Record<string, string[]> = {};
+
+    // TypeScript/JavaScript files
+    lintStaged['*.{ts,tsx,js,jsx}'] = [
+      'eslint --fix',
+      'prettier --write',
+    ];
+
+    if (config.scanSecrets) {
+      lintStaged['*.{ts,tsx,js,jsx}'].push('Guardrail scan:secrets --file');
+    }
+
+    // JSON files
+    lintStaged['*.json'] = ['prettier --write'];
+
+    // Markdown files
+    lintStaged['*.md'] = ['prettier --write'];
+
+    // CSS/SCSS files
+    lintStaged['*.{css,scss}'] = ['prettier --write'];
+
+    return lintStaged;
+  }
+
+  /**
+   * Generate package.json scripts for hooks
+   */
+  generatePackageJsonScripts(): Record<string, string> {
+    return {
+      'prepare': 'husky install',
+      'pre-commit': 'lint-staged',
+      'Guardrail:secrets': 'Guardrail scan:secrets',
+      'Guardrail:vulnerabilities': 'Guardrail scan:vulnerabilities',
+      'Guardrail:compliance': 'Guardrail scan:compliance',
+      'Guardrail:full': 'Guardrail scan:all',
+    };
+  }
+
+  /**
+   * Generate commitlint configuration
+   */
+  generateCommitlintConfig(): Record<string, any> {
+    return {
+      extends: ['@commitlint/config-conventional'],
+      rules: {
+        'type-enum': [
+          2,
+          'always',
+          [
+            'feat',
+            'fix',
+            'docs',
+            'style',
+            'refactor',
+            'perf',
+            'test',
+            'build',
+            'ci',
+            'chore',
+            'revert',
+            'security',
+          ],
+        ],
+        'subject-case': [2, 'always', 'lower-case'],
+        'subject-max-length': [2, 'always', 72],
+        'body-max-line-length': [2, 'always', 100],
+      },
+    };
+  }
+
+  /**
+   * Generate default configuration
+   */
+  generateDefaultConfig(): PreCommitConfig {
+    return {
+      scanSecrets: true,
+      scanVulnerabilities: true,
+      checkCompliance: false,
+      validateTypes: true,
+      runLint: true,
+      runTests: false,
+      blockOnCritical: true,
+      blockOnHigh: false,
+      maxFileSize: 500, // 500KB
+      excludePatterns: [
+        'node_modules/**',
+        'dist/**',
+        'build/**',
+        '*.min.js',
+        '*.bundle.js',
+      ],
+    };
+  }
+
+  /**
+   * Generate setup instructions
+   */
+  generateSetupInstructions(): string {
+    return `
+# Guardrail Pre-commit Hooks Setup
+
+## Installation
+
+1. Install dependencies:
+\`\`\`bash
+npm install -D husky lint-staged @commitlint/cli @commitlint/config-conventional
+\`\`\`
+
+2. Initialize Husky:
+\`\`\`bash
+npx husky install
+\`\`\`
+
+3. Add prepare script to package.json:
+\`\`\`json
+{
+  "scripts": {
+    "prepare": "husky install"
+  }
+}
+\`\`\`
+
+4. Create pre-commit hook:
+\`\`\`bash
+npx husky add .husky/pre-commit "npx lint-staged"
+\`\`\`
+
+5. Create pre-push hook:
+\`\`\`bash
+npx husky add .husky/pre-push "npx Guardrail scan:vulnerabilities"
+\`\`\`
+
+## Configuration
+
+Add lint-staged config to package.json:
+\`\`\`json
+{
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"]
+  }
+}
+\`\`\`
+
+## Usage
+
+Hooks will run automatically on:
+- **Pre-commit**: Lint, format, and secret scanning
+- **Pre-push**: Vulnerability and compliance scanning
+- **Commit-msg**: Conventional commit validation
+`.trim();
+  }
+}
+
+// Export singleton
+export const preCommitGenerator = new PreCommitGenerator();