Sunbelt Computer Software

SBOM Manager

A comprehensive web-based application for generating, managing, and analyzing Software Bill of Materials (SBOM) with vulnerability tracking and license compliance in accordance with CERT-In Technical Guidelines v2.0.

🎯 Current Status

✅ Phase 1: Foundation - Complete
✅ Phase 2: Core Scanner - Complete
✅ Phase 3: Vulnerability & License Tracking - Complete
✅ Phase 4: Export, Authentication & Docker - Complete

🚀 Production Ready! Full Docker deployment with authentication and comprehensive export capabilities.

🚀 Key Features

✅ SBOM Generation

5 Ecosystem Support: Node.js, Python, Java, Go, Rust
12 File Formats: package.json, package-lock.json, requirements.txt, Pipfile, Pipfile.lock, pyproject.toml, pom.xml, build.gradle, build.gradle.kts, go.mod, go.sum, Cargo.toml, Cargo.lock
🆕 Multi-File Upload: Upload multiple dependency files in a single scan with drag-and-drop support
Mixed Ecosystems: Combine files from different package managers (e.g., package.json + requirements.txt)
Smart Deduplication: Automatically merges components from multiple files
File Validation: Real-time validation and ecosystem detection for uploaded files
SPDX 2.3 Compliant: Full specification support with validation
CERT-In Compliance: All 21 minimum data fields included
🆕 Auto-Enrichment: Automatic CPE, PURL, SWID, and dependency relationship population via NVD API
Automatic Scanning: Background vulnerability scanning after SBOM generation

✅ Vulnerability Tracking

NVD API Integration: National Vulnerability Database with CVSS scores
OSV API Fallback: Open Source Vulnerabilities for faster results
Smart Caching: 24-hour cache to avoid rate limits
Version Matching: Intelligent version range detection
Severity Classification: Critical, High, Medium, Low, None
Real-Time Dashboard: Live vulnerability summaries across all projects

✅ License Compliance

SPDX License Mapping: 14+ common licenses with automatic normalization
Policy Engine: 4 built-in policies (Commercial, Permissive, Open Source, Unrestricted)
Risk Scoring: Automatic risk level assignment (Low, Medium, High)
Policy Violations: Real-time alerts for non-compliant licenses
Compatibility Checking: Verify license compatibility across dependencies

✅ Advanced Dashboard

System Health Monitoring: Database and API status
Vulnerability Summary Cards: Color-coded by severity
License Breakdown: Risk distribution and top licenses
Policy Violation Alerts: Expandable alerts with component details
Recent Projects: Quick navigation to project details

✅ Authentication & Security (Phase 4)

JWT Authentication: Secure token-based auth with 7-day expiry
User Management: Email/password registration and login
Protected Routes: All app features require authentication
Password Security: bcrypt hashing with validation
Session Management: Automatic token refresh and logout

✅ Export Capabilities (Phase 4)

CSV Export: Components and vulnerabilities in tabular format
Excel (.xlsx): Multi-sheet workbooks with summary data
JSON Export: Native SBOM Manager format with full data
SPDX 2.3: Industry-standard SBOM format
CycloneDX 1.5: OWASP Bill of Materials format
Authenticated Downloads: Secure token-based file access

✅ Docker Deployment (Phase 4)

One-Command Setup: docker compose up for full stack
Multi-Service Architecture: Frontend, Backend, Database, Reverse Proxy
Health Monitoring: Automated health checks for all services
Auto-Migration: Database schema updates on startup
Production Ready: Optimized multi-stage builds
Data Persistence: PostgreSQL volumes for data retention

🏗️ Architecture

Tech Stack

Frontend: React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui + TanStack Query
Backend: Node.js 20 + Hono + Drizzle ORM
Database: PostgreSQL 14+
External APIs: NVD (vulnerabilities), OSV (vulnerabilities fallback)

Project Structure

