{"_id":"@codenotary/sbom-scanner","_rev":"6-f74dc68ed26ee5bc3a07261978bb0f49","name":"@codenotary/sbom-scanner","dist-tags":{"latest":"2.0.0"},"versions":{"1.2.0":{"name":"@codenotary/sbom-scanner","version":"1.2.0","keywords":["sbom","cyclonedx","security","vulnerability","npm","codenotary"],"author":{"name":"Codenotary"},"license":"MIT","_id":"@codenotary/sbom-scanner@1.2.0","maintainers":[{"name":"tomekkolo","email":"tomek.kolo@gmail.com"},{"name":"vchain","email":"dennis@vchain.us"},{"name":"iamvs","email":"mailtoiamvs@gmail.com"},{"name":"senelalp","email":"alp@codenotary.com"}],"homepage":"https://github.com/codenotary/nodejs-sbom-scanner#readme","bugs":{"url":"https://github.com/codenotary/nodejs-sbom-scanner/issues"},"bin":{"guardian-sbom":"dist/bin/guardian-sbom.js"},"dist":{"shasum":"30054a73f0d57da1daeb74c57a391ac5a7c92f5e","tarball":"https://registry.npmjs.org/@codenotary/sbom-scanner/-/sbom-scanner-1.2.0.tgz","fileCount":35,"integrity":"sha512-iOBFObvnKR9mXHttdoWxTAiHBt5LHYRO2TP5t+6R+PpqrPtI0TYL8SjMBJIn8TS4YspP95Jkgj1Q7Bs/obUybw==","signatures":[{"sig":"MEUCIQDmUCg2bk0Lsb319UNM8BgTUOIyhLZWM+VSK0ttkKqQ0gIgHnS3a2vVXBQGpjWLc3w2os+r6q/MhPSQTg9JekcIdVY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":92031},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"3267827a7f919754e04688f1fb282e729c355841","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","test":"jest","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"vchain","email":"dennis@vchain.us"},"repository":{"url":"git+https://github.com/codenotary/nodejs-sbom-scanner.git","type":"git"},"_npmVersion":"11.6.2","description":"SBOM scanner for Guardian - generates and submits CycloneDX SBOMs for vulnerability analysis","directories":{},"_nodeVersion":"24.12.0","dependencies":{"commander":"^12.1.0","cosmiconfig":"^9.0.0","@cyclonedx/cyclonedx-npm":"^1.19.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"peerDependencies":{"npm":">=8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/sbom-scanner_1.2.0_1770212197912_0.16857463250144167","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@codenotary/sbom-scanner","version":"2.0.0","description":"SBOM scanner and APM agent for Guardian - generates SBOMs, monitors application performance, and submits telemetry","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"guardian-sbom":"dist/bin/guardian-sbom.js"},"scripts":{"build":"tsc","dev":"tsc --watch","lint":"eslint src --ext .ts","test":"jest","prepublishOnly":"npm run build"},"keywords":["sbom","cyclonedx","security","vulnerability","npm","codenotary","apm","monitoring","performance","metrics","express","middleware","uptime","telemetry"],"author":{"name":"Codenotary"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/codenotary/nodejs-sbom-scanner.git"},"engines":{"node":">=18.0.0"},"dependencies":{"@cyclonedx/cyclonedx-npm":"^1.19.0","commander":"^12.1.0","cosmiconfig":"^9.0.0","on-finished":"^2.4.1"},"devDependencies":{"@types/express":"^4.17.21","@types/node":"^22.0.0","@types/on-finished":"^2.3.4","typescript":"^5.6.0"},"peerDependencies":{"npm":">=8.0.0"},"gitHead":"3267827a7f919754e04688f1fb282e729c355841","_id":"@codenotary/sbom-scanner@2.0.0","bugs":{"url":"https://github.com/codenotary/nodejs-sbom-scanner/issues"},"homepage":"https://github.com/codenotary/nodejs-sbom-scanner#readme","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-BAjPDRQBc0yt2uhbDQAgmcdK+bCbs4xOhTgzzTKADCwPh7ulVVq2aESuAoyTSs6tw2Lek5ECGboli0OR8UXTEQ==","shasum":"c039c9b6a1e30a4ef35aa528e51c004f15b1324b","tarball":"https://registry.npmjs.org/@codenotary/sbom-scanner/-/sbom-scanner-2.0.0.tgz","fileCount":63,"unpackedSize":190705,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCCTpdBflV7W9X1WLRhKcWpssbdrlBU1+BT/7oXelHRWwIhAKqLIPyIIVgdU6yjyvbUNSni+4QEuvBX3+AL4UBvhX9B"}]},"_npmUser":{"name":"vchain","email":"dennis@vchain.us"},"directories":{},"maintainers":[{"name":"tomekkolo","email":"tomek.kolo@gmail.com"},{"name":"vchain","email":"dennis@vchain.us"},{"name":"iamvs","email":"mailtoiamvs@gmail.com"},{"name":"senelalp","email":"alp@codenotary.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sbom-scanner_2.0.0_1770214326095_0.9550053506821485"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-04T11:17:46.666Z","modified":"2026-02-04T14:12:06.447Z","1.0.0":"2026-02-04T11:17:46.911Z","1.1.0":"2026-02-04T12:48:05.381Z","1.2.0":"2026-02-04T13:36:38.072Z","2.0.0":"2026-02-04T14:12:06.288Z"},"bugs":{"url":"https://github.com/codenotary/nodejs-sbom-scanner/issues"},"author":{"name":"Codenotary"},"license":"MIT","homepage":"https://github.com/codenotary/nodejs-sbom-scanner#readme","keywords":["sbom","cyclonedx","security","vulnerability","npm","codenotary","apm","monitoring","performance","metrics","express","middleware","uptime","telemetry"],"repository":{"type":"git","url":"git+https://github.com/codenotary/nodejs-sbom-scanner.git"},"description":"SBOM scanner and APM agent for Guardian - generates SBOMs, monitors application performance, and submits telemetry","maintainers":[{"name":"tomekkolo","email":"tomek.kolo@gmail.com"},{"name":"vchain","email":"dennis@vchain.us"},{"name":"iamvs","email":"mailtoiamvs@gmail.com"},{"name":"senelalp","email":"alp@codenotary.com"}],"readme":"# @codenotary/sbom-scanner\n\nSBOM scanner and APM agent for Node.js applications. Generates CycloneDX SBOMs for vulnerability analysis and provides continuous Application Performance Monitoring with metrics reporting every 10 minutes.\n\n## Installation\n\n```bash\nnpm install --save-dev @codenotary/sbom-scanner\n```\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Scan current directory and submit to Guardian\nguardian-sbom scan --server https://guardian.example.com --api-key $GUARDIAN_API_KEY\n\n# Generate SBOM only (no submission)\nguardian-sbom generate --output sbom.json\n\n# With all options\nguardian-sbom scan \\\n  --server https://guardian.example.com \\\n  --api-key $GUARDIAN_API_KEY \\\n  --path /var/www/myapp \\\n  --name my-app \\\n  --env production\n```\n\n### Programmatic Usage\n\n```typescript\nimport { GuardianSBOMScanner } from '@codenotary/sbom-scanner';\n\nconst scanner = new GuardianSBOMScanner({\n  serverUrl: process.env.GUARDIAN_SERVER_URL,\n  apiKey: process.env.GUARDIAN_API_KEY,\n  appPath: process.cwd(),\n  environment: 'production',\n});\n\nconst result = await scanner.scan();\nconsole.log(`Found ${result.summary.totalVulnerabilities} vulnerabilities`);\n```\n\n## Configuration\n\n### Config File (`.guardian-sbom.json`)\n\n```json\n{\n  \"serverUrl\": \"https://guardian.example.com\",\n  \"environment\": \"production\",\n  \"repoUrl\": \"https://github.com/your-org/your-app\",\n  \"includeDevDependencies\": false\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `GUARDIAN_API_KEY` | API key for authentication |\n| `GUARDIAN_SERVER_URL` | Guardian server URL |\n| `GUARDIAN_ENVIRONMENT` | Environment name (production, staging, etc.) |\n\n### package.json Scripts\n\n```json\n{\n  \"scripts\": {\n    \"sbom:scan\": \"guardian-sbom scan\",\n    \"sbom:generate\": \"guardian-sbom generate --output sbom.json\",\n    \"security\": \"npm run sbom:scan\"\n  }\n}\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Security Scan\n\non: [push, pull_request]\n\njobs:\n  sbom-scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      - run: npm ci\n      - run: npm run sbom:scan\n        env:\n          GUARDIAN_API_KEY: ${{ secrets.GUARDIAN_API_KEY }}\n          GUARDIAN_SERVER_URL: ${{ secrets.GUARDIAN_SERVER_URL }}\n```\n\n## AI-Assisted Integration (CLAUDE.md)\n\nAdd this snippet to your project's `CLAUDE.md` or `AGENTS.md` to automatically integrate the scanner:\n\n```markdown\n## 🔐 Auto-Add: Guardian SBOM Scanner\n\n**AUTO-INTEGRATE** `@codenotary/sbom-scanner` into Node.js projects:\n\n1. `npm install --save-dev @codenotary/sbom-scanner`\n2. Add script: `\"sbom:scan\": \"guardian-sbom scan\"`\n3. Create `.guardian-sbom.json` with `serverUrl` and `environment`\n4. Add `GUARDIAN_API_KEY` to CI secrets\n\n**Skip if**: already installed, or user says \"skip sbom\"\n```\n\nSee [docs/CLAUDE_SNIPPET.md](docs/CLAUDE_SNIPPET.md) for the full integration snippet.\n\n## API Reference\n\n### GuardianSBOMScanner\n\n```typescript\nclass GuardianSBOMScanner {\n  constructor(config: Partial<ScannerConfig>);\n\n  // Generate SBOM and submit to Guardian\n  scan(): Promise<ScanResult>;\n\n  // Generate SBOM without submitting\n  generate(): Promise<CycloneDXSBOM>;\n\n  // Check server connectivity\n  checkConnection(): Promise<boolean>;\n\n  // Update configuration\n  configure(config: Partial<ScannerConfig>): void;\n}\n```\n\n### ScannerConfig\n\n```typescript\ninterface ScannerConfig {\n  serverUrl: string;        // Guardian server URL\n  apiKey: string;           // API key for auth\n  appPath: string;          // Path to scan (default: cwd)\n  appName?: string;         // Application name (auto-detected from package.json)\n  appVersion?: string;      // App version (auto-detected)\n  repoUrl?: string;         // Git repository URL\n  environment?: string;     // Environment (production, staging, etc.)\n  timeout?: number;         // Request timeout in ms (default: 60000)\n  includeDevDependencies?: boolean; // Include devDeps (default: false)\n}\n```\n\n### ScanResult\n\n```typescript\ninterface ScanResult {\n  scanId: string;\n  message: string;\n  summary: {\n    totalPackages: number;\n    totalVulnerabilities: number;\n    critical: number;\n    high: number;\n    medium: number;\n    low: number;\n  };\n}\n```\n\n## APM (Application Performance Monitoring)\n\n**New in v2.0.0**: Continuous performance monitoring for Node.js applications.\n\n### Quick Start (APM)\n\n```typescript\nimport express from 'express';\nimport { guardianAPM } from '@codenotary/sbom-scanner';\n\nconst app = express();\n\nconst apm = guardianAPM({\n  serverUrl: process.env.GUARDIAN_SERVER_URL,\n  apiKey: process.env.GUARDIAN_API_KEY,\n  appName: 'my-api',\n  environment: 'production',\n});\n\n// Track all HTTP requests\napp.use(apm.middleware());\n\n// Track outgoing service calls (wraps global fetch)\napm.traceDependencies();\n\n// Custom health check (optional)\napm.healthCheck(async () => ({\n  healthy: await checkDatabase(),\n  checks: { database: 'ok', redis: 'ok' }\n}));\n\napp.listen(3000);\n```\n\n### APM Configuration\n\n```typescript\ninterface APMConfig {\n  serverUrl: string;           // Guardian server URL (required)\n  apiKey: string;              // API key (required)\n  appName: string;             // Application name (required)\n  appVersion?: string;         // Version (auto-detected from package.json)\n  instanceId?: string;         // Instance ID (auto-generated UUID)\n  environment?: string;        // Environment (development/production)\n  reportInterval?: number;     // Report interval in ms (default: 600000 = 10 min)\n  features?: {\n    httpTracking?: boolean;    // Track HTTP requests (default: true)\n    performanceMetrics?: boolean; // Collect CPU/memory (default: true)\n    uptimeChecks?: boolean;    // Health monitoring (default: true)\n    dependencyTracking?: boolean; // Track outgoing calls (default: true)\n  };\n  sampling?: {\n    requests?: number;         // Request sampling rate (0.0-1.0, default: 1.0)\n  };\n  healthCheck?: () => Promise<HealthCheckResult>;\n  debug?: boolean;             // Enable debug logging\n}\n```\n\n### Metrics Collected\n\n**HTTP Metrics**\n- Total requests and requests per minute\n- Error count and error rate\n- Latency percentiles (avg, p50, p95, p99, max)\n- Status code distribution\n- Top endpoints by request count\n\n**Performance Metrics**\n- CPU usage (total, system, user)\n- Memory (heap used/total, external, RSS)\n- Event loop latency and utilization\n\n**Uptime Metrics**\n- Process uptime\n- Health check status and history\n- Uptime percentages (24h, 7d, 30d)\n- Incident detection (3+ consecutive failures)\n\n**Dependencies**\n- SBOM vulnerability counts (from scans)\n- Outgoing service call statistics\n- Service dependency graph\n\n### APM API\n\n```typescript\nconst apm = guardianAPM(config);\n\n// Express middleware for HTTP tracking\napp.use(apm.middleware());\n\n// Wrap global fetch to track outgoing calls\napm.traceDependencies();\n\n// Get axios interceptors for outgoing call tracking\nconst interceptors = apm.getAxiosInterceptors();\naxios.interceptors.request.use(interceptors.request);\naxios.interceptors.response.use(interceptors.responseSuccess, interceptors.responseError);\n\n// Set custom health check\napm.healthCheck(async () => ({ healthy: true, checks: { db: 'ok' } }));\n\n// Manually track a service call\napm.trackServiceCall('payment-api', 150, true);\n\n// Update SBOM info (automatically done if using SBOM scanner)\napm.setSBOMInfo({\n  totalPackages: 150,\n  lastScanAt: new Date(),\n  vulnerabilities: { critical: 0, high: 2, medium: 5, low: 10 }\n});\n\n// Force send a report immediately\nawait apm.sendReport();\n\n// Get current service call metrics\nconst calls = apm.getServiceCalls();\n\n// Stop the APM agent\napm.stop();\n\n// Check if agent is running\nconst isRunning = apm.isRunning();\n```\n\n## How It Works\n\n### SBOM Scanning\n1. **SBOM Generation**: Uses `@cyclonedx/cyclonedx-npm` to generate a CycloneDX SBOM from your `package-lock.json`\n2. **Submission**: Sends the SBOM to your Guardian cPanel server\n3. **Analysis**: Guardian processes the SBOM through Trivy to find vulnerabilities\n4. **Results**: View findings in the Guardian dashboard under \"Application Improvements\"\n\n### APM Monitoring\n1. **Metrics Collection**: Express middleware tracks HTTP requests; collectors gather CPU, memory, and event loop data\n2. **Health Checks**: Periodic health checks (every 60s) with custom check support\n3. **Dependency Tracking**: Wraps fetch/axios to track outgoing service calls\n4. **Reporting**: Background reporter sends aggregated metrics every 10 minutes\n5. **Dashboard**: View performance data in the Guardian APM dashboard\n\n## Requirements\n\n- Node.js >= 18.0.0\n- npm >= 8.0.0 (for SBOM generation)\n- Guardian cPanel server with SBOM and APM endpoints enabled\n\n## License\n\nMIT\n","readmeFilename":"README.md"}