PathGuard — Sensitive File Protection

Overview

PathGuard is Yukkai's centralized file-access protection system. It intercepts every file operation triggered by Yukkai's built-in tools — before the operation executes — and checks the target path against a set of protection rules. If the path is sensitive, PathGuard pauses the action and asks you for explicit approval.

This means the AI assistant can never silently read your private keys, credentials, browser history, or other protected data. You are always in control.

How it works

PathGuard runs inside Yukkai's ToolRegistry, the layer that sits between the AI model and the actual tool execution. Here's the flow for every tool call that involves a file path:

1. Intercept — Before any tool executes, PathGuard inspects its parameters for file paths (file_path, path, source_path, output_path, etc.).
2. Analyze — For shell commands (bash), PathGuard parses the command text to detect paths expressed as absolute paths, ~, or $HOME references.
3. Resolve — Each detected path is resolved to its canonical form (expanding symlinks and ~ shorthand).
4. Compare — The resolved path is matched against all active protection rules — both built-in and custom.
5. Decide — If the path matches a Critical or Sensitive rule, a popup appears in the Yukkai UI asking you to approve or deny the access. If no rule matches, the tool proceeds normally.

Severity levels

PathGuard classifies protected paths into two severity tiers:

Severity	Icon	What it protects	Examples
Critical	🔴	Cryptographic keys & credentials	~/.ssh, ~/.gnupg, ~/.aws, ~/.azure, ~/.gcloud, ~/.kube, ~/.docker/config.json, ~/.netrc, ~/.git-credentials, ~/.npmrc, ~/Library/Keychains, /etc/master.passwd, browser password stores
Sensitive	🟠	Personal data & traces	~/.bash_history, ~/.zsh_history, ~/Library/Cookies, ~/Library/Safari, Chrome/Firefox cookie databases

There are approximately 22 built-in rules covering the most common sensitive locations on macOS.

Key principles

• Never silent — PathGuard never blocks an action without telling you. A popup always appears, showing the exact path and the requested operation (read, write, delete, etc.).
• Session-only approval — If you approve access to a sensitive path, that approval is valid only for the current session. When you restart Yukkai, all approvals are reset.
• No permanent access for sensitive paths — You cannot configure PathGuard to permanently allow access to Critical or Sensitive paths. Each new session requires fresh approval.
• Built-in rules can be disabled, not deleted — You can turn off a default rule if it's too restrictive for your workflow, but it remains available to re-enable later.

How to use it

PathGuard is enabled by default and works automatically — no setup required. However, you can customize its behavior:

Viewing and managing rules

1. Open Settings in Yukkai.
2. Navigate to Security > PathGuard.
3. You'll see the list of built-in rules (grouped by severity) and any custom rules you've added.

From there you can:

• Toggle a built-in rule on or off.
• Add a custom rule for a path you want protected.
• Delete a custom rule (built-in rules cannot be deleted, only disabled).

Adding a custom rule

Custom rules support three pattern types:

Pattern type	Syntax	Example	Matches
Exact path	Full path, no wildcards	/Users/me/secret.env	Only that specific file
Folder prefix	Path ending with /	/Users/me/private/	Everything inside that folder (any depth)
Glob	Uses * and **	/Users/me/**/*.pem	Any .pem file at any depth under your home directory

When creating a custom rule, you also choose a severity level (Critical or Sensitive). Both levels trigger the approval popup — the severity label helps you quickly understand why a path is protected.

Examples

Example 1: Reading a config file inside a protected folder

The AI tries to read ~/.aws/credentials:

⚠️ PathGuard — Access Request

  Path:    /Users/you/.aws/credentials
  Rule:    Critical — AWS credentials
  Action:  Read

  [ Approve for this session ]   [ Deny ]

If you click Deny, the tool call is cancelled and the AI is informed that access was refused. If you click Approve, the read proceeds — but only for this session.

Example 2: Bash command touching a protected path

The AI runs a bash command:

cat ~/.ssh/id_rsa.pub

PathGuard parses the command, detects ~/.ssh/id_rsa.pub, matches it against the Critical — SSH keys rule, and shows the approval popup before the command is allowed to run.

Example 3: Adding a custom rule for a project secrets folder

Suppose you keep environment files in /Users/me/projects/.secrets/. You can add a custom rule:

• Pattern: /Users/me/projects/.secrets/
• Type: Folder prefix
• Severity: Critical

From now on, any attempt to read or write inside that folder triggers an approval popup.

Example 4: Disabling a rule that's too broad

If the ~/.npmrc rule blocks legitimate workflow (e.g., you frequently need the AI to read your npm config), you can disable it in Settings > Security > PathGuard. The file will no longer trigger a popup. You can re-enable the rule at any time.

Tips & best practices

• Leave Critical rules on — They protect your most valuable secrets (SSH keys, cloud credentials). Disabling them removes a key layer of defense.
• Use custom rules for project-specific secrets — If you store .env files, private certificates, or API keys in a specific project folder, add a custom rule with a folder-prefix pattern.
• Review approvals at the end of a session — Since approvals are session-scoped, take a moment to recall what you approved. If something seems unexpected, restart Yukkai to reset all approvals.
• Don't disable PathGuard entirely — While individual rules can be toggled, keeping PathGuard active ensures that any new sensitive path the AI might target is still caught by the default rule set.
• Glob patterns are powerful but broad — A pattern like ~/**/*.key will match any .key file anywhere under your home directory. Use broad globs for severity levels you're comfortable with, and prefer folder-prefix patterns for targeted protection.
• PathGuard complements the Vault — PathGuard protects files on disk from being accessed without your knowledge. The Vault protects secrets by encrypting them and never exposing their values to the AI. Together they form a two-layer defense for your sensitive data.