safedeps 0.2.7

Cross-ecosystem dependency policy gate for safer installs and updates.

SafeDeps

SafeDeps is a dependency safety gate.

It checks your project dependencies before install/update and can block risky changes (for example vulnerable, untrusted, or floating versions).

It works with Python, npm, NuGet, and Git dependency definitions.

You can use SafeDeps in two ways:

• Terminal/CLI mode (safedeps scan, safedeps setup, safedeps help, etc.)
• Web UI mode (recommended for guided usage)

Open the UI with:

python -m safedeps.cli ui . --host 127.0.0.1 --port 8877 --open-browser

Install from PyPI (recommended for standard usage):

pip install safedeps

Status note (May 2026): PyPI publishing is now available.
npm and NuGet publishing are still being finalized.

Start In 60 Seconds

1. Get the repository (choose one option):

Option A - clone with Git:

git clone https://github.com/jaydemks/SafeDeps.git
cd SafeDeps

Option B - download ZIP from GitHub and extract it:

cd /path/to/extracted/SafeDeps

2. Create and activate a virtual environment:

macOS/Linux:

python3 -m venv .venv-test
source .venv-test/bin/activate

Windows (PowerShell):

py -m venv .venv-test
.\.venv-test\Scripts\Activate.ps1

If script execution is blocked in PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv-test\Scripts\Activate.ps1

3. Install SafeDeps from the local repository folder:

python -m pip install -e .[dev]

4. In your project folder, run one-time setup:

safedeps setup .
source .safedeps/activate.sh

Windows (PowerShell) setup + activation:

python -m safedeps.cli setup .
. .\.safedeps\activate.ps1

5. Open the UI (recommended command, works even if shell entrypoint is missing):

python -m safedeps.cli ui . --host 127.0.0.1 --port 8877 --open-browser

Then open http://127.0.0.1:8877/.

6. Re-scan from UI or CLI:

safedeps scan . --fail-on HIGH

After activation, runtime dependency operations are guarded in the shell session.

What It Is (Simple)

SafeDeps is a guardrail you run before installing or updating dependencies.

It helps you block risky dependency changes early, for example:

• unpinned/floating versions
• untrusted registries/sources
• known vulnerable packages (from configured local intelligence/feed)
• missing lockfiles
• suspicious package patterns

In short: it is a backend safety gate for dependency workflows in local dev and CI.

UI full guide: docs/UI_DOCUMENTATION.md

Test Status (Current)

• Tested and validated now:
  • Python CLI flow
  • pip and python -m pip runtime guard behavior
  • UI guard toggles and dynamic updates
• Still in active validation:
  • npm runtime guard end-to-end
  • NuGet/.NET runtime flows end-to-end

Current State

• Core engine: Python CLI/library (safedeps package)
• npm distribution: wrapper package present in packages/npm-wrapper
• .NET global tool wrapper: implemented in packages/dotnet-tool
• Publish status:
  • PyPI: published (installable with pip install safedeps)
  • npm: not published yet
  • NuGet: not published yet
  • Target: finalize npm/NuGet publishing after release validation checks pass
• Security outputs:
  • security-artifacts/safedeps-report.json
  • security-artifacts/safedeps-sbom.json

Versioning Policy

• Single public version for all official distributions.
• Python core package version in pyproject.toml must match:
  • safedeps/__init__.py (__version__)
  • packages/npm-wrapper/package.json (version)
• Release tags must follow vX.Y.Z.
• No package publish if versions are inconsistent.
• CI enforces this with python scripts/check_versions.py.

Features

• Central policy file: .safedeps/policy.json
• Python scanning:
  • requirements*.txt
• npm scanning:
  • package.json
  • .npmrc
  • lockfile presence checks
  • install lifecycle scripts checks
  • pnpm-lock.yaml deep parsing (PyYAML-backed)
• .NET scanning:
  • .csproj
  • NuGet.Config
  • lockfile presence checks
