chines, centralize detection logic in a single TOML configuration. This file defines severity thresholds, allowed paths, and action guard profiles.

// security-init.ts
import { execSync } from 'child_process';
import { writeFileSync, existsSync } from 'fs';

export function bootstrapGuardrailPolicy(projectRoot: string): void {
  const policyPath = `${projectRoot}/guardrail.toml`;
  
  if (!existsSync(policyPath)) {
    execSync('shk init', { cwd: projectRoot, stdio: 'inherit' });
    console.log('[Guardrail] Policy scaffold generated.');
  } else {
    console.log('[Guardrail] Policy already exists. Skipping initialization.');
  }
}

The initialization step creates a deterministic baseline. All subsequent scans, hooks, and CI runs reference this single source of truth. This eliminates configuration drift between developer environments and automated pipelines.

Step 2: Orchestrate Scanning and Masking

Raw CLI output is human-readable but unsuitable for automation. Parse the JSON report to enforce thresholds programmatically. The masking workflow operates independently, sanitizing prompts before they reach external models.

// context-sanitizer.ts
import { execSync } from 'child_process';

interface ScanReport {
  findings: Array<{
    rule_id: string;
    severity: 'LOW' | 'MED' | 'HIGH' | 'CRITICAL';
    file_path: string;
    line_number: number;
    redacted_value: string;
  }>;
}

export function runWorkspaceScan(targetDir: string): ScanReport {
  const rawOutput = execSync(`shk scan ${targetDir} --json`, { encoding: 'utf-8' });
  return JSON.parse(rawOutput) as ScanReport;
}

export function sanitizePrompt(inputPath: string, outputPath: string): void {
  execSync(`shk mask < ${inputPath} > ${outputPath}`, { stdio: 'inherit' });
}

The JSON contract guarantees that raw matched values are never emitted. Findings use deterministic redaction placeholders, ensuring that automation pipelines never accidentally log credentials. The masking utility operates as a stream transformer, making it safe to pipe into AI chat interfaces or documentation generators.

Step 3: Deploy Managed AI Hooks

AI tools expose configuration files that accept pre-execution hooks. Instead of manually editing JSON or TOML files, use the managed installer to inject standardized guard entries. These entries are tagged for lifecycle management and can be toggled between audit and enforcement modes.

// hook-deployer.ts
import { execSync } from 'child_process';

type AIPlatform = 'claude-code' | 'cursor' | 'codex';

export function installAgentHooks(
  platform: AIPlatform,
  mode: 'audit' | 'enforce',
  scope: 'project' | 'global' = 'project'
): void {
  const scopeFlag = scope === 'global' ? '--global' : '';
  const modeFlag = mode === 'audit' ? '--audit' : '';
  
  const command = `shk hooks install-ai --tool ${platform} ${modeFlag} ${scopeFlag}`.trim();
  
  try {
    execSync(command, { stdio: 'inherit' });
    console.log(`[Hooks] ${platform} guard deployed (${mode} mode, ${scope} scope).`);
  } catch (error) {
    console.error(`[Hooks] Failed to deploy ${platform} hooks.`);
    throw error;
  }
}

Managed hooks read the AI tool's JSON payload before execution. They evaluate operation shapes (file reads, command execution, network calls) against an action guard profile. This moves beyond text scanning to intent verification.

Step 4: Integrate CI/CD with Exit-Code Contract

The guardrail binary communicates through a strict exit-code contract:

• 0: Pass or audit mode completed
• 1: Findings met or exceeded active threshold
• 2: Blocking pre-hook fired or executed outside Git repository

This contract enables seamless CI integration without custom parsing logic.

# .github/workflows/guardrail-check.yml
name: Workspace Security Guardrail
on:
  pull_request:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install guardrail binary
        run: |
          curl --proto '=https' --tlsv1.2 -LsSf \
            https://github.com/Kazuki-tam/security-harness-kit/releases/latest/download/shk-cli-installer.sh | sh
      - name: Run pre-commit scan
        run: shk scan . --json --fail-on high

The workflow uses minimal token permissions, cancels stale runs on new pushes, and installs the prebuilt release binary to avoid Rust toolchain compilation overhead. This keeps CI execution time predictable and secure.

Architecture Rationale

1. Single Binary Distribution: A compiled Rust binary eliminates dependency management, version conflicts, and runtime overhead. It runs identically across macOS, Linux, and Windows.
2. Exit-Code Contract: Standardized return codes allow the tool to plug into any CI system, shell script, or IDE extension without custom adapters.
3. Audit-First Rollout: Detection and enforcement are decoupled. Teams can observe false positive rates and tune thresholds before blocking developer workflows.
4. HMAC-Based Suppression: Allowlists use deterministic fingerprints instead of plaintext secrets. This prevents policy files from becoming accidental credential repositories.

Pitfall Guide

1. Treating Pre-Commit Hooks as Complete Coverage

Explanation: Developers assume Git hooks catch all credential leaks. AI agents read files, execute commands, and generate code outside the commit lifecycle. Fix: Deploy managed AI hooks alongside Git hooks. Verify that pre-interaction scanning covers prompt masking and action guard evaluation.

