DEV Community

Cover image for shk: A Local-First Security Guardrail CLI for AI Coding Agents
Kazuki Yonemoto
Kazuki Yonemoto

Posted on

shk: A Local-First Security Guardrail CLI for AI Coding Agents

#ai #programming #productivity #opensource

Secret scanning often starts at Git. AI coding agents can make that too late.

They can read local files, summarize logs, run commands, and transform sensitive context before anything is committed. shk is a local-first CLI for that messy pre-commit space: scan secrets and PII, mask prompts, and install managed hooks for Claude Code, Cursor, and Codex.

The problem is no longer just "secret reaches Git"

Most secret-scanning workflows are built around a familiar boundary: stop credentials before they land in Git, CI logs, or a release artifact.

AI coding agents move that boundary earlier.

An agent might read a file while following an import chain. It might summarize a pasted error log. It might run a shell command that prints .env contents. It might create a new file that quietly contains a token from earlier context. None of that requires a commit.

That is the gap shk is trying to cover: the local, messy, pre-commit space where AI tools actually operate.

What shk does in practice

shk is not one more dashboard you have to check. It is a single Rust binary that you put around the workflows where sensitive context tends to leak:

  • Before sharing context with an AI tool, use shk mask to redact secrets and PII from a prompt, log, or snippet.
  • Before an AI tool reads, writes, fetches, or runs something, use managed hooks to audit or block risky operations.
  • Before a commit or pull request, use the same scanner through Git pre-commit hooks and GitHub Actions.

That gives you one policy file, one set of rules, and one exit-code contract across local use, AI hooks, Git, and CI.

A quick tour

Install the latest release:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Kazuki-tam/security-harness-kit/releases/latest/download/shk-cli-installer.sh | sh
Enter fullscreen mode Exit fullscreen mode

Windows users can install from PowerShell:

powershell -c "irm https://github.com/Kazuki-tam/security-harness-kit/releases/latest/download/shk-cli-installer.ps1 | iex"
Enter fullscreen mode Exit fullscreen mode

Both shk and security-harness-kit resolve to the same CLI.

Start with a policy file:

shk init
Enter fullscreen mode Exit fullscreen mode

Scan the current project:

shk scan .
Enter fullscreen mode Exit fullscreen mode

Example output:

3 findings

HIGH  secret.openai_api_key  src/app.ts:12    Possible OpenAI API key detected
MED   pii.ja.phone           config/dev.ts:5  Japanese phone number detected
MED   pii.en.ssn             docs/test.md:8   US Social Security Number detected
Enter fullscreen mode Exit fullscreen mode

Need a machine-readable report for automation? Use JSON. Raw matched values are not emitted; findings use redacted_value: "[REDACTED]".

shk scan . --json
Enter fullscreen mode Exit fullscreen mode

Need to paste a production log into an AI chat? Mask it first:

shk mask < prompt.txt
Enter fullscreen mode Exit fullscreen mode

Need to protect the commit path?

shk scan --staged
shk hooks install
Enter fullscreen mode Exit fullscreen mode

The basic loop is intentionally boring: scan, review, mask, and block only when a configured threshold is met.

The AI-specific part: managed hooks

The more interesting piece is shk hooks install-ai.

Instead of relying on you to remember to scan every prompt, shk can write managed hook entries into supported AI tool configs:

# Preview the changes first.
shk hooks install-ai --dry-run

# Start in audit mode: log findings, never block.
shk hooks install-ai --audit

# Or target one tool.
shk hooks install-ai --tool cursor
shk hooks install-ai --tool claude-code --global
Enter fullscreen mode Exit fullscreen mode

Project-level installs are the default. Global installs write to the user-level config for the selected tool.

Supported integrations:

Tool Managed config
Claude Code .claude/settings.json
Cursor .cursor/hooks.json
Codex .codex/config.toml

