Eligahyu/dsh-sentinel-scanner ↗★ 5

deepseek-harness-sentinel

🛡️ 给 DeepSeek Harness 插件拍 X 光 —— DSH 插件安全体检与健康检查。静态启发式审计:代码执行、凭据访问、外传端点、混淆、安装脚本、bundle 清单合规,输出 0-100 风险分与裁决。Plugin security & health scanner for DeepSeek Harness: heuristic static audit (code execution, credential access, exfiltration, obfuscation, install scripts, bundle manifest compliance) with a 0-100 risk score and verdict. Works as a DSH tool plugin and as a standalone self-contained CLI. 适合需要在安装或运行 DSH 插件前进行静态安全审计与风险评估的开发者。

パッケージ
deepseek-harness-sentinel
互換性
未検証
Harness ピア範囲
*
Cordis ピア範囲
*
バージョン
0.4.4
ライセンス
MIT
最終更新
2026/09/14

同名パッケージの別リポジトリ

インストール

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Eligahyu/dsh-sentinel-scanner

ドキュメント

README 全文を読む ↗

🛡️ dsh-sentinel

Awesome DSH Plugin

Read-only security, supply-chain, and health scanner for DeepSeek Harness plugins

Heuristic rules, AST/taint analysis, package quarantine, dependency intelligence, SBOM export, SARIF, and CI policy enforcement—without executing scanned code.

Node.js ^22.18.0 or >=24.11.0 · Static analysis primary; Phase B dynamic analysis is explicit opt-in and network-denied · MIT

English · 中文 · Rules · Architecture · Roadmap


English

What is dsh-sentinel?

dsh-sentinel gives DeepSeek Harness (DSH) plugins an X-ray before you trust or install them. It is a read-only static security scanner for plugin source trees, published npm packages, DSH profiles, and CI pipelines.

The scanner looks for command execution, dynamic code evaluation, credential access, data exfiltration, obfuscation, unsafe lifecycle scripts, persistence, native binaries, manifest escape paths, and package drift. It combines 51 heuristic rules with AST-based taint analysis, bounded module and cross-file analysis, supply-chain metadata, and explicit scan-coverage reporting.

Every scan produces a structured report with a 0–100 risk score, a safe / review / risky / dangerous verdict, evidence for each finding, and actionable remediation guidance. The same engine is available as:

  • a DSH Agent Tool plugin: sentinel_scan, sentinel_scan_profile, and sentinel_audit_package;
  • a standalone CLI: npm package deepseek-harness-sentinel, executable dsh-sentinel;
  • a GitHub Action with SARIF upload support;
  • a JavaScript API for programmatic integrations.

Security disclaimer: heuristic static analysis is not a proof of safety. A finding means “review this evidence,” not “this plugin is malicious.” A clean report means that enabled checks found no issue; it does not guarantee safety.

Why this project exists

DSH plugins may run with the same filesystem, network, credential, and process permissions as the user or agent that loads them. A small install script, hidden download-and-execute chain, unsafe tool argument, or escaped manifest path can therefore become a supply-chain incident.

dsh-sentinel is designed for two audiences:

  • Plugin users: inspect third-party code before installation or activation.
  • Plugin authors and maintainers: detect dangerous behavior, packaging drift, incomplete scans, and manifest defects before publishing.

Security model and non-negotiable boundaries

  1. Scanned code is never executed. The scanner does not require, import, eval, or spawn target code.
  2. Pre-install audit does not run npm install. It downloads a tarball, verifies integrity, extracts it into quarantine, scans it, and cleans up.
  3. Source code is not uploaded. Optional OSV lookup is disabled by default and sends only package name and version when enabled.
  4. Secrets are always redacted. Reports retain fingerprints and evidence without exposing raw secret values.
  5. Skipped work is visible. Limits, oversized files, ignored paths, parser boundaries, and policy skips are represented in the report.
  6. Automation is not detection. SARIF, HTML, GitHub Actions, and SBOM formats transport or present results; detection capability lives in the engine.
  7. Dynamic analysis is explicit opt-in. Static analysis remains the default; --dynamic adds a separate Phase B layer and never changes the static result.
  8. Phase B has no host-execution fallback. It can run only inside a local, scanner-owned, immutable-image Docker or Podman runner. This checkout has no compiled/deployed approved image, so production resolution currently reports unavailable rather than executing a package.

Capabilities

