ngx-security-audit 1.0.0

package/src/config.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CONFIG = {
+  // Severity threshold for exit code (critical, high, medium, low, info)
+  threshold: 'high',
+  // Output format (console, json, html, sarif)
+  format: 'console',
+  // Output file for report
+  output: null,
+  // Directories to scan (relative to project root)
+  include: ['src/**/*.ts', 'src/**/*.html', 'src/**/*.js'],
+  // Patterns to ignore
+  exclude: [],
+  // Rules to disable
+  disabledRules: [],
+  // Rules to treat as specific severity (overrides)
+  ruleOverrides: {},
+  // Verbose output
+  verbose: false,
+};
+
+/**
+ * Load configuration from .ngsecurityrc.json or package.json
+ */
+function loadConfig(projectPath, cliOptions = {}) {
+  let fileConfig = {};
+
+  // Try .ngsecurityrc.json
+  const rcPath = path.join(projectPath, '.ngsecurityrc.json');
+  if (fs.existsSync(rcPath)) {
+    try {
+      const content = fs.readFileSync(rcPath, 'utf-8');
+      fileConfig = JSON.parse(content);
+    } catch {
+      // Ignore invalid config
+    }
+  }
+
+  // Try package.json "ngxSecurityAudit" key
+  if (Object.keys(fileConfig).length === 0) {
+    const pkgPath = path.join(projectPath, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg.ngxSecurityAudit) {
+          fileConfig = pkg.ngxSecurityAudit;
+        }
+      } catch {
+        // Ignore
+      }
+    }
+  }
+
+  // Merge: defaults <- file config <- CLI options
+  return {
+    ...DEFAULT_CONFIG,
+    ...fileConfig,
+    ...cliOptions,
+  };
+}
+
+module.exports = { loadConfig, DEFAULT_CONFIG };

package/src/index.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const Scanner = require('./scanner');
+const { getReporter } = require('./reporters');
+const { SEVERITY, calculateScore, getGrade } = require('./utils/severity');
+const allRules = require('./rules');
+
+/**
+ * Run security audit on an Angular project
+ * @param {string} projectPath - Path to the Angular project root
+ * @param {object} options - Configuration options
+ * @returns {Promise<object>} Audit result
+ */
+async function audit(projectPath, options = {}) {
+  const scanner = new Scanner(projectPath, options);
+  return scanner.scan();
+}
+
+/**
+ * Generate formatted report from audit result
+ * @param {object} result - Audit result from audit()
+ * @param {string} format - Report format (console, json, html, sarif)
+ * @returns {string} Formatted report
+ */
+function generateReport(result, format = 'console') {
+  const reporter = getReporter(format);
+  return reporter(result);
+}
+
+/**
+ * List all available security rules
+ * @returns {Array} List of rule objects
+ */
+function listRules() {
+  return allRules.map((rule) => ({
+    id: rule.id,
+    name: rule.name,
+    description: rule.description,
+    category: rule.category,
+    severity: rule.severity,
+    owasp: rule.owasp,
+    cwe: rule.cwe,
+  }));
+}
+
+module.exports = {
+  audit,
+  generateReport,
+  listRules,
+  Scanner,
+  SEVERITY,
+  calculateScore,
+  getGrade,
+};

