Skip to content

README.md

Latest commit

 

History

History
148 lines (103 loc) · 7.11 KB

README.md

File metadata and controls

148 lines (103 loc) · 7.11 KB

sentinel

The sentinel extension adds content-aware security guards that intercept tool calls before they execute.

It addresses cross-cutting security gaps that pure command-based guardrails miss:

  • Content-in-location — a file the agent is about to read contains secrets
  • Indirect execution — a file the agent wrote earlier in the session is later executed via bash
  • Out-of-scope operations — a raw bash command performs a system-level action (sudo, curl | bash, brew install, rm -rf /Library/...) or a write/edit targets a file outside the project root (shell config, system directory)
  • Credential safety — the LLM never hardcodes API keys or secrets in tool calls

Configuration

Sentinel reads and merges optional JSON config from three scopes:

  1. Global: $PI_CODING_AGENT_DIR/extensions/sentinel.json or ~/.pi/agent/extensions/sentinel.json
  2. Local/project: a current-working-directory scoped file under $PI_CODING_AGENT_DIR/extensions/sentinel/projects/ or ~/.pi/agent/extensions/sentinel/projects/
  3. Memory: session-only grants written internally while Pi is running

Merge priority is memory > local > global > defaults.

Local/project config is stored in Pi's agent directory instead of the user's working directory, so Sentinel does not create .pi/ files in arbitrary project folders. Existing legacy .pi/extensions/sentinel.json files are still read for compatibility, but new local/project writes go to the agent directory.

{
  "enabled": true,
  "features": {
    "outputScanner": true,
    "executionTracker": true,
    "permissionGate": true,
    "pathAccess": false
  },
  "pathAccess": {
    "mode": "ask",
    "allowedPaths": []
  },
  "permissionGate": {
    "requireConfirmation": true,
    "allowedPatterns": [],
    "autoDenyPatterns": []
  },
  "outputScanner": {
    "readAllowedPaths": []
  }
}

All fields are optional. Path access is available but disabled by default to avoid surprising existing users.

Path access grants

When features.pathAccess is enabled, Sentinel checks read, write, edit, and path-like bash arguments that point outside ctx.cwd.

Modes:

  • allow — no outside-project restrictions
  • ask — prompt to allow once, allow file/directory for the session, allow file/directory always, or deny
  • block — block outside-project paths unless they match pathAccess.allowedPaths

Allowed directory grants use a trailing slash, e.g. /tmp/shared/; exact file grants omit it.

Events

Sentinel emits best-effort extension events for other extensions:

  • sentinel:dangerous when a guard detects risky content or behavior
  • sentinel:blocked when a guard blocks a tool call

Payloads include feature, toolName, input, and either description/labels or reason/userDenied.

Guards

1. output-scanner — secret detection on read

Pre-reads files before read tool calls execute and scans for credential patterns. If secrets are found, the user is asked before the read is allowed. The same guard also intercepts bash commands that read file content (cat, head, tail, less, more) and pre-scans their targets.

Detected patterns include:

  • AWS access and secret keys
  • GitHub personal access and OAuth tokens
  • Anthropic, OpenAI, Slack, Stripe, Google OAuth keys
  • PEM private keys
  • Generic secret/password/token/api_key = "..." assignments
  • High-entropy strings above a Shannon-entropy threshold

Scan results are cached per file by mtime and invalidated via context-guard:file-modified events. If a detected secret is safe for the current file (for example, documentation containing fake/example keys), the confirmation dialog offers Allow once, Always allow this file, or Deny. Remembered files are stored in Sentinel's persistent whitelist.

2. execution-tracker — write/execute correlation

Two hooks working together:

  • Write-time tracking — every write and edit tool call is recorded in a session write registry. The new content is scanned for dangerous patterns but the write is never blocked.
  • Execution-time correlation — when bash runs a script, the path is extracted and checked against the registry. If the script was written in this session and contains dangerous patterns, execution is escalated to the user (or blocked when there is no UI).

Flagged patterns include curl | bash, wget | bash, eval against untrusted input, curl -X POST exfiltration, rm -rf, chmod 777, sudo, and persistence hooks (crontab, systemctl enable, launchctl).

If the target file was modified after the tracked write, it is re-read and re-scanned before the decision — avoiding false positives when the agent rewrote the dangerous content out.

3. permission-gate — proactive bash / write / edit gate

Where execution-tracker only fires for session-written scripts, permission-gate intercepts every bash command and every write / edit and matches them against a fixed set of risk classes. It runs in addition to the other two guards.

Bash analysis uses Sentinel's small internal shell parser for quotes, redirects, pipelines, and command boundaries, with regex fallbacks when parsing fails.

Bash risk classes

Risk class Example
remote-pipe-exec curl -Ls https://mise.run | bash
privilege-escalation sudo systemctl restart nginx
destructive-system-rm rm -rf /Library/Developer/CommandLineTools
package-manager-install brew install ripgrep
persistence crontab -l, systemctl enable, launchctl load
shell-config-write echo "export FOO=1" >> ~/.zshrc
system-binary-install cp ./mybin /usr/local/bin/mybin

rm -rf on project-local paths (e.g. node_modules, dist, ./build/cache) is intentionally not flagged.

Path categories for write / edit

Category Example
shell-config ~/.zshrc, ~/.bashrc, ~/.profile
system-directory /usr/*, /Library/*, /opt/*, /etc/*
outside-project any absolute path not under ctx.cwd

Decision matrix

UI available + user allows  → proceed
UI available + user denies  → block with reason
No UI + dangerous detected  → block with reason (fail-safe)
No risk classes matched     → proceed

When multiple risk classes match a single command, all matched labels are surfaced in one combined confirmation dialog instead of stacking prompts.

Behavior

  • No UI available — guards fail safe by blocking with a clear reason.
  • UI available — the user sees a dialog with the matched labels, line numbers, and snippets, and can allow once, remember the file/path when supported, or deny.
  • Session state (scan cache, write registry) is cleared on session_start.

Install

pi install npm:pi-mono-sentinel