• Git dependency checks:
  • .gitmodules
• Rule enforcement:
  • denylist packages
  • floating/unpinned versions
  • untrusted registries/indexes
  • expired exceptions
  • runtime strict checks for pip, python -m pip, and npm guarded wrappers
• CI-friendly exit codes

Install

Python (local development)

pip install .

Install with development tooling (tests):

pip install .[dev]

Or bootstrap a local virtual environment automatically:

./scripts/bootstrap_dev.sh

Windows manual setup:

py -m venv .venv-test
.\.venv-test\Scripts\Activate.ps1
pip install -e .[dev]

Python (from PyPI, after publish)

pip install safedeps

npm (from wrapper package)

From this repository:

cd packages/npm-wrapper
npm install -g .

From npm registry (after publish):

npm install -g @jaydemks/safedeps

Note: npm runtime flow is implemented, but full cross-environment validation is still in progress.

.NET

From this repository (after pack/install):

dotnet tool install --global --add-source ./artifacts/dotnet SafeDeps.Tool

Command:

safedeps-dotnet scan .

From NuGet (after publish):

dotnet tool install -g SafeDeps.Tool

Note: NuGet/.NET runtime flow is implemented, but full cross-environment validation is still in progress.

Quickstart

safedeps init
safedeps scan .

One-time project auto-configuration (guard pip install automatically in this project shell):

safedeps setup .
source .safedeps/activate.sh

Windows (PowerShell):

python -m safedeps.cli setup .
. .\.safedeps\activate.ps1

Quick help command (terminal/cmd/powershell):

safedeps help

Fail CI on high/critical findings:

safedeps scan . --fail-on HIGH

Optional online npm audit:

safedeps scan . --online-audit

Optional SARIF export:

safedeps scan . --sarif security-artifacts/safedeps.sarif

Optional CycloneDX export:

safedeps scan . --cyclonedx security-artifacts/safedeps.cdx.json

Optional SPDX export:

safedeps scan . --spdx security-artifacts/safedeps.spdx.json

Optional HTML export:

safedeps scan . --html security-artifacts/safedeps-report.html

Exporter notes:

• SARIF includes rule catalog and severity mapping.
• CycloneDX/SPDX exporters deduplicate repeated components.
• SPDX and CycloneDX include purl metadata when manager/version are available.

Validate local setup and metadata cache health:

safedeps doctor .

Explain a specific finding rule:

safedeps explain FLOATING_VERSION

Create vulnerability baseline from the latest report:

safedeps baseline . --report security-artifacts/safedeps-report.json --output .safedeps/vuln-baseline.json

Add/update an expiring suppression entry:

safedeps approve . --manager npm --rule FLOATING_VERSION --package lodash --file package.json --expires 2026-12-31

Run the local visual UI:

python -m safedeps.cli ui . --host 127.0.0.1 --port 8877 --open-browser

The UI is fully in English and includes visual flows for:

• initial auto-scan on UI open + Re-Scan
• dependency inventory table with quick approval action
• direct per-row Uninstall and Safe Update actions
• rule explanation (explain)
• baseline generation (baseline)
• expiring approvals (approve --expires)
• one-click finding pickup ("Use For Approval") to prefill approval fields
• policy quick editor for allowlist registries and deny packages
• pip install guard panel showing blocking pip findings and reasons
• intelligence editor for .safedeps/vuln-feed.json and .safedeps/metadata-cache.json
• one-click starter template generation for local "safe" intelligence files
• light/dark theme toggle persisted in browser
• dynamic partial refresh for scan/dependency actions (reduced full-page reload behavior)

UI options:

• --host (default 127.0.0.1)
• --port (default 8765)
• --fail-on (default HIGH)

Protection scope behavior:

• Project Only: guard blocks runtime dependency changes only when working inside this project path.
• Global: guard blocks runtime dependency changes both inside and outside this project path.
• UI toggles are available under guard controls:
  • Scope: Project Only
  • Scope: Global