AreaWhat it does
Heuristic rules51 rules across execution, credentials, exfiltration, obfuscation, install scripts, filesystem, network, manifests, Agent Tools, taint, supply chain, binaries, and persistence.
Agent Tool analysisTraces defineTool inputs such as args.* into shell, filesystem, network, and dynamic-code sinks. Handles aliases, computed properties, optional chaining, variable propagation, and bounded cross-function flows.
Module and cross-file analysisBuilds a bounded JS/TS module graph across ESM and statically provable CommonJS require / require.resolve edges, including constant string concatenation and TypeScript .js specifiers that map to .ts sources. Cross-file taint follows ESM imports and destructured CommonJS exports; unprovable dynamic module specifiers are reported instead of guessed. TypeScript parser limits are reported as a capability boundary instead of falsely failing every TS scan.
Language-aware coverageJS-family files receive semantic analysis. TypeScript is conservatively degraded where syntax exceeds the parser boundary. Python and PowerShell files are not incorrectly fed into the JS parser and still receive applicable heuristic scanning.
DSH manifest validationAudits dsh.bundle, cordis.patch.yml, package entry contracts, and lexical/realpath/symlink containment. Escaping paths trigger SEN-MAN-009.
Scan modessource skips generated build trees by default; package includes distributable output such as dist and build; profile discovers and audits installed DSH plugins.
Pre-install quarantineSafely extracts npm tarballs while blocking traversal, absolute paths, drive paths, symlink/hardlink entries, and tar bombs. Verifies sha512 integrity and cleans up all artifacts.
Supply-chain analysisInspects lifecycle scripts, npm and pnpm v9 normalized lockfile graphs, package metadata, optional OSV advisories, optional provenance, and source-versus-package drift. Unsupported lockfile formats remain explicit warnings.
Native artifactsAudits .wasm, .exe, .dll, .so, .node, and related files using magic bytes, size, SHA-256, entropy, and printable strings. Binaries are never executed.
Professional report layersStable report schema v2 with module graph, dependency graph, capability graph, SBOM, provenance, attack chains, coverage, and failure metadata.
Output and CIText, JSON, SARIF 2.1.0, standalone HTML, CycloneDX, and SPDX output; stable fingerprints, baselines, threshold exits, and incomplete-scan enforcement.
PrivacyAutomatic secret redaction, optional path anonymization with --redact-paths, and no hidden ignore/skip behavior.
Dynamic analysis (Phase B)Explicit opt-in, static-preflight-gated, network-denied Docker/Podman runner with immutable image and staged-input contracts. The current release remains unavailable until a scanner-owned image is compiled/deployed.

Core analysis versus auxiliary analysis

Scan completeness distinguishes security-critical coverage from optional enrichment:

  • failures in core coverage, such as module or cross-file analysis failures, can set scanComplete=false;
  • dependency graph, SBOM, provenance, and capability-graph failures are preserved as warnings and degraded output rather than falsely claiming source files were not scanned;
  • unsupported or complex lockfile formats are reported instead of producing guessed dependency data.

Dynamic Analysis (Phase B)

Static completeness and dynamic completeness are separate signals. The static scan remains the primary verdict and continues to report summary.scanComplete. When --dynamic is requested, a dedicated analysisLayers.dynamic record reports the deep-analysis state instead of changing or hiding static coverage.

Phase B is an explicit opt-in release gate layered after static analysis. It is not a claim that a finite runtime exercise proves a plugin safe. Static preflight remains authoritative for the static verdict, while analysisLayers.dynamic reports the independent dynamic state. A scan without --dynamic does not probe Docker or Podman and does not start a runner.

The production resolver accepts only a scanner-owned image compiled/deployed at an immutable digest and a local Docker or Podman capability probe. If the image is absent, mutable, remote, or unhealthy, the dynamic layer is unavailable with a fixed reason such as trusted-image-unavailable; it does not pull, build, execute on the host, or silently fall back. The current package ships no approved image, so normal CLI/API use remains safely unavailable until the release deployment supplies one.

Static preflight and status

Static analysis always runs first. Phase B refuses execution when preflight finds high-risk native executables or native Node modules selected for execution, container-control or escape signals, artifact limits, unresolved entrypoints, incomplete core traversal, or an unavailable isolation backend. Refusal is reportable and never erases static findings.

The dynamic status is one of not-requested, unavailable, refused, complete, or incomplete:

StatusMeaning
not-requestedNo --dynamic request was made. No engine probe occurs.
unavailableThe local, immutable Phase B prerequisites are not present; the target was not run.
refusedStatic preflight rejected the target as outside the Phase B threat boundary.
completeAll allowlisted stages produced bounded evidence and exact cleanup completed.
incompleteA stage, evidence parser, timeout, cancellation, resource limit, or cleanup path was uncertain.

With --fail-on-incomplete or --strict-exit-codes, requested unavailable/refused/incomplete dynamic results return exit code 3. Without those strict controls, the result remains visible and the static exit policy is unchanged. complete means only that the supplied stages and stimuli completed; it is not a proof of safety, and no observed traffic means only that these bounded stages did not trigger traffic.

Linux prerequisites and Phase B runner boundary