2. Hardcoding Secrets in Allowlists

Explanation: Pasting raw credentials into suppression rules turns policy files into security liabilities. If the repository is cloned or shared, the "suppressed" secret becomes visible. Fix: Use value_hash suppression with HMAC-SHA256 fingerprints. The guardrail recomputes the hash at runtime, keeping raw values out of configuration files.

3. Assuming the Action Guard is a Shell Interpreter

Explanation: The action guard uses heuristic pattern matching to flag risky operation shapes. It does not parse nested commands or evaluate dynamic string interpolation. Fix: Treat the guard as a conservative filter. Enable the strict profile to block opaque execution forms (bash -c, python -c, node -e) and require explicit command structures in AI prompts.

4. Skipping the Audit Phase

Explanation: Enabling enforcement immediately causes workflow paralysis. High false positive rates block legitimate development and trigger alert fatigue. Fix: Always start with --audit mode. Review .shk/audit.log for metadata patterns (tool name, hook phase, severity distribution) over a 3-5 day soak period before switching to enforcement.

5. Over-Privileging CI Tokens

Explanation: Generated workflows sometimes inherit broad repository permissions. This violates least-privilege principles and increases blast radius if the CI environment is compromised. Fix: Explicitly set permissions: contents: read in GitHub Actions. Avoid write or admin scopes unless the workflow explicitly modifies repository state.

6. Equating PII Detection with Compliance

Explanation: Built-in PII rules are designed for prompt hygiene, not regulatory compliance. They catch common patterns (SSNs, phone numbers, emails) but do not validate format correctness or jurisdictional requirements. Fix: Use PII scanning as a developer guardrail, not a compliance control. Route sensitive data handling through dedicated DLP or compliance platforms for audit trails and legal validation.

7. Ignoring Threshold Tuning

Explanation: Default thresholds prioritize safety over usability. In large codebases with legacy test fixtures, this generates excessive noise. Fix: Adjust [thresholds] in the policy file. Lower enforcement to MED only after validating that HIGH and CRITICAL findings are legitimate. Use path-based allowlists for known safe directories like test/fixtures/ or docs/examples/.

Production Bundle

Action Checklist

• Initialize policy: Run shk init to generate a centralized configuration file
• Configure thresholds: Adjust [thresholds] to match team risk tolerance before enforcement
• Deploy audit hooks: Install AI tool hooks with --audit mode and monitor .shk/audit.log
• Tune allowlists: Add path-based rules and HMAC value hashes for known safe patterns
• Switch to enforcement: Reinstall hooks without --audit and verify exit-code behavior
• Integrate CI: Generate GitHub Actions workflow with minimal permissions and concurrency controls
• Validate masking: Test shk mask on production logs and error traces before AI prompt usage
• Rotate credentials: Treat any HIGH/CRITICAL finding as an immediate rotation trigger

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo developer / Open source	Local scan + Git pre-commit hook	Minimal overhead, catches accidental commits	Near-zero CI cost, fast feedback
Mid-size team / Internal repo	AI hooks (audit → enforce) + CI scan	Prevents AI context leaks, standardizes team policy	Moderate CI time, reduced credential rotation costs
Enterprise / Regulated workload	Strict action guard + HMAC suppression + dedicated DLP pipeline	Meets compliance boundaries, eliminates plaintext policy storage	Higher initial tuning effort, lower incident response cost

Configuration Template

# shk.toml
[thresholds]
pre_commit = "HIGH"
ai_pre_hook = "MED"
ci_pipeline = "HIGH"

[audit]
enabled = true
log_path = ".shk/audit.log"
max_entries = 5000

[[allowlist]]
paths = ["test/fixtures/", "docs/api-examples/", "migrations/seed_data.sql"]
description = "Known safe test and documentation files"

[[allowlist]]
value_hash = "sha256-hmac:a1b2c3d4e5f6..."
rule_id = "secret.aws_access_key"
description = "Legacy demo key rotated in staging"

[action_guard]
profile = "recommended"
deny_patterns = ["bash -c", "python -c", "node -e", "rm -rf /", "DROP TABLE", "GRANT ALL"]
allow_patterns = ["npm install", "git status", "cat .env.example"]

[pii]
enabled = true
regions = ["en", "ja"]
rules = ["ssn", "phone", "email", "credit_card"]

Quick Start Guide

1. Install the binary: Execute the platform-specific installer script (curl for Unix, powershell for Windows) to fetch the latest release.
2. Generate policy: Run shk init in your project root. Review the generated shk.toml and adjust thresholds to match your team's risk appetite.
3. Deploy audit hooks: Execute shk hooks install-ai --audit for your primary AI assistant. Let it run for 3-5 days while monitoring .shk/audit.log for false positive patterns.
4. Tune and enforce: Add path-based allowlists and HMAC value hashes for known safe patterns. Reinstall hooks without --audit to enable blocking on high-severity findings.
5. Validate CI integration: Run shk ci init github to generate a workflow. Verify that permissions: contents: read and concurrency controls are applied before merging.