@npm-safe/dsh-tool-npm-safe
A DeepSeek Harness (dsh) tool plugin that exposes the @npm-safe/core-dsh supply-chain security engine as 14 dsh tools. AI agents can call package security scans directly inside a conversation, acting as a "check before you install" gate.
If this plugin is useful in your workflow, please Star the repository so other DSH users can find it.
Installation
dsh plugin --profile tui add @npm-safe/dsh-tool-npm-safe --allow-build=better-sqlite3
dsh --profile tui
The package declares a DSH bundle and activates cordis.patch.yml
automatically. The --allow-build flag grants install-script permission only
to the SQLite driver used for the local cache; pnpm continues blocking build
scripts from other dependencies. Restart an already-running profile after
installation.
Peer Dependencies
This plugin requires the following peer packages (all from the same RC family):
| Package | Version |
|---|
@deepseek-ai/cordis | ^4.0.1 |
@deepseek-ai/dsh-tools | 0.1.0-rc.6 |
@deepseek-ai/dsh-jobs-local | 0.1.0-rc.6 |
Quick Start
Configure a model provider in DSH, then ask the agent to scan a package. A
DeepSeek API key is only required when DeepSeek is your selected provider.
dsh --profile tui
Deep-scan fast-glob before installing it. Explain every finding.
Tools
The plugin registers the following 14 tools in a dsh session:
| Tool | Purpose | Execution |
|---|
check_package | Check one package; optional deep tarball inspection | Foreground (signal-forwarded) |
check_packages | Check multiple packages; optional deep inspection | Foreground (rate-limited) |
search_packages | Keyword search of the npm registry | Foreground |
watch_add | Add a package to the watchlist | Foreground |
watch_remove | Remove a package from the watchlist | Foreground |
watch_list | List all watched packages | Foreground |
rules_list | List all scan rules with status | Foreground |
rule_enable | Enable a scan rule (persisted) | Foreground |
rule_disable | Disable a scan rule (persisted) | Foreground |
rule_set_severity | Override a rule's severity (persisted) | Foreground |
settings_get | Read an engine setting | Foreground |
settings_set | Write an engine setting (persisted) | Foreground |
ci_scan | Dependency gate scan; optional deep inspection | Foreground |
refresh_all | Refresh all watched packages | Background (ctx.jobs.start) |
Usage Examples
Check a single package
> Use check_package to check lodash
lodash@4.18.1: safe (85/100, 2 findings)
For higher assurance before installation, ask the agent to set deep: true:
> Deep-scan lodash with check_package before installing it
lodash@4.17.21: safe (82/100, 2 findings); deep scan complete, 154 files, integrity verified
Deep mode downloads the published tarball, rejects cross-origin downloads,
verifies npm integrity metadata, and inspects bounded source content entirely
in memory. It is optional because archive downloads add latency and bandwidth.
Batch check
> Use check_packages to check lodash, express, and axios
lodash: safe (85/100, 2 findings)
express: suspicious (62/100, 5 findings)
axios: safe (90/100, 1 findings)
CI gate scan
> Use ci_scan to scan dependencies
dir: /project
dependencies: 142
fail level: dangerous
failed: false
safe: 130
suspicious: 10
dangerous: 2
Background refresh
> Use refresh_all to refresh all watched packages
Background refresh job started: job-abc123
Engine
This plugin is powered by @npm-safe/core-dsh, a fork of @npm-safe/core re-architected for dsh integration. The engine provides:
- 10 metadata rules plus 12 deep-content rules for archive integrity, unsafe paths, remote shell execution, obfuscation, process execution, secrets, and binaries
- SQLite-backed caching with TTL-based staleness (default 1 hour)
- TokenBucket rate limiter (5 tokens/s, 10 burst) to prevent registry throttling
- Typed API for programmatic use
Original Repository
License
Apache-2.0 — Copyright 2026 Nisconder, InfiniteScope, Escap1ng, StoryBegins.