The managed entries are tagged so they are easy to identify later ("_shk_managed": true in JSON configs, or # shk-managed-start / # shk-managed-end in shell and TOML blocks).

It checks intent, not only text

Secret scanners usually inspect content. AI hooks also need to inspect actions.

In hook mode, shk reads the AI tool's JSON hook payload and runs an action guard before scanning extracted text. The guard looks for operation shapes such as:

  • Reads or writes involving sensitive paths.
  • Commands that dump .env-style files.
  • Destructive recursive removal.
  • Direct database mutation commands.
  • Privilege or system configuration changes.
  • External transfer commands.
  • Package-manager operations.

The default recommended profile is conservative. A strict profile can also block opaque execution forms such as bash -c, python -c, and node -e, because pretending to safely interpret every nested command string is usually worse than being explicit about the risk.

You can tune this in shk.toml with [action_guard] allow and deny patterns.

Audit first, then block

Hooks make decisions through exit codes, so the contract is small:

Code Meaning
0 No finding at or above the active threshold, or audit/post-hook completed.
1 Scan findings met or exceeded the active threshold.
2 A blocking AI pre-hook fired, or shk scan --staged ran outside a Git repo.

--audit always exits 0. Post-tool hooks also always exit 0, because the operation already happened and the useful behavior is reporting, not pretending to undo it.

That makes rollout straightforward:

shk hooks install-ai --audit
Enter fullscreen mode Exit fullscreen mode

Let it run for a few days. Review .shk/audit.log. The log is metadata-only: counts, tool name, hook phase, display path, suppressed count, and maximum severity. It does not store raw matched values.

Once the noise level is acceptable, reinstall without --audit and let high-severity pre-hook findings block.

Same binary for Git and CI

AI hooks are the new boundary, but Git still matters.

Install a managed pre-commit hook:

shk hooks install
Enter fullscreen mode Exit fullscreen mode

Generate a GitHub Actions workflow:

shk ci init github
Enter fullscreen mode Exit fullscreen mode

The generated workflow installs the prebuilt release binary and runs:

shk scan . --json --fail-on high
Enter fullscreen mode Exit fullscreen mode

It also uses a few defaults I wanted out of the box:

  • permissions: contents: read for minimal GITHUB_TOKEN scope.
  • concurrency: cancel-in-progress: true so newer PR pushes cancel stale runs.
  • actions/checkout@v6.
  • Release installer instead of cargo install, so CI does not rebuild a Rust toolchain.

You can also generate rollout variants when you need them:

  • shk ci init github --mode audit for non-blocking CI adoption.
  • shk ci init github --shk-version v0.2.3 for reproducible pinned installs.

A few workflows beyond scanning

These are the commands that make shk feel less like a one-off scanner and more like a local security harness:

  • shk doctor checks project hygiene, including ignore coverage and plaintext .env files.
  • shk doctor ignore --fix appends missing required patterns to .gitignore.
  • shk env dotenvx import-keys .env.keys moves dotenvx private keys into the OS credential store.
  • shk env dotenvx run -- npm test injects stored dotenvx keys only into the child process.
  • shk secrets push pushes dotenv payloads into AWS Secrets Manager or GCP Secret Manager through the official aws / gcloud CLIs, with dry-run, audit logging, and PII pre-scan.
  • shk skills install deploys an embedded agent skill for Claude Code, Codex, and Cursor so agents know how to call shk in the project.

All of these are optional. The tool is still useful if you only use scan, mask, and hooks.

Suppression without pasting secrets into config

False positives happen. Test fixtures happen. Public demo values happen.

shk supports a few suppression shapes:

  • Inline comments such as # shk-ignore <rule_id> and # shk-ignore-next-line <rule_id>.
  • Path-based [[allowlist]] entries in shk.toml.
  • Value-specific suppression using value_hash = "sha256-hmac:...".

The value hash is not encryption. It is a deterministic HMAC-SHA256 fingerprint over the raw value and rule id, so someone with the candidate value can recompute it. Its purpose is narrower and practical: your policy file should not become the place where people paste the secret they are trying to suppress.

Expired allowlist entries turn into low-severity warning findings instead of silently disappearing.

What it intentionally does not promise

Security tooling gets dangerous when it overstates its guarantees, so here is the honest scope.

shk is pattern-based. Built-in rules combine hand-tuned shk detections with generated secret.gitleaks.* rules adapted from the gitleaks default configuration. That covers many common providers and formats, but false positives and false negatives are both possible.

The PII rules are designed for "do not paste this into an AI prompt" hygiene. They are not compliance evidence.

The action guard is heuristic. It can flag risky operation shapes in hook payloads, but it is not a shell interpreter and should not pretend to be one.

shk is also not a replacement for a secret manager, a cloud provider's scanning features, or a dedicated enterprise secret-scanning platform. It is a local guardrail layer for the part of development where AI tools read, transform, and generate context.

Try it on an existing repo

The smallest useful sequence is:

shk init
shk scan .
shk hooks install-ai --audit
Enter fullscreen mode Exit fullscreen mode

If the audit log looks reasonable after a short soak period, reinstall without --audit and block on high-severity pre-hook findings. If it is noisy, tune [thresholds], [[allowlist]], and [action_guard] first.

The goal is not to make the tool dramatic. The goal is to make secrets, PII, and risky AI operations visible before they leave the local development boundary.

Issues, rule contributions, and false-positive reports are welcome. The rule set gets better as more real codebases run through it.

Top comments (0)