aegis-mcp-server 0.1.3 → 0.1.4
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.
|
@@ -5,6 +5,14 @@
|
|
|
5
5
|
* Every call is validated against the loaded policy before execution.
|
|
6
6
|
* The agent never sees the policy — only the verdict.
|
|
7
7
|
*
|
|
8
|
+
* ENFORCEMENT DIRECTIVE: Every tool description includes a clear statement
|
|
9
|
+
* that agents must use these tools exclusively — no native file operations.
|
|
10
|
+
* This directive reaches the agent at connection time via the MCP tool list,
|
|
11
|
+
* before any conversation begins.
|
|
12
|
+
*
|
|
13
|
+
* LOGGING: Every denied action is logged to overrides.jsonl by the server
|
|
14
|
+
* process — no agent involvement required.
|
|
15
|
+
*
|
|
8
16
|
* Tools:
|
|
9
17
|
* aegis_check_permissions — Pre-check before writing (saves wasted generation)
|
|
10
18
|
* aegis_write_file — Governed write with path + content validation
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"file-tools.d.ts","sourceRoot":"","sources":["../../src/tools/file-tools.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"file-tools.d.ts","sourceRoot":"","sources":["../../src/tools/file-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ7D,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,iBAAiB,EAClC,QAAQ,EAAE,MAAM,WAAW,EAC3B,OAAO,EAAE,MAAM,YAAY,GAC1B,IAAI,CA0YN"}
|
package/dist/tools/file-tools.js
CHANGED
|
@@ -5,6 +5,14 @@
|
|
|
5
5
|
* Every call is validated against the loaded policy before execution.
|
|
6
6
|
* The agent never sees the policy — only the verdict.
|
|
7
7
|
*
|
|
8
|
+
* ENFORCEMENT DIRECTIVE: Every tool description includes a clear statement
|
|
9
|
+
* that agents must use these tools exclusively — no native file operations.
|
|
10
|
+
* This directive reaches the agent at connection time via the MCP tool list,
|
|
11
|
+
* before any conversation begins.
|
|
12
|
+
*
|
|
13
|
+
* LOGGING: Every denied action is logged to overrides.jsonl by the server
|
|
14
|
+
* process — no agent involvement required.
|
|
15
|
+
*
|
|
8
16
|
* Tools:
|
|
9
17
|
* aegis_check_permissions — Pre-check before writing (saves wasted generation)
|
|
10
18
|
* aegis_write_file — Governed write with path + content validation
|
|
@@ -18,11 +26,15 @@ import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
|
|
|
18
26
|
import { dirname, join, isAbsolute } from 'node:path';
|
|
19
27
|
import { execSync } from 'node:child_process';
|
|
20
28
|
import { z } from 'zod';
|
|
29
|
+
// ─── Enforcement Directive ──────────────────────────────────────────────────
|
|
30
|
+
// This prefix is prepended to every tool description. It reaches the agent
|
|
31
|
+
// at MCP connection time as part of the tool list — before any user prompt.
|
|
32
|
+
const ENFORCEMENT_DIRECTIVE = `IMPORTANT: You are connected to the Aegis MCP enforcement layer. ALL file read, write, and delete operations MUST use the aegis_* tools. Do NOT use native file tools (Read, Write, Edit, etc.). Aegis validates every action against your role's governance policy. Blocked actions are logged automatically.\n\n`;
|
|
21
33
|
export function registerTools(server, getEngine, getState, getRole) {
|
|
22
34
|
// ─── aegis_check_permissions ──────────────────────────────────────────────
|
|
23
35
|
server.registerTool('aegis_check_permissions', {
|
|
24
36
|
title: 'Check Permissions',
|
|
25
|
-
description:
|
|
37
|
+
description: `${ENFORCEMENT_DIRECTIVE}Check if an operation is allowed on a path before attempting it. Use this to pre-validate before writing or reading files — saves you from composing content that would be blocked. Denied checks are logged automatically by the server.
|
|
26
38
|
|
|
27
39
|
Args:
|
|
28
40
|
- path (string): Target file path relative to project root
|
|
@@ -42,9 +54,14 @@ Returns:
|
|
|
42
54
|
},
|
|
43
55
|
}, async ({ path, operation }) => {
|
|
44
56
|
const engine = getEngine();
|
|
57
|
+
const role = getRole();
|
|
45
58
|
const verdict = operation === 'read'
|
|
46
59
|
? engine.validateRead(path)
|
|
47
60
|
: engine.validateWrite(path);
|
|
61
|
+
// Log denied permission checks
|
|
62
|
+
if (!verdict.allowed) {
|
|
63
|
+
await logBlocked(engine, role, path, `check_permissions (${operation})`, verdict.reason);
|
|
64
|
+
}
|
|
48
65
|
return {
|
|
49
66
|
content: [{
|
|
50
67
|
type: 'text',
|
|
@@ -57,7 +74,7 @@ Returns:
|
|
|
57
74
|
// ─── aegis_write_file ─────────────────────────────────────────────────────
|
|
58
75
|
server.registerTool('aegis_write_file', {
|
|
59
76
|
title: 'Write File (Governed)',
|
|
60
|
-
description:
|
|
77
|
+
description: `${ENFORCEMENT_DIRECTIVE}Write content to a file with governance enforcement. Path is validated against your role's permissions and governance boundaries. Content is scanned for sensitive patterns. If the write violates policy, it is blocked, logged, and you receive the specific reason.
|
|
61
78
|
|
|
62
79
|
Args:
|
|
63
80
|
- path (string): File path relative to project root
|
|
@@ -105,7 +122,7 @@ Returns:
|
|
|
105
122
|
// ─── aegis_read_file ──────────────────────────────────────────────────────
|
|
106
123
|
server.registerTool('aegis_read_file', {
|
|
107
124
|
title: 'Read File (Governed)',
|
|
108
|
-
description:
|
|
125
|
+
description: `${ENFORCEMENT_DIRECTIVE}Read the contents of a file with governance enforcement. Path is validated against your role's read permissions. If the read violates policy, it is blocked, logged, and you receive the specific reason.
|
|
109
126
|
|
|
110
127
|
Args:
|
|
111
128
|
- path (string): File path relative to project root
|
|
@@ -124,8 +141,10 @@ Returns:
|
|
|
124
141
|
}, async ({ path }) => {
|
|
125
142
|
const engine = getEngine();
|
|
126
143
|
const state = getState();
|
|
144
|
+
const role = getRole();
|
|
127
145
|
const verdict = engine.validateRead(path);
|
|
128
146
|
if (!verdict.allowed) {
|
|
147
|
+
await logBlocked(engine, role, path, 'read', verdict.reason);
|
|
129
148
|
return blocked(verdict.reason);
|
|
130
149
|
}
|
|
131
150
|
const absPath = toAbsolute(path, state.projectRoot);
|
|
@@ -140,7 +159,7 @@ Returns:
|
|
|
140
159
|
// ─── aegis_delete_file ────────────────────────────────────────────────────
|
|
141
160
|
server.registerTool('aegis_delete_file', {
|
|
142
161
|
title: 'Delete File (Governed)',
|
|
143
|
-
description:
|
|
162
|
+
description: `${ENFORCEMENT_DIRECTIVE}Delete a file with governance enforcement. Write permissions are required. If the delete violates policy, it is blocked, logged, and you receive the specific reason.
|
|
144
163
|
|
|
145
164
|
Args:
|
|
146
165
|
- path (string): File path relative to project root
|
|
@@ -177,7 +196,7 @@ Returns:
|
|
|
177
196
|
// ─── aegis_execute ────────────────────────────────────────────────────────
|
|
178
197
|
server.registerTool('aegis_execute', {
|
|
179
198
|
title: 'Execute Command (Governed)',
|
|
180
|
-
description:
|
|
199
|
+
description: `${ENFORCEMENT_DIRECTIVE}Execute a shell command in the project directory. Currently validates that the command runs within the project root. Future versions will enforce command-level permissions.
|
|
181
200
|
|
|
182
201
|
Args:
|
|
183
202
|
- command (string): Shell command to execute
|
|
@@ -229,7 +248,7 @@ Returns:
|
|
|
229
248
|
// ─── aegis_complete_task ──────────────────────────────────────────────────
|
|
230
249
|
server.registerTool('aegis_complete_task', {
|
|
231
250
|
title: 'Complete Task',
|
|
232
|
-
description:
|
|
251
|
+
description: `${ENFORCEMENT_DIRECTIVE}Signal task completion and run required quality gates. Maps the governance quality_gate.pre_commit flags to build_commands and runs each required check. Returns pass/fail with details.
|
|
233
252
|
|
|
234
253
|
Args:
|
|
235
254
|
- task_id (string): Identifier for the task being completed
|
|
@@ -300,10 +319,10 @@ Returns:
|
|
|
300
319
|
// ─── aegis_policy_summary ─────────────────────────────────────────────────
|
|
301
320
|
server.registerTool('aegis_policy_summary', {
|
|
302
321
|
title: 'Policy Summary',
|
|
303
|
-
description:
|
|
322
|
+
description: `${ENFORCEMENT_DIRECTIVE}Get a minimal summary of your current role and permissions. Call this FIRST before doing any work. Returns your role name, writable paths, excluded paths, forbidden actions, and key governance rules — just enough to understand your boundaries without loading full policy files.
|
|
304
323
|
|
|
305
324
|
Returns:
|
|
306
|
-
{ "role": "...", "writable_paths": [...], "forbidden_actions": [...], ... }`,
|
|
325
|
+
{ "enforcement_directive": "...", "role": "...", "writable_paths": [...], "forbidden_actions": [...], ... }`,
|
|
307
326
|
inputSchema: {},
|
|
308
327
|
annotations: {
|
|
309
328
|
readOnlyHint: true,
|
|
@@ -316,6 +335,7 @@ Returns:
|
|
|
316
335
|
const state = getState();
|
|
317
336
|
const protocol = state.governance.override_protocol;
|
|
318
337
|
const summary = {
|
|
338
|
+
enforcement_directive: 'You are governed by the Aegis MCP enforcement layer. ALL file operations (read, write, delete) MUST use aegis_* tools. Do NOT use native file tools. Violations are blocked and logged automatically. There are no exceptions to this requirement.',
|
|
319
339
|
role: role.id,
|
|
320
340
|
role_name: role.name,
|
|
321
341
|
purpose: role.purpose,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"file-tools.js","sourceRoot":"","sources":["../../src/tools/file-tools.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"file-tools.js","sourceRoot":"","sources":["../../src/tools/file-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,+EAA+E;AAC/E,2EAA2E;AAC3E,4EAA4E;AAE5E,MAAM,qBAAqB,GAAG,oTAAoT,CAAC;AAEnV,MAAM,UAAU,aAAa,CAC3B,MAAiB,EACjB,SAAkC,EAClC,QAA2B,EAC3B,OAA2B;IAG3B,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,yBAAyB,EACzB;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,GAAG,qBAAqB;;;;;;;+DAOoB;QACzD,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;YACtE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;SAC9E;QACD,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE;QAC5B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,SAAS,KAAK,MAAM;YAClC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC;YAC3B,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAE/B,+BAA+B;QAC/B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,sBAAsB,SAAS,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3F,CAAC;QAED,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB,OAAO,CAAC,OAAO;wBACb,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE;wBACnB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAC/C;iBACF,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,kBAAkB,EAClB;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,GAAG,qBAAqB;;;;;;;qFAO0C;QAC/E,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;YAC/D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;SACtD;QACD,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,IAAI;YACrB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QAEvB,4BAA4B;QAC5B,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;YAClE,OAAO,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;QAED,sCAAsC;QACtC,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACzD,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;YAC5B,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,2BAA2B,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;YACzF,OAAO,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;QAED,iBAAiB;QACjB,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAE3C,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;iBAClD,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EAAE,GAAG,qBAAqB;;;;;;oEAMyB;QAC9D,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;SAChE;QACD,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QAEvB,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7D,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAEjD,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,OAAO;iBACd,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EAAE,GAAG,qBAAqB;;;;;;qFAM0C;QAC/E,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;SAChE;QACD,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,IAAI;YACrB,cAAc,EAAE,KAAK;YACrB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QAEvB,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC/D,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAEtB,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;iBAClD,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,KAAK,EAAE,4BAA4B;QACnC,WAAW,EAAE,GAAG,qBAAqB;;;;;;;0FAO+C;QACpF,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;YACxD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;SACpF;QACD,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,IAAI;YACrB,cAAc,EAAE,KAAK;YACrB,aAAa,EAAE,IAAI;SACpB;KACF,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE;QACzB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;QAEzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE;gBAC/B,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,WAAW;gBAC7B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,MAAM;gBACf,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,EAAE;aAC5B,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;qBACxE,CAAC;aACH,CAAC;QACJ,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,GAA6D,CAAC;YAC9E,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,MAAM,EAAE,OAAO;4BACf,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;4BAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,IAAI,eAAe;yBAC7D,CAAC;qBACH,CAAC;aACH,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;IAEF,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,qBAAqB,EACrB;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,GAAG,qBAAqB;;;;;;;0FAO+C;QACpF,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;YAC/C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;SAC1D;QACD,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,sBAAsB,EAAE,CAAC;QAE9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,MAAM,EAAE,QAAQ;4BAChB,OAAO;4BACP,OAAO;4BACP,SAAS,EAAE,EAAE;4BACb,OAAO,EAAE,2DAA2D;yBACrE,CAAC;qBACH,CAAC;aACH,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAA8D,EAAE,CAAC;QAE9E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE;oBACpC,GAAG,EAAE,KAAK,CAAC,WAAW;oBACtB,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,OAAO;iBACjB,CAAC,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAChF,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,GAA4C,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,MAAM,EAAE,KAAK;oBACb,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;iBACtE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAEjD,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;wBACvC,OAAO;wBACP,OAAO;wBACP,SAAS,EAAE,OAAO;qBACnB,CAAC;iBACH,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,6EAA6E;IAE7E,MAAM,CAAC,YAAY,CACjB,sBAAsB,EACtB;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,GAAG,qBAAqB;;;8GAGmE;QACxG,WAAW,EAAE,EAAE;QACf,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,IAAI,EAAE;QACT,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC;QAEpD,MAAM,OAAO,GAAG;YACd,qBAAqB,EAAE,oPAAoP;YAC3Q,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,SAAS,EAAE,IAAI,CAAC,IAAI;YACpB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,0BAA0B,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,IAAI,EAAE;YACrF,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,IAAI,sBAAsB;YAC/D,kBAAkB,EAAE,QAAQ,EAAE,kBAAkB,IAAI,EAAE;YACtD,aAAa,EAAE;gBACb,eAAe,EAAE,KAAK,CAAC,UAAU,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,IAAI,KAAK;gBACpF,cAAc,EAAE,KAAK,CAAC,UAAU,CAAC,YAAY,EAAE,UAAU,EAAE,cAAc,IAAI,KAAK;gBAClF,mBAAmB,EAAE,KAAK,CAAC,UAAU,CAAC,YAAY,EAAE,UAAU,EAAE,mBAAmB,IAAI,KAAK;aAC7F;SACF,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;iBAC9B,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,SAAS,UAAU,CAAC,IAAY,EAAE,WAAmB;IACnD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,OAAO,CAAC,MAAc;IAI7B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;aACpD,CAAC;KACH,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,MAAyB,EACzB,IAAkB,EAClB,IAAY,EACZ,SAAiB,EACjB,MAAc;IAEd,MAAM,MAAM,CAAC,WAAW,CAAC;QACvB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,eAAe,EAAE,MAAM;QACvB,WAAW,EAAE,MAAM;QACnB,gBAAgB,EAAE,GAAG,SAAS,KAAK,IAAI,EAAE;QACzC,eAAe,EAAE,KAAK;QACtB,UAAU,EAAE,IAAI,CAAC,EAAE;QACnB,SAAS,EAAE,8BAA8B;KAC1C,CAAC,CAAC;AACL,CAAC"}
|
package/package.json
CHANGED
package/src/tools/file-tools.ts
CHANGED
|
@@ -5,6 +5,14 @@
|
|
|
5
5
|
* Every call is validated against the loaded policy before execution.
|
|
6
6
|
* The agent never sees the policy — only the verdict.
|
|
7
7
|
*
|
|
8
|
+
* ENFORCEMENT DIRECTIVE: Every tool description includes a clear statement
|
|
9
|
+
* that agents must use these tools exclusively — no native file operations.
|
|
10
|
+
* This directive reaches the agent at connection time via the MCP tool list,
|
|
11
|
+
* before any conversation begins.
|
|
12
|
+
*
|
|
13
|
+
* LOGGING: Every denied action is logged to overrides.jsonl by the server
|
|
14
|
+
* process — no agent involvement required.
|
|
15
|
+
*
|
|
8
16
|
* Tools:
|
|
9
17
|
* aegis_check_permissions — Pre-check before writing (saves wasted generation)
|
|
10
18
|
* aegis_write_file — Governed write with path + content validation
|
|
@@ -23,6 +31,12 @@ import { z } from 'zod';
|
|
|
23
31
|
import type { EnforcementEngine } from '../services/enforcement-engine.js';
|
|
24
32
|
import type { PolicyState, ResolvedRole } from '../types.js';
|
|
25
33
|
|
|
34
|
+
// ─── Enforcement Directive ──────────────────────────────────────────────────
|
|
35
|
+
// This prefix is prepended to every tool description. It reaches the agent
|
|
36
|
+
// at MCP connection time as part of the tool list — before any user prompt.
|
|
37
|
+
|
|
38
|
+
const ENFORCEMENT_DIRECTIVE = `IMPORTANT: You are connected to the Aegis MCP enforcement layer. ALL file read, write, and delete operations MUST use the aegis_* tools. Do NOT use native file tools (Read, Write, Edit, etc.). Aegis validates every action against your role's governance policy. Blocked actions are logged automatically.\n\n`;
|
|
39
|
+
|
|
26
40
|
export function registerTools(
|
|
27
41
|
server: McpServer,
|
|
28
42
|
getEngine: () => EnforcementEngine,
|
|
@@ -36,7 +50,7 @@ export function registerTools(
|
|
|
36
50
|
'aegis_check_permissions',
|
|
37
51
|
{
|
|
38
52
|
title: 'Check Permissions',
|
|
39
|
-
description:
|
|
53
|
+
description: `${ENFORCEMENT_DIRECTIVE}Check if an operation is allowed on a path before attempting it. Use this to pre-validate before writing or reading files — saves you from composing content that would be blocked. Denied checks are logged automatically by the server.
|
|
40
54
|
|
|
41
55
|
Args:
|
|
42
56
|
- path (string): Target file path relative to project root
|
|
@@ -57,10 +71,16 @@ Returns:
|
|
|
57
71
|
},
|
|
58
72
|
async ({ path, operation }) => {
|
|
59
73
|
const engine = getEngine();
|
|
74
|
+
const role = getRole();
|
|
60
75
|
const verdict = operation === 'read'
|
|
61
76
|
? engine.validateRead(path)
|
|
62
77
|
: engine.validateWrite(path);
|
|
63
78
|
|
|
79
|
+
// Log denied permission checks
|
|
80
|
+
if (!verdict.allowed) {
|
|
81
|
+
await logBlocked(engine, role, path, `check_permissions (${operation})`, verdict.reason);
|
|
82
|
+
}
|
|
83
|
+
|
|
64
84
|
return {
|
|
65
85
|
content: [{
|
|
66
86
|
type: 'text' as const,
|
|
@@ -80,7 +100,7 @@ Returns:
|
|
|
80
100
|
'aegis_write_file',
|
|
81
101
|
{
|
|
82
102
|
title: 'Write File (Governed)',
|
|
83
|
-
description:
|
|
103
|
+
description: `${ENFORCEMENT_DIRECTIVE}Write content to a file with governance enforcement. Path is validated against your role's permissions and governance boundaries. Content is scanned for sensitive patterns. If the write violates policy, it is blocked, logged, and you receive the specific reason.
|
|
84
104
|
|
|
85
105
|
Args:
|
|
86
106
|
- path (string): File path relative to project root
|
|
@@ -138,7 +158,7 @@ Returns:
|
|
|
138
158
|
'aegis_read_file',
|
|
139
159
|
{
|
|
140
160
|
title: 'Read File (Governed)',
|
|
141
|
-
description:
|
|
161
|
+
description: `${ENFORCEMENT_DIRECTIVE}Read the contents of a file with governance enforcement. Path is validated against your role's read permissions. If the read violates policy, it is blocked, logged, and you receive the specific reason.
|
|
142
162
|
|
|
143
163
|
Args:
|
|
144
164
|
- path (string): File path relative to project root
|
|
@@ -158,9 +178,11 @@ Returns:
|
|
|
158
178
|
async ({ path }) => {
|
|
159
179
|
const engine = getEngine();
|
|
160
180
|
const state = getState();
|
|
181
|
+
const role = getRole();
|
|
161
182
|
|
|
162
183
|
const verdict = engine.validateRead(path);
|
|
163
184
|
if (!verdict.allowed) {
|
|
185
|
+
await logBlocked(engine, role, path, 'read', verdict.reason);
|
|
164
186
|
return blocked(verdict.reason);
|
|
165
187
|
}
|
|
166
188
|
|
|
@@ -182,7 +204,7 @@ Returns:
|
|
|
182
204
|
'aegis_delete_file',
|
|
183
205
|
{
|
|
184
206
|
title: 'Delete File (Governed)',
|
|
185
|
-
description:
|
|
207
|
+
description: `${ENFORCEMENT_DIRECTIVE}Delete a file with governance enforcement. Write permissions are required. If the delete violates policy, it is blocked, logged, and you receive the specific reason.
|
|
186
208
|
|
|
187
209
|
Args:
|
|
188
210
|
- path (string): File path relative to project root
|
|
@@ -228,7 +250,7 @@ Returns:
|
|
|
228
250
|
'aegis_execute',
|
|
229
251
|
{
|
|
230
252
|
title: 'Execute Command (Governed)',
|
|
231
|
-
description:
|
|
253
|
+
description: `${ENFORCEMENT_DIRECTIVE}Execute a shell command in the project directory. Currently validates that the command runs within the project root. Future versions will enforce command-level permissions.
|
|
232
254
|
|
|
233
255
|
Args:
|
|
234
256
|
- command (string): Shell command to execute
|
|
@@ -287,7 +309,7 @@ Returns:
|
|
|
287
309
|
'aegis_complete_task',
|
|
288
310
|
{
|
|
289
311
|
title: 'Complete Task',
|
|
290
|
-
description:
|
|
312
|
+
description: `${ENFORCEMENT_DIRECTIVE}Signal task completion and run required quality gates. Maps the governance quality_gate.pre_commit flags to build_commands and runs each required check. Returns pass/fail with details.
|
|
291
313
|
|
|
292
314
|
Args:
|
|
293
315
|
- task_id (string): Identifier for the task being completed
|
|
@@ -368,10 +390,10 @@ Returns:
|
|
|
368
390
|
'aegis_policy_summary',
|
|
369
391
|
{
|
|
370
392
|
title: 'Policy Summary',
|
|
371
|
-
description:
|
|
393
|
+
description: `${ENFORCEMENT_DIRECTIVE}Get a minimal summary of your current role and permissions. Call this FIRST before doing any work. Returns your role name, writable paths, excluded paths, forbidden actions, and key governance rules — just enough to understand your boundaries without loading full policy files.
|
|
372
394
|
|
|
373
395
|
Returns:
|
|
374
|
-
{ "role": "...", "writable_paths": [...], "forbidden_actions": [...], ... }`,
|
|
396
|
+
{ "enforcement_directive": "...", "role": "...", "writable_paths": [...], "forbidden_actions": [...], ... }`,
|
|
375
397
|
inputSchema: {},
|
|
376
398
|
annotations: {
|
|
377
399
|
readOnlyHint: true,
|
|
@@ -386,6 +408,7 @@ Returns:
|
|
|
386
408
|
const protocol = state.governance.override_protocol;
|
|
387
409
|
|
|
388
410
|
const summary = {
|
|
411
|
+
enforcement_directive: 'You are governed by the Aegis MCP enforcement layer. ALL file operations (read, write, delete) MUST use aegis_* tools. Do NOT use native file tools. Violations are blocked and logged automatically. There are no exceptions to this requirement.',
|
|
389
412
|
role: role.id,
|
|
390
413
|
role_name: role.name,
|
|
391
414
|
purpose: role.purpose,
|