Security

Practices, detection, and reporting

On this page

Overview
Secret detection
Plugin sandboxing
Security model
Vulnerability reporting

Overview

klaudiush validates Claude Code operations to prevent security issues before they happen. Built-in secret detection, file write protection, shell safety checks, and GitHub Actions workflow validation run automatically without configuration.

Secret detection

The secrets validator checks file content against 25+ regex patterns for common credential formats. It catches secrets before they're committed.

AWS access keys          AKIA[0-9A-Z]{16}
AWS secret keys          [0-9a-zA-Z/+]{40}
GitHub tokens            ghp_/gho_/ghs_/ghu_/github_pat_ prefixed
Private keys             BEGIN (RSA|DSA|EC|OPENSSH) PRIVATE KEY
Connection strings       mongodb://, postgres://, mysql://, redis://
API keys                 Stripe (sk_live_), Twilio, SendGrid, etc.

For extra coverage, enable gitleaks integration. klaudiush runs its built-in patterns first, then optionally delegates to gitleaks for additional checks.

[validators.secrets]
enabled = true
use_gitleaks = true    # Optional: use gitleaks for extra coverage

To allow secrets in test fixtures, use the rules engine with an allow action scoped to test directories, or the exception workflow for one-off bypasses.

Plugin sandboxing

Exec plugins run as child processes with configurable timeouts. Each plugin declares what events and tools it handles via predicates - it only receives matching events.

[[plugins.plugins]]
name = "my-plugin"
type = "exec"
path = "~/.local/share/klaudiush/plugins/my-plugin.sh"
timeout = "5s"    # Execution timeout

[plugins.plugins.predicate]
event_types = ["PreToolUse"]
tool_types = ["Bash"]

Plugins communicate over stdin/stdout using JSON. They can't access klaudiush internals or modify other plugins' results. A crashing plugin is treated the same as any other crash - the operation proceeds.

Security model

klaudiush runs as a Claude Code PreToolUse hook. It receives the tool call before execution and can block it by returning a deny response. This means:

Secrets are caught before they reach disk or git history
Dangerous shell commands are blocked
Git operations go through validation first
Sensitive file paths are protected

The bash AST parser detects file writes via redirects, tee, cp, and mv. Path protection blocks writes to /tmp. Backtick detection catches unquoted command substitution.

Not a security boundary

klaudiush validates Claude Code tool calls. It does not sandbox the Claude Code process itself. A determined user can bypass klaudiush by modifying the hook configuration.

Vulnerability reporting

If you discover a security vulnerability in klaudiush, report it privately. Do not open a public GitHub issue.

Contact: bartek@smykla.com

Do NOT report vulnerabilities via public GitHub issues.

Timeline:
  1. Acknowledgment within 48 hours
  2. Investigation and fix development
  3. Release with fix
  4. Coordinated public disclosure