UBEL: Free SCA, dependencies/Linux packages/Docker firewall, and AI-assisted SAST

Notifications You must be signed in to change notification settings

Fork 0

Star 4

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

182 Commits

182 Commits

node

node

python

python

tests

tests

vscode

vscode

.gitignore

.gitignore

DISCLAIMER.md

DISCLAIMER.md

LICENSE.md

LICENSE.md

README.md

README.md

ubel_logo.svg

ubel_logo.svg

Repository files navigation

Multi-Ecosystem Supply-Chain Security Platform

Ubel resolves dependencies, generates PURLs, scans them through OSV.dev and NVD, and enforces configurable security policies at install-time to block supply-chain attacks before they reach production.

!

What is UBEL?

UBEL is a software composition analysis (SCA) tool and install-blocking firewall built for developers and teams who care about what enters their supply chain at every layer. Unlike report-only scanners, UBEL enforces policy — if a scan fails, it blocks the operation and tells you exactly why.

It spans the entire delivery chain: from the moment a developer adds a dependency, through CI validation, to what is running on a deployment server or inside an AI agent's runtime environment.

Repository Structure

ubel/ ├── python/ # Python CLI — ubel-pip, ubel (Linux host scanner) ├── node/ # Node.js CLI — ubel-npm, ubel-pnpm, ubel-bun, ubel-agent, ubel-platform └── vscode/ # VS Code extension — bundles the node/ engine at package time

The VS Code extension imports the Node.js engine directly from node/src/ at package time via the prepackage script — no separate install step required when building locally.

Features

Full dependency resolution with PURL generation across all supported ecosystems

Vulnerability scanning via batched queries to OSV.dev and NVD's APIs

Concurrent enrichment (CVSS, EPSS, fix recommendations, references) with up to 40 parallel threads

Policy engine — block/allow by severity threshold and unknown-severity packages

Malicious package detection (MAL-* advisories) — always blocked regardless of policy

check mode — dry-run resolution and scan with no side effects

install mode — scan-gate before installation; blocks if policy violated

health mode — scan the current project's installed dependencies

Full-stack monorepo scanning — all supported ecosystems in a single pass

Platform scanning — Linux (dpkg/apk/rpm) and Windows (registry/PowerShell), no elevated privileges required

Atomic lockfile revert with TOCTOU SHA-256 integrity protection (Node.js)

Automatic report generation: timestamped JSON + HTML + SBOM (*.cdx.json) + SARIF (*.sarif.json) per scan, plus latest.* convenience links

Zero external runtime dependencies (stdlib only, in both Python and Node.js)

Complete, compliant, and enriched SBOM CycloneDX v1.6 with full dependency graph and vulnerabilities in VEX format

Complete, compliant, and enriched SARIF v2.1.0 output

Supported Ecosystems

Project / Repository Scanning

Ecosystem Package Manager Resolved From

Node.js npm, pnpm, yarn, bun node_modules/ (on-disk walk)

Python pip / virtualenv .dist-info / .egg-info inside venv site-packages/

PHP Composer vendor/

Rust Cargo Cargo.lock

Go Go Modules go.sum

C# / .NET NuGet packages.lock.json / obj/project.assets.json

Java / Kotlin Maven pom.xml resolved dependencies

Ruby Bundler Gemfile.lock

Each discovered package is deduplicated by PURL before submission — packages shared across sub-projects are scanned exactly once.

Platform Scanning (Linux)

Distribution Package Manager Source PURL type

Ubuntu dpkg /var/lib/dpkg/status pkg:deb/ubuntu/

Debian dpkg /var/lib/dpkg/status pkg:deb/debian/

Alpine / Alpaquita apk /lib/apk/db/installed pkg:apk/alpine/

Red Hat / RHEL rpm rpm -qa pkg:rpm/redhat/

AlmaLinux rpm rpm -qa pkg:rpm/almalinux/

Rocky Linux rpm rpm -qa pkg:rpm/rocky-linux/

CentOS / Fedora rpm rpm -qa pkg:rpm/redhat/

Platform Scanning (Windows)

Detected via registry probes and PowerShell — no elevated privileges required.

Category Components

Operating system Windows 10 / 11 (build-accurate CPE version)

Security Windows Defender

Runtimes Node.js, Python, PHP, Go, Rust, Ruby, JRE, JDK

.NET All installed .NET Core / Desktop / ASP.NET runtimes (multi-version)

Browsers Chrome, Firefox, Microsoft Edge

Developer tools Git, Docker Desktop, VS Code, Cursor

Shell PowerShell

Vulnerabilities are matched using CPE 2.3 identifiers against the CVE/NVD database.

Components

python/ — Python CLI

pip install ubel-python

Binary Purpose

ubel-pip Python / PyPI ecosystem (virtualenv scanning, dry-run installs)

ubel Linux host OS package scanning (dpkg, apk, rpm)

Requirements: Python >= 3.8, pip available in the target virtual environment.

See python/README.md for full documentation.

node/ — Node.js CLI

npm install -g @arcane-spark/ubel-node

Binary Purpose

ubel-npm npm ecosystem

