@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.
@@ -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
+ }
@@ -11,12 +11,20 @@
11
11
  * hostile -> refuse. Not overridable at runtime. Logged.
12
12
  */
13
13
  import { type KeyObject } from "node:crypto";
14
- import { type FetchLike } from "./acquire.js";
14
+ import { acquireWithBrowser, type FetchLike } from "./acquire.js";
15
15
  import { runSandbox } from "./sandbox.js";
16
16
  import { type Finding, type IngressConfig, type IngressResult, type TaintReceipt, type Tier } from "./types.js";
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;
@@ -27,6 +35,29 @@ export interface EngineDeps {
27
35
  log?: (entry: Record<string, unknown>) => void;
28
36
  /** sandbox runner override (tests) */
29
37
  sandboxImpl?: typeof runSandbox;
38
+ /** browser fetch override for humanFetch: "browser" (tests) */
39
+ browserAcquireImpl?: typeof acquireWithBrowser;
40
+ /** randomness for user-agent choice, fetch order and jitter (tests pin it) */
41
+ random?: () => number;
42
+ /** delay between the two fetches (tests skip it) */
43
+ sleep?: (ms: number) => Promise<void>;
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;
30
61
  }
31
62
  export declare class IngressEngine {
32
63
  readonly config: IngressConfig;
@@ -42,6 +73,19 @@ export declare class IngressEngine {
42
73
  isHtml?: boolean;
43
74
  contentType?: string;
44
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>;
45
89
  /** Any analysis failure is a refusal, never a pass: the gate fails closed. */
46
90
  private guarded;
47
91
  /** Cheap structural pre-check: pathological nesting makes the HTML parser super-linear. Refuse before parsing. */
@@ -51,6 +95,7 @@ export declare class IngressEngine {
51
95
  private domainRule;
52
96
  private refuse;
53
97
  private refuseOnAcquire;
98
+ private pickAgentUserAgent;
54
99
  private receipt;
55
100
  private signerCache?;
56
101
  private signer;
@@ -88,12 +133,28 @@ export declare class IngressEngine {
88
133
  * fact, not twelve attacks)
89
134
  * - noisy-OR across kinds
90
135
  * - hidden text that carries no instruction shape is informational: it is
91
- * not delivered anyway, so visibility-only evidence is capped below the
92
- * hostile line
136
+ * never delivered, so visibility-only evidence is capped below the
137
+ * suspect line. The page passes clean, the hidden text is stripped, and
138
+ * the findings stay on the receipt (ratified 2026-11-03: hidden menus,
139
+ * collapsed sections and screen-reader labels must not refuse a page)
93
140
  * - co-occurrence of hidden-text and meaning findings, cloaking, and
94
141
  * webdriver-keyed divergence each add a bonus
95
142
  */
96
- export declare function aggregate(findings: Finding[]): number;
143
+ /** below the default suspect threshold (0.25), so hidden text alone never refuses */
144
+ export declare const VISIBILITY_ONLY_CAP = 0.2;
145
+ export declare function aggregate(findings: Finding[], ctx?: {
146
+ cloakingCompared?: boolean;
147
+ }): number;
148
+ /** words of served text with markup, link targets and bare URLs removed, so Markdown and HTML of the same page compare equal */
149
+ export declare function servedWords(text: string): string[];
150
+ /** how much of what the agent received is absent from what the browser received (word occurrences, not distinct words) */
151
+ export declare function compareServed(agentText: string, humanText: string): {
152
+ agentWords: number;
153
+ agentOnlyWords: number;
154
+ agentOnlyShare: number;
155
+ longestAgentOnlyRun: number;
156
+ sample: string;
157
+ };
97
158
  /**
98
159
  * Spotlighting-style envelope. Random boundary so content cannot forge the
99
160
  * closing marker. The model is told, in one line, how to treat the content.