bashboy 0.1.0__py3-none-any.whl
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.
- bashboy/__init__.py +5 -0
- bashboy/__main__.py +5 -0
- bashboy/classify.py +124 -0
- bashboy/cli.py +271 -0
- bashboy/config.py +219 -0
- bashboy/hooks/__init__.py +1 -0
- bashboy/hooks/claude.py +92 -0
- bashboy/installers/__init__.py +38 -0
- bashboy/installers/claude.py +135 -0
- bashboy/installers/opencode.py +199 -0
- bashboy/provider.py +215 -0
- bashboy/rules.py +225 -0
- bashboy-0.1.0.dist-info/METADATA +298 -0
- bashboy-0.1.0.dist-info/RECORD +17 -0
- bashboy-0.1.0.dist-info/WHEEL +4 -0
- bashboy-0.1.0.dist-info/entry_points.txt +2 -0
- bashboy-0.1.0.dist-info/licenses/LICENSE +21 -0
bashboy/rules.py
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
"""Structural allowlist and hard denylist fast paths.
|
|
2
|
+
|
|
3
|
+
Both functions are pure: no I/O, no environment reads, no imports beyond the
|
|
4
|
+
standard library's ``re`` and ``dataclasses``. They run before any model call,
|
|
5
|
+
so the hook path stays fast and offline.
|
|
6
|
+
|
|
7
|
+
The allowlist is deliberately structural. A command is only allowlisted when it
|
|
8
|
+
contains no shell operators, substitutions, redirections, or chaining -- a
|
|
9
|
+
command that merely *looks* like ``ls`` but smuggles a second command is never
|
|
10
|
+
allowlisted. False negatives (falling through to the model) are safe; false
|
|
11
|
+
positives are not.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import re
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
|
|
19
|
+
# Shell metacharacters that make a command structurally unsuitable for the
|
|
20
|
+
# allowlist. This deliberately excludes glob characters (``*``, ``?``, ``~``,
|
|
21
|
+
# ``[``), which cannot start a new command or substitute one, and is required to
|
|
22
|
+
# keep read-only forms such as ``find . -name '*.py'`` and ``git diff HEAD~1``
|
|
23
|
+
# allowlistable.
|
|
24
|
+
SHELL_METACHARS = frozenset(";|&$`<>(){}\\\n\r\x00")
|
|
25
|
+
|
|
26
|
+
_SIMPLE_HEADS = frozenset(
|
|
27
|
+
{"ls", "pwd", "cat", "head", "tail", "wc", "grep", "rg", "find", "echo", "which", "whoami", "date"}
|
|
28
|
+
)
|
|
29
|
+
_GIT_SUBCOMMANDS = frozenset({"status", "diff", "log", "show", "branch"})
|
|
30
|
+
_VERSION_HEADS = frozenset({"uv", "python", "node"})
|
|
31
|
+
# ``find`` is read-only until it is asked to execute or delete something.
|
|
32
|
+
_FIND_EXEC_FLAGS = frozenset({"-exec", "-execdir", "-ok", "-okdir", "-delete"})
|
|
33
|
+
|
|
34
|
+
_SPLIT_SEGMENTS = re.compile(r";|&&|\|\||\||\r?\n")
|
|
35
|
+
_MAX_SEGMENT_DEPTH = 5
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class DenyHit:
|
|
40
|
+
"""A denylist match: what rule fired and why."""
|
|
41
|
+
|
|
42
|
+
reason: str
|
|
43
|
+
pattern: str
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _command_substitutions(command: str) -> list[str]:
|
|
47
|
+
"""Return the bodies of ``$( ... )`` and backtick substitutions."""
|
|
48
|
+
bodies: list[str] = []
|
|
49
|
+
i = 0
|
|
50
|
+
length = len(command)
|
|
51
|
+
while i < length:
|
|
52
|
+
ch = command[i]
|
|
53
|
+
if ch == "`":
|
|
54
|
+
end = command.find("`", i + 1)
|
|
55
|
+
if end == -1:
|
|
56
|
+
break
|
|
57
|
+
bodies.append(command[i + 1 : end])
|
|
58
|
+
i = end + 1
|
|
59
|
+
continue
|
|
60
|
+
if ch == "$" and i + 1 < length and command[i + 1] == "(":
|
|
61
|
+
depth = 0
|
|
62
|
+
j = i + 1
|
|
63
|
+
while j < length:
|
|
64
|
+
if command[j] == "(":
|
|
65
|
+
depth += 1
|
|
66
|
+
elif command[j] == ")":
|
|
67
|
+
depth -= 1
|
|
68
|
+
if depth == 0:
|
|
69
|
+
break
|
|
70
|
+
j += 1
|
|
71
|
+
if j < length:
|
|
72
|
+
bodies.append(command[i + 2 : j])
|
|
73
|
+
i = j + 1
|
|
74
|
+
continue
|
|
75
|
+
i += 1
|
|
76
|
+
return bodies
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def segments(command: str) -> list[str]:
|
|
80
|
+
"""Split a command into the raw string plus every executable fragment.
|
|
81
|
+
|
|
82
|
+
Fragments are split on ``;``, ``&&``, ``||``, ``|`` and newlines, and the
|
|
83
|
+
bodies of command substitutions are added (recursively, capped at 5 levels).
|
|
84
|
+
"""
|
|
85
|
+
return _segments(command, 0)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _segments(command: str, depth: int) -> list[str]:
|
|
89
|
+
out = [command]
|
|
90
|
+
if depth >= _MAX_SEGMENT_DEPTH:
|
|
91
|
+
return out
|
|
92
|
+
for piece in _SPLIT_SEGMENTS.split(command):
|
|
93
|
+
if piece.strip():
|
|
94
|
+
out.append(piece)
|
|
95
|
+
for body in _command_substitutions(command):
|
|
96
|
+
out.extend(_segments(body, depth + 1))
|
|
97
|
+
return out
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
# --- denylist -------------------------------------------------------------
|
|
101
|
+
|
|
102
|
+
_RM_PREFIX = r"(?<![-\w])rm\s+(?:(?:-[A-Za-z]+|--[\w-]+)\s+)+"
|
|
103
|
+
|
|
104
|
+
# Protected targets: filesystem root, root glob, system directories, home.
|
|
105
|
+
_RM_PROTECTED_TARGET = (
|
|
106
|
+
r"(?:"
|
|
107
|
+
r"/(?=\s|$)"
|
|
108
|
+
r"|/\*"
|
|
109
|
+
r"|/(?:usr|etc|var|bin|sbin|boot|lib|lib64|opt|root|home|srv|sys|dev|proc)\b\S*"
|
|
110
|
+
r"|~(?=\s|$)"
|
|
111
|
+
r"|~/(?=\s|$)"
|
|
112
|
+
r"|~/\*"
|
|
113
|
+
r"|\$(?:HOME|\{HOME\})(?=\s|$|/)"
|
|
114
|
+
r")"
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
_RM_PROTECTED = re.compile(_RM_PREFIX + _RM_PROTECTED_TARGET, re.IGNORECASE)
|
|
118
|
+
_RM_WILDCARD = re.compile(_RM_PREFIX + r"(?:\./)?\*(?=\s|$)", re.IGNORECASE)
|
|
119
|
+
|
|
120
|
+
DENY_RULES: list[tuple[re.Pattern[str], str]] = [
|
|
121
|
+
(_RM_PROTECTED, "recursive delete of a protected path"),
|
|
122
|
+
(_RM_WILDCARD, "recursive delete of a wildcard target at the filesystem root"),
|
|
123
|
+
(re.compile(r"\bmkfs(?:\.[a-z0-9]+)?\b", re.IGNORECASE), "filesystem creation on a device"),
|
|
124
|
+
(re.compile(r"\b(?:fdisk|parted|diskpart)\b", re.IGNORECASE), "disk partitioning"),
|
|
125
|
+
(re.compile(r"\bformat\s+[a-z]:", re.IGNORECASE), "drive format"),
|
|
126
|
+
(re.compile(r"\bdd\b[^\n]*\bof=/dev/", re.IGNORECASE), "raw write to a block device"),
|
|
127
|
+
(re.compile(r">\s*/dev/(?:sd|hd|nvme|disk|vd)", re.IGNORECASE), "raw write to a block device"),
|
|
128
|
+
(re.compile(r"\bshred\b[^\n]*/dev/", re.IGNORECASE), "shred of a block device"),
|
|
129
|
+
(
|
|
130
|
+
re.compile(r":\s*\(\s*\)\s*\{[^}]*:\s*\|\s*:[^}]*&\s*\}\s*;\s*:", re.IGNORECASE),
|
|
131
|
+
"fork bomb",
|
|
132
|
+
),
|
|
133
|
+
(re.compile(r"\bchmod\s+(?:-[a-zA-Z]+\s+)*777\s+/(?=\s|$)", re.IGNORECASE), "world-writable root"),
|
|
134
|
+
(re.compile(r"\bchown\s+(?:-[a-zA-Z]+\s+)*\S+\s+/(?=\s|$)", re.IGNORECASE), "ownership change on root"),
|
|
135
|
+
(re.compile(r"\b(?:shutdown|reboot|halt|poweroff)\b", re.IGNORECASE), "host power control"),
|
|
136
|
+
(
|
|
137
|
+
re.compile(
|
|
138
|
+
r"remove-item\b[^\n]*-recurse[^\n]*(?:[a-z]:[\\/]?\s*$|\s/[\"']?\s*$)",
|
|
139
|
+
re.IGNORECASE,
|
|
140
|
+
),
|
|
141
|
+
"recursive delete of a drive root",
|
|
142
|
+
),
|
|
143
|
+
(
|
|
144
|
+
re.compile(
|
|
145
|
+
r"\bgit\s+clean\s+-[a-zA-Z]*[fdx][a-zA-Z]*[^\n]*(?:\s/(?=\s|$)|\s--\s+/)",
|
|
146
|
+
re.IGNORECASE,
|
|
147
|
+
),
|
|
148
|
+
"git clean at the filesystem root",
|
|
149
|
+
),
|
|
150
|
+
]
|
|
151
|
+
|
|
152
|
+
# ``rm -rf *`` only denies when it would run at a filesystem root, where the
|
|
153
|
+
# glob expands to the whole disk. Elsewhere the model decides.
|
|
154
|
+
_CWD_GATED = frozenset({_RM_WILDCARD.pattern})
|
|
155
|
+
|
|
156
|
+
_DRIVE_ROOT = re.compile(r"^[A-Za-z]:[\\/]?$")
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def _at_filesystem_root(cwd: str | None) -> bool:
|
|
160
|
+
if cwd is None:
|
|
161
|
+
return True
|
|
162
|
+
stripped = cwd.strip()
|
|
163
|
+
if stripped in {"/", "\\", ""}:
|
|
164
|
+
return True
|
|
165
|
+
return bool(_DRIVE_ROOT.match(stripped))
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def check_denylist(command: str, cwd: str | None = None) -> DenyHit | None:
|
|
169
|
+
"""Return the first denylist hit, or ``None``.
|
|
170
|
+
|
|
171
|
+
The raw command, every operator-split segment, and every command-substitution
|
|
172
|
+
body are scanned, so payloads hidden in compound commands are caught.
|
|
173
|
+
"""
|
|
174
|
+
if not isinstance(command, str) or not command.strip():
|
|
175
|
+
return None
|
|
176
|
+
pieces = segments(command)
|
|
177
|
+
for piece in pieces:
|
|
178
|
+
for pattern, reason in DENY_RULES:
|
|
179
|
+
if pattern.search(piece) is None:
|
|
180
|
+
continue
|
|
181
|
+
if pattern.pattern in _CWD_GATED and not _at_filesystem_root(cwd):
|
|
182
|
+
continue
|
|
183
|
+
return DenyHit(reason=reason, pattern=pattern.pattern)
|
|
184
|
+
return None
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
# --- allowlist ------------------------------------------------------------
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def check_allowlist(command: str) -> str | None:
|
|
191
|
+
"""Return a stable label when the command is a single allowlisted program."""
|
|
192
|
+
if not isinstance(command, str):
|
|
193
|
+
return None
|
|
194
|
+
cmd = command.strip()
|
|
195
|
+
if not cmd:
|
|
196
|
+
return None
|
|
197
|
+
if any(ch in SHELL_METACHARS for ch in cmd):
|
|
198
|
+
return None
|
|
199
|
+
|
|
200
|
+
tokens = cmd.split()
|
|
201
|
+
if not tokens:
|
|
202
|
+
return None
|
|
203
|
+
head = tokens[0]
|
|
204
|
+
|
|
205
|
+
if head == "cd":
|
|
206
|
+
# ``cd`` with at most one plain argument.
|
|
207
|
+
return "cd" if len(tokens) <= 2 else None
|
|
208
|
+
|
|
209
|
+
if head in _SIMPLE_HEADS:
|
|
210
|
+
if head == "find" and any(tok.lower() in _FIND_EXEC_FLAGS for tok in tokens[1:]):
|
|
211
|
+
return None
|
|
212
|
+
return head
|
|
213
|
+
|
|
214
|
+
if head in _VERSION_HEADS:
|
|
215
|
+
if len(tokens) == 2 and tokens[1] == "--version":
|
|
216
|
+
return f"{head} --version"
|
|
217
|
+
return None
|
|
218
|
+
|
|
219
|
+
if head == "git":
|
|
220
|
+
sub = next((tok for tok in tokens[1:] if not tok.startswith("-")), None)
|
|
221
|
+
if sub in _GIT_SUBCOMMANDS:
|
|
222
|
+
return f"git {sub}"
|
|
223
|
+
return None
|
|
224
|
+
|
|
225
|
+
return None
|
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: bashboy
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Classify shell commands as allow or deny before an agent runs them.
|
|
5
|
+
Project-URL: Homepage, https://github.com/Mann10/bashboy
|
|
6
|
+
Project-URL: Issues, https://github.com/Mann10/bashboy/issues
|
|
7
|
+
Project-URL: Source, https://github.com/Mann10/bashboy
|
|
8
|
+
Author-email: Mann10 <82712171+Mann10@users.noreply.github.com>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: agents,claude-code,guardrails,opencode,security,shell
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Security
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# BashBoy
|
|
19
|
+
|
|
20
|
+
BashBoy is a small, dependency-free Python CLI that classifies a shell command as
|
|
21
|
+
`allow` or `deny` **before** a coding agent runs it. It sits in front of Claude Code
|
|
22
|
+
(`PreToolUse` hook) and OpenCode (plugin) and answers one question: is this command
|
|
23
|
+
safe to run unattended?
|
|
24
|
+
|
|
25
|
+
> **BashBoy only narrows; `allow` means *no objection*.** It never approves a tool
|
|
26
|
+
> call. When BashBoy says `allow` it prints nothing (Claude) or returns normally
|
|
27
|
+
> (OpenCode), and the host's normal permission flow still applies. There is no
|
|
28
|
+
> `ask` verdict, no auto-approve path, and no way for BashBoy to widen permissions.
|
|
29
|
+
|
|
30
|
+
Three layers, in order:
|
|
31
|
+
|
|
32
|
+
1. **Local fast paths** (no network): a structural allowlist for single read-only
|
|
33
|
+
commands, and a hard denylist for destructive ones.
|
|
34
|
+
2. **Model classification** against the Clocked (`clocked/fill`) endpoint for everything
|
|
35
|
+
else.
|
|
36
|
+
3. **Host adapters** that express denial only.
|
|
37
|
+
|
|
38
|
+
Anything the fast paths do not recognise goes to the model. Anything the model path
|
|
39
|
+
cannot answer clearly becomes `deny`.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
uv tool install bashboy # install once
|
|
47
|
+
uvx bashboy --help # or run without installing
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
From a local checkout (uvx resolves the project from the path):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
uvx --from /path/to/BashBoy bashboy check --command "git status"
|
|
54
|
+
uvx --from /path/to/BashBoy bashboy install --claude
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The package has **zero runtime dependencies** — everything is the Python standard
|
|
58
|
+
library. `pytest` is a development-only dependency.
|
|
59
|
+
|
|
60
|
+
The API key is read from the environment (default `CLOCKED_API_KEY`). It is never
|
|
61
|
+
written to disk:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
export CLOCKED_API_KEY=... # bash
|
|
65
|
+
$env:CLOCKED_API_KEY = "..." # PowerShell
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Quick start
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
bashboy check --command "rm -rf /"
|
|
72
|
+
# deny (denylist): recursive delete of a protected path
|
|
73
|
+
|
|
74
|
+
bashboy check --command "git status"
|
|
75
|
+
# allow (allowlist): matches allowlist: git status
|
|
76
|
+
|
|
77
|
+
bashboy check --command "docker run --rm alpine sh" --json
|
|
78
|
+
# {"decision": "deny", "source": "fallback", "reason": "classifier unavailable: no API key ...", ...}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Exit codes:
|
|
82
|
+
|
|
83
|
+
| Code | Meaning |
|
|
84
|
+
|------|---------|
|
|
85
|
+
| `0` | `allow` |
|
|
86
|
+
| `1` | `deny` |
|
|
87
|
+
| `2` | configuration or usage error (never a silent allow) |
|
|
88
|
+
|
|
89
|
+
`--json` prints exactly one object, in this key order:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{"decision":"deny","source":"denylist","reason":"recursive delete of a protected path","risk":null,"latency_ms":0}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`source` is one of `denylist`, `allowlist`, `model`, `fallback`, `disabled`.
|
|
96
|
+
`--cwd DIR` supplies the working directory used for context (default: current
|
|
97
|
+
directory).
|
|
98
|
+
|
|
99
|
+
## Configuration
|
|
100
|
+
|
|
101
|
+
Optional file at `~/.bashboy/config.toml` (override with `BASHBOY_CONFIG`).
|
|
102
|
+
Create it with `bashboy config init`; inspect with `bashboy config show`.
|
|
103
|
+
A missing file means these defaults:
|
|
104
|
+
|
|
105
|
+
```toml
|
|
106
|
+
[provider]
|
|
107
|
+
endpoint = "https://clocked.rezolve.ai/clocked/fill"
|
|
108
|
+
api_key_env = "CLOCKED_API_KEY"
|
|
109
|
+
timeout_ms = 4000
|
|
110
|
+
|
|
111
|
+
[policy]
|
|
112
|
+
fail_mode = "closed" # closed | open
|
|
113
|
+
denylist = true
|
|
114
|
+
allowlist = true
|
|
115
|
+
|
|
116
|
+
[integrations.claude]
|
|
117
|
+
timeout_s = 15
|
|
118
|
+
|
|
119
|
+
[integrations.opencode]
|
|
120
|
+
timeout_ms = 15000
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Malformed TOML is a hard error (exit 2) from `check` — the gate never silently
|
|
124
|
+
loosens because a file failed to parse.
|
|
125
|
+
|
|
126
|
+
| Variable | Effect |
|
|
127
|
+
|----------|--------|
|
|
128
|
+
| `BASHBOY_CONFIG` | Path to the config file (default `~/.bashboy/config.toml`) |
|
|
129
|
+
| `BASHBOY_ENDPOINT` | Overrides `[provider].endpoint` |
|
|
130
|
+
| `BASHBOY_API_KEY_ENV` | Name of the environment variable holding the key |
|
|
131
|
+
| `BASHBOY_FAIL_MODE` | `closed` (default) or `open`; anything else is an error |
|
|
132
|
+
| `BASHBOY_DISABLE` | `1`/`true`/`yes` disables **all** checks (see below) |
|
|
133
|
+
| `BASHBOY_DEBUG` | `1`/`true`/`yes` writes diagnostics to stderr only |
|
|
134
|
+
|
|
135
|
+
## Claude Code setup
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
bashboy install --claude
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
This merges a `PreToolUse` hook into `~/.claude/settings.json` (override with
|
|
142
|
+
`--settings PATH`). Unrelated keys and unrelated hook events are preserved; an
|
|
143
|
+
existing BashBoy handler is updated in place, so re-running never duplicates it.
|
|
144
|
+
The previous file is copied to `settings.json.bak` and the new file is written
|
|
145
|
+
atomically.
|
|
146
|
+
|
|
147
|
+
The exact entry it writes:
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{
|
|
151
|
+
"hooks": {
|
|
152
|
+
"PreToolUse": [
|
|
153
|
+
{
|
|
154
|
+
"matcher": "Bash|PowerShell",
|
|
155
|
+
"hooks": [
|
|
156
|
+
{
|
|
157
|
+
"type": "command",
|
|
158
|
+
"command": "uvx",
|
|
159
|
+
"args": ["bashboy", "check", "--claude-hook"],
|
|
160
|
+
"timeout": 15,
|
|
161
|
+
"statusMessage": "BashBoy: checking command"
|
|
162
|
+
}
|
|
163
|
+
]
|
|
164
|
+
}
|
|
165
|
+
]
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Options:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
bashboy install --claude --dry-run # print the resulting JSON, write nothing
|
|
174
|
+
bashboy install --claude --settings ./settings.json
|
|
175
|
+
bashboy install --claude --from /path/to/BashBoy
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
`--from SPEC` rewrites the argv to
|
|
179
|
+
`["--from", SPEC, "bashboy", "check", "--claude-hook"]`, so `uvx` runs the given
|
|
180
|
+
local checkout. The path is written verbatim as a single argv element — never
|
|
181
|
+
interpolated into a shell string.
|
|
182
|
+
|
|
183
|
+
The hook reads one JSON object on stdin. On `deny` it prints the
|
|
184
|
+
`hookSpecificOutput` envelope with `permissionDecision: "deny"`; on `allow`, blank
|
|
185
|
+
input, or malformed input it prints nothing and exits `0` so the host's normal
|
|
186
|
+
permission flow continues.
|
|
187
|
+
|
|
188
|
+
## OpenCode setup
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
bashboy install --opencode
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
This writes two files under `~/.config/opencode` (override with `--config-dir DIR`):
|
|
195
|
+
|
|
196
|
+
- `plugins/bashboy.ts` — the generated plugin;
|
|
197
|
+
- `opencode.json` — registers the plugin's absolute path.
|
|
198
|
+
|
|
199
|
+
`opencode.json` is created with `{"$schema": "https://opencode.ai/config.json"}` if
|
|
200
|
+
absent. Existing keys and existing plugin entries are preserved, the BashBoy path
|
|
201
|
+
is appended only once, and the previous config is backed up before an atomic write.
|
|
202
|
+
OpenCode V2 documents the key as `plugins`; V1 used `plugin`. BashBoy reads
|
|
203
|
+
whichever key already exists, preserves it, defaults to `plugins` when neither is
|
|
204
|
+
present, and never writes both.
|
|
205
|
+
|
|
206
|
+
The plugin hooks both API generations with one shared helper:
|
|
207
|
+
|
|
208
|
+
- **V2:** `Plugin.define({ id: "bashboy", setup })` registering
|
|
209
|
+
`ctx.tool.hook("execute.before", ...)`, reading `event.input.command`.
|
|
210
|
+
- **V1 fallback:** `server()` returning `"tool.execute.before"`, reading
|
|
211
|
+
`output.args.command`.
|
|
212
|
+
|
|
213
|
+
It acts only for the `bash`/`shell` tools and runs
|
|
214
|
+
`uvx bashboy check --json --command <cmd> --cwd <dir>` via
|
|
215
|
+
`execFile(..., { shell: false, timeout: 15000, windowsHide: true })`. The command is
|
|
216
|
+
a single argv element; it is never passed through a shell and never concatenated
|
|
217
|
+
into a command line. On `deny` it throws
|
|
218
|
+
`Error("BashBoy blocked this command: <reason>")`. If `uvx` is missing, the exit is
|
|
219
|
+
non-zero without parseable JSON, the JSON is invalid, the call times out, or the
|
|
220
|
+
verdict is unexpected, it throws
|
|
221
|
+
`Error("BashBoy could not verify this command: <detail>")` — fail closed.
|
|
222
|
+
|
|
223
|
+
`bashboy install --opencode --dry-run` prints one JSON object with
|
|
224
|
+
`plugin_path`, `plugin_source`, and the would-be `config`, and writes nothing.
|
|
225
|
+
|
|
226
|
+
## Escape hatch
|
|
227
|
+
|
|
228
|
+
> **`BASHBOY_DISABLE=1` disables all checks.** Commands are allowed with
|
|
229
|
+
> `source: "disabled"` and no denylist, allowlist, or model evaluation runs.
|
|
230
|
+
> For emergencies and CI debugging only. Never set it in an agent's environment
|
|
231
|
+
> or in a shell that an agent controls.
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
BASHBOY_DISABLE=1 bashboy check --command "rm -rf /" # allow (disabled)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## Privacy
|
|
238
|
+
|
|
239
|
+
For model classification, the **command text and the working directory** are sent
|
|
240
|
+
to the configured Clocked endpoint over HTTPS (`text: "cwd: <cwd>\ncommand: <cmd>"`).
|
|
241
|
+
Nothing else is transmitted; no files are uploaded.
|
|
242
|
+
|
|
243
|
+
Fast-path verdicts (`denylist`, `allowlist`, `disabled`) never leave the machine.
|
|
244
|
+
There is no analytics, no audit log, no cache, and no telemetry. The API key is
|
|
245
|
+
read from the environment at call time, sent only as the `Authorization` header,
|
|
246
|
+
and never logged, persisted, or included in `config show`.
|
|
247
|
+
|
|
248
|
+
## Known limitation: unverified Clocked envelope
|
|
249
|
+
|
|
250
|
+
The response shape of the Clocked (`clocked/fill`) endpoint is **unverified**. Parsing
|
|
251
|
+
is deliberately tolerant (`extract_field` walks nested objects and arrays
|
|
252
|
+
breadth-first, and unwraps `value`/`text`/`answer`/`label`/`result`/`content`
|
|
253
|
+
containers). If the response cannot be resolved to a clear `allow` or `deny`, the
|
|
254
|
+
verdict is `deny` with `source: "fallback"`. Report envelope mismatches with the
|
|
255
|
+
raw (redacted) response so the parser can be extended.
|
|
256
|
+
|
|
257
|
+
## Limitations
|
|
258
|
+
|
|
259
|
+
- The structural allowlist is conservative by design: any operator, substitution,
|
|
260
|
+
redirection, or chaining disqualifies a command. False negatives simply go to the
|
|
261
|
+
model.
|
|
262
|
+
- The denylist is a fast path, not a complete policy. It catches literal destructive
|
|
263
|
+
patterns and payloads hidden behind `;`, `&&`, `||`, `|`, newlines, `$(...)`, and
|
|
264
|
+
backticks — but it does not decode base64, `r''m`-style quoting, or other
|
|
265
|
+
obfuscation. Such commands are not allowlisted and therefore reach the model,
|
|
266
|
+
which fails closed.
|
|
267
|
+
- PowerShell/bash parity is best-effort. The allowlist covers a small bash-oriented
|
|
268
|
+
set; PowerShell users should expect more commands to reach the model.
|
|
269
|
+
- `git reset --hard` is intentionally **not** denied: it is recoverable via the
|
|
270
|
+
reflog. `git clean -fdx /` at a filesystem root is denied.
|
|
271
|
+
- `--from SPEC` is trusted input: a user who runs `install --from <path>` is
|
|
272
|
+
explicitly pointing BashBoy at that checkout.
|
|
273
|
+
- v1 has no audit log; the host's own transcript remains the record.
|
|
274
|
+
|
|
275
|
+
## Development
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
uv run pytest # offline; no network access required
|
|
279
|
+
uv run bashboy selftest
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Layout:
|
|
283
|
+
|
|
284
|
+
```
|
|
285
|
+
src/bashboy/
|
|
286
|
+
cli.py check / install / config / selftest / version
|
|
287
|
+
config.py TOML defaults, env overrides, API key lookup
|
|
288
|
+
rules.py structural allowlist + hard denylist (pure)
|
|
289
|
+
provider.py Clocked client, tolerant envelope parser
|
|
290
|
+
classify.py verdict pipeline (fast paths -> model -> fail closed)
|
|
291
|
+
hooks/claude.py Claude Code PreToolUse adapter
|
|
292
|
+
installers/ Claude settings.json and OpenCode plugin installers
|
|
293
|
+
tests/ offline test suite
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
There are **no runtime dependencies beyond the standard library**. The provider is
|
|
297
|
+
imported lazily inside the model branch so the hook path stays fast, and the
|
|
298
|
+
installers are imported lazily by `install` only.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
bashboy/__init__.py,sha256=8z_YiSXRaLrGKo9gNkSwUH5WmACShwAKKqtqDyr8bPk,115
|
|
2
|
+
bashboy/__main__.py,sha256=ECpvuTVRfK-8nSCmYrYwys-NU-BwGsjPrex7WJeVAg8,85
|
|
3
|
+
bashboy/classify.py,sha256=jFpmZBKsp8dDl3Ozh52oqHfxrfNreYWmhInNKsuA3gU,4254
|
|
4
|
+
bashboy/cli.py,sha256=Tr8o4KuN2W019-1rKY1IUAbIaylfld8GsePzDjXag_M,9158
|
|
5
|
+
bashboy/config.py,sha256=COhAqiv6NY-oe9bNIrUlRAITJe17i9P086xGmjKYgXk,6590
|
|
6
|
+
bashboy/provider.py,sha256=PCJhwOLk587Sj8VfwwR88j2qe57EFUgFuikCZDYrxuU,7825
|
|
7
|
+
bashboy/rules.py,sha256=McpVKzb-TPApPhRKFpCeeAlYcb4e2f0DNL_gXWC209k,7816
|
|
8
|
+
bashboy/hooks/__init__.py,sha256=lONS1cqooFlAC4Y7rZ1H8aa6P5leoBjQE8Ty059vB24,74
|
|
9
|
+
bashboy/hooks/claude.py,sha256=FcbgET1_7YUZTl3T54sDSjYADJasvhXnHogFmEcB1c0,2850
|
|
10
|
+
bashboy/installers/__init__.py,sha256=IVEA3E3DG3SZcvPSemfCdQzB7NnZZiCyy76r9M8LcTA,974
|
|
11
|
+
bashboy/installers/claude.py,sha256=OZPMDZ2vlDLbR16DgQ0VnvezrUHv6zFNhjL2MxaQVr8,4094
|
|
12
|
+
bashboy/installers/opencode.py,sha256=wA21uf8dG6YQ8vBT10AvNIXJFVbEVxGSpgAniALgEgY,6464
|
|
13
|
+
bashboy-0.1.0.dist-info/METADATA,sha256=6kRLx7Zo4yo_MNnqvzIvZ_QJNw8UTmQOGbEk81tOcHo,10930
|
|
14
|
+
bashboy-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
15
|
+
bashboy-0.1.0.dist-info/entry_points.txt,sha256=mNMO2puTzhoLdYQhZm6qVHqsMFrX__QIKwhazLVz4Y0,45
|
|
16
|
+
bashboy-0.1.0.dist-info/licenses/LICENSE,sha256=zjV-RsxGo72MGnQNyku9dy9zFR2dcBDs8oFoKgwuu68,1063
|
|
17
|
+
bashboy-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mann10
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|