sbom-manager/
├── backend/
│   ├── src/
│   │   ├── db/               # Database schema & migrations
│   │   ├── routes/           # API routes (REST)
│   │   ├── services/         # Business logic
│   │   │   ├── vulnerability-service.ts  # NVD/OSV integration
│   │   │   └── license-service.ts        # License policy engine
│   │   ├── scanner/          # SBOM generation
│   │   │   ├── parsers/      # Ecosystem parsers (npm, python, etc.)
│   │   │   └── generators/   # SPDX generator
│   │   └── index.ts          # Main server
│   └── drizzle/              # SQL migrations
├── frontend/
│   ├── src/
│   │   ├── components/       # React components
│   │   ├── pages/            # Page components
│   │   │   ├── Dashboard.tsx        # Enhanced with vuln/license
│   │   │   ├── ProjectDetail.tsx    # Vuln scanning & summaries
│   │   │   ├── Scanner.tsx          # File upload & directory scan
│   │   │   └── Projects.tsx         # Project management
│   │   ├── lib/
│   │   │   ├── api.ts        # API client with all endpoints
│   │   │   └── utils.ts      # Utilities
│   │   └── App.tsx
│   └── public/
├── test-projects/            # Sample projects for testing
├── docker-compose.yml        # PostgreSQL container
├── PRD.md                    # Product Requirements Document
├── PHASE1_COMPLETE.md        # Phase 1 documentation
├── PHASE2_COMPLETE.md        # Phase 2 documentation
└── PHASE3_COMPLETE.md        # Phase 3 documentation

📋 Prerequisites

Node.js >= 20.0.0 (Install Node.js)
npm >= 10.0.0 (comes with Node.js)
Docker (for PostgreSQL) OR PostgreSQL >= 14 installed locally
(Optional) NVD API Key for faster vulnerability scanning (Get API Key)

🚀 Quick Start (Docker - Recommended)

One-Command Deployment

# Clone the repository
git clone https://github.com/screwgoth/sbom-manager.git
cd sbom-manager

# (Optional) Configure JWT secret
cp .env.example .env
# Edit .env and set JWT_SECRET to a secure random string

# Start the entire stack
docker compose up -d

# Verify deployment
./verify-deployment.sh

# Access the app
open http://localhost

That's it! The application is now running with:

✅ Frontend on http://localhost
✅ Backend API on http://localhost:3000
✅ PostgreSQL database with auto-migration
✅ Nginx reverse proxy

First Steps:

Open http://localhost
Click "Create an account"
Register with email/password
Start generating SBOMs!

For detailed Docker deployment guide, see DOCKER_SETUP.md.

🛠️ Development Setup (Local)

1. Clone and Install

# Clone the repository
git clone https://github.com/screwgoth/sbom-manager.git
cd sbom-manager

# Install all dependencies
npm install

2. Start Database

# Using Docker (recommended)
docker compose up -d

# Verify
docker compose ps

3. Configure Environment

# Backend
cd backend
cp .env.example .env
# Edit .env:
# DATABASE_URL=postgresql://sbom_user:sbom_password@localhost:5432/sbom_manager
# NVD_API_KEY=your_nvd_api_key_here  # Optional but recommended

# Frontend
cd ../frontend
cp .env.example .env
# Edit .env:
# VITE_API_URL=http://localhost:3000/api

4. Run Migrations

cd backend
npm run db:migrate

5. Start Servers

Option A: Both servers together

# From project root
npm run dev

Option B: Separate terminals

# Terminal 1: Backend
cd backend && npm run dev

# Terminal 2: Frontend
cd frontend && npm run dev

6. Access the Application

Frontend: http://localhost:5173
Backend API: http://localhost:3000
Health Check: http://localhost:3000/api/health

🧪 Usage Guide

Generate SBOM for a Project

Navigate to Scanner: Click "Scanner" in the navigation bar
Select Mode:
- Upload Files: Upload dependency files (package.json, requirements.txt, etc.)
- Scan Directory: Enter path to project directory on server
Fill Project Details:
- Project name
- Version
- Author (optional)
Start Scan: Click "Start Scan"
View Results: After scan completes, click "View Results" to see SBOM

Scan for Vulnerabilities

Automatic Scanning:

Vulnerability scan automatically triggers after SBOM generation
Results appear in Dashboard and Project Detail within 30-60 seconds

Manual Scanning:

Go to Project Detail page
Expand SBOM details
Click "Scan Vulnerabilities" button
Wait for scan to complete (shows loading spinner)
Vulnerability summary updates automatically

Check License Compliance

Dashboard View:
- See aggregated license risk distribution
- View policy violations across all projects
- Check top licenses used
Project Detail View:
- Expand SBOM to see per-SBOM license summary
- View components with risk-based license badges
- Identify policy violations

Change License Policy

Policies are configurable in the API. Default is "Commercial" policy which:

✅ Allows: MIT, Apache-2.0, BSD, ISC (Permissive licenses)
❌ Blocks: GPL-2.0, GPL-3.0, AGPL-3.0 (Strong copyleft)
⚠️ Warns: LGPL, MPL, EPL (Weak copyleft)

To change policy, update API calls with ?policy=permissive or ?policy=open-source.

📊 Supported Ecosystems

Ecosystem	Files Supported	Parser Status	PURL Format
Node.js	package.json, package-lock.json	✅	pkg:npm/name@version
Python	requirements.txt, Pipfile, Pipfile.lock, pyproject.toml	✅	pkg:pypi/name@version
Java	pom.xml, build.gradle, build.gradle.kts	✅	pkg:maven/group/artifact@version
Go	go.mod, go.sum	✅	pkg:golang/module@version
Rust	Cargo.toml, Cargo.lock	✅	pkg:cargo/crate@version

🔧 Development

Backend Commands

cd backend

npm run dev          # Start dev server with hot reload
npm run build        # Build for production
npm run start        # Start production server
npm run db:generate  # Generate new migrations
npm run db:migrate   # Run pending migrations
npm run db:studio    # Open Drizzle Studio (DB GUI)

Frontend Commands

cd frontend

npm run dev          # Start Vite dev server
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Run ESLint

Testing

# Test scanner with sample projects
cd /path/to/sbom-manager
node test-scanner.js

# Test specific parser
cd backend
npx tsx src/scanner/parsers/npm.ts

📡 API Endpoints

Core Endpoints

GET /api/health - System health check
GET /api/projects - List all projects
POST /api/projects - Create project
GET /api/projects/:id - Get project details
GET /api/sboms/project/:projectId - Get SBOMs for project
GET /api/components/sbom/:sbomId - Get components for SBOM

Scanner Endpoints

POST /api/scanner/scan/upload - Upload and scan files
POST /api/scanner/scan/directory - Scan directory path
POST /api/scanner/detect - Detect ecosystem from files

Analysis Endpoints (Phase 3)

Vulnerabilities:

POST /api/analysis/vulnerabilities/scan/:sbomId - Trigger vuln scan
GET /api/analysis/vulnerabilities/summary/:sbomId - Get summary
GET /api/analysis/vulnerabilities/component/:componentId - Component vulns

Licenses:

GET /api/analysis/licenses/summary/:sbomId?policy=commercial - License summary
GET /api/analysis/licenses/component/:componentId?policy=commercial - Component license
GET /api/analysis/licenses/policies - Available policies

See PHASE3_COMPLETE.md for detailed API documentation.

🔒 Security & Performance

API Rate Limiting

NVD API:
- Without key: 6 seconds between requests
- With key: 0.6 seconds between requests
OSV API: No rate limit (open source)

Caching

Vulnerability data cached for 24 hours
Cache stored in memory (lost on restart)
Cache hit rate: ~80% after initial scan

Sensitive Data

NVD API key stored in environment variable (never exposed to frontend)
Only package names and versions sent to external APIs
No proprietary source code transmitted

🐛 Troubleshooting

Database Issues

# Check if PostgreSQL is running
docker compose ps

# View logs
docker compose logs postgres

# Reset database (WARNING: deletes all data)
docker compose down -v
docker compose up -d
cd backend && npm run db:migrate

Vulnerability Scan Not Working

Check NVD API Key: Make sure NVD_API_KEY is set in backend/.env
Check Rate Limiting: Without API key, scans are slower (6s per component)
Check Logs: Run backend with npm run dev and watch console output
Verify Network: Ensure server can reach services.nvd.nist.gov and api.osv.dev

Port Conflicts

