Metadata-Version: 2.4
Name: dshpkg
Version: 0.1.0
Summary: Security & health audit CLI for DeepSeek Harness (DSH) plugins — search, info, security-scan and doctor for the everything-is-a-plugin ecosystem
Home-page: https://github.com/Exaggarate/dshpkg
Author: Exaggarate
License: MIT
Project-URL: Source, https://github.com/Exaggarate/dshpkg
Project-URL: Issues, https://github.com/Exaggarate/dshpkg/issues
Keywords: dsh deepseek-harness dsh-plugin cli security audit scanner ai-agents plugins
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# dshpkg

[![CI](https://github.com/Exaggarate/dshpkg/actions/workflows/ci.yml/badge.svg)](https://github.com/Exaggarate/dshpkg/actions/workflows/ci.yml)

**Security & health audit CLI for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugins — `npm audit` for the everything-is-a-plugin era.**

The DSH plugin wave is the fastest-growing agent ecosystem on GitHub: the harness hit **209,000+ stars in ~3 weeks**, and **13,000+ repos** already carry the `dsh-plugin` topic. Plugins are npm packages that **inject into host modules** (`@deepseek-ai/dsh-client-store`, `dsh-client-ui-conversation`, …) and can ship **host behavior patches** (`cordis.patch.yml`). That is arbitrary code running inside your agent harness with your session, your keys, and your files.

Meanwhile the ecosystem's own tracker shows **12 high-star plugins failing to install/boot** on recent dsh releases, and the community npm catalog has been **stalled since 2026-08-26**. Nobody is checking what a plugin actually does before you inject it.

`dshpkg` is the pre-flight check: search the ecosystem, get a plugin's health card, and security-scan its source — before it touches your harness.

```
$ dshpkg info XieZongChen/dsh-md-notes
dshpkg info — XieZongChen/dsh-md-notes
  repo:           XieZongChen/dsh-md-notes
  stars:          16
  open issues:    1
  pushed:         2026-09-02
  license:        MIT
  npm:            dsh-md-notes
  latest release: v0.10.0 (2026-08-31)
  inject hooks   5 host module(s):
    · @deepseek-ai/dsh-client-ui-renderer
    · @deepseek-ai/dsh-client-locale
    ...
  host patches   ./cordis.patch.yml

$ dshpkg scan dickpy/dsh-imagegen
dshpkg scan — dickpy/dsh-imagegen (default branch: main)
  inject hooks (8):
    · @deepseek-ai/dsh-client-store
    · @deepseek-ai/dsh-api-session-controller
    ...
  findings: 3
  [medium  ] child_process exec           src/updater.ts
  [medium  ] env enumeration              src/updater.ts
  [medium  ] base64 blob (obfuscation)    scripts/smoke.mjs
  GRADE C — medium findings — review before install
```

## Install

```sh
pip install dshpkg
```

Python 3.8+, **stdlib-only** — no dependencies.

## Commands

| Command | What it does |
|---|---|
| `dshpkg search QUERY` | GitHub search across `topic:dsh-plugin` (stars, freshness, description) |
| `dshpkg info OWNER/REPO` | Health card: activity, npm mapping, latest release, inject hooks, host patches, compat warnings from recent issues |
| `dshpkg scan OWNER/REPO` | Downloads the tarball, extracts it hardened (traversal/symlink/bomb guards), scans for leaked credentials and dangerous code, grades A–F |
| `dshpkg doctor` | Local environment check: dsh install, node/npm, installed plugins |

Every command accepts `--json` for scripting. Set `GITHUB_TOKEN` (or `GH_TOKEN`) to lift the anonymous API cap from 60 to 5,000 req/hr — search users will hit the wall otherwise.

## What scan looks for

- **Leaked credentials** — OpenAI/Anthropic-style keys, GitHub PATs, AWS keys, Google API keys, Slack/GitLab tokens, private key blocks (any file, including code)
- **Dangerous code** — `eval` / `new Function`, `child_process` usage, `curl | sh` installers (JS/TS **and** shell scripts), remote dynamic imports
- **Exfiltration signals** — webhook.site / pastebin / Discord-webhook / Telegram-bot endpoints
- **Obfuscation** — large base64 blobs
- **Manifest risk** — npm lifecycle scripts (`postinstall`, `prepare`, …), the full `client.inject` hook list, host patch files

Grades: **A** clean · **B** informational · **C** medium findings · **D** high findings · **F** critical (likely leaked credentials) or archive-safety refusal.

## Honest limits

`scan` is a heuristic pre-flight check, not a security guarantee — a crafted plugin can pass pattern scanning. Treat D-grade as "do not inject", A-grade as "nothing obviously wrong." Read the flagged code yourself; `--json` output gives you file paths to jump to.

## For plugin authors

A clean `dshpkg scan` is a trust signal worth putting in your README. If your plugin gets a D/F for intentional behavior (an updater using `child_process`, for example), that's expected — the grade asks humans to look, and the finding text shows exactly where.

## Compatibility

`doctor` and `info` surface compatibility signals (recent install/boot failure issues, dsh version mismatches). The `dsh-plugin` ecosystem is young and moving fast — pin and verify.

## License

MIT — [Exaggarate/dshpkg](https://github.com/Exaggarate/dshpkg)
