auto-permission-system 3.8.0 → 3.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +9 -0
- package/README.md +332 -219
- package/assets/demo.gif +0 -0
- package/assets/demo.mp4 +0 -0
- package/assets/logo.png +0 -0
- package/banner.png +0 -0
- package/package.json +8 -6
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,15 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
Entries below [1.0.0] are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from [Conventional Commits](https://www.conventionalcommits.org/) — do not edit by hand.
|
|
5
5
|
|
|
6
|
+
# [3.9.0](https://github.com/Navin009/auto-permission-system/compare/v3.8.0...v3.9.0) (2026-10-13)
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
|
|
10
|
+
* **demo:** crisp widescreen HD terminal recording (`demo.mp4`, `demo.gif`) demonstrating Cloud Auto Mode and Advanced Secure Mode
|
|
11
|
+
* **branding:** official security shield logo and banner in documentation and package
|
|
12
|
+
* **docs:** comprehensive FAQ, Cloud Auto Mode architecture, interactive prompt guides, and zero-trust documentation
|
|
13
|
+
* **metadata:** package keywords, clean npm manifest, and remove legacy PyPI references
|
|
14
|
+
|
|
6
15
|
# [2.0.0](https://github.com/Navin009/auto-permission-system/compare/v1.2.0...v2.0.0) (2026-10-02)
|
|
7
16
|
|
|
8
17
|
|
package/README.md
CHANGED
|
@@ -1,346 +1,459 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://pi.dev/packages">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/Navin009/auto-permission-system/main/assets/logo.png" alt="Auto Permission System Logo" width="160" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
# Auto Permission System: Secure Auto Mode & Security for Pi Coding Agent
|
|
2
8
|
|
|
3
9
|
[](https://www.npmjs.com/package/auto-permission-system)
|
|
4
10
|
[](https://www.npmjs.com/package/auto-permission-system)
|
|
5
11
|
[](./LICENSE)
|
|
6
12
|
[](https://pi.dev/packages)
|
|
7
13
|
[](https://github.com/Navin009/auto-permission-system/actions/workflows/ci.yml)
|
|
8
|
-
[](#
|
|
9
|
-
[](#security-for-pi
|
|
10
|
-
[](#permission-system
|
|
14
|
+
[](#secure-auto-mode--cloud-auto-mode)
|
|
15
|
+
[](#security-for-pi-how-it-works)
|
|
16
|
+
[](#permission-system--modes)
|
|
17
|
+
|
|
18
|
+
**Auto Permission System** is a zero-trust permission architecture and **Secure Auto Mode / Cloud Auto Mode for the [Pi coding agent](https://pi.dev)**. It brings the confidence of **Claude's auto mode** to Pi—enabling autonomous agent workflows while actively scanning files, shell commands, and tool content to **prevent data breaches and credential exfiltration**.
|
|
11
19
|
|
|
12
|
-
|
|
20
|
+
Whether running interactively with keyboard-driven ask prompts or running headlessly in CI/CD pipelines, this package enforces multi-layer boundaries across filesystem access, network egress, shell commands, and MCP tools.
|
|
21
|
+
|
|
22
|
+
---
|
|
13
23
|
|
|
14
|
-
|
|
24
|
+
## Demo: Zero-Trust Security in Action
|
|
15
25
|
|
|
16
|
-
|
|
17
|
-
- **Layer 2** — In-process tool guard applying the same policy to the tools the OS sandbox can't reach: `read`, `grep`, `find`, `ls`, `write`, `edit`, `fetch_content`, `web_search`, `get_search_content`. `grep` output lines from denied files beneath an allowed search root are removed before the model sees them.
|
|
18
|
-
- **Layer 3** — Subagent posture: optionally drop or restrict network access when running headless (`-p`, JSON mode, subagents).
|
|
26
|
+
|
|
19
27
|
|
|
20
|
-
|
|
28
|
+
> **High-Definition Video:** Watch or download the full-resolution recording at [assets/demo.mp4](https://raw.githubusercontent.com/Navin009/auto-permission-system/main/assets/demo.mp4) (H.264, 60fps). Run `./demo/run-demo.sh` locally to reproduce this live simulation.
|
|
29
|
+
|
|
30
|
+
### Demonstrated Moments in the Recording:
|
|
31
|
+
1. **Interactive `.env` Read Guard:** Intercepts `read(".env")` before the AI can see secrets. Displays a 10s countdown prompt defaulting to `No` (Block).
|
|
32
|
+
2. **Kernel OS Sandbox Confinement:** Prevents bash commands from writing to system paths outside allowed roots (`EROFS: Read-only file system`).
|
|
33
|
+
3. **Governed Network Egress:** Catches unknown outbound connections (`curl`) with an interactive domain ask prompt and a 15s countdown timer.
|
|
34
|
+
4. **Real-Time API Key & Secret Redaction:** Automatically detects exposed API tokens (`sk-proj-...`, `ghp_...`) in command output and replaces them with `***REDACTED***` before reaching the LLM context.
|
|
35
|
+
5. **Autonomous Cloud Auto Mode:** Demonstrates headless, fail-closed CI execution (`pi -p`) with zero deadlocks and zero hangs.
|
|
36
|
+
|
|
37
|
+
---
|
|
21
38
|
|
|
22
39
|
## Contents
|
|
23
40
|
|
|
24
|
-
- [
|
|
41
|
+
- [Quickstart & Installation](#quickstart--installation)
|
|
25
42
|
- [Requirements](#requirements)
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
43
|
+
- [Key Features at a Glance](#key-features-at-a-glance)
|
|
44
|
+
- [Security for Pi: How It Works](#security-for-pi-how-it-works)
|
|
45
|
+
- [Interactive Ask Prompts](#interactive-ask-prompts)
|
|
46
|
+
- [Secure Auto Mode & Cloud Auto Mode](#secure-auto-mode--cloud-auto-mode)
|
|
47
|
+
- [Real-Time Secret Detection & Content Scanning](#real-time-secret-detection--content-scanning)
|
|
48
|
+
- [Permission System & Modes](#permission-system--modes)
|
|
49
|
+
- [Configuration Reference](#configuration-reference)
|
|
50
|
+
- [Commands & Mid-Session Controls](#commands--mid-session-controls)
|
|
51
|
+
- [Escape Hatches](#escape-hatches)
|
|
52
|
+
- [Audit Logging](#audit-logging)
|
|
53
|
+
- [FAQ & Scenarios](#faq--scenarios)
|
|
54
|
+
- [Development & Testing](#development--testing)
|
|
36
55
|
- [Releasing](#releasing)
|
|
37
56
|
- [License](#license)
|
|
38
57
|
|
|
39
|
-
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Quickstart & Installation
|
|
40
61
|
|
|
41
|
-
`auto-permission-system`
|
|
62
|
+
Install `auto-permission-system` directly through the [Pi package manager](https://pi.dev/packages):
|
|
42
63
|
|
|
43
64
|
```bash
|
|
44
|
-
#
|
|
65
|
+
# 1. Install from npm (recommended)
|
|
45
66
|
pi install npm:auto-permission-system
|
|
46
67
|
|
|
47
|
-
#
|
|
68
|
+
# 2. Or install directly from GitHub
|
|
48
69
|
pi install git:github.com/Navin009/auto-permission-system
|
|
49
70
|
|
|
50
|
-
#
|
|
71
|
+
# 3. Or try it for a single session without permanent installation
|
|
51
72
|
pi -e npm:auto-permission-system
|
|
52
73
|
```
|
|
53
74
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
## Requirements
|
|
75
|
+
Once installed, the extension automatically loads whenever you launch `pi`. Check your active security status in the terminal footer or by typing `/security`.
|
|
57
76
|
|
|
58
|
-
|
|
59
|
-
- macOS: `sandbox-exec` is built in
|
|
60
|
-
- Linux: `bubblewrap`, `socat`
|
|
61
|
-
|
|
62
|
-
## Configuration
|
|
77
|
+
---
|
|
63
78
|
|
|
64
|
-
|
|
79
|
+
## Requirements
|
|
65
80
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
| `<cwd>/.pi/sandbox.json` | Project-local (auto-written by ask-tier prompts) |
|
|
81
|
+
- **Linux:** Requires `bubblewrap` and `socat` for Layer 1 OS-level isolation:
|
|
82
|
+
```bash
|
|
83
|
+
# Ubuntu / Debian
|
|
84
|
+
sudo apt-get install -y bubblewrap socat
|
|
71
85
|
|
|
72
|
-
|
|
86
|
+
# Fedora / RHEL
|
|
87
|
+
sudo dnf install -y bubblewrap socat
|
|
73
88
|
|
|
74
|
-
|
|
89
|
+
# Arch Linux
|
|
90
|
+
sudo pacman -S bubblewrap socat
|
|
91
|
+
```
|
|
92
|
+
- **macOS:** Built-in `sandbox-exec` is utilized automatically (no extra packages required).
|
|
93
|
+
- **Node.js:** v18.0.0 or later.
|
|
94
|
+
- **Pi Coding Agent:** `@earendil-works/pi-coding-agent` ([pi.dev](https://pi.dev)).
|
|
75
95
|
|
|
76
|
-
|
|
77
|
-
{
|
|
78
|
-
"enabled": true, // set false to disable Layer 2 without --yolo
|
|
79
|
-
"mode": "default", // "default" (rules) | "advanced-secure" (secret detection, ADR-018)
|
|
80
|
-
"network": {
|
|
81
|
-
"allowedDomains": [ // domains the URL tools and bash may reach
|
|
82
|
-
"github.com", "*.github.com",
|
|
83
|
-
"registry.npmjs.org"
|
|
84
|
-
],
|
|
85
|
-
"deniedDomains": [], // hard deny, checked first, never ask-able
|
|
86
|
-
"strictAllowlist": false // true = deny unknown hosts instead of asking
|
|
87
|
-
},
|
|
88
|
-
"filesystem": {
|
|
89
|
-
"denyRead": ["~/.ssh", "~/.aws", "~/.pi/agent"], // Layer 1 + Layer 2: no read at all
|
|
90
|
-
"askRead": [".env", ".env.*"], // Layer 1 + Layer 2: ask before reading, not hard-denied (ADR-019)
|
|
91
|
-
"modelDenyRead": ["~/.netrc"], // Layer 2 only: model's read tool blocked; subprocesses ok
|
|
92
|
-
"allowWrite": [".", "/tmp"], // Layer 2: writes only inside these roots
|
|
93
|
-
"denyWrite": [".env", "*.pem"] // Layer 1 + Layer 2: write always blocked
|
|
94
|
-
},
|
|
95
|
-
"subagent": {
|
|
96
|
-
"network": "allow" // "allow" | "deny" | "research-only"
|
|
97
|
-
},
|
|
98
|
-
"mcp": { // Advanced Secure MCP gate tuning (ADR-032)
|
|
99
|
-
"allowTools": ["mcp__diffusion_studio__context"], // exact names that never ask
|
|
100
|
-
"allowPrefixes": ["mcp__ticktick__get_"], // name prefixes that never ask
|
|
101
|
-
"askTools": [], // exact names that always ask
|
|
102
|
-
"trustAnnotations": false, // true = a server's readOnlyHint allows without asking
|
|
103
|
-
"allowSimpleUpdates": true, // narrow field updates skip the ask
|
|
104
|
-
"askThreshold": 30 // risk score at which a call asks (lower = stricter)
|
|
105
|
-
},
|
|
106
|
-
"commands": {
|
|
107
|
-
"ask": ["printenv", "env", "/proc/*/environ"] // bash: ask before these (they can print env tokens)
|
|
108
|
-
}
|
|
109
|
-
}
|
|
110
|
-
```
|
|
96
|
+
---
|
|
111
97
|
|
|
112
|
-
|
|
98
|
+
## Key Features at a Glance
|
|
113
99
|
|
|
114
|
-
|
|
100
|
+
| Feature | Description | Protection Level |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| 🛡️ **3-Layer Defense** | OS Kernel sandbox (`bubblewrap`/`sandbox-exec`) + in-process tool guard + real-time content redactor. | Zero-Trust |
|
|
103
|
+
| ⚡ **Secure Auto Mode** | Autonomous execution inspired by Claude's auto mode; scans files and output to prevent data breaches. | Autonomous / Cloud |
|
|
104
|
+
| 🔑 **Interactive Ask Prompts** | Real-time terminal prompts with 10s countdowns (`Once`, `Session`, `Project`, `Global`). | Interactive Human-in-the-Loop |
|
|
105
|
+
| 🔍 **AST & Regex Secret Scanner** | Scans tool stdout/stderr for API keys, private keys, and tokens, redacting them before model context. | Data Breach Prevention |
|
|
106
|
+
| 🌐 **Network Egress Gate** | Intercepts unapproved network connections and prompts for confirmation with wildcards. | Data Leak Prevention |
|
|
107
|
+
| 🔒 **Absolute-Deny Tier** | Strict two-step confirmation required for high-risk keys (`~/.ssh`, `~/.aws`, `auth.json`). | Maximum Protection |
|
|
108
|
+
| 📋 **Full JSONL Audit Trail** | Every allow, deny, ask, and redaction event is recorded to `~/.pi/agent/audit.log`. | Compliance & Auditing |
|
|
115
109
|
|
|
116
|
-
|
|
117
|
-
- **Changes that make your security weaker do not apply** until you trust the file. Examples: turn off auto-permission-system, let bash write to `/`, allow more websites.
|
|
118
|
-
- auto-permission-system shows a warning that lists these changes in plain words.
|
|
119
|
-
- **Did you write the file?** Type `/security trust`. auto-permission-system shows the changes and asks you. If you say "No", it does not warn again until the file changes.
|
|
120
|
-
- Trust is for the file as it is now. If the file changes, auto-permission-system asks again.
|
|
121
|
-
- Most folders have no `.pi/sandbox.json`, so you see nothing. Your own "always for CURRENT project" answers keep the file trusted.
|
|
122
|
-
- `/security untrust` removes the trust. `/security` shows the status.
|
|
110
|
+
---
|
|
123
111
|
|
|
124
|
-
|
|
112
|
+
## Security for Pi: How It Works
|
|
125
113
|
|
|
126
|
-
|
|
114
|
+
`auto-permission-system` employs a defense-in-depth model across three coordinated layers:
|
|
127
115
|
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
116
|
+
```
|
|
117
|
+
┌────────────────────────────────────────────────────────────────────────┐
|
|
118
|
+
│ AI Coding Agent Execution │
|
|
119
|
+
└───────────────────────────────────┬────────────────────────────────────┘
|
|
120
|
+
│
|
|
121
|
+
┌────────────────────────┴────────────────────────┐
|
|
122
|
+
▼ ▼
|
|
123
|
+
┌─────────────────────────────────────┐ ┌─────────────────────────────────────┐
|
|
124
|
+
│ Layer 2: In-Process Tool Guard │ │ Layer 1: OS Kernel Sandbox │
|
|
125
|
+
│ - Intercepts read, grep, find, ls │ │ - Bubblewrap (Linux) / sandbox-exec│
|
|
126
|
+
│ - Intercepts write, edit, fetch │ │ - Read-only root filesystem (EROFS)│
|
|
127
|
+
│ - Filters secrets from searches │ │ - Enforces allowWrite roots │
|
|
128
|
+
│ - Gates MCP tool calls & risk verbs│ │ - Intercepts unlisted network egress
|
|
129
|
+
└──────────────────┬──────────────────┘ └──────────────────┬──────────────────┘
|
|
130
|
+
│ │
|
|
131
|
+
└────────────────────┬────────────────────┘
|
|
132
|
+
▼
|
|
133
|
+
┌────────────────────────────────────────────────────────────────────────┐
|
|
134
|
+
│ Layer 3 / Auto Secure: Real-Time Content Redactor │
|
|
135
|
+
│ - Scans stdout/stderr & tool results for API keys, AWS & GitHub tokens│
|
|
136
|
+
│ - Replaces exposed secrets with ***REDACTED*** before model context │
|
|
137
|
+
└────────────────────────────────────────────────────────────────────────┘
|
|
135
138
|
```
|
|
136
139
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
Every prompt waits **10 seconds** by default. For file reads and writes, no answer resolves to the safe default: **block / deny**. For a network ask, no answer resolves to **allow once** (ADR-024); Esc still denies.
|
|
144
|
-
|
|
145
|
-
### File-name patterns
|
|
140
|
+
1. **Layer 1 (OS Kernel Sandbox):**
|
|
141
|
+
Wraps all `bash` commands in an unprivileged kernel container. Writes outside designated folders (`.` and `/tmp`) are refused by the kernel with `EROFS: Read-only file system`. Sensitive directories (`~/.ssh`, `~/.aws`, `~/.gnupg`) are masked. Network egress to unlisted domains is intercepted via a local proxy.
|
|
142
|
+
2. **Layer 2 (In-Process Tool Guard):**
|
|
143
|
+
Applies consistent policy rules to tools that run in-process within Pi (`read`, `grep`, `find`, `ls`, `write`, `edit`, `fetch_content`, `web_search`). Denied files are hidden from search listings before the LLM can observe them.
|
|
144
|
+
3. **Layer 3 / Auto Secure (Sensitive Content Redactor):**
|
|
145
|
+
Operates before any tool output reaches the model's context window. Analyzes content using AST and regex pattern matchers for known tokens (OpenAI, Anthropic, GitHub, AWS, Stripe). If sensitive data is detected, the user can withhold it or have it redacted automatically.
|
|
146
146
|
|
|
147
|
-
|
|
147
|
+
---
|
|
148
148
|
|
|
149
|
-
|
|
149
|
+
## Interactive Ask Prompts
|
|
150
150
|
|
|
151
|
-
`
|
|
151
|
+
When an unlisted domain, `.env` file, or directory write is requested during an interactive terminal session, `auto-permission-system` renders a clean, keyboard-driven prompt:
|
|
152
152
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
- **MCP calls:** `mcp__<server>__<tool>` calls are classified; a risky call asks before it runs. The gate ignores the server namespace, reads the operation from the head verb of the tool name (or the first verb of the description), and asks for destructive names, mutating names (`update_*`, `create_*`, `run_*`, `evaluate_*`), and destructive arguments (SQL `DELETE`, `rm -rf`, `*` targets, HTTP `DELETE`, production targets). A documented tool with an unclassified name (`context`, `capture`, `logs`) does not ask; a tool with no description counts as opaque and does. Tune it under `mcp` in `sandbox.json` — `allowTools` / `allowPrefixes` skip asks, `askTools` forces them, `trustAnnotations` trusts a server's `readOnlyHint`, `askThreshold` moves the score line (ADR-032).
|
|
157
|
-
- **Tool/command/file output:** before any output reaches the model, a secret-like hit shows `⚠ Sensitive information detected`, the file, and each detected line as `lineNo: text`, and the question **Should the AI be allowed to see it?** with two choices — **No, keep private** or **Yes, allow**. A bare `key` counts only when the value looks machine-generated: `key=<random>` asks, while `key=value`, `key=subagent.network`, and code such as `const key = x` stay clean. No, keep private withholds the output and tells the model plainly that the output was withheld because it may contain sensitive information, so the model does not mistake it for a failure or an empty result. Esc or timeout keeps it private.
|
|
153
|
+
### 1. Sensitive `.env` Read Prompt
|
|
154
|
+
```
|
|
155
|
+
🔑 Let pi read your .env file?
|
|
158
156
|
|
|
159
|
-
|
|
157
|
+
File ~/workspace/app/.env
|
|
158
|
+
Command grep -r TOKEN .env
|
|
159
|
+
Why .env files usually hold passwords and API keys
|
|
160
|
+
Risk the AI will see any keys in it
|
|
161
|
+
Note can't be saved as a permanent rule (secrets tier)
|
|
160
162
|
|
|
161
|
-
|
|
163
|
+
> No
|
|
164
|
+
Yes, just this once
|
|
165
|
+
Yes, for this session
|
|
162
166
|
|
|
163
|
-
|
|
167
|
+
Default: No (10s)
|
|
168
|
+
```
|
|
169
|
+
- **Preselected Default:** `No` is preselected. Pressing Enter immediately blocks the read.
|
|
170
|
+
- **Expiry:** If unattended for 10 seconds, the prompt resolves safely to **No** (Block).
|
|
164
171
|
|
|
165
|
-
###
|
|
172
|
+
### 2. Governed Network Egress Prompt
|
|
173
|
+
```
|
|
174
|
+
🌐 Let bash connect to unknown-telemetry.io?
|
|
166
175
|
|
|
167
|
-
|
|
176
|
+
Site unknown-telemetry.io
|
|
177
|
+
Command curl -s https://unknown-telemetry.io/ping
|
|
178
|
+
Why this site isn't on your allowed list yet
|
|
168
179
|
|
|
169
|
-
|
|
180
|
+
> No
|
|
181
|
+
Yes, just this once
|
|
182
|
+
Yes, all in group for this session
|
|
183
|
+
Yes, always…
|
|
170
184
|
|
|
171
|
-
|
|
185
|
+
Default: Yes, just this once (15s)
|
|
186
|
+
```
|
|
187
|
+
- **Network Expiry Rule:** Domain prompts feature a 15-second countdown defaulting to `Allow once` for smooth browsing. Pressing `↑` or `↓` immediately stops the countdown, returning complete control to Enter/Esc.
|
|
172
188
|
|
|
173
|
-
###
|
|
189
|
+
### 3. Real-Time Token Leak Redaction Prompt
|
|
190
|
+
```
|
|
191
|
+
⚠ Sensitive information detected: API Secret Key
|
|
174
192
|
|
|
175
|
-
|
|
193
|
+
Tool bash (node verify_service.js)
|
|
194
|
+
Finding sk-(?!ant-)[A-Za-z0-9_-] (score: 90 / CRITICAL)
|
|
195
|
+
Question Should the AI be allowed to see it?
|
|
176
196
|
|
|
177
|
-
|
|
197
|
+
> No, keep private (recommended)
|
|
198
|
+
Yes, allow
|
|
199
|
+
```
|
|
200
|
+
- Choosing **No, keep private** replaces the token with `***REDACTED***` in the model's context window, preventing credentials from leaking to LLM providers.
|
|
178
201
|
|
|
179
|
-
|
|
202
|
+
---
|
|
180
203
|
|
|
181
|
-
##
|
|
204
|
+
## Secure Auto Mode & Cloud Auto Mode
|
|
182
205
|
|
|
183
|
-
|
|
206
|
+
In modern AI coding tools like Claude Code, developers love **auto mode** because the agent can execute tasks autonomously without constantly prompting for confirmation on trivial, harmless steps.
|
|
184
207
|
|
|
185
|
-
|
|
208
|
+
However, unconstrained auto mode is a significant data breach risk. If an autonomous agent reads credentials, runs unvetted scripts, or sends code to third-party endpoints, the entire developer environment can be compromised.
|
|
186
209
|
|
|
187
|
-
|
|
188
|
-
- **
|
|
189
|
-
- **
|
|
210
|
+
**Cloud Auto Mode for Pi** delivers **Claude-style auto mode with zero-trust security**:
|
|
211
|
+
- **Autonomous Execution with Real-Time Guardrails:** The agent operates autonomously within approved boundaries, allowing rapid development while guarding sensitive resources.
|
|
212
|
+
- **Advanced Secure Scanning:** Uses `advanced-secure` mode to scan files, commands, and content to stop data breaches before they can occur.
|
|
213
|
+
- **Fail-Closed in Headless CI/CD:** When running unattended (`pi -p`, GitHub Actions, Docker, remote devboxes), unapproved operations fail closed immediately with a structured reason instead of hanging or deadlocking the pipeline.
|
|
190
214
|
|
|
191
|
-
### Activating Cloud Auto Mode in
|
|
215
|
+
### Activating Cloud Auto Mode in CI/CD:
|
|
192
216
|
|
|
193
217
|
```bash
|
|
194
218
|
# 1. Copy the shipped Cloud Auto Mode template to your repository:
|
|
219
|
+
mkdir -p .pi
|
|
195
220
|
cp node_modules/auto-permission-system/sandbox.cloud.json .pi/sandbox.json
|
|
196
221
|
|
|
197
222
|
# 2. Run Pi headlessly with complete automated protection:
|
|
198
|
-
pi -p "Review pull request changes and execute test suite"
|
|
223
|
+
pi -p "Review pull request changes, verify dependencies, and execute test suite"
|
|
199
224
|
```
|
|
200
225
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
226
|
+
#### GitHub Actions Workflow Example:
|
|
227
|
+
```yaml
|
|
228
|
+
name: CI Security & Agent Review
|
|
229
|
+
on: [pull_request]
|
|
230
|
+
|
|
231
|
+
jobs:
|
|
232
|
+
agent-review:
|
|
233
|
+
runs-on: ubuntu-latest
|
|
234
|
+
steps:
|
|
235
|
+
- uses: actions/checkout@v4
|
|
236
|
+
- uses: actions/setup-node@v4
|
|
237
|
+
with:
|
|
238
|
+
node-version: 20
|
|
239
|
+
- name: Install Pi and Auto Permission System
|
|
240
|
+
run: |
|
|
241
|
+
npm install -g @earendil-works/pi-coding-agent
|
|
242
|
+
pi install npm:auto-permission-system
|
|
243
|
+
- name: Activate Cloud Auto Mode Preset
|
|
244
|
+
run: |
|
|
245
|
+
mkdir -p .pi
|
|
246
|
+
cp node_modules/auto-permission-system/sandbox.cloud.json .pi/sandbox.json
|
|
247
|
+
- name: Run Autonomous Review in Auto Mode
|
|
248
|
+
run: |
|
|
249
|
+
pi -p "Verify changes, run npm test, and flag security issues"
|
|
250
|
+
```
|
|
204
251
|
|
|
205
|
-
|
|
252
|
+
---
|
|
206
253
|
|
|
207
|
-
|
|
254
|
+
## Real-Time Secret Detection & Content Scanning
|
|
208
255
|
|
|
209
|
-
|
|
210
|
-
2. **In-Process Tool Guard (Layer 2):** Guards the agent's internal tools (`read`, `write`, `edit`, `grep`, `find`, `ls`, `fetch_content`, `web_search`). Denied files are filtered out of directory listings and search outputs before the LLM can observe them.
|
|
211
|
-
3. **Secret Detection & Output Redactor (Auto Secure):** Analyzes tool outputs and bash output streams in real time. Credentials, private keys, API tokens, and environment secrets are masked before reaching the model context window.
|
|
256
|
+
When running in **Advanced Secure Mode** (`advanced-secure`), `auto-permission-system` continuously inspects tool payloads and command stdout/stderr:
|
|
212
257
|
|
|
213
|
-
|
|
214
|
-
- **
|
|
215
|
-
- **
|
|
216
|
-
- **Step 3:** For CI/CD and cloud runs, adopt `sandbox.cloud.json` to enforce strict domain and path boundaries.
|
|
258
|
+
- **High-Confidence Credential Recognition:** Recognizes OpenAI API keys, Anthropic keys, AWS credentials (`AKIA...`), GitHub personal access tokens (`ghp_...`, `github_pat_...`), database URIs (`postgres://`, `mongodb://`), and RSA/OpenSSH private keys.
|
|
259
|
+
- **Context Protection:** If a build command or tool outputs a secret, the system intercepts the stream and prompts the user or redacts the credential to `***REDACTED***`.
|
|
260
|
+
- **Zero-Loss Model Feedback:** The language model is informed that sensitive information was masked, allowing the AI to continue its task without ever seeing or transmitting the actual secret.
|
|
217
261
|
|
|
218
262
|
---
|
|
219
263
|
|
|
220
|
-
## Permission System
|
|
264
|
+
## Permission System & Modes
|
|
221
265
|
|
|
222
|
-
|
|
266
|
+
`auto-permission-system` provides three selectable permission modes:
|
|
223
267
|
|
|
224
|
-
|
|
|
268
|
+
| Mode | Inspection Level | Use Case |
|
|
225
269
|
|---|---|---|
|
|
226
|
-
|
|
|
227
|
-
|
|
|
228
|
-
|
|
|
229
|
-
| **Cloud Auto Mode** | In headless runs (`-p`), unapproved operations fail closed without blocking execution. | Headless subagents, Docker containers, GitHub Actions |
|
|
270
|
+
| **`advanced-secure`** *(Recommended)* | Full rule engine + real-time AST/regex secret detection + MCP risk scoring. | Daily development, autonomous auto mode, untrusted codebases. |
|
|
271
|
+
| **`default`** *(Shipped)* | Rule-based filesystem and network sandbox without inspecting payload content. | Standard development where secret detection is not required. |
|
|
272
|
+
| **`yolo`** *(Emergency)* | Temporarily disables all sandboxing and tool guards. | Emergency troubleshooting only. |
|
|
230
273
|
|
|
231
|
-
|
|
232
|
-
-
|
|
233
|
-
-
|
|
234
|
-
-
|
|
274
|
+
Switch modes anytime mid-session using `/permission-mode`. Your choice is saved to global settings (`~/.pi/agent/extensions/sandbox.json`) and reflected in the status chip:
|
|
275
|
+
- `Sandbox: 🧠 N domains, M paths` for `advanced-secure`
|
|
276
|
+
- `Sandbox: 🔒 N domains, M paths` for `default`
|
|
277
|
+
- `⚠️ YOLO — all security layers disabled` for `yolo`
|
|
235
278
|
|
|
236
279
|
---
|
|
237
280
|
|
|
238
|
-
##
|
|
281
|
+
## Configuration Reference
|
|
239
282
|
|
|
240
|
-
|
|
283
|
+
Policy files are merged hierarchically:
|
|
241
284
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
285
|
+
| Priority | Scope | Location | Purpose |
|
|
286
|
+
|---|---|---|---|
|
|
287
|
+
| 1 (Base) | Package Default | `sandbox.default.json` | Baseline policy shipped with the extension. |
|
|
288
|
+
| 2 (Global) | User Global | `~/.pi/agent/extensions/sandbox.json` | Global overrides across all repositories. |
|
|
289
|
+
| 3 (Project) | Project Local | `<cwd>/.pi/sandbox.json` | Repository-specific rules (auto-written by prompts). |
|
|
246
290
|
|
|
247
|
-
|
|
291
|
+
### Annotated `sandbox.json`:
|
|
248
292
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
293
|
+
```jsonc
|
|
294
|
+
{
|
|
295
|
+
"enabled": true, // Set false to disable Layer 2
|
|
296
|
+
"mode": "advanced-secure", // "advanced-secure" (recommended) | "default" | "yolo"
|
|
297
|
+
"network": {
|
|
298
|
+
"allowedDomains": [ // Allowed domains for bash and fetch_content
|
|
299
|
+
"github.com", "*.github.com",
|
|
300
|
+
"registry.npmjs.org"
|
|
301
|
+
],
|
|
302
|
+
"deniedDomains": [], // Hard-denied domains (never asked, always blocked)
|
|
303
|
+
"strictAllowlist": false // true = fail closed on unknown domains without asking
|
|
304
|
+
},
|
|
305
|
+
"filesystem": {
|
|
306
|
+
"denyRead": [ // Absolute denied reads (Layer 1 + Layer 2)
|
|
307
|
+
"~/.ssh", "~/.aws", "~/.pi/agent"
|
|
308
|
+
],
|
|
309
|
+
"askRead": [ // Sensitive files that prompt instead of hard-blocking
|
|
310
|
+
".env", ".env.*"
|
|
311
|
+
],
|
|
312
|
+
"modelDenyRead": ["~/.netrc"], // Hidden from LLM read tool; subprocesses can read
|
|
313
|
+
"allowWrite": [".", "/tmp"], // Writable roots for bash and edit/write tools
|
|
314
|
+
"denyWrite": [".env", "*.pem"] // Writes always blocked
|
|
315
|
+
},
|
|
316
|
+
"subagent": {
|
|
317
|
+
"network": "allow" // "allow" | "deny" | "research-only"
|
|
318
|
+
},
|
|
319
|
+
"mcp": {
|
|
320
|
+
"allowTools": [], // MCP tool names that never prompt
|
|
321
|
+
"askThreshold": 30 // Risk score threshold to prompt (lower = stricter)
|
|
322
|
+
},
|
|
323
|
+
"commands": {
|
|
324
|
+
"ask": ["printenv", "env", "/proc/*/environ"] // Bash commands that prompt before running
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
### Project Policy Files & Trust (ADR-013)
|
|
330
|
+
When cloning a repository with a `.pi/sandbox.json`:
|
|
331
|
+
- **Hardening rules** (additional deny paths) apply immediately.
|
|
332
|
+
- **Relaxing rules** (allowing `/`, disabling layers, adding external domains) require explicit trust.
|
|
333
|
+
- Run `/security trust` to inspect and approve changes, or `/security untrust` to revoke.
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## Commands & Mid-Session Controls
|
|
338
|
+
|
|
339
|
+
| Command | Action |
|
|
340
|
+
|---|---|
|
|
341
|
+
| `/security` | View active Layer 2 policy, project trust status, and the last 10 audit events. |
|
|
342
|
+
| `/sandbox` | View active Layer 1 (OS sandbox) status and configuration. |
|
|
343
|
+
| `/sandbox reload` | Hot-reload policy rules after manual edits to `sandbox.json`. |
|
|
344
|
+
| `/permission-mode` | Switch between **Default**, **Advanced Secure**, and **YOLO** mid-session. |
|
|
345
|
+
| `/security trust` | Inspect and trust project-local policy widening in `.pi/sandbox.json`. |
|
|
346
|
+
| `/security untrust` | Revoke trust for the current project's policy file. |
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## Escape Hatches
|
|
255
351
|
|
|
256
|
-
|
|
352
|
+
For emergencies or troubleshooting, disable security temporarily:
|
|
257
353
|
|
|
258
354
|
```bash
|
|
259
|
-
|
|
260
|
-
pi --
|
|
355
|
+
# Disable all security layers for a single invocation
|
|
356
|
+
pi --yolo
|
|
357
|
+
|
|
358
|
+
# Alias for --yolo
|
|
359
|
+
pi --no-sandbox
|
|
261
360
|
```
|
|
262
361
|
|
|
263
|
-
Mid-session, `/permission-mode`
|
|
362
|
+
Mid-session, type `/permission-mode` and pick **YOLO** to disable layers in place without restarting.
|
|
363
|
+
|
|
364
|
+
---
|
|
264
365
|
|
|
265
|
-
## Audit
|
|
366
|
+
## Audit Logging
|
|
266
367
|
|
|
267
|
-
Every
|
|
368
|
+
Every decision (allow, block, ask, redaction) is appended as a structured JSON Line to `~/.pi/agent/audit.log`:
|
|
268
369
|
|
|
269
|
-
```
|
|
370
|
+
```json
|
|
270
371
|
{
|
|
271
|
-
"ts": "2026-
|
|
272
|
-
"layer":
|
|
273
|
-
"tool": "
|
|
274
|
-
"subject": "/
|
|
275
|
-
"reason": "denyWrite matched
|
|
372
|
+
"ts": "2026-10-13T19:22:15.000Z",
|
|
373
|
+
"layer": 1,
|
|
374
|
+
"tool": "bash",
|
|
375
|
+
"subject": "/etc/crontab",
|
|
376
|
+
"reason": "denyWrite matched /etc/crontab",
|
|
276
377
|
"decision": "no",
|
|
277
|
-
"cwd": "/
|
|
378
|
+
"cwd": "/home/user/workspace/app"
|
|
278
379
|
}
|
|
279
380
|
```
|
|
280
381
|
|
|
281
|
-
|
|
382
|
+
### Querying the Audit Log:
|
|
383
|
+
```bash
|
|
384
|
+
# View recent blocked actions
|
|
385
|
+
grep '"decision":"no"' ~/.pi/agent/audit.log | tail -n 10
|
|
282
386
|
|
|
283
|
-
|
|
284
|
-
|
|
387
|
+
# View secret redaction events
|
|
388
|
+
grep '"finding"' ~/.pi/agent/audit.log | tail -n 10
|
|
389
|
+
```
|
|
285
390
|
|
|
286
|
-
|
|
287
|
-
Auto Permission System includes native pattern recognizers for PyPI API tokens (`pypi-*`), hard-blocks model access to `~/.pypirc`, and gates `pip install` network requests to trusted hosts (`pypi.org`, `*.pypi.org`), preventing AI agents from leaking deployment secrets or pulling unvetted dependencies.
|
|
391
|
+
---
|
|
288
392
|
|
|
289
|
-
|
|
290
|
-
Add it to `network.allowedDomains` in a policy file (global `~/.pi/agent/extensions/sandbox.json` or project `<cwd>/.pi/sandbox.json`), or just run the tool (or a bash `curl`) once and pick an **always** option in the ask prompt — that writes the domain to the project file for you.
|
|
393
|
+
## FAQ & Scenarios
|
|
291
394
|
|
|
292
|
-
|
|
293
|
-
Add the folder to `filesystem.allowWrite`. Relative paths (`.`, `/tmp`) resolve from the project root.
|
|
395
|
+
A selection of common questions is below. For the complete, detailed guide, read **[docs/FAQ.md](docs/FAQ.md)**.
|
|
294
396
|
|
|
295
|
-
###
|
|
296
|
-
|
|
397
|
+
### How does Cloud Auto Mode secure unattended runs?
|
|
398
|
+
In headless mode (`pi -p` or subagent executions), interactive ask prompts cannot be presented to a human. Auto Permission System operates in a fail-closed posture: any tool call or bash command targeting an unlisted domain, credential file, or outside-project path is automatically blocked, and the refusal reason is provided to the agent and recorded in the audit log.
|
|
297
399
|
|
|
298
|
-
###
|
|
299
|
-
|
|
400
|
+
### What is the relationship between Cloud Auto Mode and Claude's auto mode?
|
|
401
|
+
Claude Code popularized autonomous "auto mode", allowing developers to let AI code without stopping for confirmation on harmless steps. Cloud Auto Mode brings this exact convenience to the Pi coding agent, but adds essential zero-trust boundaries: using Advanced Secure Mode to scan files, shell commands, and content to guarantee that autonomous execution never leads to data breaches or leaked API tokens.
|
|
300
402
|
|
|
301
|
-
###
|
|
302
|
-
|
|
403
|
+
### How do I allow the agent to reach a new domain?
|
|
404
|
+
Add it to `network.allowedDomains` in `<cwd>/.pi/sandbox.json` or `~/.pi/agent/extensions/sandbox.json`, or run a curl command once and select **Yes, always… → All in group in this project**.
|
|
303
405
|
|
|
304
|
-
###
|
|
305
|
-
|
|
406
|
+
### Why was my tool call or command blocked?
|
|
407
|
+
Run `/security` to inspect active policy rules and the last 10 audit events. Check `~/.pi/agent/audit.log` to view the exact matching rule (`reason`).
|
|
306
408
|
|
|
307
409
|
### Does it work on Windows?
|
|
308
|
-
|
|
410
|
+
Layer 2 (In-Process Tool Guard) and Layer 3 (Output Redactor) are platform-independent. Layer 1 (OS Sandbox) requires `sandbox-exec` (macOS, built-in) or `bubblewrap` + `socat` (Linux).
|
|
309
411
|
|
|
310
|
-
|
|
311
|
-
Project answers go to `<cwd>/.pi/sandbox.json`; global answers go to `~/.pi/agent/extensions/sandbox.json`. Session-only grants live in memory and are never written to disk.
|
|
412
|
+
---
|
|
312
413
|
|
|
313
|
-
## Development
|
|
414
|
+
## Development & Testing
|
|
314
415
|
|
|
416
|
+
### Running Tests:
|
|
315
417
|
```bash
|
|
418
|
+
# Clone repository
|
|
316
419
|
git clone https://github.com/Navin009/auto-permission-system
|
|
317
420
|
cd auto-permission-system
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
421
|
+
|
|
422
|
+
# Install development dependencies
|
|
423
|
+
npm install
|
|
424
|
+
|
|
425
|
+
# Typecheck TypeScript against Pi's bundled types
|
|
426
|
+
npm run typecheck
|
|
427
|
+
|
|
428
|
+
# Run unit and contract test suites (27 test suites)
|
|
429
|
+
npm test
|
|
430
|
+
|
|
431
|
+
# Run manual Layer 1 sandbox end-to-end test (requires bubblewrap)
|
|
432
|
+
APS_E2E=1 node --import ./security/tests/ts-loader.mjs security/tests/e2e/sandbox-fs.mjs
|
|
321
433
|
```
|
|
322
434
|
|
|
323
|
-
|
|
435
|
+
### Running the Demo Suite:
|
|
436
|
+
```bash
|
|
437
|
+
# Run interactive terminal simulation
|
|
438
|
+
./demo/run-demo.sh
|
|
324
439
|
|
|
325
|
-
|
|
440
|
+
# Regenerate MP4 and GIF recording assets
|
|
441
|
+
python3 demo/generate-recording.py
|
|
442
|
+
```
|
|
326
443
|
|
|
327
|
-
|
|
328
|
-
- `feat: ...` → minor release
|
|
329
|
-
- `feat!: ...` or a `BREAKING CHANGE:` footer → major release
|
|
330
|
-
- `chore:`, `docs:`, `refactor:`, `test:`, `ci:` etc. → no release by themselves
|
|
444
|
+
---
|
|
331
445
|
|
|
332
|
-
|
|
446
|
+
## Releasing
|
|
333
447
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
5. Publishes to npm (`npm publish --provenance`) — **only when the repository variable `NPM_PUBLISH` is `true`**.
|
|
448
|
+
Releases are fully automated with [semantic-release](https://semantic-release.gitbook.io/), driven by [Conventional Commits](https://www.conventionalcommits.org/) on `main`:
|
|
449
|
+
- `fix: ...` → Patch release
|
|
450
|
+
- `feat: ...` → Minor release
|
|
451
|
+
- `feat!: ...` or `BREAKING CHANGE:` → Major release
|
|
339
452
|
|
|
340
|
-
|
|
453
|
+
Pull requests are verified via `commitlint`. Publishing to npm is triggered automatically when `NPM_PUBLISH` is `true`. See **[PUBLISHING.md](PUBLISHING.md)** for details.
|
|
341
454
|
|
|
342
|
-
|
|
455
|
+
---
|
|
343
456
|
|
|
344
457
|
## License
|
|
345
458
|
|
|
346
|
-
MIT
|
|
459
|
+
MIT © [Navin Kumar](https://github.com/Navin009)
|
package/assets/demo.gif
ADDED
|
Binary file
|
package/assets/demo.mp4
ADDED
|
Binary file
|
package/assets/logo.png
ADDED
|
Binary file
|
package/banner.png
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "auto-permission-system",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "3.9.0",
|
|
4
|
+
"description": "Secure auto mode & cloud auto mode for Pi. A zero-trust permission system for the Pi coding agent powered by Advanced Secure mode to scan files, content, and tools to prevent data breaches.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "Navin Kumar",
|
|
7
7
|
"keywords": [
|
|
@@ -23,10 +23,11 @@
|
|
|
23
23
|
"auto-secure",
|
|
24
24
|
"secure",
|
|
25
25
|
"secure-it",
|
|
26
|
-
"
|
|
27
|
-
"
|
|
28
|
-
"
|
|
29
|
-
"
|
|
26
|
+
"auto-mode",
|
|
27
|
+
"safe-auto-mode",
|
|
28
|
+
"claude-auto-mode",
|
|
29
|
+
"data-breach-prevention",
|
|
30
|
+
"content-scan",
|
|
30
31
|
"cloud",
|
|
31
32
|
"cloud-security",
|
|
32
33
|
"auto-mode",
|
|
@@ -87,6 +88,7 @@
|
|
|
87
88
|
"extensions/",
|
|
88
89
|
"src/",
|
|
89
90
|
"skills/",
|
|
91
|
+
"assets/",
|
|
90
92
|
"sandbox.example.json",
|
|
91
93
|
"sandbox.default.json",
|
|
92
94
|
"sandbox.cloud.json",
|