# Change backend port
# Edit backend/.env: PORT=3001

# Change frontend port
# Edit frontend/vite.config.ts: server: { port: 5174 }

# Update frontend API URL
# Edit frontend/.env: VITE_API_URL=http://localhost:3001/api

Build Errors

# Clear cache and reinstall
rm -rf node_modules backend/node_modules frontend/node_modules package-lock.json
npm install

# Rebuild backend
cd backend && npm run build

# Rebuild frontend
cd frontend && npm run build

📚 Documentation

PRD.md - Product Requirements Document
PHASE1_COMPLETE.md - Foundation implementation
PHASE2_COMPLETE.md - Scanner implementation
PHASE3_COMPLETE.md - Vulnerability & license tracking
🆕 MULTI_FILE_UPLOAD.md - Multi-file upload feature guide

External Resources

🎯 Roadmap

✅ Completed

Phase 1: Foundation (Database, API, UI framework)
Phase 2: Core Scanner (5 ecosystem parsers, SPDX generation)
Phase 3: Vulnerability & License Tracking (NVD/OSV integration, policy engine)

🔜 Phase 4: Export & Polish (Next)

🔮 Future Enhancements

CI/CD integration (GitHub Actions, GitLab CI)
Container image scanning
Dependency graph visualization
Historical vulnerability tracking
Team collaboration features
RBAC (Role-Based Access Control)
SBOM signing and verification
Scheduled background scans
Redis cache for distributed systems

📊 Statistics

Code Metrics

Features Delivered

✅ 5 ecosystem parsers
✅ 12 dependency file formats
✅ SPDX 2.3 generation and validation
✅ 21 CERT-In minimum data fields
✅ NVD + OSV vulnerability scanning
✅ 14+ SPDX license mappings
✅ 4 license policy templates
✅ 20+ API endpoints
✅ 6 UI pages with responsive design

🤝 Contributing

Contributions are welcome! Please read the PRD and existing phase documentation before submitting PRs.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License. See LICENSE file for details.

👥 Authors

ScrewMolt - Initial development and architecture

🙏 Acknowledgments

CERT-In for SBOM guidelines
SPDX community for specifications
NVD and OSV for vulnerability data
Open source community for ecosystem parsers

Status: Phase 3 Complete ✅ | Ready for Phase 4 🚀

For detailed implementation notes, see phase documentation:

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
frontend		frontend
test-multi-upload		test-multi-upload
test-projects		test-projects
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CERT_IN_IMPLEMENTATION.md		CERT_IN_IMPLEMENTATION.md
CHANGELOG.md		CHANGELOG.md
DESIGN_SYSTEM.md		DESIGN_SYSTEM.md
ENRICHMENT_COMPLETE.md		ENRICHMENT_COMPLETE.md
IMPLEMENTATION_SUMMARY.txt		IMPLEMENTATION_SUMMARY.txt
MIGRATION_COMPLETE.txt		MIGRATION_COMPLETE.txt
MULTI_FILE_FEATURE_COMPLETE.md		MULTI_FILE_FEATURE_COMPLETE.md
README.md		README.md
REDESIGN_SUMMARY.txt		REDESIGN_SUMMARY.txt
THEME_REFERENCE.md		THEME_REFERENCE.md
UI_IMPROVEMENTS_SUMMARY.md		UI_IMPROVEMENTS_SUMMARY.md
UI_REDESIGN_COMPLETE.md		UI_REDESIGN_COMPLETE.md
UI_UX_IMPROVEMENTS_COMPLETE.md		UI_UX_IMPROVEMENTS_COMPLETE.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
nginx-proxy.conf		nginx-proxy.conf
package-lock.json		package-lock.json
package.json		package.json
setup.sh		setup.sh
test-e2e.sh		test-e2e.sh
test-multi-file-upload.sh		test-multi-file-upload.sh
test-scanner.js		test-scanner.js
verify-deployment.sh		verify-deployment.sh

Phase	Backend LOC	Frontend LOC	Total
Phase 1	~800	~400	~1,200
Phase 2	~1,200	~350	~1,550
Phase 3	~1,157	~865	~2,022
Total	~3,157	~1,615	~4,772