The supported release gate is a protected, administrator-managed Linux self-hosted runner labeled self-hosted, linux, and dsh-sentinel-phase-b, with a local Docker or rootless Podman engine and a preloaded scanner-owned image referenced by a full sha256 digest. The protected environment is named dynamic-analysis-protected. The image must already be present: Phase B uses --pull=never and performs no image build. Engine selection is the fixed docker|podman allowlist; the accepted image form is ^[a-z0-9](https://github.com/Eligahyu/dsh-sentinel-scanner/blob/5fe1af4fc813e4c3f0e84073aff4e507911c3968/)@sha256:[a-f0-9]{64}$. Remote endpoints and contexts are not accepted. Before either engine command, the gate enumerates exported environment names, canonicalizes them to uppercase, and rejects any non-empty casing variant of DOCKER_HOST, DOCKER_CONTEXT, CONTAINER_HOST, CONTAINER_CONNECTION, DOCKER_CONFIG, CONTAINERS_CONF, CONTAINERS_STORAGE_CONF, PODMAN_CONNECTIONS_CONF, or XDG_CONFIG_HOME, then unsets those selectors/configuration variables. It uses only /usr/bin/docker or /usr/bin/podman, a controlled empty environment and / as the working directory, with Docker bound to --host=unix:///var/run/docker.sock or Podman bound to --url=unix:///run/user//podman/podman.sock. An unsafe selector fails closed before image inspection; the inspect command has a fixed 15-second host timeout with TERM and 5-second kill-after bounds, while the smoke run has a fixed 90-second host timeout. The engine socket is never mounted into the container.

Each allowlisted stage uses a fresh, short-lived runner with the following fixed properties:

The read-only staging mount is the only package input available to the runner; the original workspace is never mounted.

  • --network=none; Phase B has no public or private egress and does not provide a gateway or network observation path;
  • private PID and IPC namespaces, a read-only root filesystem, a read-only staging mount, a non-root UID, dropped capabilities (all Linux capabilities are dropped), and no-new-privileges;
  • bounded CPU, memory, PID, temporary-storage, output, and wall-clock budgets;
  • no user-provided container flags, no host workspace mount, no engine socket, no host namespaces, no host credentials, and no real credentials;
  • no package-manager or lifecycle execution: no preinstall, install, postinstall, or prepare.

The staging lifecycle resolves and contains the scan root, copies only approved regular files into a scanner-owned temporary snapshot, excludes links/devices, sockets, VCS metadata, worktrees, and escape paths, mounts that snapshot read-only, and removes it idempotently. Cleanup is ownership-scoped to the current run. Any cleanup uncertainty is reported as incomplete; a report must not expose raw engine diagnostics, full request bodies, host absolute paths, or secret values.

Phase B versus Phase C

Phase B intentionally stops at network denial. It binds the selected local Docker/Podman endpoint and fixed harness executable through scanner-owned arguments; callers cannot replace the endpoint, executable, image, mount, or namespace policy. Trusted image ownership belongs to the scanner release, while the staged package remains untrusted input. Gateway routing, DNS/HTTP/TCP/UDP observation, Node preload probes, canary correlation, and any explicitly allowlisted replay network belong to Phase C and are not implemented or implied by a Phase B complete result.

The Linux-only CI gate is opt-in and runs only on that protected self-hosted runner. It skips with an explicit unavailable reason when the protected immutable image digest is absent or the exact image is not locally preloaded. It has fixed two-minute job and 90-second host-command timeouts and never changes the default static workflow. See .github/workflows/dynamic-smoke.yml for the release contract.

The four opt-in controls are:

OptionPhase B behavior
--dynamicOpt in to Phase B after static preflight; no request means no engine probe.
--dynamic-backend Select a local engine; Phase B still requires the immutable scanner-owned image and network denial.
--dynamic-profile observeSelect the bounded Phase B observation contract; Phase C gateway/probe behavior is not included.
--dynamic-timeout Request a bounded timeout. Default: 15000; values are clamped to the enforced 1000–30000 ms range.

An unavailable, refused, or incomplete requested deep scan exits with code 3 only when --fail-on-incomplete or --strict-exit-codes is set. Without either strict flag, the deep-layer result remains visible but does not by itself fail CI. This policy applies independently of static completeness.

pnpm v9 dependency intelligence

dsh-sentinel supports the pnpm v9 lockfile layout as a read-only, normalized dependency graph. It parses importers, packages, and snapshots with a standards-aware YAML parser, preserves peer-suffixed package instances, resolves workspace: / link: importer relationships, and keeps npm aliases attached to the installed package identity. Workspace importer paths are containment-checked; malformed YAML, path escapes, unresolved references, oversized lockfiles, and unsupported pnpm lockfile versions are reported as explicit dependency-layer failures rather than converted into guessed nodes.

The graph separates root direct dependencies from transitive package instances. The dependency summary uses this normalized graph for pnpm v9, so its direct and transitive counts are reproducible from the lockfile rather than inferred from indentation or regular-expression matches. If normalization fails, the summary returns zero counts with an explicit incomplete reason; it never presents a partial count as e