package/src/reporters/console-reporter.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const chalk = require('chalk');
+const { SEVERITY_COLORS, SEVERITY_LABELS, SEVERITY } = require('../utils/severity');
+
+/**
+ * Console Reporter - Beautiful terminal output with colors
+ */
+function consoleReport(result) {
+  const lines = [];
+
+  // Header
+  lines.push('');
+  lines.push(chalk.bold.cyan('╔══════════════════════════════════════════════════════════════╗'));
+  lines.push(chalk.bold.cyan('║') + chalk.bold.white('          NGX SECURITY AUDIT REPORT                         ') + chalk.bold.cyan('║'));
+  lines.push(chalk.bold.cyan('╚══════════════════════════════════════════════════════════════╝'));
+  lines.push('');
+
+  // Project info
+  lines.push(chalk.bold('  Project:  ') + chalk.white(result.projectName || 'Unknown'));
+  lines.push(chalk.bold('  Angular:  ') + chalk.white(result.angularVersion || 'Unknown'));
+  lines.push(chalk.bold('  Date:     ') + chalk.white(new Date(result.scanDate).toLocaleString()));
+  lines.push(chalk.bold('  Files:    ') + chalk.white(`${result.filesScanned} scanned`));
+  lines.push(chalk.bold('  Rules:    ') + chalk.white(`${result.rulesExecuted} executed`));
+  lines.push('');
+
+  // Score
+  const scoreColor = result.score >= 80 ? 'green' : result.score >= 60 ? 'yellow' : 'red';
+  lines.push(chalk.bold('  ┌─────────────────────────────────────┐'));
+  lines.push(chalk.bold('  │  Security Score: ') + chalk.bold[scoreColor](`${result.score}/100 (Grade: ${result.grade})`) + chalk.bold('      │'));
+  lines.push(chalk.bold('  └─────────────────────────────────────┘'));
+  lines.push('');
+
+  // Summary
+  lines.push(chalk.bold('  FINDINGS SUMMARY'));
+  lines.push(chalk.bold('  ─────────────────────────────────────'));
+  if (result.summary.critical > 0) {
+    lines.push(chalk.red(`  ● CRITICAL:  ${result.summary.critical}`));
+  }
+  if (result.summary.high > 0) {
+    lines.push(chalk.redBright(`  ● HIGH:      ${result.summary.high}`));
+  }
+  if (result.summary.medium > 0) {
+    lines.push(chalk.yellow(`  ● MEDIUM:    ${result.summary.medium}`));
+  }
+  if (result.summary.low > 0) {
+    lines.push(chalk.cyan(`  ● LOW:       ${result.summary.low}`));
+  }
+  if (result.summary.info > 0) {
+    lines.push(chalk.gray(`  ● INFO:      ${result.summary.info}`));
+  }
+  lines.push(chalk.bold(`  ─────────────────────────────────────`));
+  lines.push(chalk.bold(`  TOTAL:       ${result.summary.total}`));
+  lines.push('');
+
+  // Detailed findings
+  if (result.findings.length > 0) {
+    lines.push(chalk.bold('  DETAILED FINDINGS'));
+    lines.push(chalk.bold('  ═══════════════════════════════════════════════════════════'));
+    lines.push('');
+
+    // Group by severity
+    const severityOrder = [SEVERITY.CRITICAL, SEVERITY.HIGH, SEVERITY.MEDIUM, SEVERITY.LOW, SEVERITY.INFO];
+
+    for (const severity of severityOrder) {
+      const severityFindings = result.findings.filter((f) => f.severity === severity);
+      if (severityFindings.length === 0) continue;
+
+      const color = SEVERITY_COLORS[severity];
+      const label = SEVERITY_LABELS[severity];
+
+      lines.push(chalk[color].bold(`  ── ${label} (${severityFindings.length}) ──────────────────────────`));
+      lines.push('');
+
+      for (let i = 0; i < severityFindings.length; i++) {
+        const finding = severityFindings[i];
+        lines.push(chalk[color].bold(`  ${i + 1}. [${finding.ruleId}]`));
+        lines.push(chalk.white(`     ${finding.message}`));
+        lines.push(chalk.gray(`     File: ${finding.file}${finding.line ? `:${finding.line}` : ''}`));
+
+        if (finding.code) {
+          lines.push(chalk.gray('     ┌──────────────────────────────'));
+          const codeLines = finding.code.split('\n');
+          for (const codeLine of codeLines) {
+            lines.push(chalk.gray(`     │ ${codeLine}`));
+          }
+          lines.push(chalk.gray('     └──────────────────────────────'));
+        }
+
+        if (finding.recommendation) {
+          lines.push(chalk.green(`     ✓ ${finding.recommendation}`));
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  // Footer
+  lines.push(chalk.bold('  ═══════════════════════════════════════════════════════════'));
+  if (result.passed) {
+    lines.push(chalk.green.bold(`  ✅ PASSED - No findings at or above "${result.threshold}" severity threshold`));
+  } else {
+    lines.push(chalk.red.bold(`  ❌ FAILED - Found issues at or above "${result.threshold}" severity threshold`));
+  }
+  lines.push(chalk.gray(`  Threshold: ${result.threshold} | Exit code: ${result.passed ? 0 : 1}`));
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = consoleReport;

package/src/reporters/html-reporter.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const { SEVERITY, SEVERITY_LABELS } = require('../utils/severity');
+
+/**
+ * HTML Reporter - Beautiful HTML report for stakeholders
+ */
+function htmlReport(result) {
+  const severityColors = {
+    [SEVERITY.CRITICAL]: '#dc2626',
+    [SEVERITY.HIGH]: '#ea580c',
+    [SEVERITY.MEDIUM]: '#d97706',
+    [SEVERITY.LOW]: '#2563eb',
+    [SEVERITY.INFO]: '#6b7280',
+  };
+
+  const scoreColor = result.score >= 80 ? '#16a34a' : result.score >= 60 ? '#d97706' : '#dc2626';
+
+  const findingsHtml = result.findings
+    .sort((a, b) => {
+      const order = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+      return (order[a.severity] || 5) - (order[b.severity] || 5);
+    })
+    .map((f) => `
+      <div class="finding finding-${f.severity}">
+        <div class="finding-header">
+          <span class="badge" style="background:${severityColors[f.severity]}">${SEVERITY_LABELS[f.severity]}</span>
+          <span class="rule-id">${escapeHtml(f.ruleId)}</span>
+          <span class="category">${escapeHtml(f.category)}</span>
+        </div>
+        <p class="finding-message">${escapeHtml(f.message)}</p>
+        <div class="finding-meta">
+          <span>📁 ${escapeHtml(f.file)}${f.line ? `:${f.line}` : ''}</span>
+        </div>
+        ${f.code ? `<pre class="code-block"><code>${escapeHtml(f.code)}</code></pre>` : ''}
+        ${f.recommendation ? `<div class="recommendation">✅ <strong>Recommendation:</strong> ${escapeHtml(f.recommendation)}</div>` : ''}
+      </div>
+    `)
+    .join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>NGX Security Audit Report - ${escapeHtml(result.projectName || 'Angular Project')}</title>
+  <style>
+    :root {
+      --bg: #0f172a;
+      --surface: #1e293b;
+      --surface2: #334155;
+      --text: #f1f5f9;
+      --text-dim: #94a3b8;
+      --accent: #38bdf8;
+      --success: #22c55e;
+      --danger: #ef4444;
+      --border: #475569;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: 'Segoe UI', system-ui, -apple-system, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; }
+    .container { max-width: 1200px; margin: 0 auto; padding: 2rem; }
+    header { text-align: center; padding: 3rem 0; border-bottom: 1px solid var(--border); margin-bottom: 2rem; }
+    header h1 { font-size: 2.5rem; background: linear-gradient(135deg, #38bdf8, #818cf8); -webkit-background-clip: text; -webkit-text-fill-color: transparent; margin-bottom: 0.5rem; }
+    header .subtitle { color: var(--text-dim); font-size: 1.1rem; }
+    .info-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
+    .info-card { background: var(--surface); border-radius: 12px; padding: 1.5rem; border: 1px solid var(--border); }
+    .info-card label { color: var(--text-dim); font-size: 0.85rem; text-transform: uppercase; letter-spacing: 0.05em; }
+    .info-card .value { font-size: 1.3rem; font-weight: 600; margin-top: 0.25rem; }
+    .score-section { text-align: center; padding: 3rem; background: var(--surface); border-radius: 16px; margin-bottom: 2rem; border: 1px solid var(--border); }
+    .score-circle { display: inline-flex; align-items: center; justify-content: center; width: 160px; height: 160px; border-radius: 50%; border: 8px solid ${scoreColor}; margin-bottom: 1rem; }
+    .score-number { font-size: 3rem; font-weight: 800; color: ${scoreColor}; }
+    .score-grade { font-size: 1.5rem; color: ${scoreColor}; font-weight: 700; }
+    .status { display: inline-block; padding: 0.5rem 2rem; border-radius: 50px; font-weight: 700; font-size: 1.1rem; margin-top: 1rem; }
+    .status-pass { background: rgba(34, 197, 94, 0.15); color: #22c55e; border: 2px solid #22c55e; }
+    .status-fail { background: rgba(239, 68, 68, 0.15); color: #ef4444; border: 2px solid #ef4444; }
+    .summary-grid { display: grid; grid-template-columns: repeat(5, 1fr); gap: 1rem; margin-bottom: 2rem; }
+    .summary-card { background: var(--surface); border-radius: 12px; padding: 1.2rem; text-align: center; border: 1px solid var(--border); }
+    .summary-card .count { font-size: 2rem; font-weight: 800; }
+    .summary-card .label { color: var(--text-dim); font-size: 0.85rem; text-transform: uppercase; }
+    .findings-section h2 { font-size: 1.5rem; margin-bottom: 1rem; padding-bottom: 0.5rem; border-bottom: 2px solid var(--accent); }
+    .finding { background: var(--surface); border-radius: 12px; padding: 1.5rem; margin-bottom: 1rem; border-left: 4px solid var(--border); border: 1px solid var(--border); }
+    .finding-critical { border-left-color: #dc2626; }
+    .finding-high { border-left-color: #ea580c; }
+    .finding-medium { border-left-color: #d97706; }
+    .finding-low { border-left-color: #2563eb; }
+    .finding-info { border-left-color: #6b7280; }
+    .finding-header { display: flex; align-items: center; gap: 0.75rem; margin-bottom: 0.75rem; flex-wrap: wrap; }
+    .badge { padding: 0.2rem 0.75rem; border-radius: 50px; color: white; font-size: 0.75rem; font-weight: 700; text-transform: uppercase; }
+    .rule-id { font-family: monospace; color: var(--accent); font-size: 0.9rem; }
+    .category { color: var(--text-dim); font-size: 0.85rem; background: var(--surface2); padding: 0.15rem 0.5rem; border-radius: 4px; }
+    .finding-message { margin-bottom: 0.75rem; }
+    .finding-meta { color: var(--text-dim); font-size: 0.85rem; margin-bottom: 0.75rem; }
+    .code-block { background: #0d1117; border-radius: 8px; padding: 1rem; overflow-x: auto; margin: 0.75rem 0; border: 1px solid #30363d; }
+    .code-block code { font-family: 'Cascadia Code', 'Fira Code', monospace; font-size: 0.85rem; color: #c9d1d9; white-space: pre; }
+    .recommendation { background: rgba(34, 197, 94, 0.08); border: 1px solid rgba(34, 197, 94, 0.2); border-radius: 8px; padding: 0.75rem 1rem; font-size: 0.9rem; color: #86efac; }
+    footer { text-align: center; padding: 2rem 0; color: var(--text-dim); border-top: 1px solid var(--border); margin-top: 2rem; font-size: 0.85rem; }
+    @media (max-width: 768px) {
+      .summary-grid { grid-template-columns: repeat(2, 1fr); }
+      .info-grid { grid-template-columns: 1fr; }
+      header h1 { font-size: 1.8rem; }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>🛡️ NGX Security Audit Report</h1>
+      <p class="subtitle">Angular Application Security Analysis powered by ngx-security-audit</p>
+    </header>
+
+    <div class="info-grid">
+      <div class="info-card">
+        <label>Project</label>
+        <div class="value">${escapeHtml(result.projectName || 'Angular Project')}</div>
+      </div>
+      <div class="info-card">
+        <label>Angular Version</label>
+        <div class="value">${escapeHtml(result.angularVersion || 'Unknown')}</div>
+      </div>
+      <div class="info-card">
+        <label>Scan Date</label>
+        <div class="value">${new Date(result.scanDate).toLocaleDateString()}</div>
+      </div>
+      <div class="info-card">
+        <label>Files Scanned</label>
+        <div class="value">${result.filesScanned}</div>
+      </div>
+      <div class="info-card">
+        <label>Rules Executed</label>
+        <div class="value">${result.rulesExecuted}</div>
+      </div>
+    </div>
+
+    <div class="score-section">
+      <div class="score-circle">
+        <span class="score-number">${result.score}</span>
+      </div>
+      <div class="score-grade">Grade: ${result.grade}</div>
+      <div class="status ${result.passed ? 'status-pass' : 'status-fail'}">
+        ${result.passed ? '✅ PASSED' : '❌ FAILED'} (threshold: ${escapeHtml(result.threshold)})
+      </div>
+    </div>
+
+    <div class="summary-grid">
+      <div class="summary-card">
+        <div class="count" style="color:#dc2626">${result.summary.critical}</div>
+        <div class="label">Critical</div>
+      </div>
+      <div class="summary-card">
+        <div class="count" style="color:#ea580c">${result.summary.high}</div>
+        <div class="label">High</div>
+      </div>
+      <div class="summary-card">
+        <div class="count" style="color:#d97706">${result.summary.medium}</div>
+        <div class="label">Medium</div>
+      </div>
+      <div class="summary-card">
+        <div class="count" style="color:#2563eb">${result.summary.low}</div>
+        <div class="label">Low</div>
+      </div>
+      <div class="summary-card">
+        <div class="count" style="color:#6b7280">${result.summary.info}</div>
+        <div class="label">Info</div>
+      </div>
+    </div>
+
+    <div class="findings-section">
+      <h2>Detailed Findings (${result.summary.total})</h2>
+      ${result.findings.length === 0 ? '<p style="color: #22c55e; text-align: center; padding: 2rem;">🎉 No security issues found! Your Angular application passed all checks.</p>' : findingsHtml}
+    </div>
+
+    <footer>
+      <p>Generated by <strong>ngx-security-audit v1.0.0</strong> | ${new Date(result.scanDate).toISOString()}</p>
+      <p>OWASP Top 10 Aligned | ${result.rulesExecuted} Security Rules | Angular-Specific Analysis</p>
+    </footer>
+  </div>
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+module.exports = htmlReport;

package/src/reporters/index.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const consoleReport = require('./console-reporter');
+const jsonReport = require('./json-reporter');
+const htmlReport = require('./html-reporter');
+const sarifReport = require('./sarif-reporter');
+
+const reporters = {
+  console: consoleReport,
+  json: jsonReport,
+  html: htmlReport,
+  sarif: sarifReport,
+};
+
+function getReporter(format) {
+  const reporter = reporters[format];
+  if (!reporter) {
+    throw new Error(`Unknown report format: "${format}". Available formats: ${Object.keys(reporters).join(', ')}`);
+  }
+  return reporter;
+}
+
+module.exports = { getReporter, reporters };

package/src/reporters/json-reporter.js

@@ -0,0 +1,10 @@
+'use strict';
+
+/**
+ * JSON Reporter - Machine-readable output for CI/CD pipelines
+ */
+function jsonReport(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = jsonReport;

package/src/reporters/sarif-reporter.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { SEVERITY } = require('../utils/severity');
+
+/**
+ * SARIF Reporter - Static Analysis Results Interchange Format
+ * Compatible with GitHub Code Scanning, Azure DevOps, and other SARIF tools
+ * Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ */
+function sarifReport(result) {
+  const severityToLevel = {
+    [SEVERITY.CRITICAL]: 'error',
+    [SEVERITY.HIGH]: 'error',
+    [SEVERITY.MEDIUM]: 'warning',
+    [SEVERITY.LOW]: 'note',
+    [SEVERITY.INFO]: 'note',
+  };
+
+  const severityToRank = {
+    [SEVERITY.CRITICAL]: 9.5,
+    [SEVERITY.HIGH]: 8.0,
+    [SEVERITY.MEDIUM]: 5.0,
+    [SEVERITY.LOW]: 3.0,
+    [SEVERITY.INFO]: 1.0,
+  };
+
+  // Build unique rules list
+  const ruleMap = new Map();
+  for (const finding of result.findings) {
+    if (!ruleMap.has(finding.ruleId)) {
+      ruleMap.set(finding.ruleId, {
+        id: finding.ruleId,
+        name: finding.ruleId.replace(/\//g, '-'),
+        shortDescription: { text: finding.message.substring(0, 200) },
+        fullDescription: { text: finding.message },
+        defaultConfiguration: {
+          level: severityToLevel[finding.severity] || 'warning',
+          rank: severityToRank[finding.severity] || 5.0,
+        },
+        properties: {
+          tags: ['security', finding.category || 'general'],
+        },
+      });
+    }
+  }
+
+  // Build results
+  const results = result.findings.map((finding) => {
+    const sarifResult = {
+      ruleId: finding.ruleId,
+      level: severityToLevel[finding.severity] || 'warning',
+      message: {
+        text: finding.message,
+      },
+      locations: [],
+    };
+
+    if (finding.file && finding.file !== 'project-wide') {
+      sarifResult.locations.push({
+        physicalLocation: {
+          artifactLocation: {
+            uri: finding.file.replace(/\\/g, '/'),
+            uriBaseId: '%SRCROOT%',
+          },
+          region: {
+            startLine: finding.line || 1,
+            startColumn: 1,
+          },
+        },
+      });
+    }
+
+    if (finding.recommendation) {
+      sarifResult.fixes = [
+        {
+          description: { text: finding.recommendation },
+        },
+      ];
+    }
+
+    return sarifResult;
+  });
+
+  const sarif = {
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'ngx-security-audit',
+            version: '1.0.0',
+            informationUri: 'https://github.com/noredinebahri/ngx-security-audit',
+            rules: Array.from(ruleMap.values()),
+          },
+        },
+        results,
+        invocations: [
+          {
+            executionSuccessful: true,
+            endTimeUtc: result.scanDate,
+          },
+        ],
+      },
+    ],
+  };
+
+  return JSON.stringify(sarif, null, 2);
+}
+
+module.exports = sarifReport;