Introduction¶

DSH’s philosophy is “Everything is a plugin.” For AI agent developers, plugins typically require reading the repository first, then executing the installation. Here lies a sequencing problem: if the installation command executes first, the installation hooks within the plugin may have already run; by the time files are scanned after installation, it is too late.

dsh-provenance addresses this sequencing issue. It checks whether the incoming tarball to be installed matches the read source code before the DeepSeek Harness plugin is installed, and provides a result of ok, review, or block before the code runs.

What is it¶

dsh-provenance is a DSH plugin maintained by Darren Tang and is MIT licensed. It performs supply chain origin checks before installation, does not execute the audited package, and does not replace code behavior scanning.

The runtime requirement is Node.js >=22.19.0. The README states it has no runtime dependencies; @deepseek-ai/cordis and @deepseek-ai/dsh-tools are optional peer dependencies.

Core Checks¶

Below introduces the categories of origin issues it checks.

Source Fixity¶

Checks if the installation specifier points to immutable content. Resolvable names or branches might resolve to different content under the same name.

Registry Integrity¶

Compares the received bytes against the digest published by the registry.

Install Hooks¶

Checks the install hooks that will be executed during the dsh plugin add process. This type of code may run before the post-install scan.

Build Source¶

Checks whether the artifact can be associated with a specific commit and CI workflow via SLSA attestation. It parses the attestation payload but does not perform sigstore signature verification.

Artifact vs. Source Comparison¶

Compares published files with upstream source code for a specified commit and detects if new files were added during publishing.

If there are no published files to match, it reports diff.nothing-verified instead of reporting 0 mismatch.

Usage¶

dsh-provenance registers two tools for the DSH agent:

provenance_preflight: Audits a source before installation.
provenance_verify: Checks installed plugins in a specific profile.

It also provides a CLI. The CLI’s preflight and verify modes support --json and --strict, which can be used in CI.

Exit codes:
- 0: ok or notice
- 1: requires review under --strict
- 2: block

Installation and Enabling¶

As a DSH plugin:

dsh plugin --profile web add dsh-provenance

As a standalone CLI:

npm install -g dsh-provenance

Before enabling, ensure Node.js >=22.19.0 and check the source code and MIT license. DSH plugins generally run with the permissions of the current dsh process, so it is recommended to audit before installing.

Typical Usage¶

Preflight Check¶

Perform preflight first:

dsh-provenance preflight some-plugin@1.2.3
dsh-provenance preflight github:owner/repo
dsh-provenance preflight some-plugin --json

Check Installed Plugins¶

Then run verify for a specific profile:

dsh-provenance verify --profile web

CI Gating¶

Use --strict in CI:

dsh-provenance preflight some-plugin@1.2.3 --strict
dsh-provenance preflight github:owner/repo#<sha> --strict

Installation Interception¶

Within a DSH session, dsh-provenance intercepts installation attempts: if a source has not passed preflight in the session first, it will reject the installation. If needed, you should audit the source using provenance_preflight first, then retry the installation.

If this installation interception disrupts your workflow, you can disable it with the following configuration:

{ guardInstalls: false }

Boundaries and Considerations¶

Its boundaries are quite clear:

It does not verify sigstore signatures; it only parses the attestation payload without cryptographic verification.
It cannot verify build artifacts; lib/, dist/, and compressed files will be reported as unverifiable and will not be reported as match.
A clean report does not equal a security proof; it only indicates that no issues were found under current rules.
It is not a code behavior scanner; it checks where the code comes from, not what the code does.
It is not a runtime ledger; it does not observe or record behavior after installation.
It does not execute the audited package; archives are parsed in memory.

Conclusion¶

The value of dsh-provenance lies in handling the question “Is the source code consistent?” earlier, before installation. It can be used in conjunction with code behavior scanning: the former answers whether the source is correct, and the latter answers whether the code behavior is trustworthy.

GitHub repository: https://github.com/Darren-Tang/dsh-provenance

dsh-provenance: Provenance verification before DeepSeek Harness plugin installation