deepseek-harness-sentinel

dsh plugin --profile web add deepseek-harness-sentinel

<div align="center">

🛡️ dsh-sentinel


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 only · MIT

[English](#english) · [中文](#中文说明) · [Rules](docs/rules.md) ·

[Architecture](docs/architecture.md) · [Roadmap](docs/roadmap.md)

</div>

---

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.

Capabilities

Area · What it does

Heuristic rules · 51 rules across execution, credentials, exfiltration, obfuscation, install scripts, filesystem, network, manifests, Agent Tools, taint, supply chain, binaries, and persistence.

Agent Tool analysis · Traces 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 analysis · Builds a bounded JS/TS module graph, resolves common relative imports—including TypeScript .js specifiers that map to .ts sources—and supports bounded cross-file taint analysis. TypeScript parser limits are reported as a capability boundary instead of falsely failing every TS scan.

Language-aware coverage · JS-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 validation · Audits dsh.bundle, cordis.patch.yml, package entry contracts, and lexical/realpath/symlink containment. Escaping paths trigger SEN-MAN-009.

Scan modes · source skips generated build trees by default; package includes distributable output such as dist and build; profile discovers and audits installed DSH plugins.

Pre-install quarantine · Safely 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 analysis · Inspects lifecycle scripts, lockfiles, normalized dependency graphs, package metadata, optional OSV advisories, optional provenance, and source-versus-package drift.

Native artifacts · Audits .wasm, .exe, .dll, .so, .node, and related files using magic bytes, size, SHA-256, entropy, and printable strings. Binaries are never executed.

Professional report layers · Stable report schema v2 with module graph, dependency graph, capability graph, SBOM, provenance, attack chains, coverage, and failure metadata.

Output and CI · Text, JSON, SARIF 2.1.0, standalone HTML, CycloneDX, and SPDX output; stable fingerprints, baselines, threshold exits, and incomplete-scan enforcement.

Privacy · Automatic secret redaction, optional path anonymization with --redact-paths, and no

…(truncated)