@acepaste/ingress 0.8.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.
@@ -0,0 +1,240 @@
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
+ const MAX_UNIT = 200_000;
19
+ const FENCE = /```([A-Za-z0-9_+-]*)[^\n]*\n([\s\S]*?)```/g;
20
+ const TAGS = {
21
+ js: "javascript", javascript: "javascript", jsx: "javascript", ts: "javascript", typescript: "javascript", tsx: "javascript", node: "javascript", mjs: "javascript", cjs: "javascript",
22
+ py: "python", python: "python", python3: "python",
23
+ sh: "shell", bash: "shell", zsh: "shell", shell: "shell", console: "shell", terminal: "shell", fish: "shell",
24
+ ps: "powershell", ps1: "powershell", powershell: "powershell", pwsh: "powershell",
25
+ go: "go", golang: "go",
26
+ };
27
+ export function guessLang(src) {
28
+ const head = src.slice(0, 200);
29
+ if (/^#!.*\b(?:ba|z|k)?sh\b/.test(head))
30
+ return "shell";
31
+ if (/^#!.*\bpython/.test(head))
32
+ return "python";
33
+ if (/^#!.*\bnode\b/.test(head))
34
+ return "javascript";
35
+ if (/^\s*package\s+\w+\s*$/m.test(src) && /\bfunc\s+\w*\s*\(/.test(src))
36
+ return "go";
37
+ if (/\b(?:Invoke-Expression|IEX|New-Object\s+Net\.WebClient|Write-Host|Get-ChildItem|\$env:)/i.test(src))
38
+ return "powershell";
39
+ if (/^\s*(?:>>>\s+)?(?:import\s+[\w.]+|from\s+[\w.]+\s+import|def\s+\w+\s*\(|print\()/m.test(src))
40
+ return "python";
41
+ if (/\b(?:const|let|var)\s+\w+\s*=|\brequire\(|\bfunction\s*\w*\s*\(|=>\s*[{(]|\bawait\s+fetch\(/.test(src))
42
+ return "javascript";
43
+ if (/^\s*(?:\$\s+)?(?:sudo\s+)?(?:curl|wget|echo|export|chmod|cd|cat|nc|bash|sh)\b/m.test(src))
44
+ return "shell";
45
+ return "unknown";
46
+ }
47
+ /** split source into code (comments removed, string literals replaced by STR) and the list of string literals */
48
+ export function lex(src, lang) {
49
+ let code = "", comments = "";
50
+ const strings = [];
51
+ const lineComment = lang === "python" || lang === "shell" || lang === "powershell" ? "#" : "//";
52
+ const block = lang === "javascript" || lang === "go" ? ["/*", "*/"] : lang === "powershell" ? ["<#", "#>"] : null;
53
+ const quotes = lang === "go" ? ['"', "`"] : lang === "javascript" ? ['"', "'", "`"] : ['"', "'"];
54
+ let i = 0;
55
+ const n = src.length;
56
+ while (i < n) {
57
+ if (lang === "python" && (src.startsWith('"""', i) || src.startsWith("'''", i))) {
58
+ const q = src.slice(i, i + 3);
59
+ const end = src.indexOf(q, i + 3);
60
+ const j = end < 0 ? n : end + 3;
61
+ strings.push(src.slice(i + 3, end < 0 ? n : end));
62
+ code += " STR ";
63
+ i = j;
64
+ continue;
65
+ }
66
+ if (block && src.startsWith(block[0], i)) {
67
+ const end = src.indexOf(block[1], i + block[0].length);
68
+ const j = end < 0 ? n : end + block[1].length;
69
+ comments += src.slice(i, j) + "\n";
70
+ code += " ";
71
+ i = j;
72
+ continue;
73
+ }
74
+ // shell: "#" starts a comment only at a word boundary (not in ${#var} or a URL fragment)
75
+ if (src.startsWith(lineComment, i) && (lineComment !== "#" || i === 0 || /\s/.test(src[i - 1]))) {
76
+ const end = src.indexOf("\n", i);
77
+ const j = end < 0 ? n : end;
78
+ comments += src.slice(i, j) + "\n";
79
+ i = j;
80
+ continue;
81
+ }
82
+ const c = src[i];
83
+ if (quotes.includes(c)) {
84
+ let j = i + 1, s = "";
85
+ while (j < n && src[j] !== c) {
86
+ if (src[j] === "\\" && j + 1 < n && !(lang === "shell" && c === "'")) {
87
+ s += src[j + 1];
88
+ j += 2;
89
+ continue;
90
+ }
91
+ if (src[j] === "\n" && c !== "`" && lang !== "shell")
92
+ break;
93
+ s += src[j];
94
+ j++;
95
+ }
96
+ strings.push(s);
97
+ code += ` STR `;
98
+ i = j + 1;
99
+ // shell strings are still commands when evaluated; keep their text in the code view too
100
+ if (lang === "shell")
101
+ code += ` ${s} `;
102
+ continue;
103
+ }
104
+ code += c;
105
+ i++;
106
+ }
107
+ return { code, strings, comments };
108
+ }
109
+ const PIPE_TO_INTERPRETER = /\b(?:curl|wget|iwr|Invoke-WebRequest)\b[^|\n]*\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b|\b(?:curl|wget)\b[^|\n]*\|\s*(?:python3?|node|perl|ruby)\b/i;
110
+ const SECRET_PATHS = /(?:~|\$HOME|\/home\/\w+|\/Users\/\w+|%USERPROFILE%|\$env:USERPROFILE)[\\/](?:\.ssh[\\/]|\.aws[\\/]credentials|\.npmrc|\.netrc|\.docker[\\/]config\.json|\.kube[\\/]config|\.config[\\/]gcloud|\.gnupg)|\bid_(?:rsa|ed25519)\b|\/etc\/shadow/i;
111
+ const SECRET_ENV = /(?:process\.env\.?|os\.environ|os\.Getenv\(?|os\.getenv\(?|\$env:|\$\{?)(?:\[?["']?)?(?:AWS_SECRET_ACCESS_KEY|AWS_ACCESS_KEY_ID|GITHUB_TOKEN|GH_TOKEN|NPM_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|SLACK_TOKEN|STRIPE_SECRET_KEY|DATABASE_URL|[A-Z_]*(?:SECRET|TOKEN|PASSWORD|API_KEY))\b/;
112
+ const NETWORK_OUT = {
113
+ javascript: /\b(?:fetch|axios(?:\.\w+)?|https?\.request|XMLHttpRequest|navigator\.sendBeacon|got|request)\s*\(/,
114
+ python: /\b(?:requests\.(?:post|put|get)|urllib\.request\.urlopen|httpx\.(?:post|put|get)|http\.client|socket\.socket|smtplib)\b/,
115
+ shell: /\b(?:curl|wget|nc|ncat|scp|rsync|ftp)\b/,
116
+ powershell: /\b(?:Invoke-WebRequest|Invoke-RestMethod|iwr|irm|Net\.WebClient|UploadString|UploadFile)\b/i,
117
+ go: /\bhttp\.(?:Post|Get|NewRequest|PostForm)\b|\bnet\.Dial\b/,
118
+ };
119
+ function behaviors(lang, src) {
120
+ const { code, strings } = lex(src, lang);
121
+ const strs = strings.join("\n");
122
+ const hits = [];
123
+ const add = (kind, what, strength = 1) => { if (!hits.some((h) => h.kind === kind))
124
+ hits.push({ kind, what, strength }); };
125
+ if (lang === "python") {
126
+ if (/\b(?:exec|eval)\s*\(\s*(?:requests\.get|urllib\.request\.urlopen|httpx\.get|urlopen)\s*\(/.test(code) || (/\b(?:exec|eval)\s*\(/.test(code) && /\.(?:text|content|read\(\))/.test(code) && /\b(?:requests|urllib|httpx)\b/.test(code)))
127
+ add("code.download_execute", "Python runs code it downloads (exec/eval of a fetched response)");
128
+ if (/\b(?:exec|eval)\s*\(\s*(?:base64\.b64decode|codecs\.decode|bytes\.fromhex|zlib\.decompress|marshal\.loads)/.test(code))
129
+ add("code.encoded_execution", "Python decodes and executes a hidden payload");
130
+ if (/\bsocket\.socket\b/.test(code) && /\b(?:os\.dup2|subprocess\.(?:call|Popen|run))\b/.test(code) && /\bconnect\s*\(/.test(code))
131
+ add("code.reverse_shell", "Python reverse shell (socket connected back, process attached to it)");
132
+ if (/\b(?:os\.system|subprocess\.(?:call|run|Popen|check_output))\s*\(/.test(code) && PIPE_TO_INTERPRETER.test(strs))
133
+ add("code.download_execute", "Python shells out to download-and-run");
134
+ }
135
+ if (lang === "javascript") {
136
+ if (/\b(?:eval|new\s+Function|Function)\s*\(/.test(code) && /\b(?:fetch|axios|https?\.get|request)\b/.test(code) && /\.(?:text|data)\b|\bres(?:ponse)?\b/.test(code))
137
+ add("code.download_execute", "JavaScript evaluates code it downloads (eval/new Function on a fetched response)");
138
+ if (/\b(?:eval|new\s+Function)\s*\(\s*(?:atob|Buffer\.from)\s*\(/.test(code))
139
+ add("code.encoded_execution", "JavaScript decodes and evaluates a hidden payload");
140
+ if (/\bchild_process\b|\b(?:exec|execSync|spawn|spawnSync)\s*\(/.test(code) && PIPE_TO_INTERPRETER.test(strs))
141
+ add("code.download_execute", "Node shells out to download-and-run");
142
+ if (/\bnet\.(?:connect|Socket)\b|\bnew\s+net\.Socket\b/.test(code) && /\b(?:spawn|exec)\s*\(\s*STR/.test(code) && /(?:\/bin\/(?:ba)?sh|cmd\.exe)\b/.test(strs))
143
+ add("code.reverse_shell", "Node reverse shell (socket piped to a shell)");
144
+ }
145
+ if (lang === "shell") {
146
+ if (/\/dev\/tcp\/[^\s/]+\/\d+/.test(code) || /\b(?:nc|ncat|netcat)\b[^\n]*\s-(?:e|c)\s/.test(code) || /\bbash\s+-i\b[^\n]*>&/.test(code) || /\bmkfifo\b[^\n]*\|\s*(?:nc|ncat)\b/.test(code))
147
+ add("code.reverse_shell", "shell reverse shell (interactive shell connected to a remote host)");
148
+ if (/\bbase64\s+(?:-d|--decode|-D)\b[^\n]*\|\s*(?:sudo\s+)?(?:ba|z)?sh\b|\becho\s+[A-Za-z0-9+/=]{40,}\s*\|\s*base64\s+(?:-d|--decode)/.test(code))
149
+ add("code.encoded_execution", "shell decodes base64 and runs it");
150
+ if (/\b(?:crontab\s+-|launchctl\s+(?:load|bootstrap)|systemctl\s+enable)\b/.test(code) || /(?:>>|tee\s+-a)\s*~?\/?[^\s]*(?:\.bashrc|\.zshrc|\.profile|\.bash_profile)\b/.test(code) && NETWORK_OUT.shell.test(code))
151
+ add("code.persistence", "shell sets up persistence (cron, launch agent, service, shell profile)", 0.8);
152
+ }
153
+ if (lang === "powershell") {
154
+ if (/\b(?:IEX|Invoke-Expression)\b[^\n]*(?:DownloadString|Invoke-WebRequest|iwr|irm|Invoke-RestMethod)/i.test(code) || /(?:DownloadString|irm|iwr)[^\n]*\|\s*(?:IEX|Invoke-Expression)\b/i.test(code))
155
+ add("code.download_execute", "PowerShell downloads and runs a script (IEX of a download)");
156
+ if (/-(?:e|enc|EncodedCommand)\s+[A-Za-z0-9+/=]{40,}/i.test(src) || /FromBase64String[^\n]*(?:IEX|Invoke-Expression)|(?:IEX|Invoke-Expression)[^\n]*FromBase64String/i.test(code))
157
+ add("code.encoded_execution", "PowerShell runs an encoded command");
158
+ }
159
+ if (lang === "go") {
160
+ if (/\bexec\.Command\s*\(/.test(code) && /\bhttp\.Get\b/.test(code) && /\b(?:sh|bash)\b/.test(strs))
161
+ add("code.download_execute", "Go fetches and runs a shell command");
162
+ if (/\bnet\.Dial\b/.test(code) && /\bexec\.Command\b/.test(code) && /\/bin\/(?:ba)?sh/.test(strs))
163
+ add("code.reverse_shell", "Go reverse shell (connection attached to a shell)");
164
+ }
165
+ // any language: a secret read and a network send in the same unit
166
+ const readsSecret = SECRET_PATHS.test(src) || SECRET_ENV.test(code) || SECRET_ENV.test(src);
167
+ if (readsSecret && NETWORK_OUT[lang].test(code))
168
+ add("code.secret_exfiltration", "reads credentials (key files, cloud or API tokens) and sends data over the network", 1);
169
+ return hits;
170
+ }
171
+ /** code units in what the model will receive: fenced blocks, <pre>/<code> text, whole files, decoded payloads */
172
+ export function extractCodeUnits(input) {
173
+ const units = [];
174
+ if (input.kind === "javascript")
175
+ units.push({ lang: "javascript", source: input.raw, where: "file", hidden: false });
176
+ // syntax highlighting splits one <pre> block into many text nodes: join consecutive nodes of the same block
177
+ const merged = [];
178
+ const blockOf = (path) => { const i = path.search(/\/pre(?:\/|$|\[)/i); return i < 0 ? null : path.slice(0, i + 4); };
179
+ for (const s of input.segments) {
180
+ const k = blockOf(s.path);
181
+ const last = merged[merged.length - 1];
182
+ if (k && last && blockOf(last.path) === k && last.visibility === s.visibility) {
183
+ merged[merged.length - 1] = { ...last, text: last.text + s.text };
184
+ continue;
185
+ }
186
+ merged.push(s);
187
+ }
188
+ for (const s of merged) {
189
+ const hidden = !(s.visibility === "visible");
190
+ for (const m of s.text.matchAll(FENCE)) {
191
+ const tag = m[1].toLowerCase();
192
+ units.push({ lang: TAGS[tag] ?? guessLang(m[2]), source: m[2], where: `${s.path} (fenced ${tag || "block"})`, hidden });
193
+ }
194
+ // a <pre> block, or a multi-line <code>; inline <code> spans are words in a sentence, not programs
195
+ const isBlock = /\/pre(?:\/|$|\[)/i.test(s.path) || (/\/code(?:\/|$|\[)/i.test(s.path) && s.text.includes("\n") && s.text.length >= 40);
196
+ if (isBlock || /^#!/.test(s.text))
197
+ units.push({ lang: guessLang(s.text), source: s.text, where: s.path, hidden });
198
+ else if (hidden && s.text.length > 30 && guessLang(s.text) !== "unknown" && !s.text.includes("```"))
199
+ units.push({ lang: guessLang(s.text), source: s.text, where: s.path, hidden });
200
+ }
201
+ if (input.kind === "text" && /^#!/.test(input.raw))
202
+ units.push({ lang: guessLang(input.raw), source: input.raw, where: "file", hidden: false });
203
+ for (const p of input.decodedPayloads) {
204
+ const l = guessLang(p);
205
+ if (l !== "unknown")
206
+ units.push({ lang: l, source: p, where: "decoded payload", hidden: true });
207
+ }
208
+ return units;
209
+ }
210
+ export function scanCode(input) {
211
+ const units = extractCodeUnits(input);
212
+ const coverage = { units: units.length, inspected: {}, unknown: 0, skipped: 0, depth: "lexical" };
213
+ const findings = [];
214
+ const seen = new Set();
215
+ for (const u of units) {
216
+ if (u.source.length > MAX_UNIT) {
217
+ coverage.skipped++;
218
+ continue;
219
+ }
220
+ if (u.lang === "unknown") {
221
+ coverage.unknown++;
222
+ continue;
223
+ }
224
+ coverage.inspected[u.lang] = (coverage.inspected[u.lang] ?? 0) + 1;
225
+ for (const h of behaviors(u.lang, u.source)) {
226
+ const key = `${h.kind}|${u.where}`;
227
+ if (seen.has(key))
228
+ continue;
229
+ seen.add(key);
230
+ findings.push({
231
+ pass: "code", kind: h.kind,
232
+ // visible code is documentation (cheat sheets, security posts): recorded, far below a refusal on its own
233
+ confidence: (u.hidden ? 0.85 : 0.2) * h.strength, severity: u.hidden ? 0.9 : 0.4,
234
+ message: `${h.what} (${u.lang}${u.hidden ? ", in code a human would not see" : ", visible code: documentation unless other evidence"})`,
235
+ excerpt: u.source.replace(/\s+/g, " ").slice(0, 120), location: u.where, inHidden: u.hidden, action: "none",
236
+ });
237
+ }
238
+ }
239
+ return { findings, coverage };
240
+ }
@@ -17,6 +17,14 @@ import { type Finding, type IngressConfig, type IngressResult, type TaintReceipt
17
17
  export interface IngressOptions {
18
18
  /** human explicitly asked for a suspect page anyway; delivers neutralized text. Never applies to hostile. */
19
19
  override?: boolean;
20
+ /**
21
+ * the caller's own quarantine: refuse this source without fetching it. Logged as
22
+ * ingress.quarantined, never as an attack verdict, so a customer's list never reaches
23
+ * the public feed.
24
+ */
25
+ quarantined?: string;
26
+ /** the caller's quarantine as a test, also applied to every redirect hop and the final URL */
27
+ quarantineCheck?: (url: string) => string | undefined;
20
28
  }
21
29
  export interface EngineDeps {
22
30
  fetchImpl?: FetchLike;
@@ -34,6 +42,23 @@ export interface EngineDeps {
34
42
  /** delay between the two fetches (tests skip it) */
35
43
  sleep?: (ms: number) => Promise<void>;
36
44
  }
45
+ export declare const ASSEMBLED_LIMITS: {
46
+ readonly fragments: 32;
47
+ readonly fragmentBytes: 64000;
48
+ readonly assembledBytes: 256000;
49
+ };
50
+ export interface AssembledResult {
51
+ /** worst of every fragment and the combination */
52
+ tier: Tier;
53
+ /** the combination is worse than each fragment alone: a split instruction */
54
+ composedOnly: boolean;
55
+ fragments: IngressResult[];
56
+ assembled: IngressResult;
57
+ /** digest of the exact combined text; send this text, unaltered, as the external-data block */
58
+ sha256: string;
59
+ /** the combined text when everything is clean, else "" */
60
+ delivered: string;
61
+ }
37
62
  export declare class IngressEngine {
38
63
  readonly config: IngressConfig;
39
64
  private cache;
@@ -48,6 +73,19 @@ export declare class IngressEngine {
48
73
  isHtml?: boolean;
49
74
  contentType?: string;
50
75
  }): Promise<IngressResult>;
76
+ /**
77
+ * Gate what the model will actually receive when several sources are combined (search
78
+ * results, retrieved chunks, several tool results). An instruction can be split so each
79
+ * fragment looks harmless alone: each fragment is gated, then the text that would be
80
+ * delivered from all of them together is gated as one. `composedOnly` is true when the
81
+ * combination is worse than every fragment on its own.
82
+ */
83
+ scanAssembled(fragments: ReadonlyArray<{
84
+ sourceId: string;
85
+ text: string;
86
+ isHtml?: boolean;
87
+ contentType?: string;
88
+ }>): Promise<AssembledResult>;
51
89
  /** Any analysis failure is a refusal, never a pass: the gate fails closed. */
52
90
  private guarded;
53
91
  /** Cheap structural pre-check: pathological nesting makes the HTML parser super-linear. Refuse before parsing. */
@@ -18,12 +18,14 @@ import { countHostileInvisibles } from "./acepaste-alphabet.js";
18
18
  import { analyzeScripts } from "./script.js";
19
19
  import { scanMeaning, neutralizeMeaning } from "./meaning.js";
20
20
  import { scanSupplyChain } from "./supplychain.js";
21
+ import { scanCode } from "./codepass.js";
21
22
  import { scanSecrets, redactSecrets, collectSecrets, scrubExcerpt } from "./secrets.js";
22
23
  import { attachEvidence } from "./evidence.js";
23
24
  import { adaptJavascript, adaptJson, adaptMarkdown, adaptText, decodeEntities, detectKind } from "./adapters.js";
24
25
  import { runSandbox } from "./sandbox.js";
25
26
  import { DEFAULT_CONFIG, ENGINE_VERSION, RULESET_VERSION, } from "./types.js";
26
27
  const sha256 = (s) => createHash("sha256").update(s, "utf8").digest("hex");
28
+ export const ASSEMBLED_LIMITS = { fragments: 32, fragmentBytes: 64_000, assembledBytes: 256_000 };
27
29
  export class IngressEngine {
28
30
  config;
29
31
  cache = new Map();
@@ -58,6 +60,9 @@ export class IngressEngine {
58
60
  async fetch(url, opts = {}) {
59
61
  const t0 = performance.now();
60
62
  const timings = {};
63
+ const preQ = opts.quarantined ?? opts.quarantineCheck?.(url);
64
+ if (preQ)
65
+ return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `source is quarantined by your organization: ${preQ}`, action: "none" }], timings, t0, "text", "hostile", true);
61
66
  const cached = this.cacheGet(url, opts);
62
67
  if (cached)
63
68
  return cached;
@@ -111,6 +116,13 @@ export class IngressEngine {
111
116
  }
112
117
  timings.acquire = performance.now() - ta;
113
118
  }
119
+ if (opts.quarantineCheck) {
120
+ for (const hop of [...agentRes.redirectChain, agentRes.finalUrl]) {
121
+ const q = opts.quarantineCheck(hop);
122
+ if (q)
123
+ return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `redirected to a source quarantined by your organization: ${q}`, action: "none" }], timings, t0, "text", "hostile", true);
124
+ }
125
+ }
114
126
  if (agentRes.redirectChain.length) {
115
127
  const hosts = new Set(agentRes.redirectChain.concat(agentRes.finalUrl).map(hostOf));
116
128
  if (hosts.size > 2)
@@ -159,6 +171,8 @@ export class IngressEngine {
159
171
  async scan(content, opts = {}) {
160
172
  const t0 = performance.now();
161
173
  const url = opts.url ?? "inline:";
174
+ if (opts.quarantined)
175
+ return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `source is quarantined by your organization: ${opts.quarantined}`, action: "none" }], {}, t0, "text", "hostile", true);
162
176
  const bytes = Buffer.byteLength(content, "utf8");
163
177
  if (bytes > this.config.maxBodyBytes) {
164
178
  return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 0.5, severity: 0.5, message: `content is ${bytes} bytes, over the ${this.config.maxBodyBytes} byte limit`, action: "none" }], {}, t0, "text");
@@ -167,6 +181,35 @@ export class IngressEngine {
167
181
  const rule = url.startsWith("inline:") ? undefined : this.domainRule(url);
168
182
  return this.guarded(url, kind, t0, () => this.analyze({ url, finalUrl: url, redirectChain: [], raw: content, kind, externalRules: [], timings: {}, t0, override: !!opts.override, extraFindings: [], rule }));
169
183
  }
184
+ /**
185
+ * Gate what the model will actually receive when several sources are combined (search
186
+ * results, retrieved chunks, several tool results). An instruction can be split so each
187
+ * fragment looks harmless alone: each fragment is gated, then the text that would be
188
+ * delivered from all of them together is gated as one. `composedOnly` is true when the
189
+ * combination is worse than every fragment on its own.
190
+ */
191
+ async scanAssembled(fragments) {
192
+ if (!fragments.length || fragments.length > ASSEMBLED_LIMITS.fragments)
193
+ throw new Error(`scanAssembled: between 1 and ${ASSEMBLED_LIMITS.fragments} fragments`);
194
+ for (const f of fragments) {
195
+ if (!f.sourceId || Buffer.byteLength(f.sourceId, "utf8") > 256)
196
+ throw new Error("scanAssembled: each fragment needs a sourceId of at most 256 bytes");
197
+ if (Buffer.byteLength(f.text, "utf8") > ASSEMBLED_LIMITS.fragmentBytes)
198
+ throw new Error(`scanAssembled: fragment ${f.sourceId} is over ${ASSEMBLED_LIMITS.fragmentBytes} bytes`);
199
+ }
200
+ const results = [];
201
+ for (const f of fragments)
202
+ results.push(await this.scan(f.text, { url: `inline:${f.sourceId}`, isHtml: f.isHtml, contentType: f.contentType }));
203
+ // the combined representation: what each clean fragment would deliver, joined in order
204
+ const joined = results.filter((r) => r.tier === "clean").map((r) => r.delivered).join("\n");
205
+ if (Buffer.byteLength(joined, "utf8") > ASSEMBLED_LIMITS.assembledBytes)
206
+ throw new Error(`scanAssembled: combined text is over ${ASSEMBLED_LIMITS.assembledBytes} bytes`);
207
+ const assembled = await this.scan(joined, { url: "inline:assembled", isHtml: false });
208
+ const rank = (t) => ({ clean: 0, unreachable: 0, suspect: 1, hostile: 2 })[t];
209
+ const worstFragment = results.reduce((m, r) => Math.max(m, rank(r.tier)), 0);
210
+ const tier = ["clean", "suspect", "hostile"][Math.max(worstFragment, rank(assembled.tier))];
211
+ return { tier, composedOnly: rank(assembled.tier) > worstFragment, fragments: results, assembled, sha256: sha256(joined), delivered: tier === "clean" ? joined : "" };
212
+ }
170
213
  /** Any analysis failure is a refusal, never a pass: the gate fails closed. */
171
214
  async guarded(url, kind, t0, run) {
172
215
  try {
@@ -319,10 +362,16 @@ export class IngressEngine {
319
362
  }
320
363
  // supply-chain pass (underlight lineage): manifests, lockfiles, install commands
321
364
  const tsc = performance.now();
322
- const sc = scanSupplyChain({ kind: a.kind, raw, segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads });
365
+ const sc = scanSupplyChain({ kind: a.kind, raw, segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads, pageHost: a.finalUrl.startsWith("inline:") ? undefined : hostOf(a.finalUrl) });
323
366
  findings.push(...sc);
324
367
  timings.supplychain = performance.now() - tsc;
325
368
  passesRun.push("supplychain");
369
+ // code behavior pass: what code the model receives would do
370
+ const tcode = performance.now();
371
+ const codeScan = scanCode({ kind: a.kind, raw, segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads });
372
+ findings.push(...codeScan.findings);
373
+ timings.code = performance.now() - tcode;
374
+ passesRun.push("code");
326
375
  // meaning pass over cleaned segments and decoded payloads
327
376
  const tm = performance.now();
328
377
  findings.push(...scanMeaning({ segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads }));
@@ -378,7 +427,7 @@ export class IngressEngine {
378
427
  timings.total = performance.now() - a.t0;
379
428
  if (tier !== "clean")
380
429
  this.deps.log(buildLogEntry(a.finalUrl, tier, score, findings, safePayloads, receipt, overridden));
381
- return { tier, score, contentKind: a.kind, delivered, envelope, findings, receipt, timings, overridden };
430
+ return { tier, score, contentKind: a.kind, delivered, envelope, findings, receipt, timings, overridden, coverage: { code: codeScan.coverage } };
382
431
  }
383
432
  async fetchStylesheets(html, baseUrl) {
384
433
  const rules = [];
@@ -420,14 +469,16 @@ export class IngressEngine {
420
469
  return p.startsWith(".") ? host === p.slice(1) || host.endsWith(p) : host === p;
421
470
  });
422
471
  }
423
- refuse(url, findings, timings, t0, kind, tier = "hostile") {
472
+ refuse(url, findings, timings, t0, kind, tier = "hostile", quarantine = false) {
424
473
  attachEvidence(findings, sha256(""));
425
474
  const score = tier === "hostile" ? 1 : 0;
426
475
  const receipt = this.receipt({ url, finalUrl: url, redirectChain: [], kind, raw: "", delivered: "", tier, score, findings, overridden: false, passesRun: tier === "hostile" ? ["policy"] : ["acquire"], acepasteInvisibleCount: 0 });
427
476
  const envelope = buildEnvelope(url, tier, "", findings, receipt, false);
428
477
  timings.total = performance.now() - t0;
429
478
  // unreachable is not an attack: it goes to the operational log, never to the attack log or public feed
430
- if (tier === "hostile")
479
+ if (quarantine)
480
+ this.deps.log({ event: "ingress.quarantined", at: this.deps.now().toISOString(), url });
481
+ else if (tier === "hostile")
431
482
  this.deps.log(buildLogEntry(url, "hostile", 1, findings, [], receipt, false));
432
483
  else
433
484
  this.deps.log({ event: "ingress.unreachable", at: this.deps.now().toISOString(), url, reason: findings[0]?.message ?? "" });
@@ -1,5 +1,6 @@
1
1
  export { IngressEngine, aggregate, buildEnvelope, buildLogEntry, compareServed, servedWords, VISIBILITY_ONLY_CAP } from "./engine.js";
2
- export type { EngineDeps, IngressOptions } from "./engine.js";
2
+ export type { EngineDeps, IngressOptions, AssembledResult } from "./engine.js";
3
+ export { ASSEMBLED_LIMITS } from "./engine.js";
3
4
  export { acquire, acquireWithBrowser, AcquireError, MAX_REDIRECTS, HONEST_USER_AGENT } from "./acquire.js";
4
5
  export type { FetchLike, AcquireOptions } from "./acquire.js";
5
6
  export { summarize, findingWeight, cloakingConfigFromEnv } from "./summary.js";
@@ -26,3 +27,14 @@ export { countHostileInvisibles, ACEPASTE_INVISIBLE_SOURCE, ACEPASTE_INVISIBLE_S
26
27
  export * from "./types.js";
27
28
  /** @deprecated renamed to IngressEngine in 0.7.0 (AcePaste Gate -> AcePaste Ingress) */
28
29
  export { IngressEngine as GateEngine } from "./engine.js";
30
+ export { ActionBroker, isSideEffectName, DEFAULT_BROKER_POLICY, canonicalJson, actionDigest, destinationsIn, exfilShapes, describeApproval } from "./broker.js";
31
+ export type { ActionDecision, ActionRule, BrokerPolicy, ProposedAction, ApprovalRequest, Approver, BrokerVerdict, BrokerEvent } from "./broker.js";
32
+ export { macosDialogApprover, callbackApprover, denyAllApprover } from "./approvers.js";
33
+ export { scanMultilingual, MULTILINGUAL_RULES, MULTILINGUAL_RULESET } from "./multilingual.js";
34
+ export { scanCode, extractCodeUnits, guessLang, lex } from "./codepass.js";
35
+ export type { CodeUnit, CodeLang, CodeCoverage } from "./codepass.js";
36
+ export { INSTRUCTION_FILE_PATTERNS, discoverInstructionFiles, readInstructionBytes, approveInstructionFile, checkInstructionFiles, loadInstructionFiles } from "./instructions.js";
37
+ export type { InstructionFile, InstructionCheck, InstructionStatus, ApprovalEntry } from "./instructions.js";
38
+ export { auditEnvironment, formatAudit, readChromiumExtensions } from "./audit.js";
39
+ export type { AuditReport, AuditCheck, AuditOptions } from "./audit.js";
40
+ export * from "./audit-parsers.js";
package/dist/src/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { IngressEngine, aggregate, buildEnvelope, buildLogEntry, compareServed, servedWords, VISIBILITY_ONLY_CAP } from "./engine.js";
2
+ export { ASSEMBLED_LIMITS } from "./engine.js";
2
3
  export { acquire, acquireWithBrowser, AcquireError, MAX_REDIRECTS, HONEST_USER_AGENT } from "./acquire.js";
3
4
  export { summarize, findingWeight, cloakingConfigFromEnv } from "./summary.js";
4
5
  export { checkTarget, isPrivateIP, isPrivateIPv4, isPrivateIPv6, NetPolicyError, DEFAULT_NET_POLICY } from "./netpolicy.js";
@@ -18,3 +19,10 @@ export { countHostileInvisibles, ACEPASTE_INVISIBLE_SOURCE, ACEPASTE_INVISIBLE_S
18
19
  export * from "./types.js";
19
20
  /** @deprecated renamed to IngressEngine in 0.7.0 (AcePaste Gate -> AcePaste Ingress) */
20
21
  export { IngressEngine as GateEngine } from "./engine.js";
22
+ export { ActionBroker, isSideEffectName, DEFAULT_BROKER_POLICY, canonicalJson, actionDigest, destinationsIn, exfilShapes, describeApproval } from "./broker.js";
23
+ export { macosDialogApprover, callbackApprover, denyAllApprover } from "./approvers.js";
24
+ export { scanMultilingual, MULTILINGUAL_RULES, MULTILINGUAL_RULESET } from "./multilingual.js";
25
+ export { scanCode, extractCodeUnits, guessLang, lex } from "./codepass.js";
26
+ export { INSTRUCTION_FILE_PATTERNS, discoverInstructionFiles, readInstructionBytes, approveInstructionFile, checkInstructionFiles, loadInstructionFiles } from "./instructions.js";
27
+ export { auditEnvironment, formatAudit, readChromiumExtensions } from "./audit.js";
28
+ export * from "./audit-parsers.js";
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Instruction-file approval for coding agents.
3
+ *
4
+ * Reading a repository's AGENTS.md to understand a project is one decision; obeying it as
5
+ * guidance is another. A dependency, a pull request or a compromised script can write one.
6
+ * This module finds the files coding agents load as instructions, and serves a file as
7
+ * guidance only when its exact bytes match a version a person approved. Anything else is
8
+ * handed over as untrusted data, gated like web content.
9
+ *
10
+ * Approvals live outside the repository (~/.acepaste-ingress/instruction-approvals.json),
11
+ * each one signed with a local key, and are made only from an interactive terminal
12
+ * (`ingress instructions approve`), never by a tool the model can call.
13
+ *
14
+ * Limits: this is enforcement only where the agent loads instructions through it (the MCP
15
+ * tool, a hook, a wrapper). An agent runtime that reads CLAUDE.md or AGENTS.md natively
16
+ * bypasses it; turn native loading off where the runtime allows. Code running as the same
17
+ * user can read the key and forge approvals. Approval means "this version may be used as
18
+ * project guidance", never "every instruction in it is authorized": tool permissions are
19
+ * still the broker's job.
20
+ */
21
+ /** file names and paths coding agents load as instructions (as of 2026-11) */
22
+ export declare const INSTRUCTION_FILE_PATTERNS: RegExp[];
23
+ export interface InstructionFile {
24
+ relPath: string;
25
+ absPath: string;
26
+ bytes: number;
27
+ sha256: string;
28
+ inDependency: boolean;
29
+ }
30
+ /** walk a repository for instruction files. Dependencies (node_modules, vendor, .venv) are searched too, and marked. */
31
+ export declare function discoverInstructionFiles(root: string, opts?: {
32
+ maxDepth?: number;
33
+ maxFiles?: number;
34
+ maxEntries?: number;
35
+ }): InstructionFile[];
36
+ export interface ApprovalEntry {
37
+ root: string;
38
+ relPath: string;
39
+ sha256: string;
40
+ approvedAt: string;
41
+ approvedBy: string;
42
+ mac: string;
43
+ }
44
+ export interface LedgerOptions {
45
+ dir?: string;
46
+ }
47
+ /** read an instruction file's bytes once, refusing links and anything outside the root */
48
+ export declare function readInstructionBytes(root: string, relPath: string): {
49
+ base: string;
50
+ abs: string;
51
+ buf: Buffer;
52
+ sha256: string;
53
+ };
54
+ /**
55
+ * Record a person's approval of one file's exact bytes. `expectedSha256` is the fingerprint
56
+ * of the bytes the person was shown; if the file changed since, nothing is approved.
57
+ */
58
+ export declare function approveInstructionFile(root: string, relPath: string, approvedBy: string, expectedSha256: string, o?: LedgerOptions): ApprovalEntry;
59
+ export type InstructionStatus = "approved" | "changed" | "unknown";
60
+ export interface InstructionCheck extends InstructionFile {
61
+ status: InstructionStatus;
62
+ approvedSha256?: string;
63
+ }
64
+ export declare function checkInstructionFiles(root: string, o?: LedgerOptions): InstructionCheck[];
65
+ /**
66
+ * Read each instruction file ONCE and decide from those bytes: approved bytes come back
67
+ * as guidance; anything else comes back only as untrusted data. `gate` is the engine's
68
+ * scan, so even approved files carry a verdict.
69
+ */
70
+ export declare function loadInstructionFiles(root: string, gate: (text: string, source: string) => Promise<{
71
+ tier: string;
72
+ envelope: string;
73
+ findings: {
74
+ kind: string;
75
+ }[];
76
+ }>, o?: LedgerOptions): Promise<{
77
+ relPath: string;
78
+ status: InstructionStatus;
79
+ inDependency: boolean;
80
+ tier: string;
81
+ sha256: string;
82
+ guidance?: string;
83
+ untrusted?: string;
84
+ }[]>;