• Default scope:
  • if SafeDeps runs inside a virtual environment: Project Only
  • if SafeDeps runs system-wide: Global

Minimal Policy Example

{
  "allowed_registries": {
    "npm": ["https://registry.npmjs.org/"],
    "pip": ["https://pypi.org/simple", "https://pypi.org/simple/"],
    "nuget": ["https://api.nuget.org/v3/index.json"]
  },
  "deny_packages": ["malicious-demo-package"],
  "allow_unpinned": false,
  "require_lockfiles": true,
  "require_expiring_exceptions": true,
  "exceptions": [
    {
      "manager": "npm",
      "package": "demo-package",
      "rule": "FLOATING_VERSION",
      "expires": "2026-12-31",
      "reason": "Temporary migration exception"
    }
  ]
}

Vulnerability baseline support:

• Default file: .safedeps/vuln-baseline.json
• Matching findings can be suppressed via suppress entries (manager, rule, package, file).
• Suppression entries may include optional expires (YYYY-MM-DD); expired entries are ignored.

Local vulnerability feed support:

• Optional file: .safedeps/vuln-feed.json
• Supported fields per entry: manager, package, id, severity, message
• Optional OSV-style entries via vulnerabilities_osv are also supported in .safedeps/vuln-feed.json.
• Severity is normalized to SafeDeps scale (CRITICAL/HIGH/MEDIUM/LOW/INFO).
• You can create/edit/validate this file directly from the UI ("Intelligence Settings"), no manual file editing required.

Local metadata cache support:

• Optional file: .safedeps/metadata-cache.json
• Used by age/churn/maintainer risk signals.
• You can create/edit/validate this file directly from the UI ("Intelligence Settings").

Verification Workflow

Run these checks before release:

1. safedeps scan examples/bad-project must fail (exit code 2).
2. safedeps scan examples/safe-project should pass or produce only accepted non-blocking findings.
3. python -m pytest must pass.
4. CI must fail on an intentionally unsafe fixture branch.

Publishing

Python / PyPI

python -m build
python -m twine upload dist/*

npm

cd packages/npm-wrapper
npm publish --access public

.NET / NuGet (planned)

dotnet pack packages/dotnet-tool/SafeDeps.Tool.csproj -c Release -o artifacts/dotnet
dotnet nuget push artifacts/dotnet/*.nupkg --source https://api.nuget.org/v3/index.json --api-key YOUR_KEY

Use trusted publishing/OIDC whenever available.

Release Automation (Template)

Run local preflight checks before triggering a release:

python scripts/release/preflight.py --expected-version 0.2.7

Release workflow template:

• .github/workflows/release-template.yml
• includes:
  • preflight checks
  • Python distribution build artifact
  • npm wrapper tarball artifact
  • .NET tool .nupkg artifact
  • release checksum manifest (release-artifacts/release-manifest.json)
  • optional publish gates (publish=true) for PyPI/npm/NuGet
  • tag-triggered release flow on v* tags
  • GitHub release publication with attached artifacts
  • build provenance attestation stage

Detailed process guide:

• docs/release/RELEASE_PROCESS.md

Artifact validation helper:

python scripts/validate_artifacts.py security-artifacts

CI Templates

Ready-to-copy templates are available in examples/ci/ for:

• GitHub Actions
• GitLab CI
• Azure Pipelines

See examples/ci/README.md for usage details.

Pre-commit Integration

This repository includes a ready pre-commit hook config:

• .pre-commit-config.yaml

Install and enable:

pip install pre-commit
pre-commit install

The hook runs:

safedeps scan . --fail-on HIGH --out security-artifacts

Security Scope

SafeDeps is a preventive gate, not a guarantee that every package is safe.

It should be used with lockfiles, code review, SBOM analysis, vulnerability feeds, signed releases where supported, and CI policy enforcement.