@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,333 @@
1
+ /**
2
+ * Environment audit: pure parsers and classifiers (no file or network access here, so
3
+ * they can be tested with fixtures). See audit.ts for the collectors.
4
+ *
5
+ * The question the audit answers: has anything on this machine been set up to change
6
+ * what an agent receives, before the gate ever sees it? Hosts-file and DNS overrides,
7
+ * per-domain resolvers, proxies and PAC files, browser search engines, browser policies
8
+ * and extensions that rewrite pages or results, trusted root certificates that allow TLS
9
+ * interception, and agent configuration (MCP servers, hooks, global instruction files).
10
+ *
11
+ * Severity: "high" = can steer what agents receive and looks out of place; "review" =
12
+ * changes what agents receive and may well be yours (say so and move on); "info" = noted.
13
+ */
14
+ /** domains whose answers an agent relies on: search, AI providers, code registries, reference */
15
+ export const WATCHED_DOMAINS = [
16
+ "google.com", "www.google.com", "bing.com", "www.bing.com", "duckduckgo.com", "search.brave.com", "kagi.com", "search.yahoo.com",
17
+ "perplexity.ai", "chatgpt.com", "openai.com", "api.openai.com", "anthropic.com", "api.anthropic.com", "claude.ai", "gemini.google.com", "generativelanguage.googleapis.com",
18
+ "registry.npmjs.org", "pypi.org", "files.pythonhosted.org", "github.com", "api.github.com", "raw.githubusercontent.com", "objects.githubusercontent.com", "crates.io", "proxy.golang.org",
19
+ "wikipedia.org", "en.wikipedia.org", "acepaste-ingress.fly.dev",
20
+ ];
21
+ const watched = (name) => WATCHED_DOMAINS.some((d) => name === d || name.endsWith("." + d) || d.endsWith("." + name));
22
+ const LOCAL_NAMES = /^(?:localhost|localhost\.localdomain|broadcasthost|ip6-localhost|ip6-loopback|ip6-localnet|ip6-mcastprefix|ip6-allnodes|ip6-allrouters|ip6-allhosts|local)$/i;
23
+ const isLocalName = (n) => LOCAL_NAMES.test(n) || /\.(?:local|localhost|lan|home|internal|test|invalid|arpa)$/i.test(n) || !n.includes(".");
24
+ export const isSinkhole = (ip) => /^(?:0\.0\.0\.0|127\.\d+\.\d+\.\d+|::1?|::ffff:127\.\d+\.\d+\.\d+|0:0:0:0:0:0:0:[01])$/.test(ip);
25
+ export const isPrivateAddr = (ip) => /^(?:10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|169\.254\.|100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.|f[cd][0-9a-f]{2}:|fe80:)/i.test(ip);
26
+ export function parseHosts(text) {
27
+ const out = [];
28
+ text.split(/\r?\n/).forEach((raw, i) => {
29
+ const l = raw.replace(/#.*/, "").trim();
30
+ if (!l)
31
+ return;
32
+ const [ip, ...names] = l.split(/\s+/);
33
+ if (ip && names.length)
34
+ out.push({ ip, names: names.map((n) => n.toLowerCase()), line: i + 1 });
35
+ });
36
+ return out;
37
+ }
38
+ /** findings from a hosts-format file (the system hosts file, dnsmasq addn-hosts, blocklists) */
39
+ export function classifyHosts(text, where) {
40
+ const out = [];
41
+ const blockedWatched = [], blockedOther = [];
42
+ for (const e of parseHosts(text)) {
43
+ for (const n of e.names) {
44
+ if (isLocalName(n))
45
+ continue;
46
+ if (isSinkhole(e.ip)) {
47
+ (watched(n) ? blockedWatched : blockedOther).push(n);
48
+ continue;
49
+ }
50
+ out.push({
51
+ area: "hosts", severity: watched(n) ? "high" : "review",
52
+ title: `${n} is pinned to ${e.ip}`,
53
+ detail: `Every program on this machine, agents included, reaches ${n} at ${e.ip} instead of asking DNS${isPrivateAddr(e.ip) ? " (a private address on your network)" : ""}. If you did not add this, someone can serve agents their own version of that site.`,
54
+ where: `${where}:${e.line}`,
55
+ });
56
+ }
57
+ }
58
+ if (blockedWatched.length)
59
+ out.push({ area: "hosts", severity: "review", title: `${blockedWatched.length} site(s) agents rely on are blocked in ${where}`, detail: `Blocked: ${blockedWatched.slice(0, 12).join(", ")}${blockedWatched.length > 12 ? " …" : ""}. Agents will fail to reach them, or fall back to other sources.`, where });
60
+ if (blockedOther.length)
61
+ out.push({ area: "hosts", severity: "info", title: `${blockedOther.length} hostnames blocked in ${where}`, detail: `Sinkholed to a local address, as ad and tracker blocklists do. Examples: ${blockedOther.slice(0, 6).join(", ")}.`, where });
62
+ return out;
63
+ }
64
+ /** dnsmasq: address= (answer overrides), server=/domain/ (per-domain upstreams), addn-hosts, cname */
65
+ export function classifyDnsmasq(text, where) {
66
+ const findings = [];
67
+ const addnHosts = [], confDirs = [];
68
+ const blocked = [];
69
+ text.split(/\r?\n/).forEach((raw, i) => {
70
+ const l = raw.replace(/\s#.*$/, "").trim();
71
+ if (!l || l.startsWith("#"))
72
+ return;
73
+ const [k, ...rest] = l.split("=");
74
+ const v = rest.join("=").trim();
75
+ if (k === "addn-hosts")
76
+ addnHosts.push(v);
77
+ else if (k === "conf-dir")
78
+ confDirs.push(v.split(",")[0]);
79
+ else if (k === "address" || k === "local" && v.includes("/")) {
80
+ const m = v.match(/^\/(.+)\/(.*)$/);
81
+ if (!m)
82
+ return;
83
+ const doms = m[1].split("/").filter(Boolean), ip = m[2];
84
+ for (const d of doms) {
85
+ if (isLocalName(d))
86
+ continue;
87
+ if (!ip || ip === "#" || isSinkhole(ip)) {
88
+ blocked.push(d);
89
+ continue;
90
+ }
91
+ findings.push({ area: "dns", severity: watched(d) ? "high" : "review", title: `dnsmasq answers ${d} with ${ip}`, detail: `Your local resolver gives ${ip} for ${d} and all its subdomains, whatever the real DNS says.`, where: `${where}:${i + 1}` });
92
+ }
93
+ }
94
+ else if (k === "server" && v.startsWith("/")) {
95
+ const m = v.match(/^\/(.+)\/(.*)$/);
96
+ if (!m)
97
+ return;
98
+ for (const d of m[1].split("/").filter(Boolean)) {
99
+ if (isLocalName(d))
100
+ continue;
101
+ findings.push({ area: "dns", severity: watched(d) ? "high" : "review", title: `queries for ${d} go to ${m[2] || "no server (blocked)"}`, detail: `dnsmasq sends lookups for ${d} to a different resolver than everything else. That resolver decides what agents reach for that domain.`, where: `${where}:${i + 1}` });
102
+ }
103
+ }
104
+ else if (k === "cname") {
105
+ findings.push({ area: "dns", severity: "review", title: `dnsmasq aliases ${v.split(",")[0]}`, detail: `cname=${v}: lookups for the first name are answered with the second.`, where: `${where}:${i + 1}` });
106
+ }
107
+ });
108
+ if (blocked.length)
109
+ findings.push({ area: "dns", severity: blocked.some(watched) ? "review" : "info", title: `dnsmasq blocks ${blocked.length} domain(s)`, detail: `Examples: ${blocked.slice(0, 8).join(", ")}${blocked.some(watched) ? ". Some are sites agents rely on." : "."}`, where });
110
+ return { findings, addnHosts, confDirs };
111
+ }
112
+ /** dnscrypt-proxy cloaking rules ("name ip" or "name othername") and forwarding rules ("name server") */
113
+ export function classifyDnscryptRules(text, where, kind) {
114
+ const out = [];
115
+ let blocked = 0;
116
+ text.split(/\r?\n/).forEach((raw, i) => {
117
+ const l = raw.replace(/#.*/, "").trim();
118
+ if (!l)
119
+ return;
120
+ const [name, target] = l.split(/\s+/);
121
+ if (!name || !target || isLocalName(name.replace(/^[=*.]+/, "")))
122
+ return;
123
+ const n = name.replace(/^[=*.]+/, "").toLowerCase();
124
+ if (kind === "cloaking" && isSinkhole(target)) {
125
+ blocked++;
126
+ return;
127
+ }
128
+ out.push({
129
+ area: "dns", severity: watched(n) ? "high" : "review",
130
+ title: kind === "cloaking" ? `dnscrypt-proxy answers ${n} with ${target}` : `dnscrypt-proxy sends ${n} lookups to ${target}`,
131
+ detail: kind === "cloaking" ? `A cloaking rule overrides the real answer for ${n}.` : `A forwarding rule hands lookups for ${n} to a different server.`,
132
+ where: `${where}:${i + 1}`,
133
+ });
134
+ });
135
+ if (blocked)
136
+ out.push({ area: "dns", severity: "info", title: `dnscrypt-proxy cloaks ${blocked} name(s) to a local address`, detail: "Blocking, as blocklists do.", where });
137
+ return out;
138
+ }
139
+ /** `localPrefixes`: the /64 prefixes of this machine's own IPv6 addresses (a router on the same network hands out addresses in its prefix) */
140
+ export function classifyResolvConf(text, where, localPrefixes = []) {
141
+ const ns = [...text.matchAll(/^\s*nameserver\s+(\S+)/gm)].map((m) => m[1].replace(/%.*$/, ""));
142
+ if (!ns.length)
143
+ return [];
144
+ const onLan = (n) => n.includes(":") && localPrefixes.some((p) => ipv6Prefix64(n) === p);
145
+ const odd = ns.filter((n) => !isSinkhole(n) && !isPrivateAddr(n) && !KNOWN_PUBLIC_RESOLVERS.has(n) && !onLan(n));
146
+ return [{ area: "dns", severity: odd.length ? "review" : "info", title: `DNS servers: ${ns.join(", ")}`, detail: odd.length ? `${odd.join(", ")} is not a well-known public resolver or a local one. Whoever runs it decides what every name on this machine resolves to.` : "Local or well-known public resolvers.", where }];
147
+ }
148
+ /** first four groups of an IPv6 address, expanded */
149
+ export function ipv6Prefix64(addr) {
150
+ const a = addr.replace(/%.*$/, "").toLowerCase();
151
+ const [head, tail = ""] = a.split("::");
152
+ const h = head ? head.split(":") : [], t = tail ? tail.split(":") : [];
153
+ const full = a.includes("::") ? [...h, ...Array(8 - h.length - t.length).fill("0"), ...t] : h;
154
+ return full.slice(0, 4).map((g) => g.replace(/^0+(?=.)/, "")).join(":");
155
+ }
156
+ export const KNOWN_PUBLIC_RESOLVERS = new Set(["1.1.1.1", "1.0.0.1", "8.8.8.8", "8.8.4.4", "9.9.9.9", "149.112.112.112", "208.67.222.222", "208.67.220.220", "94.140.14.14", "94.140.15.15", "2606:4700:4700::1111", "2606:4700:4700::1001", "2001:4860:4860::8888", "2001:4860:4860::8844", "2620:fe::fe"]);
157
+ /** macOS `scutil --dns`: resolvers scoped to particular domains */
158
+ export function classifyScutilDns(text) {
159
+ const out = [];
160
+ for (const block of text.split(/\nresolver #\d+/).slice(1)) {
161
+ const domain = block.match(/^\s*domain\s*:\s*(\S+)/m)?.[1];
162
+ const ns = [...block.matchAll(/nameserver\[\d+\]\s*:\s*(\S+)/g)].map((m) => m[1]);
163
+ if (!domain || !ns.length || isLocalName(domain) || /^(?:\d+\.)*in-addr\.arpa$|ip6\.arpa$/.test(domain))
164
+ continue;
165
+ out.push({ area: "dns", severity: watched(domain) ? "high" : "review", title: `lookups for ${domain} go to ${ns.join(", ")}`, detail: `A resolver scoped to ${domain} (set by a VPN, a profile or /etc/resolver). It decides what agents reach under that domain.`, where: "scutil --dns" });
166
+ }
167
+ return out;
168
+ }
169
+ /** macOS `scutil --proxy` output */
170
+ export function classifyScutilProxy(text) {
171
+ const kv = Object.fromEntries([...text.matchAll(/^\s*(\w+)\s*:\s*(.+?)\s*$/gm)].map((m) => [m[1], m[2]]));
172
+ const out = [];
173
+ for (const [en, host, port, label] of [["HTTPEnable", "HTTPProxy", "HTTPPort", "HTTP"], ["HTTPSEnable", "HTTPSProxy", "HTTPSPort", "HTTPS"], ["SOCKSEnable", "SOCKSProxy", "SOCKSPort", "SOCKS"]]) {
174
+ if (kv[en] === "1")
175
+ out.push({ area: "proxy", severity: "review", title: `system ${label} proxy: ${kv[host]}:${kv[port]}`, detail: `Web traffic from apps that use system settings passes through ${kv[host]}. A proxy can change any page it relays.`, where: "scutil --proxy" });
176
+ }
177
+ if (kv.ProxyAutoConfigEnable === "1") {
178
+ const u = kv.ProxyAutoConfigURLString ?? "";
179
+ out.push({ area: "proxy", severity: /^http:/i.test(u) ? "high" : "review", title: `proxy auto-config: ${u}`, detail: `A PAC script decides, per site, where traffic goes.${/^http:/i.test(u) ? " It is fetched over plain HTTP, so anyone on the network can replace it." : ""}`, where: "scutil --proxy" });
180
+ }
181
+ if (kv.ProxyAutoDiscoveryEnable === "1")
182
+ out.push({ area: "proxy", severity: "review", title: "proxy auto-discovery (WPAD) is on", detail: "The network can hand this machine a proxy without asking.", where: "scutil --proxy" });
183
+ return out;
184
+ }
185
+ export function classifyProxyEnv(env) {
186
+ const out = [];
187
+ for (const k of ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"]) {
188
+ const v = env[k];
189
+ if (!v)
190
+ continue;
191
+ let host = v;
192
+ try {
193
+ const u = new URL(v);
194
+ host = `${u.hostname}${u.port ? ":" + u.port : ""}`;
195
+ }
196
+ catch { /* not a URL */ }
197
+ out.push({ area: "proxy", severity: "review", title: `${k} is set (${host})`, detail: "Command-line tools and many agents send web requests through this proxy.", where: "environment" });
198
+ }
199
+ return out;
200
+ }
201
+ const KNOWN_SEARCH = /^https:\/\/(?:www\.google\.[a-z.]+|www\.bing\.com|duckduckgo\.com|search\.brave\.com|kagi\.com|search\.yahoo\.com|www\.ecosia\.org|www\.startpage\.com|yandex\.[a-z]+|www\.baidu\.com|search\.naver\.com|www\.qwant\.com|html\.duckduckgo\.com|perplexity\.ai|www\.perplexity\.ai)\//i;
202
+ /** Chromium-family Preferences: the default search engine */
203
+ export function classifyChromiumSearch(prefs, where) {
204
+ const t = prefs?.default_search_provider_data?.template_url_data;
205
+ const url = t?.url;
206
+ if (!url)
207
+ return [];
208
+ return [{ area: "browser-search", severity: KNOWN_SEARCH.test(url) ? "info" : "high", title: `default search: ${t.short_name ?? t.keyword ?? "unnamed"}`, detail: KNOWN_SEARCH.test(url) ? `Search goes to ${new URL(url.replace(/\{[^}]+\}/g, "x")).hostname}.` : `Searches go to ${url.replace(/\{[^}]+\}/g, "…")}, which is not a well-known search engine. Results there can be anything.`, where }];
209
+ }
210
+ const ALL_URLS = /^(?:<all_urls>|\*:\/\/\*\/\*|https?:\/\/\*\/\*|\*:\/\/\*\/|file:\/\/\/\*)$/;
211
+ export function classifyExtension(x, where) {
212
+ const out = [];
213
+ // a disabled extension changes nothing until someone turns it on: note it, at most
214
+ if (!x.enabled) {
215
+ const risky = !!x.searchOverride || x.permissions.includes("proxy") || !x.fromStore;
216
+ return risky ? [{ area: "browser-extension", severity: "info", title: `${x.name} (${x.id}) is installed but disabled`, detail: `${x.searchOverride ? "It would replace your search engine. " : ""}${x.permissions.includes("proxy") ? "It can set a proxy. " : ""}${!x.fromStore ? "It was not installed from the store. " : ""}Remove it if you don't use it.`, where }] : [];
217
+ }
218
+ const unpacked = !x.fromStore;
219
+ const allSites = [...x.hostPermissions, ...x.contentMatches, ...x.permissions].some((p) => ALL_URLS.test(p));
220
+ const net = x.permissions.some((p) => /^(?:webRequest|webRequestBlocking|declarativeNetRequest|declarativeNetRequestWithHostAccess|proxy)$/.test(p));
221
+ const label = `${x.name}${x.version ? " " + x.version : ""} (${x.id})${x.enabled ? "" : ", disabled"}`;
222
+ if (x.searchOverride)
223
+ out.push({ area: "browser-extension", severity: KNOWN_SEARCH.test(x.searchOverride) ? "review" : "high", title: `${label} replaces your search engine`, detail: `Searches go to ${x.searchOverride.replace(/\{[^}]+\}/g, "…")}.`, where });
224
+ if (x.permissions.includes("proxy"))
225
+ out.push({ area: "browser-extension", severity: unpacked ? "high" : "review", title: `${label} can route your browsing through a proxy`, detail: "The proxy permission lets it send any site's traffic elsewhere.", where });
226
+ if (x.homepageOverride || x.startupOverride)
227
+ out.push({ area: "browser-extension", severity: "review", title: `${label} sets your home or startup pages`, detail: x.homepageOverride ? `Home page: ${x.homepageOverride}.` : "Startup pages are set by the extension.", where });
228
+ if (allSites && (net || x.contentMatches.length))
229
+ out.push({ area: "browser-extension", severity: unpacked ? "high" : "review", title: `${label} can change what every site shows`, detail: `${x.contentMatches.length ? "It runs its own scripts inside every page" : "It can rewrite or redirect requests to every site"}${unpacked ? ", and it was not installed from the store" : ""}. An agent driving this browser sees the page after the extension has changed it.`, where });
230
+ else if (unpacked && x.enabled)
231
+ out.push({ area: "browser-extension", severity: "review", title: `${label} was not installed from the store`, detail: "Loaded unpacked or by another program.", where });
232
+ return out;
233
+ }
234
+ /** Chromium policy dictionary (from a managed plist or a policies JSON file) */
235
+ export function classifyChromiumPolicy(policy, where) {
236
+ const out = [];
237
+ const add = (severity, title, detail) => out.push({ area: "browser-policy", severity, title, detail, where });
238
+ if (policy.DefaultSearchProviderSearchURL)
239
+ add(KNOWN_SEARCH.test(policy.DefaultSearchProviderSearchURL) ? "review" : "high", `policy forces the search engine to ${policy.DefaultSearchProviderName ?? policy.DefaultSearchProviderSearchURL}`, `DefaultSearchProviderSearchURL = ${policy.DefaultSearchProviderSearchURL}. Users cannot change it.`);
240
+ if (policy.ExtensionInstallForcelist?.length)
241
+ add("high", `policy force-installs ${policy.ExtensionInstallForcelist.length} extension(s)`, `ExtensionInstallForcelist: ${policy.ExtensionInstallForcelist.slice(0, 6).join(", ")}. They cannot be removed from the browser.`);
242
+ if (policy.ProxyMode || policy.ProxyServer || policy.ProxyPacUrl || policy.ProxySettings)
243
+ add("high", "policy sets the browser's proxy", `ProxyMode ${policy.ProxyMode ?? policy.ProxySettings?.ProxyMode ?? "?"}${policy.ProxyServer ? `, server ${policy.ProxyServer}` : ""}${policy.ProxyPacUrl ? `, PAC ${policy.ProxyPacUrl}` : ""}.`);
244
+ if (policy.URLBlocklist?.length || policy.URLAllowlist?.length)
245
+ add("review", "policy filters which sites the browser may open", `${policy.URLBlocklist?.length ?? 0} blocked pattern(s), ${policy.URLAllowlist?.length ?? 0} allowed pattern(s). Examples: ${(policy.URLBlocklist ?? []).slice(0, 5).join(", ")}.`);
246
+ if (policy.DnsOverHttpsTemplates)
247
+ add("review", "policy sets the browser's DNS-over-HTTPS server", `DnsOverHttpsTemplates = ${policy.DnsOverHttpsTemplates}.`);
248
+ if (policy.HomepageLocation || policy.RestoreOnStartupURLs?.length || policy.NewTabPageLocation)
249
+ add("review", "policy sets home, new-tab or startup pages", [policy.HomepageLocation, policy.NewTabPageLocation, ...(policy.RestoreOnStartupURLs ?? [])].filter(Boolean).slice(0, 4).join(", "));
250
+ const known = new Set(["DefaultSearchProviderSearchURL", "DefaultSearchProviderName", "DefaultSearchProviderEnabled", "ExtensionInstallForcelist", "ProxyMode", "ProxyServer", "ProxyPacUrl", "ProxySettings", "URLBlocklist", "URLAllowlist", "DnsOverHttpsTemplates", "HomepageLocation", "RestoreOnStartupURLs", "NewTabPageLocation"]);
251
+ const other = Object.keys(policy).filter((k) => !known.has(k) && !k.startsWith("PayloadUUID") && !/^(?:PayloadIdentifier|PayloadType|PayloadVersion)$/.test(k));
252
+ if (other.length)
253
+ add("info", `${other.length} other browser policies set`, other.slice(0, 12).join(", "));
254
+ return out;
255
+ }
256
+ const MITM_TOOLS = /mitmproxy|charles|fiddler|burp|portswigger|proxyman|http toolkit|httptoolkit|zscaler|netskope|forcepoint|bluecoat|fortinet|palo alto|cisco umbrella|kaspersky|avast|eset|bitdefender|superfish|komodia/i;
257
+ /** macOS `security dump-trust-settings` output: certificates with custom trust */
258
+ export function classifyTrustSettings(text, domain) {
259
+ if (/No Trust Settings were found/i.test(text))
260
+ return [];
261
+ const names = [...text.matchAll(/Cert\s+\d+:\s*(.+)/g)].map((m) => m[1].trim());
262
+ return names.map((n) => ({
263
+ area: "certificates", severity: (MITM_TOOLS.test(n) ? "high" : "review"),
264
+ title: `custom-trusted certificate (${domain}): ${n}`,
265
+ detail: `A certificate given trust by hand${domain === "admin" ? " for every user" : ""}. A trusted root lets whoever holds its key read and change encrypted traffic, so pages and API answers can be altered in transit.${MITM_TOOLS.test(n) ? " Its name matches a traffic-inspection tool." : ""}`,
266
+ where: `security dump-trust-settings${domain === "admin" ? " -d" : ""}`,
267
+ }));
268
+ }
269
+ /** macOS `systemextensionsctl list`: active network and content-filter extensions */
270
+ export function classifySystemExtensions(text) {
271
+ const out = [];
272
+ for (const l of text.split(/\r?\n/)) {
273
+ if (!/\[activated enabled\]/.test(l))
274
+ continue;
275
+ const cols = l.split(/\t+/).map((c) => c.trim()).filter(Boolean);
276
+ const bundle = cols.find((c) => /^[a-z0-9-]+(?:\.[a-z0-9-]+){2,}/i.test(c) && !/^\d/.test(c)) ?? "";
277
+ const name = cols.find((c) => /\(\d/.test(c)) ?? bundle;
278
+ if (!/network|filter|vpn|dns|proxy|firewall|lulu|snitch|tunnel/i.test(l))
279
+ continue;
280
+ out.push({ area: "network-extension", severity: "review", title: `network extension active: ${name.replace(/\s*\(.*$/, "")}`, detail: `${bundle} can see and filter network traffic (firewalls, VPNs, DNS proxies, content filters). Yours if you installed it; otherwise it can change what agents receive.`, where: "systemextensionsctl list" });
281
+ }
282
+ return out;
283
+ }
284
+ /** MCP server configs (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code): what agents can call */
285
+ export function classifyMcpServers(config, where) {
286
+ const servers = config?.mcpServers ?? config?.servers ?? config?.mcp?.servers ?? {};
287
+ const out = [];
288
+ for (const [name, s] of Object.entries(servers)) {
289
+ const cmd = [s.command, ...(s.args ?? [])].filter(Boolean).join(" ");
290
+ const url = s.url ?? s.serverUrl;
291
+ const unpinned = /\bnpx\b|\buvx\b|\bpipx\s+run\b|\bbunx\b/.test(cmd) && !(s.args ?? []).some((a) => /@\d+\.\d+/.test(a) || /==\d/.test(a));
292
+ const envKeys = Object.keys(s.env ?? {});
293
+ out.push({
294
+ area: "agent-config", severity: url && !/^https:\/\/(?:localhost|127\.)/.test(url) ? "review" : unpinned ? "review" : "info",
295
+ title: `MCP server "${name}": ${url ? url : cmd.slice(0, 120)}`,
296
+ detail: `${url ? "A remote server: what it returns goes straight to the agent." : "A local program the agent can call."}${unpinned ? " It runs the latest published version on every start (not pinned), so a hijacked package would load automatically." : ""}${envKeys.length ? ` Environment keys: ${envKeys.join(", ")} (values not shown).` : ""}`,
297
+ where,
298
+ });
299
+ }
300
+ return out;
301
+ }
302
+ /** Claude Code settings: hooks run commands on agent events */
303
+ export function classifyHooks(settings, where) {
304
+ const hooks = settings?.hooks;
305
+ if (!hooks || typeof hooks !== "object")
306
+ return [];
307
+ const cmds = [];
308
+ for (const groups of Object.values(hooks))
309
+ for (const g of groups ?? [])
310
+ for (const h of g?.hooks ?? [])
311
+ if (h?.command)
312
+ cmds.push(h.command);
313
+ return cmds.length ? [{ area: "agent-config", severity: "review", title: `${cmds.length} agent hook command(s)`, detail: `Hooks run on agent events and can rewrite what the agent sees: ${cmds.slice(0, 4).map((c) => c.slice(0, 80)).join(" | ")}`, where }] : [];
314
+ }
315
+ /** compare what this machine resolves with DNS-over-HTTPS */
316
+ export function classifyResolution(name, local, doh, tlsError) {
317
+ const out = [];
318
+ if (tlsError)
319
+ out.push({ area: "resolution", severity: "high", title: `TLS to ${name} did not verify`, detail: `Connecting to ${name} through this machine's network failed certificate checks (${tlsError}). That is what interception looks like, though a captive portal or broken clock can cause it too.`, where: name });
320
+ if (!local.length)
321
+ return out;
322
+ if (local.every(isSinkhole))
323
+ out.push({ area: "resolution", severity: "review", title: `${name} is blocked on this machine`, detail: `It resolves to ${local.join(", ")} here.`, where: name });
324
+ else if (local.some(isPrivateAddr))
325
+ out.push({ area: "resolution", severity: "high", title: `${name} resolves to a private address`, detail: `Here it resolves to ${local.join(", ")}, an address on a local network, while public DNS says ${doh?.join(", ") || "something else"}. A machine on your network answers for it.`, where: name });
326
+ else if (doh?.length && !local.some((a) => doh.includes(a)))
327
+ out.push({ area: "resolution", severity: "info", title: `${name} resolves differently here than over DNS-over-HTTPS`, detail: `Here: ${local.join(", ")}; DNS-over-HTTPS: ${doh.join(", ")}. Large sites hand out different addresses by location, so this alone is normal.`, where: name });
328
+ return out;
329
+ }
330
+ export function summarizeAudit(findings) {
331
+ const count = (s) => findings.filter((f) => f.severity === s).length;
332
+ return { high: count("high"), review: count("review"), info: count("info") };
333
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Environment audit (collectors). Read-only: it reads settings files and runs a few
3
+ * read-only system commands; it changes nothing. Secrets are never printed (MCP env
4
+ * values, proxy credentials). macOS is covered most fully; Linux partly; what was not
5
+ * checked is listed in `checked`, so a short report is never mistaken for a clean one.
6
+ */
7
+ import { type AuditFinding, type AuditArea, type ExtensionInfo } from "./audit-parsers.js";
8
+ export interface AuditCheck {
9
+ area: AuditArea;
10
+ what: string;
11
+ status: "checked" | "not present" | "skipped" | "error";
12
+ note?: string;
13
+ }
14
+ export interface AuditReport {
15
+ at: string;
16
+ platform: string;
17
+ summary: {
18
+ high: number;
19
+ review: number;
20
+ info: number;
21
+ };
22
+ findings: AuditFinding[];
23
+ checked: AuditCheck[];
24
+ }
25
+ export interface AuditOptions {
26
+ /** also compare name resolution with DNS-over-HTTPS and test TLS to sites agents rely on */
27
+ network?: boolean;
28
+ /** gate for global agent instruction files (the engine's scan); verdicts are added to the report */
29
+ gate?: (text: string, source: string) => Promise<{
30
+ tier: string;
31
+ findings: {
32
+ kind: string;
33
+ message: string;
34
+ }[];
35
+ }>;
36
+ /**
37
+ * compare stable pages fetched from this machine with the same pages fetched by a gate
38
+ * on another network (the hosted service): tampering on this machine's path shows as a
39
+ * difference. Needs that service's API key.
40
+ */
41
+ remote?: {
42
+ base: string;
43
+ key: string;
44
+ urls?: string[];
45
+ localFetch: (url: string) => Promise<{
46
+ tier: string;
47
+ delivered: string;
48
+ }>;
49
+ };
50
+ home?: string;
51
+ /** override for tests */
52
+ run?: (cmd: string, args: string[]) => Promise<string | undefined>;
53
+ }
54
+ export declare function auditEnvironment(o?: AuditOptions): Promise<AuditReport>;
55
+ /** installed Chromium extensions from the profile's Extensions folder, joined with their settings (store or not, enabled or not) */
56
+ export declare function readChromiumExtensions(dir: string, settings: Record<string, any>): ExtensionInfo[];
57
+ export declare function formatAudit(r: AuditReport): string;