dsh-security-scan

Secret & dangerous-pattern scanner for DeepSeek Harness — one security_scan tool that walks your files and reports leaked API keys, tokens, private keys, and credential-bearing connection strings. Zero runtime dependencies (pure Node built-ins).

Overview

dsh-security-scan gives the harness a model-facing security hygiene tool. Point it at a checkout (or your whole workspace) and it finds secrets that should never have been committed — then reports them redacted, so raw key material never reaches the model context or the logs.

Who is it for?

• Anyone who has ever pushed a .env or pasted a token into a config file.
• Teams that want a cheap, built-in secret gate before commits or before handing a repo to an agent.
• Developers who want a readable reference for writing a model-facing tool plugin (bare ToolDefinition, no framework).

What it detects

Kind	Pattern (examples)
AWS access key	AKIA + 16 base62 chars
GitHub token	ghp_ + 36 chars
OpenAI-style key	sk- + 20+ chars
Bearer token	generic Bearer inline credentials
Private key	-----BEGIN ... PRIVATE KEY----- blocks
DB connection string	mysql:// / postgres:// / mongodb:// with an embedded password
Dangerous file	.env with suspicious values; *.pem / *.key / *.p12 artifacts

What it does not do (yet)

• No git-history scan, no remediation, no network checks. This is a filesystem scanner, not a full security audit suite.
• No tools/pre-execute enforcement gate (planned: block writes that would re-introduce a known secret). See Development.

Compatibility

• Requires Node.js ≥ 22.19 (uses node:fs/promises and global fetch-free built-ins only).
• Built and verified against @deepseek-ai/[email protected] / @deepseek-ai/cordis@^4.0.1.
• Last verified: 2026-08-14.
• dsh is in developer preview; re-verify after harness updates. The plugin only depends on ctx.tools.register (a stable extension point) and @deepseek-ai/dsh-tools types.

Install / Uninstall

Install into a dsh profile (local checkout):

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-security-scan

From GitHub (source install — pnpm runs the prepare script, so allow it once):

pnpm dsh plugin --profile web add github:<you>/dsh-security-scan
# pnpm ≥10 blocks the build script on first install; copy the printed package key
# into <profile>/pnpm-workspace.yaml under allowBuilds, then re-run.

Uninstall:

pnpm dsh plugin --profile web remove dsh-security-scan

Quick start

Install the bundle, then ask the agent:

Run security_scan on this repository and summarize the high-severity findings.

Or trigger it directly through the harness tools. Default behavior: scan . (relative to the harness cwd), skip node_modules/.git/dist/build, skip files over 1 MB, and cap 10 findings per file.

Example output shape (secrets redacted):

[HIGH] github-token        config/keys.ts:12  ghp_ab12****yz
[HIGH] private-key         deploy/keys.pem (file artifact)
[LOW]  db-connection-string src/db.ts:88      postgres://user:****@host/db
Scan complete: 412 files scanned, 3 findings (HIGH: 2, LOW: 1)

Configuration

All keys live under the dsh-security-scan row's config:

Key	Type	Default	Meaning
paths	string[]	['.']	Directories to scan (relative to harness cwd).
ignored	string[]	['node_modules','.git','dist','build']	Directory basenames skipped during traversal.
maxFileSizeBytes	number	1048576	Files larger than this are skipped.
maxMatchesPerFile	number	10	Max findings reported per file.

Permissions & data

• Read-only: the scanner only reads files; it never writes, edits, or deletes.
• Redaction: every matched secret is masked before it leaves the scanner (first 4 / last 2 characters shown). Raw key material does not reach the model context or logs.
• Scope: scanning is bounded to the configured paths and respects the ignore list; it does not follow symlinks out of the tree.
• No network: detection is purely local regex scanning; nothing is uploaded or sent anywhere.

Troubleshooting

Symptom	Cause	Fix
Tool reports zero files scanned	paths points at a non-existent directory relative to harness cwd	Use an absolute path or run from the intended directory
False positives on example keys	Test fixtures often contain placeholder keys (AKIAIOSFODNN7EXAMPLE is AWS's documented example)	Review findings manually; the tool reports, it does not judge intent
Slow scan on huge repos	Regex over many files	Raise ignored coverage (e.g. add vendor, third_party) or reduce paths
security_scan not visible to the model	Plugin loaded without the tools service	Verify inject: ['tools'] is present in the installed lib/index.js (rebuild after edits)

Development

pnpm install
pnpm run typecheck     # tsc --noEmit
pnpm run build         # tsc → lib/
pnpm run test          # vitest (19 tests)

Structure:

• src/index.ts — plugin entry, scanner, and the security_scan tool; detection regexes and the redaction helper are exported for unit tests.
• tests/ — redaction, ignore-directory, and detection-vocabulary coverage.
• cordis.patch.yml — the bundle patch layer that mounts the plugin row.

Design notes:

• Detection is intentionally regex-based and conservative — better to flag a false positive than to miss a real secret. Add patterns as new SecretKinds and pin them in tests.
• Roadmap: a tools/pre-execute enforcement gate (reject writes that reintroduce a known secret) and git-history scanning.

License & security

MIT. Report security issues privately via the repository's security advisory (or open an issue without secrets). The scanner runs entirely on the operator's machine with read-only access; it sends nothing anywhere.