@acepaste/ingress 0.9.24 → 0.9.26
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/agent-hooks.d.ts +50 -0
- package/dist/src/agent-hooks.js +155 -6
- package/dist/src/blocklist-update.d.ts +57 -0
- package/dist/src/blocklist-update.js +133 -0
- package/dist/src/broker.d.ts +12 -0
- package/dist/src/broker.js +10 -0
- package/dist/src/cli.js +168 -34
- package/dist/src/egress-proxy.d.ts +182 -0
- package/dist/src/egress-proxy.js +567 -0
- package/dist/src/engine.d.ts +13 -0
- package/dist/src/engine.js +71 -16
- package/dist/src/index.d.ts +6 -1
- package/dist/src/index.js +4 -1
- package/dist/src/policyfile.js +2 -0
- package/dist/src/summary.d.ts +2 -0
- package/dist/src/summary.js +4 -0
- package/dist/src/types.d.ts +10 -3
- package/dist/src/types.js +3 -2
- package/package.json +1 -1
|
@@ -22,6 +22,8 @@
|
|
|
22
22
|
* Everything that gates fails closed: if the gate cannot run, the content is withheld with the reason.
|
|
23
23
|
*/
|
|
24
24
|
import { type BurstPolicy } from "./safeguards.js";
|
|
25
|
+
import { type Approver } from "./broker.js";
|
|
26
|
+
import { type ProxyConnection } from "./egress-proxy.js";
|
|
25
27
|
import { Blocklist } from "./egress.js";
|
|
26
28
|
import type { ContentKind, IngressResult, SourceInfo } from "./types.js";
|
|
27
29
|
/** What a hook needs from Ingress: the engine in this process, or the local service over HTTP. */
|
|
@@ -58,6 +60,16 @@ export interface HookOptions {
|
|
|
58
60
|
agent?: string;
|
|
59
61
|
from?: string;
|
|
60
62
|
} | undefined;
|
|
63
|
+
/**
|
|
64
|
+
* The egress proxy is on (INGRESS_EGRESS_PROXY=on): what it logged for a session since a shell command started.
|
|
65
|
+
* A command whose programs connected somewhere has outside content in its output, whatever the command looked like.
|
|
66
|
+
*/
|
|
67
|
+
proxyConnections?: (session: string, toolUseId: string | undefined) => ProxyConnection[];
|
|
68
|
+
/** the egress proxy is on: its port, and the file the harness reads shell variables from (CLAUDE_ENV_FILE at session start) */
|
|
69
|
+
egressProxy?: {
|
|
70
|
+
port: number;
|
|
71
|
+
envFile?: string;
|
|
72
|
+
};
|
|
61
73
|
}
|
|
62
74
|
type Json = Record<string, unknown>;
|
|
63
75
|
export declare function withheld(source: string, why: string): string;
|
|
@@ -107,6 +119,44 @@ export interface EgressHookOptions extends HookOptions {
|
|
|
107
119
|
now?: () => number;
|
|
108
120
|
}
|
|
109
121
|
export declare function preToolUse(event: Json, o?: EgressHookOptions): Json | undefined;
|
|
122
|
+
/**
|
|
123
|
+
* The same decision, with every "ask" put to a person through `approver` before the hook answers
|
|
124
|
+
* (INGRESS_HOOK_APPROVER=macos-presence). The harness's "ask" is a prompt the harness may answer for the
|
|
125
|
+
* person: a mode that approves prompts automatically turns it into "allow". With an approver, the question
|
|
126
|
+
* goes to a channel the model cannot drive (the exact action in a system dialog, then Touch ID or the login
|
|
127
|
+
* password), and only then does the hook answer:
|
|
128
|
+
* approved nothing. The harness's own permission flow carries on as if this hook had no opinion.
|
|
129
|
+
* The hook never says "allow": a person's yes to this question is not a yes to the harness's.
|
|
130
|
+
* anything else (declined, nobody answered, the approver could not run) "deny", with the reason.
|
|
131
|
+
* The outcome is appended to the egress log beside the question (never the arguments).
|
|
132
|
+
*
|
|
133
|
+
* `answerWithinMs`: the hook answers "deny" itself when the person has not answered by then. It must be shorter
|
|
134
|
+
* than the timeout the harness gives the hook: a hook the harness has to kill has said nothing, and the
|
|
135
|
+
* harness would carry on without it.
|
|
136
|
+
*/
|
|
137
|
+
export declare function preToolUseAnswered(event: Json, approver: Approver, o?: EgressHookOptions & {
|
|
138
|
+
answerWithinMs?: number;
|
|
139
|
+
}): Promise<Json | undefined>;
|
|
140
|
+
/**
|
|
141
|
+
* With the egress proxy on, what the pre-tool-use hook does for a shell command after the egress decision
|
|
142
|
+
* (`reply` is that decision's reply; undefined means the gate had no objection, or a person at the machine
|
|
143
|
+
* approved it through the approver):
|
|
144
|
+
* - records when the command started, so the hook that runs after it can ask the proxy what connected meanwhile
|
|
145
|
+
* - records the hosts the command names, when the gate had no objection: what the command starts may connect
|
|
146
|
+
* to them. A command that was refused or put to the harness's prompt grants nothing: a prompt can be
|
|
147
|
+
* declined, and a refused command must not open a door for the next one.
|
|
148
|
+
* - asks, when the command visibly steps around the proxy settings, or the proxy is not running and could
|
|
149
|
+
* not be started (`ensure`)
|
|
150
|
+
* It never rewrites the command. The session's commands were pointed at the proxy when the session started.
|
|
151
|
+
*/
|
|
152
|
+
export declare function egressProxyBefore(event: Json, reply: Json | undefined, o: {
|
|
153
|
+
dir?: string;
|
|
154
|
+
now?: () => number;
|
|
155
|
+
ensure: () => Promise<{
|
|
156
|
+
ok: boolean;
|
|
157
|
+
why?: string;
|
|
158
|
+
}>;
|
|
159
|
+
}): Promise<Json | undefined>;
|
|
110
160
|
/** A gate backed by the Ingress HTTP service, so its receipts and audit trail record what hooks gated. */
|
|
111
161
|
export declare function remoteGate(base: string, key: string, timeoutMs?: number): HookGate;
|
|
112
162
|
export {};
|
package/dist/src/agent-hooks.js
CHANGED
|
@@ -26,7 +26,8 @@ import { execFileSync } from "node:child_process";
|
|
|
26
26
|
import { join } from "node:path";
|
|
27
27
|
import { stateDir } from "./changes.js";
|
|
28
28
|
import { stopReason, canaryNotice } from "./safeguards.js";
|
|
29
|
-
import { ActionBroker } from "./broker.js";
|
|
29
|
+
import { ActionBroker, destinationsIn } from "./broker.js";
|
|
30
|
+
import { noteCommandStart, noteVisibleHosts, proxyEnv, proxySecret, sessionToken } from "./egress-proxy.js";
|
|
30
31
|
import { Blocklist } from "./egress.js";
|
|
31
32
|
import { scanCharacters } from "./character.js";
|
|
32
33
|
import { shellOutputSource, shellWrites, shellUploads } from "./shell-commands.js";
|
|
@@ -88,7 +89,21 @@ async function postToolUseInner(event, gate, o, seen) {
|
|
|
88
89
|
const isMcp = name.startsWith("mcp__") && !gated.some((s) => name.startsWith(`mcp__${s}__`));
|
|
89
90
|
const emit = (out) => ({ hookSpecificOutput: { hookEventName: "PostToolUse", ...out } });
|
|
90
91
|
const cwd = typeof event.cwd === "string" ? event.cwd : undefined;
|
|
91
|
-
|
|
92
|
+
// What the egress proxy saw this command's programs do. A program that connected somewhere brought outside
|
|
93
|
+
// content back, whether or not the command looked like a network command.
|
|
94
|
+
let viaProxy = [];
|
|
95
|
+
if (name === "Bash" && obj && o.proxyConnections) {
|
|
96
|
+
try {
|
|
97
|
+
viaProxy = o.proxyConnections(String(event.session_id ?? ""), typeof event.tool_use_id === "string" ? event.tool_use_id : undefined);
|
|
98
|
+
}
|
|
99
|
+
catch { /* the proxy's log is extra knowledge */ }
|
|
100
|
+
}
|
|
101
|
+
const carried = [...new Set(viaProxy.filter((c) => c.decision === "allow").map((c) => c.host))];
|
|
102
|
+
const proxyNote = proxyNotes(viaProxy);
|
|
103
|
+
const bashSource = name !== "Bash" ? undefined
|
|
104
|
+
: shellOutputSource(String(input.command ?? ""), { cwd, ownPort: o.ownPort })
|
|
105
|
+
?? (carried.length ? `shell:a program that connected to ${carried.slice(0, 3).join(", ")}${carried.length > 3 ? ` and ${carried.length - 3} more` : ""}` : undefined);
|
|
106
|
+
const noted = (out) => (!proxyNote ? out : { hookSpecificOutput: { hookEventName: "PostToolUse", ...(out?.hookSpecificOutput ?? {}), additionalContext: proxyNote } });
|
|
92
107
|
try {
|
|
93
108
|
if (name === "WebFetch" && obj) {
|
|
94
109
|
const url = String(input.url ?? "");
|
|
@@ -123,11 +138,16 @@ async function postToolUseInner(event, gate, o, seen) {
|
|
|
123
138
|
// command output is terminal output: read as a terminal would show it, at open-channel trust
|
|
124
139
|
const text = out + (err ? `\n--- stderr ---\n${err}` : "");
|
|
125
140
|
seen.push({ ref: bashSource });
|
|
141
|
+
for (const h of carried)
|
|
142
|
+
seen.push({ ref: bashSource, host: h }); // where its programs really went joins what the session has contacted
|
|
126
143
|
const env = await refusal(gate, text, bashSource, { kind: "log", source: { channel: "shell command output", trust: 5 } });
|
|
127
144
|
if (!env)
|
|
128
145
|
seen.push({ ref: bashSource, text });
|
|
129
|
-
return env ? emit({ updatedToolOutput: { ...obj, stdout: env, stderr: "" } }) : undefined;
|
|
146
|
+
return noted(env ? emit({ updatedToolOutput: { ...obj, stdout: env, stderr: "" } }) : undefined);
|
|
130
147
|
}
|
|
148
|
+
// nothing came back through the proxy, but it refused something: the model is told why its command failed
|
|
149
|
+
if (name === "Bash" && proxyNote)
|
|
150
|
+
return noted(undefined);
|
|
131
151
|
if (name === "Read" && obj && isTaskOutput(String(input.file_path ?? ""))) {
|
|
132
152
|
const f = obj.file;
|
|
133
153
|
if (!f || typeof f.content !== "string")
|
|
@@ -253,6 +273,19 @@ async function postToolUseInner(event, gate, o, seen) {
|
|
|
253
273
|
}
|
|
254
274
|
return undefined;
|
|
255
275
|
}
|
|
276
|
+
/** What the model is told about connections the egress proxy refused or flagged while a command ran. */
|
|
277
|
+
function proxyNotes(conns) {
|
|
278
|
+
const refused = [...new Map(conns.filter((c) => c.decision === "refuse").map((c) => [`${c.host}:${c.port}`, c])).values()];
|
|
279
|
+
const flags = [...new Set(conns.map((c) => c.flag).filter((f) => typeof f === "string"))];
|
|
280
|
+
if (!refused.length && !flags.length)
|
|
281
|
+
return undefined;
|
|
282
|
+
const parts = [];
|
|
283
|
+
if (refused.length)
|
|
284
|
+
parts.push(`AcePaste Ingress's egress proxy refused ${refused.length === 1 ? "a connection" : `${refused.length} connections`} a program started by this command tried to make: ${refused.slice(0, 4).map((c) => `${c.host}:${c.port} (${c.reason})`).join("; ")}. That is a refusal, not a fault: do not unset the proxy settings or reach the destination another way. Tell the person, who can name the host in their own words or put it on the allowlist.`);
|
|
285
|
+
if (flags.length)
|
|
286
|
+
parts.push(`AcePaste Ingress's egress proxy flagged this command: ${flags.slice(0, 4).join("; ")}. Tell the person.`);
|
|
287
|
+
return parts.join("\n");
|
|
288
|
+
}
|
|
256
289
|
// ---------- UserPromptSubmit: the paste gate ----------
|
|
257
290
|
const PASTED = /<pasted_content id="([^"]*)">\n?([\s\S]*?)\n?<\/pasted_content id="\1">/g;
|
|
258
291
|
/** a person typing this, outside any pasted block, sends the prompt as it is */
|
|
@@ -407,6 +440,20 @@ export function sessionStart(event, o = {}) {
|
|
|
407
440
|
}
|
|
408
441
|
catch { /* without a marker the other checks still run */ }
|
|
409
442
|
}
|
|
443
|
+
// the egress proxy: this session's shell commands are pointed at it, with a token that says whose they are
|
|
444
|
+
if (session && o.egressProxy) {
|
|
445
|
+
try {
|
|
446
|
+
const vars = proxyEnv(o.egressProxy.port, sessionToken(proxySecret(dir), session));
|
|
447
|
+
if (o.egressProxy.envFile) {
|
|
448
|
+
appendFileSync(o.egressProxy.envFile, Object.entries(vars).map(([k, v]) => `export ${k}='${v}'`).join("\n") + "\n");
|
|
449
|
+
notes.push(`Network connections made by shell commands in this session go through AcePaste Ingress's egress proxy on this machine (127.0.0.1:${o.egressProxy.port}), which decides each one by its destination. A connection it refuses fails with "403" from the proxy and the reason. That is a refusal: do not unset the proxy variables or reach the destination another way. Tell the person.`);
|
|
450
|
+
}
|
|
451
|
+
else {
|
|
452
|
+
notes.push("AcePaste Ingress's egress proxy is turned on, but this harness gave the session-start hook no environment file (CLAUDE_ENV_FILE), so this session's shell commands are not routed through it.");
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
catch { /* the other hooks still run */ }
|
|
456
|
+
}
|
|
410
457
|
return notes.length ? { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: notes.join("\n\n") } } : undefined;
|
|
411
458
|
}
|
|
412
459
|
// ---------- what the session has read, carried between hook calls ----------
|
|
@@ -471,6 +518,101 @@ function asAction(name, input) {
|
|
|
471
518
|
return undefined;
|
|
472
519
|
}
|
|
473
520
|
export function preToolUse(event, o = {}) {
|
|
521
|
+
return decideEgress(event, o)?.reply;
|
|
522
|
+
}
|
|
523
|
+
/**
|
|
524
|
+
* The same decision, with every "ask" put to a person through `approver` before the hook answers
|
|
525
|
+
* (INGRESS_HOOK_APPROVER=macos-presence). The harness's "ask" is a prompt the harness may answer for the
|
|
526
|
+
* person: a mode that approves prompts automatically turns it into "allow". With an approver, the question
|
|
527
|
+
* goes to a channel the model cannot drive (the exact action in a system dialog, then Touch ID or the login
|
|
528
|
+
* password), and only then does the hook answer:
|
|
529
|
+
* approved nothing. The harness's own permission flow carries on as if this hook had no opinion.
|
|
530
|
+
* The hook never says "allow": a person's yes to this question is not a yes to the harness's.
|
|
531
|
+
* anything else (declined, nobody answered, the approver could not run) "deny", with the reason.
|
|
532
|
+
* The outcome is appended to the egress log beside the question (never the arguments).
|
|
533
|
+
*
|
|
534
|
+
* `answerWithinMs`: the hook answers "deny" itself when the person has not answered by then. It must be shorter
|
|
535
|
+
* than the timeout the harness gives the hook: a hook the harness has to kill has said nothing, and the
|
|
536
|
+
* harness would carry on without it.
|
|
537
|
+
*/
|
|
538
|
+
export async function preToolUseAnswered(event, approver, o = {}) {
|
|
539
|
+
const d = decideEgress(event, o);
|
|
540
|
+
if (!d?.ask)
|
|
541
|
+
return d?.reply;
|
|
542
|
+
let answer;
|
|
543
|
+
let timer;
|
|
544
|
+
try {
|
|
545
|
+
const asked = approver.request(d.ask);
|
|
546
|
+
answer = o.answerWithinMs === undefined ? await asked : await Promise.race([asked, new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), o.answerWithinMs); })]);
|
|
547
|
+
}
|
|
548
|
+
catch {
|
|
549
|
+
answer = "unavailable";
|
|
550
|
+
}
|
|
551
|
+
finally {
|
|
552
|
+
if (timer)
|
|
553
|
+
clearTimeout(timer);
|
|
554
|
+
}
|
|
555
|
+
if (answer !== "approved" && answer !== "denied" && answer !== "timeout")
|
|
556
|
+
answer = "unavailable";
|
|
557
|
+
try {
|
|
558
|
+
appendFileSync(join(d.dir, "egress-log.jsonl"), JSON.stringify({ at: new Date(o.now?.() ?? Date.now()).toISOString(), session: d.ask.runId, tool: d.ask.tool, decision: "ask", answer, approver: approver.name, action: d.ask.digest }) + "\n", { mode: 0o600 });
|
|
559
|
+
}
|
|
560
|
+
catch { /* the answer stands whether or not it could be recorded */ }
|
|
561
|
+
if (answer === "approved")
|
|
562
|
+
return undefined;
|
|
563
|
+
const how = answer === "denied" ? "A person at this machine was asked and declined" : answer === "timeout" ? "A person at this machine was asked and did not answer" : `It needs a person at this machine to confirm it, and the approval prompt (${approver.name}) could not be shown`;
|
|
564
|
+
return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `AcePaste Ingress: ${d.ask.reasons.join("; ")}. ${how}. This is refused; do not try another route. Tell the person what you wanted to do.` } };
|
|
565
|
+
}
|
|
566
|
+
/** visible ways a command steps around the proxy settings its session was given */
|
|
567
|
+
const PROXY_TAMPER = /(?:^|[\s;&|(])(?:unset\s+(?:-\w+\s+)*(?:https?_proxy|all_proxy|no_proxy|node_use_env_proxy)\b|(?:export\s+)?(?:https?_proxy|all_proxy|no_proxy|node_use_env_proxy)=|env\s+(?:-\w+\s+)*-u\s*(?:https?_proxy|all_proxy)\b)|\s--no-?proxy\b|\s--proxy(?:-server)?[=\s]|\bhttps?\.proxy=/i;
|
|
568
|
+
/**
|
|
569
|
+
* With the egress proxy on, what the pre-tool-use hook does for a shell command after the egress decision
|
|
570
|
+
* (`reply` is that decision's reply; undefined means the gate had no objection, or a person at the machine
|
|
571
|
+
* approved it through the approver):
|
|
572
|
+
* - records when the command started, so the hook that runs after it can ask the proxy what connected meanwhile
|
|
573
|
+
* - records the hosts the command names, when the gate had no objection: what the command starts may connect
|
|
574
|
+
* to them. A command that was refused or put to the harness's prompt grants nothing: a prompt can be
|
|
575
|
+
* declined, and a refused command must not open a door for the next one.
|
|
576
|
+
* - asks, when the command visibly steps around the proxy settings, or the proxy is not running and could
|
|
577
|
+
* not be started (`ensure`)
|
|
578
|
+
* It never rewrites the command. The session's commands were pointed at the proxy when the session started.
|
|
579
|
+
*/
|
|
580
|
+
export async function egressProxyBefore(event, reply, o) {
|
|
581
|
+
if (String(event.tool_name ?? "") !== "Bash")
|
|
582
|
+
return reply;
|
|
583
|
+
const session = String(event.session_id ?? "");
|
|
584
|
+
if (!session)
|
|
585
|
+
return reply;
|
|
586
|
+
const decided = (reply?.hookSpecificOutput?.permissionDecision ?? "");
|
|
587
|
+
if (decided === "deny")
|
|
588
|
+
return reply;
|
|
589
|
+
const dir = o.dir ?? stateDir(), now = o.now?.() ?? Date.now();
|
|
590
|
+
const command = String((event.tool_input ?? {}).command ?? "");
|
|
591
|
+
try {
|
|
592
|
+
noteCommandStart(dir, session, typeof event.tool_use_id === "string" ? event.tool_use_id : "", now);
|
|
593
|
+
}
|
|
594
|
+
catch { /* best effort */ }
|
|
595
|
+
if (reply !== undefined)
|
|
596
|
+
return reply; // already a question: it stands, and grants nothing
|
|
597
|
+
try {
|
|
598
|
+
noteVisibleHosts(dir, session, destinationsIn({ command }).hosts, now);
|
|
599
|
+
}
|
|
600
|
+
catch { /* best effort */ }
|
|
601
|
+
const ask = (why) => {
|
|
602
|
+
try {
|
|
603
|
+
appendFileSync(join(dir, "egress-log.jsonl"), JSON.stringify({ at: new Date(now).toISOString(), session, tool: "Bash", decision: "ask", reasons: [why] }) + "\n", { mode: 0o600 });
|
|
604
|
+
}
|
|
605
|
+
catch { /* the question stands */ }
|
|
606
|
+
return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: `AcePaste Ingress: ${why}.` } };
|
|
607
|
+
};
|
|
608
|
+
if (PROXY_TAMPER.test(command))
|
|
609
|
+
return ask("this command changes or steps around the proxy settings that send its network calls through the egress proxy");
|
|
610
|
+
const up = await o.ensure();
|
|
611
|
+
if (!up.ok)
|
|
612
|
+
return ask(`the egress proxy is not running (${up.why ?? "unknown reason"}), so this command's network calls would fail or go unchecked`);
|
|
613
|
+
return undefined;
|
|
614
|
+
}
|
|
615
|
+
function decideEgress(event, o) {
|
|
474
616
|
const name = String(event.tool_name ?? "");
|
|
475
617
|
const action = asAction(name, (event.tool_input ?? {}));
|
|
476
618
|
const session = String(event.session_id ?? "");
|
|
@@ -500,14 +642,21 @@ export function preToolUse(event, o = {}) {
|
|
|
500
642
|
}
|
|
501
643
|
const say = (permissionDecision) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: `AcePaste Ingress: ${c.reasons.join("; ")}.${permissionDecision === "deny" ? " This is refused, not a question; do not try another route. Tell the person what you wanted to do." : ""}` } });
|
|
502
644
|
if (c.decision === "deny")
|
|
503
|
-
return say("deny");
|
|
645
|
+
return { reply: say("deny"), dir };
|
|
504
646
|
// counted as having run: if the person declines at the prompt the count is one too high, which errs toward asking
|
|
647
|
+
let sources = [];
|
|
505
648
|
try {
|
|
506
649
|
broker.noteRan({ runId: session, tool: action.tool, args: action.args });
|
|
507
|
-
|
|
650
|
+
const run = broker.exportRun(session);
|
|
651
|
+
sources = run.sources;
|
|
652
|
+
saveRun(dir, session, run);
|
|
508
653
|
}
|
|
509
654
|
catch { /* best effort */ }
|
|
510
|
-
|
|
655
|
+
if (c.decision !== "require_approval")
|
|
656
|
+
return { reply: undefined, dir };
|
|
657
|
+
// what a person would be shown if the question goes to them directly: the harness's tool name and exactly what will run
|
|
658
|
+
const ask = { id: c.digest.slice(0, 16), runId: session, tool: name, canonicalArgs: c.canonicalArgs, digest: c.digest, reasons: c.reasons, destinations: c.destinations, fields: c.fields, sources, createdAt: o.now?.() ?? Date.now(), expiresAt: (o.now?.() ?? Date.now()) + 300_000 };
|
|
659
|
+
return { reply: say("ask"), ask, dir };
|
|
511
660
|
}
|
|
512
661
|
// ---------- a gate that talks to the local service ----------
|
|
513
662
|
/** A gate backed by the Ingress HTTP service, so its receipts and audit trail record what hooks gated. */
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keeping the blocklists current.
|
|
3
|
+
*
|
|
4
|
+
* `ingress blocklist update` downloads the free lists. Until 0.9.25 a person had to run it, so an installed
|
|
5
|
+
* gate had an empty list on its first day and a stale one a month later. Now the lists refresh themselves:
|
|
6
|
+
* when the newest downloaded list is more than a day old (or there is none), the session-start hook, the HTTP
|
|
7
|
+
* service and the MCP proxy start the same command as a separate, detached process and carry on. Nothing waits
|
|
8
|
+
* for it and nothing fails because of it. INGRESS_BLOCKLIST_AUTO=off turns that off.
|
|
9
|
+
*
|
|
10
|
+
* Only the addresses in BLOCKLIST_FEEDS are contacted. A download is kept only if it parses as a list: a block
|
|
11
|
+
* page or an error page saved as a list would silently protect nothing.
|
|
12
|
+
*/
|
|
13
|
+
import { BLOCKLIST_FEEDS } from "./egress.js";
|
|
14
|
+
/** lists older than this are refreshed */
|
|
15
|
+
export declare const BLOCKLIST_MAX_AGE_MS: number;
|
|
16
|
+
/** after an attempt, nothing tries again for this long: several sessions starting together refresh once, and a machine without a network does not retry at every session */
|
|
17
|
+
export declare const BLOCKLIST_RETRY_MS: number;
|
|
18
|
+
type Feed = (typeof BLOCKLIST_FEEDS)[number];
|
|
19
|
+
type FetchText = (url: string) => Promise<{
|
|
20
|
+
ok: boolean;
|
|
21
|
+
status: number;
|
|
22
|
+
text: string;
|
|
23
|
+
}>;
|
|
24
|
+
export interface FeedOutcome {
|
|
25
|
+
name: string;
|
|
26
|
+
what: string;
|
|
27
|
+
entries?: number;
|
|
28
|
+
error?: string;
|
|
29
|
+
}
|
|
30
|
+
/** Download each feed into `dir`. A feed that fails, or does not parse as a list, leaves the previous copy in place. */
|
|
31
|
+
export declare function updateBlocklists(dir?: string, o?: {
|
|
32
|
+
feeds?: readonly Feed[];
|
|
33
|
+
fetchText?: FetchText;
|
|
34
|
+
now?: () => number;
|
|
35
|
+
}): Promise<FeedOutcome[]>;
|
|
36
|
+
/** When the newest downloaded list was written, or undefined when none has been. Lists a person added do not count. */
|
|
37
|
+
export declare function blocklistsRefreshedAt(dir?: string, feeds?: readonly Feed[]): number | undefined;
|
|
38
|
+
export declare function blocklistRefreshDue(dir: string, now: number, feeds?: readonly Feed[]): boolean;
|
|
39
|
+
/**
|
|
40
|
+
* One refresh at a time, and not more often than BLOCKLIST_RETRY_MS: the file is created exclusively, so of
|
|
41
|
+
* several processes that find the lists stale at the same moment exactly one gets it. It is never removed; its
|
|
42
|
+
* age is the time since the last attempt.
|
|
43
|
+
*/
|
|
44
|
+
export declare function claimBlocklistRefresh(dir: string, now: number): boolean;
|
|
45
|
+
export type RefreshStart = "started" | "off" | "fresh" | "recently-tried" | "failed";
|
|
46
|
+
/**
|
|
47
|
+
* Start `ingress blocklist update --quiet` as a detached process if the lists are due. Returns at once, and
|
|
48
|
+
* never throws: a refresh that cannot start leaves the lists as they were.
|
|
49
|
+
*/
|
|
50
|
+
export declare function startBlocklistRefresh(o?: {
|
|
51
|
+
dir?: string;
|
|
52
|
+
env?: Record<string, string | undefined>;
|
|
53
|
+
now?: () => number;
|
|
54
|
+
cli?: string;
|
|
55
|
+
spawnImpl?: (command: string, args: string[]) => void;
|
|
56
|
+
}): RefreshStart;
|
|
57
|
+
export {};
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keeping the blocklists current.
|
|
3
|
+
*
|
|
4
|
+
* `ingress blocklist update` downloads the free lists. Until 0.9.25 a person had to run it, so an installed
|
|
5
|
+
* gate had an empty list on its first day and a stale one a month later. Now the lists refresh themselves:
|
|
6
|
+
* when the newest downloaded list is more than a day old (or there is none), the session-start hook, the HTTP
|
|
7
|
+
* service and the MCP proxy start the same command as a separate, detached process and carry on. Nothing waits
|
|
8
|
+
* for it and nothing fails because of it. INGRESS_BLOCKLIST_AUTO=off turns that off.
|
|
9
|
+
*
|
|
10
|
+
* Only the addresses in BLOCKLIST_FEEDS are contacted. A download is kept only if it parses as a list: a block
|
|
11
|
+
* page or an error page saved as a list would silently protect nothing.
|
|
12
|
+
*/
|
|
13
|
+
import { spawn } from "node:child_process";
|
|
14
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
|
|
15
|
+
import { join } from "node:path";
|
|
16
|
+
import { fileURLToPath } from "node:url";
|
|
17
|
+
import { HONEST_USER_AGENT } from "./acquire.js";
|
|
18
|
+
import { stateDir } from "./changes.js";
|
|
19
|
+
import { Blocklist, BLOCKLIST_FEEDS } from "./egress.js";
|
|
20
|
+
/** lists older than this are refreshed */
|
|
21
|
+
export const BLOCKLIST_MAX_AGE_MS = 24 * 3600 * 1000;
|
|
22
|
+
/** after an attempt, nothing tries again for this long: several sessions starting together refresh once, and a machine without a network does not retry at every session */
|
|
23
|
+
export const BLOCKLIST_RETRY_MS = 3600 * 1000;
|
|
24
|
+
const defaultFetch = async (url) => {
|
|
25
|
+
const res = await fetch(url, { signal: AbortSignal.timeout(30_000), redirect: "follow", headers: { "user-agent": HONEST_USER_AGENT } });
|
|
26
|
+
return { ok: res.ok, status: res.status, text: res.ok ? await res.text() : "" };
|
|
27
|
+
};
|
|
28
|
+
/** Download each feed into `dir`. A feed that fails, or does not parse as a list, leaves the previous copy in place. */
|
|
29
|
+
export async function updateBlocklists(dir = join(stateDir(), "blocklists"), o = {}) {
|
|
30
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
31
|
+
const out = [];
|
|
32
|
+
for (const f of o.feeds ?? BLOCKLIST_FEEDS) {
|
|
33
|
+
try {
|
|
34
|
+
const res = await (o.fetchText ?? defaultFetch)(f.url);
|
|
35
|
+
if (!res.ok)
|
|
36
|
+
throw new Error(`HTTP ${res.status}`);
|
|
37
|
+
if (res.text.length > 50_000_000)
|
|
38
|
+
throw new Error("larger than 50 MB");
|
|
39
|
+
const n = new Blocklist().add(res.text, f.name);
|
|
40
|
+
if (n < 5)
|
|
41
|
+
throw new Error(`only ${n} entries parsed; keeping the previous copy`);
|
|
42
|
+
const p = join(dir, `${f.name}.txt`);
|
|
43
|
+
writeFileSync(`${p}.tmp`, `# ${f.what}\n# from ${f.url} on ${new Date(o.now?.() ?? Date.now()).toISOString()} (${f.terms})\n${res.text}`, { mode: 0o600 });
|
|
44
|
+
renameSync(`${p}.tmp`, p);
|
|
45
|
+
out.push({ name: f.name, what: f.what, entries: n });
|
|
46
|
+
}
|
|
47
|
+
catch (e) {
|
|
48
|
+
out.push({ name: f.name, what: f.what, error: e.message ?? String(e) });
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return out;
|
|
52
|
+
}
|
|
53
|
+
/** When the newest downloaded list was written, or undefined when none has been. Lists a person added do not count. */
|
|
54
|
+
export function blocklistsRefreshedAt(dir = join(stateDir(), "blocklists"), feeds = BLOCKLIST_FEEDS) {
|
|
55
|
+
let newest;
|
|
56
|
+
for (const f of feeds) {
|
|
57
|
+
try {
|
|
58
|
+
const t = statSync(join(dir, `${f.name}.txt`)).mtimeMs;
|
|
59
|
+
if (newest === undefined || t > newest)
|
|
60
|
+
newest = t;
|
|
61
|
+
}
|
|
62
|
+
catch { /* not downloaded yet */ }
|
|
63
|
+
}
|
|
64
|
+
return newest;
|
|
65
|
+
}
|
|
66
|
+
export function blocklistRefreshDue(dir, now, feeds = BLOCKLIST_FEEDS) {
|
|
67
|
+
const at = blocklistsRefreshedAt(dir, feeds);
|
|
68
|
+
return at === undefined || now - at > BLOCKLIST_MAX_AGE_MS;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* One refresh at a time, and not more often than BLOCKLIST_RETRY_MS: the file is created exclusively, so of
|
|
72
|
+
* several processes that find the lists stale at the same moment exactly one gets it. It is never removed; its
|
|
73
|
+
* age is the time since the last attempt.
|
|
74
|
+
*/
|
|
75
|
+
export function claimBlocklistRefresh(dir, now) {
|
|
76
|
+
const lock = join(dir, ".refresh-attempt");
|
|
77
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
78
|
+
for (let i = 0; i < 2; i++) {
|
|
79
|
+
try {
|
|
80
|
+
writeFileSync(lock, `${new Date(now).toISOString()} pid ${process.pid}\n`, { flag: "wx", mode: 0o600 });
|
|
81
|
+
return true;
|
|
82
|
+
}
|
|
83
|
+
catch {
|
|
84
|
+
let at;
|
|
85
|
+
try {
|
|
86
|
+
at = Date.parse(readFileSync(lock, "utf8").split(" ")[0]);
|
|
87
|
+
}
|
|
88
|
+
catch {
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
91
|
+
// an unreadable stamp is treated as old: better one extra download than never refreshing again
|
|
92
|
+
if (Number.isFinite(at) && now - at < BLOCKLIST_RETRY_MS)
|
|
93
|
+
return false;
|
|
94
|
+
try {
|
|
95
|
+
unlinkSync(lock);
|
|
96
|
+
}
|
|
97
|
+
catch {
|
|
98
|
+
return false;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return false;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Start `ingress blocklist update --quiet` as a detached process if the lists are due. Returns at once, and
|
|
106
|
+
* never throws: a refresh that cannot start leaves the lists as they were.
|
|
107
|
+
*/
|
|
108
|
+
export function startBlocklistRefresh(o = {}) {
|
|
109
|
+
try {
|
|
110
|
+
const env = o.env ?? process.env;
|
|
111
|
+
if (/^(off|0|false|no)$/i.test(env.INGRESS_BLOCKLIST_AUTO ?? ""))
|
|
112
|
+
return "off";
|
|
113
|
+
const dir = o.dir ?? join(stateDir(), "blocklists");
|
|
114
|
+
const now = o.now?.() ?? Date.now();
|
|
115
|
+
if (!blocklistRefreshDue(dir, now))
|
|
116
|
+
return "fresh";
|
|
117
|
+
if (!claimBlocklistRefresh(dir, now))
|
|
118
|
+
return "recently-tried";
|
|
119
|
+
const cli = o.cli ?? fileURLToPath(new URL("./cli.js", import.meta.url));
|
|
120
|
+
if (!o.spawnImpl && !existsSync(cli))
|
|
121
|
+
return "failed";
|
|
122
|
+
const run = o.spawnImpl ?? ((command, args) => {
|
|
123
|
+
const child = spawn(command, args, { detached: true, stdio: "ignore", env: { ...process.env, INGRESS_BLOCKLIST_AUTO: "off" } });
|
|
124
|
+
child.on("error", () => { });
|
|
125
|
+
child.unref();
|
|
126
|
+
});
|
|
127
|
+
run(process.execPath, [cli, "blocklist", "update", "--quiet"]);
|
|
128
|
+
return "started";
|
|
129
|
+
}
|
|
130
|
+
catch {
|
|
131
|
+
return "failed";
|
|
132
|
+
}
|
|
133
|
+
}
|
package/dist/src/broker.d.ts
CHANGED
|
@@ -243,6 +243,18 @@ export declare class ActionBroker {
|
|
|
243
243
|
sources: string[];
|
|
244
244
|
quarantined: string[];
|
|
245
245
|
};
|
|
246
|
+
/**
|
|
247
|
+
* What this run knows about one destination, for something that sees a connection rather than an action
|
|
248
|
+
* (the egress proxy): is it on the allowlist, did the person name it, and did it first appear in outside
|
|
249
|
+
* content (and where). The same facts `classify` judges an action's destinations with.
|
|
250
|
+
*/
|
|
251
|
+
hostStanding(runId: string, host: string): {
|
|
252
|
+
allowed: boolean;
|
|
253
|
+
typed: boolean;
|
|
254
|
+
fromContent?: string;
|
|
255
|
+
tainted: boolean;
|
|
256
|
+
heardPerson: boolean;
|
|
257
|
+
};
|
|
246
258
|
/** decide without asking anyone (for previews and tests) */
|
|
247
259
|
classify(action: ProposedAction): {
|
|
248
260
|
decision: ActionDecision;
|
package/dist/src/broker.js
CHANGED
|
@@ -345,6 +345,16 @@ export class ActionBroker {
|
|
|
345
345
|
const r = this.run(runId);
|
|
346
346
|
return { tainted: r.sources.size > 0, sources: [...r.sources], quarantined: [...r.quarantined] };
|
|
347
347
|
}
|
|
348
|
+
/**
|
|
349
|
+
* What this run knows about one destination, for something that sees a connection rather than an action
|
|
350
|
+
* (the egress proxy): is it on the allowlist, did the person name it, and did it first appear in outside
|
|
351
|
+
* content (and where). The same facts `classify` judges an action's destinations with.
|
|
352
|
+
*/
|
|
353
|
+
hostStanding(runId, host) {
|
|
354
|
+
const r = this.run(runId);
|
|
355
|
+
const h = host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
|
|
356
|
+
return { allowed: hostAllowed(h, this.policy.allowHosts), typed: typedBy(r, h), fromContent: metIn(r, h), tainted: r.sources.size > 0, heardPerson: r.heardPerson };
|
|
357
|
+
}
|
|
348
358
|
/** decide without asking anyone (for previews and tests) */
|
|
349
359
|
classify(action) {
|
|
350
360
|
const r = this.run(action.runId);
|