atp-hermes-hook 0.2.0 → 0.2.1

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/README.md CHANGED
@@ -9,13 +9,14 @@ Requires Node.js 20 or newer. Want to see the decisions before changing Hermes s
9
9
  Requires Hermes on your PATH and Node.js 20 or newer. From any directory, run:
10
10
 
11
11
  ```bash
12
- npx --yes atp-hermes-hook@0.2.0 setup
12
+ npx --yes atp-hermes-hook@0.2.1 setup
13
13
  ```
14
14
 
15
15
  This creates an `atp-pilot` Hermes profile if needed, installs a fixed copy under
16
16
  `~/.hermes/agent-hooks/atp`, and creates a `safe-default` policy that allows reads
17
17
  only within a disposable test folder. Terminal, write and patch calls are blocked.
18
- It runs standalone read/terminal/write decision checks, backs up the profile's
18
+ Every tool call is intercepted; unmapped tools, including `execute_code`, are blocked.
19
+ It runs standalone read/terminal/write and unmapped-tool decision checks, backs up the profile's
19
20
  `config.yaml`, and merges a fail-closed hook while preserving other hooks and
20
21
  settings. It does not install packages into your current directory.
21
22
 
@@ -39,7 +40,7 @@ Standalone checks do not prove live enforcement or signed mandate verification.
39
40
  To choose another profile and read scope:
40
41
 
41
42
  ```bash
42
- npx --yes atp-hermes-hook@0.2.0 setup --hermes-profile my-test-profile --read /absolute/path/to/docs
43
+ npx --yes atp-hermes-hook@0.2.1 setup --hermes-profile my-test-profile --read /absolute/path/to/docs
43
44
  ```
44
45
 
45
46
  `--read` may be repeated; it replaces the default test-folder read scope on first
@@ -50,8 +51,20 @@ use manual installation for different policies per profile. `--hermes-home` sele
50
51
  a custom Hermes root. Setup rejects malformed YAML, preserves existing ATP policies,
51
52
  and refuses to replace their read scope implicitly. Rerunning setup does not add
52
53
  duplicate copies of the same command. Existing manually configured ATP commands
53
- are preserved with other hooks; review them separately if migrating. Other tool
54
- names are outside the default four-tool matcher. Use WSL on Windows.
54
+ are preserved with other hooks; review them separately if migrating. Unmapped
55
+ tools are blocked, so features such as code execution, browser automation and
56
+ delegation are unavailable until explicitly mapped and reviewed. Use WSL on Windows.
57
+
58
+ ### Upgrade from 0.2.0 or a manual four-tool matcher
59
+
60
+ The earlier `^(read_file|terminal|write_file|patch)$` matcher did not intercept
61
+ `execute_code`. A live pilot reported a blocked terminal call followed by a
62
+ successful Python subprocess through that alternate tool. The four-tool check
63
+ therefore did not establish execution containment. Re-run setup at 0.2.1 to
64
+ replace the installer's matcher with `.*`, or update your manual matcher below.
65
+ Upgrading the package alone does not update profile YAML. Restart the affected
66
+ CLI session (and deliberately restart any affected gateway) after configuration
67
+ changes. Verify both `terminal` and `execute_code` are blocked through Hermes.
55
68
 
56
69
  To undo the YAML change, restore the exact backup path printed by setup. This
57
70
  restores the whole pre-setup file, so preserve later configuration edits first.
@@ -106,7 +119,7 @@ Then add the hook to your Hermes profile's `config.yaml`, using absolute paths:
106
119
  ```yaml
107
120
  hooks:
108
121
  pre_tool_call:
109
- - matcher: "^(read_file|terminal|write_file|patch)$"
122
+ - matcher: ".*"
110
123
  command: "/home/me/.hermes/agent-hooks/atp/node_modules/.bin/atp-hermes-hook --config /home/me/.hermes/agent-hooks/atp/atp-hermes.json"
111
124
  timeout: 10
112
125
  fail_closed: true
@@ -139,7 +152,10 @@ Every block writes `{"action":"block","message":"ATP: ..."}` and **exits with co
139
152
  | `patch` | `filesystem` (write) | `path` |
140
153
  | `terminal` | `shell` | — |
141
154
 
142
- To cover more tools, map them and widen the Hermes `matcher` to match:
155
+ Every tool reaches this hook. To permit another tool, map it explicitly after
156
+ reviewing its capabilities. Do not map a general interpreter to a harmless
157
+ category: `execute_code` can run subprocesses and access files directly.
158
+ For example, to evaluate a network tool and remove the terminal mapping:
143
159
 
144
160
  ```json
145
161
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "atp-hermes-hook",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Fail-closed Hermes Agent pre_tool_call hook that enforces Agent Trust Protocol (ATP) security profiles at the tool boundary",
5
5
  "type": "module",
6
6
  "main": "./src/index.mjs",
package/src/setup.mjs CHANGED
@@ -7,7 +7,9 @@ import { randomUUID } from 'node:crypto';
7
7
  import { parseDocument } from 'yaml';
8
8
  import { loadConfig } from './index.mjs';
9
9
 
10
- const MATCHER = '^(read_file|terminal|write_file|patch)$';
10
+ // Dispatch every tool through ATP. Otherwise an unmapped execution tool (for
11
+ // example execute_code -> subprocess) can route around a blocked terminal call.
12
+ const MATCHER = '.*';
11
13
  const packageRoot = fileURLToPath(new URL('../', import.meta.url));
12
14
 
13
15
  function run(command, args, options = {}) {
@@ -96,6 +98,8 @@ export function setupHermes({ profile = 'atp-pilot', hermesHome = process.env.HE
96
98
  const tests = [
97
99
  ['terminal blocked', { tool_name: 'terminal', tool_input: { command: 'echo ATP-test' } }, 2],
98
100
  ['write blocked', { tool_name: 'write_file', tool_input: { path: fixture, content: 'must not be written' } }, 2],
101
+ ['execute_code blocked', { tool_name: 'execute_code', tool_input: { code: 'import subprocess' } }, 2],
102
+ ['unmapped tool blocked', { tool_name: 'future_execution_tool', tool_input: {} }, 2],
99
103
  ];
100
104
  // The default fixture is the only read scope we can prove without reading a user's files.
101
105
  if (config.roots.read.includes(fixtureDir)) {
@@ -131,7 +135,7 @@ export function setupHermes({ profile = 'atp-pilot', hermesHome = process.env.HE
131
135
  output(`Configured Hermes profile: ${profile}`);
132
136
  if (backup) output(`Backup: ${backup}`);
133
137
  output(`Policy: ${policyFile}`);
134
- output('Scope: read_file, terminal, write_file and patch only. Other tools are outside this matcher.');
138
+ output('Scope: every pre_tool_call is checked. Unmapped tools, including execute_code, are blocked.');
135
139
  output('Standalone self-tests passed. Live Hermes enforcement is not verified yet.');
136
140
  output(`Next: hermes -p ${profile} hooks test pre_tool_call --for-tool terminal`);
137
141
  output('Review and approve the local hook when Hermes requests first-use consent.');