@acepaste/ingress 0.7.0 → 0.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/dist/src/acquire.d.ts +19 -1
- package/dist/src/acquire.js +130 -5
- package/dist/src/approvers.d.ts +18 -0
- package/dist/src/approvers.js +43 -0
- package/dist/src/audit-parsers.d.ts +85 -0
- package/dist/src/audit-parsers.js +333 -0
- package/dist/src/audit.d.ts +57 -0
- package/dist/src/audit.js +393 -0
- package/dist/src/broker.d.ts +178 -0
- package/dist/src/broker.js +396 -0
- package/dist/src/cli.js +115 -1
- package/dist/src/codepass.d.ts +57 -0
- package/dist/src/codepass.js +240 -0
- package/dist/src/engine.d.ts +65 -4
- package/dist/src/engine.js +214 -60
- package/dist/src/index.d.ts +18 -4
- package/dist/src/index.js +11 -2
- package/dist/src/instructions.d.ts +84 -0
- package/dist/src/instructions.js +185 -0
- package/dist/src/meaning.js +20 -12
- package/dist/src/multilingual.d.ts +33 -0
- package/dist/src/multilingual.js +89 -0
- package/dist/src/summary.d.ts +40 -0
- package/dist/src/summary.js +62 -0
- package/dist/src/supplychain.d.ts +4 -0
- package/dist/src/supplychain.js +22 -1
- package/dist/src/taint.js +1 -1
- package/dist/src/types.d.ts +35 -5
- package/dist/src/types.js +10 -2
- package/package.json +1 -1
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Action broker: the enforcement point between an agent and its side-effecting tools.
|
|
3
|
+
*
|
|
4
|
+
* The gate's verdict never authorizes an action. The broker decides, outside the model:
|
|
5
|
+
* - a run is tainted as soon as it has taken in any outside content, whatever that
|
|
6
|
+
* content scored (a low score is a prioritization signal, not proof of safety)
|
|
7
|
+
* - while tainted, tools the policy marks as side-effecting need a person's approval of
|
|
8
|
+
* the EXACT call (tool + arguments, by digest); approvals are single-use, short-lived
|
|
9
|
+
* and bound to the run
|
|
10
|
+
* - approvals come only from an Approver: a channel the model cannot drive (a native
|
|
11
|
+
* dialog, a console behind its own credential). There is no tool the model can call
|
|
12
|
+
* to approve itself
|
|
13
|
+
* - arguments that carry data out (long query strings, encoded blobs, URLs to hosts
|
|
14
|
+
* outside an allowlist) need approval while tainted, even on "read" tools
|
|
15
|
+
* - a run that touched a quarantined source is denied side effects outright
|
|
16
|
+
*
|
|
17
|
+
* Limit, stated plainly: the broker enforces only on calls routed through it. A tool the
|
|
18
|
+
* agent can reach directly is outside its control.
|
|
19
|
+
*/
|
|
20
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
21
|
+
export const DEFAULT_BROKER_POLICY = {
|
|
22
|
+
name: "default",
|
|
23
|
+
version: 2,
|
|
24
|
+
rules: [],
|
|
25
|
+
readOnlyTools: ["ingress_fetch", "ingress_scan", "ingress_status", "ingress_instructions", "ingress_environment_audit", "ingress_verify_receipt"],
|
|
26
|
+
sideEffectHints: ["send", "email", "mail", "post", "publish", "write", "edit", "create", "update", "delete", "remove", "move", "rename", "pay", "transfer", "purchase", "order", "execute", "exec", "run", "shell", "bash", "command", "deploy", "push", "commit", "merge", "install", "upload", "share", "invite", "message", "reply", "comment", "schedule", "start", "kill", "set", "insert", "drop", "save", "put", "submit", "trigger", "invoke", "eval", "navigate", "type", "click", "fork"],
|
|
27
|
+
allowHosts: [],
|
|
28
|
+
guardOutboundData: true,
|
|
29
|
+
approvalTtlMs: 120_000,
|
|
30
|
+
maxShownArgChars: 4000,
|
|
31
|
+
onApproverUnavailable: "deny",
|
|
32
|
+
};
|
|
33
|
+
/** deterministic JSON: object keys sorted at every depth, so one call has one digest */
|
|
34
|
+
export function canonicalJson(v) {
|
|
35
|
+
const seen = new WeakSet();
|
|
36
|
+
const norm = (x) => {
|
|
37
|
+
if (x === null || typeof x !== "object")
|
|
38
|
+
return typeof x === "number" && !Number.isFinite(x) ? String(x) : x;
|
|
39
|
+
if (seen.has(x))
|
|
40
|
+
throw new Error("cyclic arguments");
|
|
41
|
+
seen.add(x);
|
|
42
|
+
if (Array.isArray(x))
|
|
43
|
+
return x.map(norm);
|
|
44
|
+
return Object.fromEntries(Object.keys(x).sort().map((k) => [k, norm(x[k])]));
|
|
45
|
+
};
|
|
46
|
+
return JSON.stringify(norm(v) ?? null);
|
|
47
|
+
}
|
|
48
|
+
export function actionDigest(runId, tool, canonicalArgs) {
|
|
49
|
+
return createHash("sha256").update(JSON.stringify(["ingress-action:v1", runId, tool, canonicalArgs]), "utf8").digest("hex");
|
|
50
|
+
}
|
|
51
|
+
/** the tool's own name: the part after the first "server__" prefix */
|
|
52
|
+
const ownName = (tool) => { const i = tool.indexOf("__"); return i >= 0 ? tool.slice(i + 2) : tool; };
|
|
53
|
+
/**
|
|
54
|
+
* Whether a tool's name says it acts. Used only to explain a decision: an unknown tool
|
|
55
|
+
* needs approval while tainted whatever its name says.
|
|
56
|
+
*/
|
|
57
|
+
export function isSideEffectName(tool, hints) {
|
|
58
|
+
const words = ownName(tool).replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
|
|
59
|
+
return words.some((w) => hints.some((h) => w === h || w.startsWith(h)));
|
|
60
|
+
}
|
|
61
|
+
function globMatch(pattern, name) {
|
|
62
|
+
const re = new RegExp("^" + pattern.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
|
|
63
|
+
return re.test(name);
|
|
64
|
+
}
|
|
65
|
+
const LIMITS = { depth: 32, strings: 5000, bytes: 1_000_000 };
|
|
66
|
+
/** every string (and object key) inside the arguments; `complete` is false if a limit cut the walk short */
|
|
67
|
+
function walkStrings(v) {
|
|
68
|
+
const strings = [], fields = new Set();
|
|
69
|
+
let bytes = 0, complete = true;
|
|
70
|
+
const go = (x, depth) => {
|
|
71
|
+
if (!complete)
|
|
72
|
+
return;
|
|
73
|
+
if (depth > LIMITS.depth || strings.length > LIMITS.strings || bytes > LIMITS.bytes) {
|
|
74
|
+
complete = false;
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
if (typeof x === "string") {
|
|
78
|
+
strings.push(x);
|
|
79
|
+
bytes += x.length;
|
|
80
|
+
}
|
|
81
|
+
else if (typeof x === "number" || typeof x === "boolean" || x === null || x === undefined)
|
|
82
|
+
return;
|
|
83
|
+
else if (Array.isArray(x))
|
|
84
|
+
for (const y of x)
|
|
85
|
+
go(y, depth + 1);
|
|
86
|
+
else if (typeof x === "object")
|
|
87
|
+
for (const [k, y] of Object.entries(x)) {
|
|
88
|
+
fields.add(k);
|
|
89
|
+
strings.push(k);
|
|
90
|
+
go(y, depth + 1);
|
|
91
|
+
}
|
|
92
|
+
};
|
|
93
|
+
go(v, 0);
|
|
94
|
+
return { strings, fields: [...fields], complete };
|
|
95
|
+
}
|
|
96
|
+
const URLISH = /(?:\b[a-z][a-z0-9+.-]{1,15}:(?:\/\/|\\\\)?|(?<![\w/])\/\/)[^\s"'<>()]+/gi;
|
|
97
|
+
const BARE_DOMAIN = /(?<![\w@.-])(?:[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?\.)+[\p{L}]{2,24}(?![\p{L}\p{N}-])/giu;
|
|
98
|
+
const EMAIL_DOMAIN = /@(\[[^\]\s]{2,64}\]|(?:[\p{L}\p{N}-]+\.)+[\p{L}]{2,24})/giu;
|
|
99
|
+
const IPV4 = /(?<![\d.])(?:\d{1,3}\.){3}\d{1,3}(?![\d.])/g;
|
|
100
|
+
const toAsciiHost = (h) => {
|
|
101
|
+
const t = h.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
|
|
102
|
+
if (/^[\d.]+$/.test(t) || t.includes(":"))
|
|
103
|
+
return t;
|
|
104
|
+
try {
|
|
105
|
+
return new URL(`http://${t}/`).hostname.replace(/\.$/, "");
|
|
106
|
+
}
|
|
107
|
+
catch {
|
|
108
|
+
return undefined;
|
|
109
|
+
}
|
|
110
|
+
};
|
|
111
|
+
/** hosts and addresses named in the arguments, broadly: URLs of any scheme, scheme-less URLs, bare domains, email domains, IP addresses */
|
|
112
|
+
export function destinationsIn(args) {
|
|
113
|
+
const { strings, complete } = walkStrings(args);
|
|
114
|
+
const hosts = new Set(), oddities = [];
|
|
115
|
+
for (const s of strings) {
|
|
116
|
+
for (const m of s.matchAll(URLISH)) {
|
|
117
|
+
const raw = m[0];
|
|
118
|
+
if (/^(?:data|blob|about|javascript|mailto|tel):/i.test(raw)) {
|
|
119
|
+
if (/^javascript:/i.test(raw))
|
|
120
|
+
oddities.push("a javascript: URL");
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
if (raw.includes("\\"))
|
|
124
|
+
oddities.push(`a URL with a backslash (${raw.slice(0, 60)}), which parsers read differently`);
|
|
125
|
+
const auth = raw.replace(/^[a-z][a-z0-9+.-]*:/i, "").replace(/^[\\/]+/, "").split(/[\\/?#]/)[0];
|
|
126
|
+
if (auth.includes("@"))
|
|
127
|
+
oddities.push(`a URL with credentials or an @ before the host (${raw.slice(0, 60)}), which parsers read differently`);
|
|
128
|
+
try {
|
|
129
|
+
const u = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${auth}/`);
|
|
130
|
+
if (u.hostname)
|
|
131
|
+
hosts.add(u.hostname.replace(/\.$/, "").toLowerCase());
|
|
132
|
+
}
|
|
133
|
+
catch {
|
|
134
|
+
oddities.push(`an address that does not parse (${raw.slice(0, 60)})`);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
for (const m of s.matchAll(EMAIL_DOMAIN)) {
|
|
138
|
+
const h = toAsciiHost(m[1]);
|
|
139
|
+
if (h)
|
|
140
|
+
hosts.add(h);
|
|
141
|
+
}
|
|
142
|
+
for (const m of s.matchAll(BARE_DOMAIN)) {
|
|
143
|
+
const h = toAsciiHost(m[0]);
|
|
144
|
+
if (h)
|
|
145
|
+
hosts.add(h);
|
|
146
|
+
}
|
|
147
|
+
for (const m of s.matchAll(IPV4))
|
|
148
|
+
hosts.add(m[0]);
|
|
149
|
+
}
|
|
150
|
+
for (const h of hosts)
|
|
151
|
+
if (/^xn--|\.xn--/.test(h))
|
|
152
|
+
oddities.push(`an international domain (${h}) that may imitate another`);
|
|
153
|
+
return { hosts: [...hosts], oddities, complete };
|
|
154
|
+
}
|
|
155
|
+
/** characters of a token that look like data rather than words: mixed letter cases and digits */
|
|
156
|
+
const dataLike = (t) => t.length >= 6 && [/[a-z]/, /[A-Z]/, /[0-9]/].filter((r) => r.test(t)).length >= 2;
|
|
157
|
+
/** argument shapes that look like data leaving through a URL: encoded tokens anywhere in it, long subdomains, long query or fragment */
|
|
158
|
+
export function exfilShapes(args) {
|
|
159
|
+
const why = [];
|
|
160
|
+
const { strings, complete } = walkStrings(args);
|
|
161
|
+
if (!complete)
|
|
162
|
+
why.push("arguments too large or deep to inspect fully");
|
|
163
|
+
for (const s of strings) {
|
|
164
|
+
for (const m of s.matchAll(URLISH)) {
|
|
165
|
+
let u;
|
|
166
|
+
try {
|
|
167
|
+
u = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(m[0]) ? m[0] : `http://${m[0].replace(/^[a-z][a-z0-9+.-]*:/i, "").replace(/^[\\/]+/, "")}`);
|
|
168
|
+
}
|
|
169
|
+
catch {
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
let decoded = `${u.hostname} ${u.pathname} ${u.search} ${u.hash}`;
|
|
173
|
+
try {
|
|
174
|
+
decoded = decodeURIComponent(decoded);
|
|
175
|
+
}
|
|
176
|
+
catch { /* keep encoded */ }
|
|
177
|
+
const tokens = decoded.split(/[^A-Za-z0-9+=]+/).filter(Boolean);
|
|
178
|
+
const dataChars = tokens.filter(dataLike).reduce((n, t) => n + t.length, 0);
|
|
179
|
+
if (dataChars >= 24)
|
|
180
|
+
why.push(`URL to ${u.hostname} carries ${dataChars} characters that look like encoded data`);
|
|
181
|
+
if (u.hostname.split(".").some((l) => l.length >= 40))
|
|
182
|
+
why.push(`URL to ${u.hostname} has a very long subdomain label`);
|
|
183
|
+
if (u.search.length + u.hash.length > 150)
|
|
184
|
+
why.push(`URL to ${u.hostname} carries ${u.search.length + u.hash.length} characters of query and fragment`);
|
|
185
|
+
if (u.username || u.password)
|
|
186
|
+
why.push(`URL to ${u.hostname} carries credentials`);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
return [...new Set(why)];
|
|
190
|
+
}
|
|
191
|
+
const hostAllowed = (host, allow) => allow.some((a) => { const x = a.toLowerCase().replace(/\.$/, ""); return x.startsWith(".") ? host === x.slice(1) || host.endsWith(x) : host === x; });
|
|
192
|
+
const hostMatches = (host, q) => host === q || host.endsWith("." + q);
|
|
193
|
+
export class ActionBroker {
|
|
194
|
+
deps;
|
|
195
|
+
policy;
|
|
196
|
+
runs = new Map();
|
|
197
|
+
globalQuarantine = new Set();
|
|
198
|
+
used = new Set();
|
|
199
|
+
constructor(policy = {}, deps = {}) {
|
|
200
|
+
this.deps = deps;
|
|
201
|
+
this.policy = { ...DEFAULT_BROKER_POLICY, ...policy, readOnlyTools: policy.readOnlyTools ?? DEFAULT_BROKER_POLICY.readOnlyTools };
|
|
202
|
+
}
|
|
203
|
+
run(runId) {
|
|
204
|
+
let r = this.runs.get(runId);
|
|
205
|
+
if (!r) {
|
|
206
|
+
r = { sources: new Set(), receipts: new Set(), hosts: new Set(), quarantined: new Set() };
|
|
207
|
+
this.runs.set(runId, r);
|
|
208
|
+
}
|
|
209
|
+
return r;
|
|
210
|
+
}
|
|
211
|
+
quarantineHit(ref, host) {
|
|
212
|
+
for (const q of this.globalQuarantine) {
|
|
213
|
+
if (ref && (ref === q || ref.startsWith(q)))
|
|
214
|
+
return q;
|
|
215
|
+
if (host && hostMatches(host, q))
|
|
216
|
+
return q;
|
|
217
|
+
}
|
|
218
|
+
return undefined;
|
|
219
|
+
}
|
|
220
|
+
/** is this URL or host quarantined? (check before fetching, and on the final URL after redirects) */
|
|
221
|
+
isQuarantined(urlOrHost) {
|
|
222
|
+
let host;
|
|
223
|
+
try {
|
|
224
|
+
host = new URL(urlOrHost).hostname.toLowerCase().replace(/\.$/, "");
|
|
225
|
+
}
|
|
226
|
+
catch {
|
|
227
|
+
host = urlOrHost.toLowerCase().replace(/\.$/, "");
|
|
228
|
+
}
|
|
229
|
+
return this.quarantineHit(urlOrHost, host);
|
|
230
|
+
}
|
|
231
|
+
/** record outside content the run has taken in. Any source taints the run, whatever its verdict. */
|
|
232
|
+
ingest(runId, source) {
|
|
233
|
+
const r = this.run(runId);
|
|
234
|
+
r.sources.add(source.ref);
|
|
235
|
+
if (source.receiptDigest)
|
|
236
|
+
r.receipts.add(source.receiptDigest);
|
|
237
|
+
const host = source.host?.toLowerCase().replace(/\.$/, "");
|
|
238
|
+
if (host)
|
|
239
|
+
r.hosts.add(host);
|
|
240
|
+
const q = this.quarantineHit(source.ref, host) ?? (source.receiptDigest && this.globalQuarantine.has(source.receiptDigest) ? source.receiptDigest : undefined);
|
|
241
|
+
if (q)
|
|
242
|
+
r.quarantined.add(q);
|
|
243
|
+
return { tainted: true, sources: [...r.sources] };
|
|
244
|
+
}
|
|
245
|
+
/** mark a source (URL prefix, host with its subdomains, or receipt digest) as quarantined everywhere; returns the runs that already touched it */
|
|
246
|
+
quarantine(ref) {
|
|
247
|
+
const q = /^https?:/i.test(ref) ? ref : ref.toLowerCase().replace(/\.$/, "");
|
|
248
|
+
this.globalQuarantine.add(q);
|
|
249
|
+
const hit = [];
|
|
250
|
+
for (const [id, r] of this.runs) {
|
|
251
|
+
const touched = r.receipts.has(q) || [...r.sources].some((s) => s.startsWith(q)) || [...r.hosts].some((h) => hostMatches(h, q));
|
|
252
|
+
if (touched) {
|
|
253
|
+
r.quarantined.add(q);
|
|
254
|
+
hit.push(id);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
return hit;
|
|
258
|
+
}
|
|
259
|
+
state(runId) {
|
|
260
|
+
const r = this.run(runId);
|
|
261
|
+
return { tainted: r.sources.size > 0, sources: [...r.sources], quarantined: [...r.quarantined] };
|
|
262
|
+
}
|
|
263
|
+
/** decide without asking anyone (for previews and tests) */
|
|
264
|
+
classify(action) {
|
|
265
|
+
const r = this.run(action.runId);
|
|
266
|
+
const tainted = r.sources.size > 0;
|
|
267
|
+
const canonicalArgs = canonicalJson(action.args);
|
|
268
|
+
const digest = actionDigest(action.runId, action.tool, canonicalArgs);
|
|
269
|
+
const reasons = [];
|
|
270
|
+
const rule = this.policy.rules.find((x) => globMatch(x.tool, action.tool));
|
|
271
|
+
const readOnly = !rule && this.policy.readOnlyTools.some((g) => globMatch(g, action.tool));
|
|
272
|
+
const dest = destinationsIn(action.args);
|
|
273
|
+
const fields = walkStrings(action.args).fields;
|
|
274
|
+
let decision;
|
|
275
|
+
if (rule) {
|
|
276
|
+
decision = (tainted ? rule.tainted : rule.clean) ?? (tainted ? "require_approval" : "allow");
|
|
277
|
+
reasons.push(`rule ${rule.tool}: ${decision}${tainted ? " (run has taken in outside content)" : ""}`);
|
|
278
|
+
if (rule.allowDestinations && decision === "allow") {
|
|
279
|
+
const outside = dest.hosts.filter((h) => !hostAllowed(h, rule.allowDestinations));
|
|
280
|
+
if (outside.length) {
|
|
281
|
+
decision = "require_approval";
|
|
282
|
+
reasons.push(`destination outside the allowlist: ${outside.join(", ")}`);
|
|
283
|
+
}
|
|
284
|
+
if (!dest.complete) {
|
|
285
|
+
decision = "require_approval";
|
|
286
|
+
reasons.push("arguments too large or deep to check every destination");
|
|
287
|
+
}
|
|
288
|
+
if (dest.oddities.length) {
|
|
289
|
+
decision = "require_approval";
|
|
290
|
+
reasons.push(...dest.oddities);
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
else if (!tainted) {
|
|
295
|
+
decision = "allow";
|
|
296
|
+
}
|
|
297
|
+
else if (readOnly) {
|
|
298
|
+
decision = "allow";
|
|
299
|
+
}
|
|
300
|
+
else {
|
|
301
|
+
decision = "require_approval";
|
|
302
|
+
reasons.push(isSideEffectName(action.tool, this.policy.sideEffectHints)
|
|
303
|
+
? "a tool that acts, in a run that has taken in outside content"
|
|
304
|
+
: "a tool not known to be read-only, in a run that has taken in outside content");
|
|
305
|
+
}
|
|
306
|
+
if (tainted && this.policy.guardOutboundData) {
|
|
307
|
+
const ex = exfilShapes(action.args).filter((w) => !this.policy.allowHosts.some((a) => w.includes(` ${a.replace(/^\./, "")} `)));
|
|
308
|
+
if (ex.length) {
|
|
309
|
+
decision = strongest(decision, "require_approval");
|
|
310
|
+
reasons.push(...ex);
|
|
311
|
+
}
|
|
312
|
+
if (dest.oddities.length && decision === "allow") {
|
|
313
|
+
decision = "require_approval";
|
|
314
|
+
reasons.push(...dest.oddities);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
if (r.quarantined.size && decision !== "allow" || r.quarantined.size && !readOnly) {
|
|
318
|
+
decision = "deny";
|
|
319
|
+
reasons.push(`run touched a quarantined source: ${[...r.quarantined].join(", ")}`);
|
|
320
|
+
}
|
|
321
|
+
return { decision, reasons, digest, canonicalArgs, destinations: dest.hosts, fields };
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* Decide, asking the approver when needed. The caller must then execute EXACTLY the
|
|
325
|
+
* arguments it gets back (frozen) or not at all.
|
|
326
|
+
*/
|
|
327
|
+
async authorize(action) {
|
|
328
|
+
const c = this.classify(action);
|
|
329
|
+
const now = this.deps.now?.() ?? Date.now();
|
|
330
|
+
const policyRef = { name: this.policy.name, version: this.policy.version };
|
|
331
|
+
let verdict;
|
|
332
|
+
if (c.decision === "allow")
|
|
333
|
+
verdict = { decision: "allow", permitted: true, reasons: c.reasons, digest: c.digest, policy: policyRef };
|
|
334
|
+
else if (c.decision === "deny")
|
|
335
|
+
verdict = { decision: "deny", permitted: false, reasons: c.reasons, digest: c.digest, policy: policyRef };
|
|
336
|
+
else if (c.canonicalArgs.length > this.policy.maxShownArgChars) {
|
|
337
|
+
// what the person cannot see in full, they cannot approve
|
|
338
|
+
c.reasons.push(`arguments are ${c.canonicalArgs.length} characters, too long to show in full for approval (limit ${this.policy.maxShownArgChars}), so it was refused`);
|
|
339
|
+
verdict = { decision: "require_approval", permitted: false, reasons: c.reasons, digest: c.digest, approval: { id: "", outcome: "unavailable" }, policy: policyRef };
|
|
340
|
+
}
|
|
341
|
+
else {
|
|
342
|
+
const req = {
|
|
343
|
+
id: randomBytes(9).toString("base64url"), runId: action.runId, tool: action.tool, canonicalArgs: c.canonicalArgs, digest: c.digest,
|
|
344
|
+
reasons: [...c.reasons], destinations: c.destinations, fields: c.fields, sources: this.state(action.runId).sources, createdAt: now, expiresAt: now + this.policy.approvalTtlMs,
|
|
345
|
+
};
|
|
346
|
+
let outcome = "unavailable";
|
|
347
|
+
if (this.deps.approver) {
|
|
348
|
+
try {
|
|
349
|
+
outcome = await this.deps.approver.request(req);
|
|
350
|
+
}
|
|
351
|
+
catch {
|
|
352
|
+
outcome = "unavailable";
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
const late = (this.deps.now?.() ?? Date.now()) > req.expiresAt;
|
|
356
|
+
if (outcome === "approved" && late)
|
|
357
|
+
outcome = "timeout";
|
|
358
|
+
if (outcome === "approved" && this.used.has(req.id))
|
|
359
|
+
outcome = "denied";
|
|
360
|
+
if (outcome === "approved")
|
|
361
|
+
this.used.add(req.id);
|
|
362
|
+
const permitted = outcome === "approved";
|
|
363
|
+
if (!permitted)
|
|
364
|
+
c.reasons.push(outcome === "unavailable" ? "approval needed but no approver is set up or reachable, so it was refused (fails closed)" : outcome === "denied" ? "the person declined" : "the person did not answer in time");
|
|
365
|
+
verdict = { decision: "require_approval", permitted, reasons: c.reasons, digest: c.digest, approval: { id: req.id, outcome }, policy: policyRef };
|
|
366
|
+
}
|
|
367
|
+
this.deps.log?.({ event: "broker.decision", at: new Date(now).toISOString(), runId: action.runId, tool: action.tool, digest: c.digest, decision: verdict.decision, permitted: verdict.permitted, reasons: verdict.reasons, approval: verdict.approval, sources: this.state(action.runId).sources, policy: policyRef });
|
|
368
|
+
return { ...verdict, args: deepFreeze(JSON.parse(c.canonicalArgs)) };
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
function strongest(a, b) {
|
|
372
|
+
const rank = { allow: 0, require_approval: 1, deny: 2 };
|
|
373
|
+
return rank[a] >= rank[b] ? a : b;
|
|
374
|
+
}
|
|
375
|
+
function deepFreeze(o) {
|
|
376
|
+
if (o && typeof o === "object") {
|
|
377
|
+
Object.freeze(o);
|
|
378
|
+
for (const v of Object.values(o))
|
|
379
|
+
deepFreeze(v);
|
|
380
|
+
}
|
|
381
|
+
return o;
|
|
382
|
+
}
|
|
383
|
+
/** readable text of an approval request for a human: destinations and field names first, every invisible or format character made visible */
|
|
384
|
+
export function describeApproval(req, maxArgs = 4000) {
|
|
385
|
+
const vis = (t) => t.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\u00ad\u034f\u115f\u1160\u180e\u3164\uffa0]/gu, (c) => (c === "\n" ? "\\n" : `<U+${c.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}>`));
|
|
386
|
+
const args = req.canonicalArgs.length > maxArgs ? req.canonicalArgs.slice(0, maxArgs) + ` … (${req.canonicalArgs.length - maxArgs} more characters NOT SHOWN: deny)` : req.canonicalArgs;
|
|
387
|
+
return [
|
|
388
|
+
`An AI agent wants to run: ${vis(req.tool)}`,
|
|
389
|
+
req.destinations?.length ? `It names these hosts or addresses: ${req.destinations.map(vis).join(", ")}` : "It names no hosts or addresses.",
|
|
390
|
+
req.fields?.length ? `Fields: ${req.fields.map(vis).join(", ")}` : "",
|
|
391
|
+
`Arguments (exactly what will run): ${vis(args)}`,
|
|
392
|
+
`Why this needs you: ${req.reasons.map(vis).join("; ")}`,
|
|
393
|
+
req.sources.length ? `Outside content this run has read: ${req.sources.slice(-5).map(vis).join(", ")}` : "",
|
|
394
|
+
`Action fingerprint: ${req.digest.slice(0, 16)}`,
|
|
395
|
+
].filter(Boolean).join("\n\n");
|
|
396
|
+
}
|
package/dist/src/cli.js
CHANGED
|
@@ -11,7 +11,14 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import { readFileSync } from "node:fs";
|
|
13
13
|
import { IngressEngine } from "./engine.js";
|
|
14
|
+
import { HONEST_USER_AGENT } from "./acquire.js";
|
|
15
|
+
import { summarize, cloakingConfigFromEnv } from "./summary.js";
|
|
14
16
|
import { loadPolicyFile } from "./policyfile.js";
|
|
17
|
+
import { checkInstructionFiles, approveInstructionFile, readInstructionBytes } from "./instructions.js";
|
|
18
|
+
import { macosDialogApprover } from "./approvers.js";
|
|
19
|
+
import { auditEnvironment, formatAudit } from "./audit.js";
|
|
20
|
+
import { createInterface } from "node:readline/promises";
|
|
21
|
+
import { userInfo } from "node:os";
|
|
15
22
|
const args = process.argv.slice(2);
|
|
16
23
|
const flag = (n) => args.includes(`--${n}`);
|
|
17
24
|
const opt = (n) => args.find((a) => a.startsWith(`--${n}=`))?.split("=")[1];
|
|
@@ -19,6 +26,27 @@ const url = args.find((a) => /^https?:\/\//.test(a));
|
|
|
19
26
|
async function main() {
|
|
20
27
|
const chunksIn = async () => { const c = []; for await (const x of process.stdin)
|
|
21
28
|
c.push(x); return Buffer.concat(c).toString("utf8"); };
|
|
29
|
+
if (args[0] === "instructions")
|
|
30
|
+
return instructionsCommand(args.slice(1));
|
|
31
|
+
if (args[0] === "audit") {
|
|
32
|
+
// read-only: what on this machine could change what agents receive (hosts, DNS, proxies, browsers, certificates, agent configs)
|
|
33
|
+
const gateEngine = new IngressEngine({ cloakingCheck: false, sandbox: "off" }, { log: () => { } });
|
|
34
|
+
const remoteBase = opt("remote");
|
|
35
|
+
if (remoteBase && !process.env.INGRESS_API_KEY) {
|
|
36
|
+
console.error("--remote needs INGRESS_API_KEY (an API key for that gate)");
|
|
37
|
+
process.exit(2);
|
|
38
|
+
}
|
|
39
|
+
const fetchEngine = new IngressEngine({ cloakingCheck: false, sandbox: "off", cacheTtlSeconds: 0 }, { log: () => { } });
|
|
40
|
+
const r = await auditEnvironment({
|
|
41
|
+
network: flag("network"),
|
|
42
|
+
gate: (t, src) => gateEngine.scan(t, { url: src, contentType: "text/markdown" }),
|
|
43
|
+
remote: remoteBase ? { base: remoteBase, key: process.env.INGRESS_API_KEY, localFetch: (u) => fetchEngine.fetch(u) } : undefined,
|
|
44
|
+
});
|
|
45
|
+
console.log(flag("json") ? JSON.stringify(r, null, 2) : formatAudit(r));
|
|
46
|
+
if (r.summary.high)
|
|
47
|
+
process.exitCode = 1;
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
22
50
|
if (flag("keygen")) {
|
|
23
51
|
const k = IngressEngine.generateSigningKeys();
|
|
24
52
|
console.log(`# keyId ${k.keyId}\n# private key: keep secret; set INGRESS_SIGNING_PRIVATE_KEY_FILE to its path\n${k.privateKeyPem}\n# public key: publish; anyone can verify receipts with it\n${k.publicKeyPem}`);
|
|
@@ -32,8 +60,12 @@ async function main() {
|
|
|
32
60
|
return;
|
|
33
61
|
}
|
|
34
62
|
const cfg = opt("policy") ? loadPolicyFile(opt("policy")) : {};
|
|
63
|
+
Object.assign(cfg, cloakingConfigFromEnv(process.env, HONEST_USER_AGENT));
|
|
35
64
|
if (flag("no-cloaking"))
|
|
36
65
|
cfg.cloakingCheck = false;
|
|
66
|
+
const hf = opt("human-fetch");
|
|
67
|
+
if (hf === "browser" || hf === "http")
|
|
68
|
+
cfg.humanFetch = hf;
|
|
37
69
|
const sb = opt("sandbox");
|
|
38
70
|
if (sb === "always" || sb === "escalate" || sb === "off")
|
|
39
71
|
cfg.sandbox = sb;
|
|
@@ -50,14 +82,96 @@ async function main() {
|
|
|
50
82
|
else if (url)
|
|
51
83
|
result = await engine.fetch(url, { override });
|
|
52
84
|
else {
|
|
53
|
-
console.error("usage: ingress <url> | ingress --text < file [--json] [--no-cloaking] [--override] [--sandbox=always|escalate|off] [--policy=file.json] | ingress --verify < receipt.json");
|
|
85
|
+
console.error("usage: ingress <url> | ingress --text < file [--json | --summary] [--no-cloaking] [--human-fetch=http|browser] [--override] [--sandbox=always|escalate|off] [--policy=file.json] | ingress --verify < receipt.json");
|
|
54
86
|
process.exit(2);
|
|
55
87
|
}
|
|
56
88
|
if (flag("json")) {
|
|
57
89
|
console.log(JSON.stringify(result, null, 2));
|
|
58
90
|
return;
|
|
59
91
|
}
|
|
92
|
+
if (flag("summary")) {
|
|
93
|
+
console.log(JSON.stringify(summarize(result)));
|
|
94
|
+
if (result.tier === "unreachable")
|
|
95
|
+
process.exitCode = 1;
|
|
96
|
+
return;
|
|
97
|
+
}
|
|
60
98
|
console.log(result.envelope);
|
|
61
99
|
console.error(`\n[timings] ${Object.entries(result.timings).map(([k, v]) => `${k}=${v.toFixed(1)}ms`).join(" ")}`);
|
|
62
100
|
}
|
|
63
101
|
main().catch((e) => { console.error(e); process.exit(1); });
|
|
102
|
+
/**
|
|
103
|
+
* ingress instructions [dir] list instruction files and their approval status
|
|
104
|
+
* ingress instructions approve <dir> <relPath> approve one file's exact bytes (interactive terminal only)
|
|
105
|
+
*/
|
|
106
|
+
async function instructionsCommand(a) {
|
|
107
|
+
if (a[0] === "approve") {
|
|
108
|
+
const [dir, rel] = [a[1], a[2]];
|
|
109
|
+
if (!dir || !rel) {
|
|
110
|
+
console.error("usage: ingress instructions approve <dir> <relative path>");
|
|
111
|
+
process.exit(2);
|
|
112
|
+
}
|
|
113
|
+
if (!process.stdin.isTTY || !process.stdout.isTTY) {
|
|
114
|
+
console.error("refused: approval needs an interactive terminal, typed by a person");
|
|
115
|
+
process.exit(3);
|
|
116
|
+
}
|
|
117
|
+
// read once: what is shown is what gets fingerprinted and approved
|
|
118
|
+
let bytes;
|
|
119
|
+
try {
|
|
120
|
+
bytes = readInstructionBytes(dir, rel);
|
|
121
|
+
}
|
|
122
|
+
catch (e) {
|
|
123
|
+
console.error(e.message);
|
|
124
|
+
process.exit(2);
|
|
125
|
+
}
|
|
126
|
+
const text = bytes.buf.toString("utf8");
|
|
127
|
+
const MAX_SHOWN = 100_000;
|
|
128
|
+
if (bytes.buf.length > MAX_SHOWN) {
|
|
129
|
+
console.error(`refused: ${rel} is ${bytes.buf.length} bytes, more than can be shown for review (${MAX_SHOWN})`);
|
|
130
|
+
process.exit(2);
|
|
131
|
+
}
|
|
132
|
+
const engine = new IngressEngine({ cloakingCheck: false, sandbox: "off" }, { log: () => { } });
|
|
133
|
+
const r = await engine.scan(text, { url: `file:${rel}`, contentType: "text/markdown" });
|
|
134
|
+
// terminal escape sequences and invisible characters are shown, never interpreted
|
|
135
|
+
const shown = text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, (c) => (c === "\n" || c === "\t" ? c : `<U+${c.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}>`));
|
|
136
|
+
const inDep = /(?:^|\/)(?:node_modules|vendor|\.venv|venv|site-packages|third_party)\//.test(rel);
|
|
137
|
+
console.log(`\n${rel} (${bytes.buf.length} bytes, fingerprint ${bytes.sha256.slice(0, 16)})${inDep ? " INSIDE A DEPENDENCY" : ""}`);
|
|
138
|
+
console.log(`gate verdict: ${r.tier}${r.findings.length ? " — " + [...new Set(r.findings.map((x) => x.kind))].join(", ") : ""}`);
|
|
139
|
+
console.log(`\n----- file (complete) -----\n${shown}\n----- end -----\n`);
|
|
140
|
+
let ok = false;
|
|
141
|
+
if (process.platform === "darwin") {
|
|
142
|
+
// confirmation through a native dialog: a pseudo-terminal driven by a program cannot click it
|
|
143
|
+
const answer = await macosDialogApprover({ timeoutSec: 180 }).request({
|
|
144
|
+
id: "instructions", runId: "instructions", tool: `approve instruction file ${rel}`, canonicalArgs: JSON.stringify({ file: rel, bytes: bytes.buf.length, fingerprint: bytes.sha256.slice(0, 16), verdict: r.tier }),
|
|
145
|
+
digest: bytes.sha256, reasons: ["you are approving this exact version as project guidance for coding agents; the full text is in your terminal"], destinations: [], fields: [], sources: [], createdAt: Date.now(), expiresAt: Date.now() + 180_000,
|
|
146
|
+
});
|
|
147
|
+
ok = answer === "approved";
|
|
148
|
+
}
|
|
149
|
+
else {
|
|
150
|
+
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
151
|
+
const typed = (await rl.question(`To approve this exact version, type the first 8 characters of its fingerprint: `)).trim();
|
|
152
|
+
rl.close();
|
|
153
|
+
ok = typed === bytes.sha256.slice(0, 8);
|
|
154
|
+
}
|
|
155
|
+
if (!ok) {
|
|
156
|
+
console.log("not approved");
|
|
157
|
+
process.exit(1);
|
|
158
|
+
}
|
|
159
|
+
try {
|
|
160
|
+
const e = approveInstructionFile(dir, rel, userInfo().username, bytes.sha256);
|
|
161
|
+
console.log(`approved ${rel} at ${e.approvedAt}. Any change to the file needs approval again.`);
|
|
162
|
+
}
|
|
163
|
+
catch (e) {
|
|
164
|
+
console.error(e.message);
|
|
165
|
+
process.exit(1);
|
|
166
|
+
}
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
const dir = a[0] ?? ".";
|
|
170
|
+
const files = checkInstructionFiles(dir);
|
|
171
|
+
if (!files.length) {
|
|
172
|
+
console.log("no instruction files found");
|
|
173
|
+
return;
|
|
174
|
+
}
|
|
175
|
+
for (const f of files)
|
|
176
|
+
console.log(`${f.status.padEnd(9)} ${f.inDependency ? "[dependency] " : ""}${f.relPath} ${f.sha256.slice(0, 12)}`);
|
|
177
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Code behavior pass.
|
|
3
|
+
*
|
|
4
|
+
* Code an agent receives (a fenced block in a README, a <pre> in a page, a script file,
|
|
5
|
+
* a decoded payload) is judged by what it would DO, with comments separated from code
|
|
6
|
+
* and string literals held apart, so "exec" in a comment or a tutorial sentence is not a
|
|
7
|
+
* call. Behaviors: download then execute, encoded payload executed, reverse shell,
|
|
8
|
+
* secrets sent out, persistence. Languages: JavaScript/TypeScript, Python, shell,
|
|
9
|
+
* PowerShell, Go. This is lexical analysis, not data flow: it sees one code unit at a
|
|
10
|
+
* time and does not follow values across files. The coverage report says exactly which
|
|
11
|
+
* units and languages were inspected.
|
|
12
|
+
*
|
|
13
|
+
* Weighting: visible code is documentation and scores low on its own (security posts
|
|
14
|
+
* show reverse shells); hidden or decoded code carries full weight. The supply-chain pass
|
|
15
|
+
* already covers install commands (pipe-to-shell, URL installs); this pass does not
|
|
16
|
+
* double-count those.
|
|
17
|
+
*/
|
|
18
|
+
import type { Finding, TextSegment } from "./types.js";
|
|
19
|
+
export type CodeLang = "javascript" | "python" | "shell" | "powershell" | "go";
|
|
20
|
+
export interface CodeUnit {
|
|
21
|
+
lang: CodeLang | "unknown";
|
|
22
|
+
source: string;
|
|
23
|
+
where: string;
|
|
24
|
+
hidden: boolean;
|
|
25
|
+
}
|
|
26
|
+
export interface CodeCoverage {
|
|
27
|
+
units: number;
|
|
28
|
+
inspected: Partial<Record<CodeLang, number>>;
|
|
29
|
+
/** code-like units whose language could not be told, so not inspected */
|
|
30
|
+
unknown: number;
|
|
31
|
+
/** units over the size limit, skipped */
|
|
32
|
+
skipped: number;
|
|
33
|
+
depth: "lexical";
|
|
34
|
+
}
|
|
35
|
+
export declare function guessLang(src: string): CodeLang | "unknown";
|
|
36
|
+
/** split source into code (comments removed, string literals replaced by STR) and the list of string literals */
|
|
37
|
+
export declare function lex(src: string, lang: CodeLang): {
|
|
38
|
+
code: string;
|
|
39
|
+
strings: string[];
|
|
40
|
+
comments: string;
|
|
41
|
+
};
|
|
42
|
+
/** code units in what the model will receive: fenced blocks, <pre>/<code> text, whole files, decoded payloads */
|
|
43
|
+
export declare function extractCodeUnits(input: {
|
|
44
|
+
kind: string;
|
|
45
|
+
raw: string;
|
|
46
|
+
segments: TextSegment[];
|
|
47
|
+
decodedPayloads: readonly string[];
|
|
48
|
+
}): CodeUnit[];
|
|
49
|
+
export declare function scanCode(input: {
|
|
50
|
+
kind: string;
|
|
51
|
+
raw: string;
|
|
52
|
+
segments: TextSegment[];
|
|
53
|
+
decodedPayloads: readonly string[];
|
|
54
|
+
}): {
|
|
55
|
+
findings: Finding[];
|
|
56
|
+
coverage: CodeCoverage;
|
|
57
|
+
};
|