ubel-pnpm pnpm ecosystem

ubel-bun bun ecosystem

ubel-agent AI agent workspace scan (OS, runtimes, tools, dependencies)

ubel-platform Host platform scan (OS, runtimes, tools)

Requirements: Node.js >= 18.0.0, target package manager binary on PATH.

yarn does not support a lockfile-only dry-run — yarn add always writes node_modules. UBEL supports yarn in health mode only and cannot provide install-blocking firewall coverage for it.

See node/README.md for full documentation.

vscode/ — VS Code Extension

From the Marketplace:

ext install Arcane-Spark.ubel-vscode

From VSIX:

Download ubel-vscode-extension.vsix from the releases page.

Open the Command Palette → Extensions: Install from VSIX…

Select the downloaded file.

Requirements: Node.js >= 18.0.0, VS Code ^1.85.0.

Command Shortcut (Win/Linux) Shortcut (Mac) What it scans

UBEL: Scan Project Ctrl+Alt+U Cmd+Alt+U All ecosystems inside the open workspace folder

UBEL: Scan Code Editor's Extensions Ctrl+Alt+X Cmd+Alt+X npm packages inside installed VS Code / Cursor extensions

UBEL: Scan Host Platform Ctrl+Alt+P Cmd+Alt+P System software installed on this machine

See vscode/README.md for full documentation.

Firewall Mechanics (Node.js)

ubel-npm/pnpm/bun check and install invoke the package manager's lockfile-only flag, resolving the full dependency tree and writing a candidate lockfile without touching node_modules/. UBEL scans the candidate lockfile, then makes a binary decision:

Clean — the candidate lockfile is accepted and the actual install proceeds.

Violation — the lockfile is reverted to its pre-scan state from the disk backup. node_modules/ is never touched.

Before any real install is allowed to proceed, SHA-256 digests of the candidate lockfile and package.json are re-verified to close the TOCTOU window between scan and install.

All three package managers are invoked with --ignore-scripts to block malicious pre/post install scripts.

Policy

Policy is stored as JSON at .ubel/local/policy/config.json relative to the project root (Linux host scanner and the VS Code extension's host scan use ~/.ubel/).

Default policy created on first run:

{ "severity_threshold": "high", "block_unknown_vulnerabilities": true }

Field Values Default Behaviour

severity_threshold low medium high critical none high Block packages at or above this severity

block_unknown_vulnerabilities true false true Block packages with CVEs but no CVSS score

Infections (MAL-*) — always blocked Cannot be toggled; unconditionally blocked

The threshold is inclusive — high blocks both high and critical. Setting none disables severity blocking but infections are still blocked.

Reports

Every scan writes files to a timestamped path and overwrites the latest.* convenience links:

.ubel/reports/latest.json .ubel/reports/latest.html .ubel/reports/latest.cdx.json .ubel/reports/latest.sarif.json

.ubel/local/reports////// __.json .html .cdx.json __.sarif.json

The HTML report is fully self-contained (no server required) and includes:

Dashboard with severity breakdown chart and policy decision

Searchable, filterable vulnerability table

Full inventory with state (safe / vulnerable / infected / undetermined)

Interactive force-directed dependency graph with vulnerable-subtree filter

Per-vulnerability detail modals (CVSS vector, fix recommendations, OSV/NVD references)

System and runtime metadata

The SBOM is a fully valid CycloneDX v1.6 document including all components, their dependency relationships, and enriched vulnerability data in VEX format. The SARIF output is a fully valid SARIF v2.1.0 file with deterministic SHA-256 fingerprinting per finding.

CI/CD Integration

All CLI commands exit non-zero on policy violations:

GitHub Actions

• name: UBEL dependency scan

run: ubel-npm check # or ubel-pip check

• name: UBEL firewall-gated install

run: ubel-npm install # or ubel-pip install

Dockerfile

RUN ubel-npm install RUN ubel-pip install

Programmatic API

Both engines expose a main() entry point for agents, CI tools, and the VS Code extension.

Node.js:

import { main } from "@arcane-spark/ubel-node";

const report = await main({ projectRoot : "/abs/path/to/project", engine : "npm", mode : "health", is_script : true, save_reports: true, scan_os : false, full_stack : false, scan_node : true, scan_scope : "repository", // repository | agent | developer_platform | editor_extension });

Python:

from ubel.main import main

report = main({ "project_root": "/abs/path/to/project", "engine": "pip", "mode": "health", "packages": [], "is_script": True, "save_reports": True, "scan_os": False, "full_stack": False, "scan_venv": True, "scan_scope": "repository", })

When called this way, the banner and interactive console output are suppressed. The return value is the same machine-readable report object written to disk.

Privacy

UBEL is fully local. The only external calls are to osv.dev's public API and NVD's API, which receive package PURLs (name + version) to check for known vulnerabilities. No file contents, no dependency graphs, no machine identifiers, and no telemetry are sent anywhere.

License

See LICENSE.md for details or contact [email protected] for commercial licensing.

Ubel — Secure every dependency, before it reaches production.

Resources

Readme

License

Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks

Report repository