net-guard

1import type { EngineInterface, Register } from 'claude-code'
2
3import { parseTarget } from './hosts'
4import { judge, policyFrom, type Decision, type Policy } from './policy'
5import { fetchRequest, requestsIn, type Request } from './requests'
6
7const ONCE = 'Allow once'
8const BLOCK = 'Block'
9
10// This session's hosts and tally; a reload starts them over, the all-time count is in $.store.
11const sessionHosts = new Set<string>()
12const tally = { checked: 0, asked: 0, blocked: 0 }
13let lastBlocked = ''
14
15async function refuseNetwork($: EngineInterface, tool: string, decision: Decision) {
16  tally.blocked += 1
17  lastBlocked = `${decision.host ?? '(run-time host)'}: ${decision.why}`
18  $.ui.toast(`net-guard blocked ${decision.host ?? 'a network call'}`)
19  const total = Number((await $.store.get('blockedTotal')) ?? 0) + 1
20  await $.store.set('blockedTotal', total)
21
22  return {
23    deny:
24      `net-guard blocked this ${tool === 'WebFetch' ? 'fetch' : 'command'}: it ${decision.why}. ` +
25      "Don't retry through another host, tool or encoding. Tell the user what you wanted to fetch or send; they can allow the host with /net-guard allow <host>.",
26  }
27}
28
29function verdictLines(requests: readonly Request[], policy: Policy): string {
30  if (requests.length === 0) return 'no network requests found.'
31  return judge(requests, policy, sessionHosts)
32    .map(({ request, decision }) => {
33      const label = decision.action === 'deny' ? 'BLOCK' : decision.action === 'ask' ? 'ASK  ' : 'ALLOW'
34      const where = decision.host ?? request.raw
35      return `  ${label} ${request.tool} → ${where}${request.isUpload ? ' (sends data)' : ''}${decision.action === 'allow' ? '' : `: ${decision.why}`}`
36    })
37    .join('\n')
38}
39
40export const register: Register = (on, options) => {
41  const policy = policyFrom(options)
42
43  on('session.start', async ($, e, next) => {
44    await $.command.register({
45      name: 'net-guard',
46      description: "What net-guard has allowed and blocked; /net-guard check <url or command>, allow <host>, forget",
47      argumentHint: '[check <url|command> | allow <host> | forget]',
48    })
49    return next(e)
50  })
51
52  on('tool.call', { tool: ['Bash', 'WebFetch'] }, async ($, e, next) => {
53    const requests = e.tool === 'Bash' ? requestsIn(e.command) : fetchRequest(e.url)
54    if (requests.length === 0) return next(e)
55    tally.checked += 1
56
57    const verdicts = judge(requests, policy, sessionHosts)
58    const worst = verdicts[0]!
59    if (worst.decision.action === 'deny') return refuseNetwork($, e.tool, worst.decision)
60    if (worst.decision.action === 'allow') return next(e)
61
62    const asks = verdicts.filter(v => v.decision.action === 'ask')
63    const hosts = [...new Set(asks.map(v => v.decision.host).filter((h): h is string => h !== null))]
64    const remember = hosts.length === 1 ? `Allow ${hosts[0]!.slice(0, 40)} this session` : hosts.length > 1 ? 'Allow these hosts this session' : undefined
65    const reasons = [...new Set(asks.map(v => v.decision.why))].slice(0, 3).join('; ')
66    const shown = e.tool === 'Bash' ? `$ ${e.command.length > 240 ? `${e.command.slice(0, 240)}…` : e.command}` : e.url
67    tally.asked += 1
68
69    let answer = BLOCK
70    try {
71      answer = await $.ui.ask(`net-guard: this ${e.tool === 'WebFetch' ? 'fetch' : 'command'} ${reasons}.\n\n  ${shown}\n\nLet it through?`, {
72        header: 'net-guard',
73        options: remember === undefined ? [ONCE, BLOCK] : [ONCE, remember, BLOCK],
74      })
75    } catch {
76      // Nobody to ask (a -p run) or the dialog was dismissed: stay safe.
77    }
78    if (answer === ONCE) return next(e)
79    if (remember !== undefined && answer === remember) {
80      for (const host of hosts) sessionHosts.add(host)
81      return next(e)
82    }
83    return refuseNetwork($, e.tool, { ...asks[0]!.decision, why: `${asks[0]!.decision.why}, and the user didn't allow it` })
84  })
85
86  on('command.run', { command: 'net-guard' }, async ($, e) => {
87    const [verb = '', ...rest] = e.args.trim().split(/\s+/)
88    const arg = rest.join(' ')
89
90    if (verb === 'check') {
91      if (arg === '') return { text: 'Usage: /net-guard check <url or shell command>' }
92      const requests = /\s/.test(arg) ? requestsIn(arg) : arg.includes('://') ? fetchRequest(arg) : requestsIn(arg).length > 0 ? requestsIn(arg) : fetchRequest(arg)
93      return { text: `${arg}:\n${verdictLines(requests, policy)}` }
94    }
95    if (verb === 'allow') {
96      const target = parseTarget(arg)
97      if (target === undefined || target === null) return { text: 'Usage: /net-guard allow <host>' }
98      sessionHosts.add(target.host)
99      return { text: `allowed ${target.host} for the rest of this session.` }
100    }
101    if (verb === 'forget') {
102      const n = sessionHosts.size
103      sessionHosts.clear()
104      return { text: `forgot ${n} host${n === 1 ? '' : 's'} allowed this session.` }
105    }
106
107    const total = Number((await $.store.get('blockedTotal')) ?? 0)
108    const lines = [
109      `on: unknown hosts ${policy.unknown}, fetches of unknown hosts ${policy.fetchUnknown}, uploads ask when ${policy.askUploads === 'unlisted' ? 'the host is unlisted' : policy.askUploads}.`,
110      `Lists: ${policy.allow.length + policy.userAllow.length} allowed, ${policy.deny.length + policy.userDeny.length} denied${policy.allowPrivate ? ', private networks allowed' : ''}.`,
111      `This session: ${tally.checked} network calls checked, ${tally.asked} asked, ${tally.blocked} blocked. All time: ${total} blocked.`,
112      sessionHosts.size === 0 ? 'No hosts allowed for this session.' : `Allowed this session: ${[...sessionHosts].join(', ')}`,
113    ]
114    if (lastBlocked !== '') lines.push(`Last blocked: ${lastBlocked.slice(0, 160)}`)
115    return { text: lines.join('\n') }
116  })
117}
118

1// Hosts and host patterns: no `$`, pure.
2
3export type Target = { host: string; path: string }
4
5const NETWORK_SCHEMES = /^(https?|ftps?|wss?|ssh|git|git\+ssh|ssh\+git|rsync|sftp|scp|telnet|ldaps?|gopher|dict|smtps?|imaps?|pop3s?|mqtts?|redis|rediss)$/i
6
7/**
8 * Where a URL-ish target goes: its host (lowercased, no port, no brackets)
9 * and path. `null` when the host is only known at run time (`$HOST`), and
10 * `undefined` when it isn't a network target at all (a file path, `file://`).
11 */
12export function parseTarget(raw: string): Target | null | undefined {
13  const target = raw.trim().replace(/^['"]|['"]$/g, '')
14  if (target === '' || target.startsWith('-') || target.startsWith('@')) return undefined
15  const scheme = target.match(/^([a-z][a-z0-9+.-]*):\/\//i)
16  if (scheme !== null && !NETWORK_SCHEMES.test(scheme[1]!)) return undefined
17  if (scheme === null && (target.startsWith('/') || target.startsWith('./') || target.startsWith('../') || target.startsWith('~'))) return undefined
18
19  const rest = scheme === null ? target : target.slice(scheme[0].length)
20  const cut = rest.search(/[/?#]/)
21  const authority = cut < 0 ? rest : rest.slice(0, cut)
22  const path = cut < 0 ? '/' : rest.slice(cut)
23  const hostPort = authority.includes('@') ? authority.slice(authority.lastIndexOf('@') + 1) : authority
24
25  if (/[$`]/.test(hostPort) || hostPort.includes('{{')) return null
26  let host: string
27  if (hostPort.startsWith('[')) {
28    const end = hostPort.indexOf(']')
29    host = end < 0 ? '' : hostPort.slice(1, end)
30  } else {
31    host = hostPort.replace(/:\d*$/, '')
32  }
33  host = host.toLowerCase().replace(/\.$/, '')
34  if (host === '') return undefined
35  const isName = /^[a-z0-9_]([a-z0-9_-]*[a-z0-9_])?(\.[a-z0-9_]([a-z0-9_-]*[a-z0-9_])?)*$/.test(host)
36  const isIpv6 = host.includes(':') && /^[0-9a-f:.]+$/.test(host)
37  if (!isName && !isIpv6) return undefined
38
39  return { host, path }
40}
41
42function ipv4(host: string): number[] | undefined {
43  const parts = host.split('.')
44  if (parts.length !== 4 || !parts.every(p => /^\d{1,3}$/.test(p) && Number(p) <= 255)) return undefined
45  return parts.map(Number)
46}
47
48/** This machine: never worth asking about. */
49export function isLocal(host: string): boolean {
50  if (host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '0.0.0.0' || host === '::') return true
51  if (host.startsWith('::ffff:')) return isLocal(host.slice(7))
52  return ipv4(host)?.[0] === 127
53}
54
55/** A private network: LAN ranges and local-only names. Cloud metadata (169.254.x) is not one. */
56export function isPrivate(host: string): boolean {
57  const v4 = ipv4(host)
58  if (v4 !== undefined) {
59    const [a, b] = v4 as [number, number, number, number]
60    return a === 10 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 100 && b >= 64 && b <= 127)
61  }
62  if (host.includes(':')) return /^f[cd][0-9a-f]{2}:/.test(host) || /^fe[89ab][0-9a-f]:/.test(host)
63  return /\.(local|internal|lan|home\.arpa)$/.test(host) || host === 'host.docker.internal'
64}
65
66/**
67 * Whether `target` matches `pattern`. `example.com` covers the domain and
68 * every subdomain, `*.example.com` only the subdomains, `*` everything, and
69 * `example.com/hooks` only paths under `/hooks` there.
70 */
71export function matches(target: Target, pattern: string): boolean {
72  const slash = pattern.indexOf('/')
73  const hostPattern = slash < 0 ? pattern : pattern.slice(0, slash)
74  const pathPrefix = slash < 0 ? '' : pattern.slice(slash)
75  if (pathPrefix !== '' && !target.path.toLowerCase().startsWith(pathPrefix)) return false
76  if (hostPattern === '*') return true
77  if (hostPattern.startsWith('*.')) return target.host.endsWith(hostPattern.slice(1))
78  return target.host === hostPattern || target.host.endsWith(`.${hostPattern}`)
79}
80
81/** `a.com, *.b.com\nhttps://c.com/x` → normalised patterns. */
82export function parseList(text: string): string[] {
83  return text
84    .split(/[\s,]+/)
85    .map(item => item.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, '').replace(/\/$/, ''))
86    .filter(item => item !== '' && item !== '/')
87}
88
89/** Where the person's code and packages live: fetching from these is everyday work. */
90export const DEFAULT_ALLOW = [
91  'github.com', 'githubusercontent.com', 'githubassets.com', 'gitlab.com', 'bitbucket.org',
92  'npmjs.org', 'npmjs.com', 'yarnpkg.com', 'pypi.org', 'pythonhosted.org', 'crates.io',
93  'rubygems.org', 'proxy.golang.org', 'sum.golang.org', 'pkg.go.dev', 'go.dev',
94  'docs.python.org', 'developer.mozilla.org', 'nodejs.org', 'stackoverflow.com',
95  'stackexchange.com', 'docs.anthropic.com', 'code.claude.com', 'wikipedia.org',
96]
97
98/** Paste sites, request catchers and tunnels: where stolen data usually goes. */
99export const DEFAULT_DENY = [
100  'pastebin.com', 'paste.ee', 'hastebin.com', 'ghostbin.com', 'dpaste.com', 'dpaste.org',
101  'transfer.sh', 'file.io', '0x0.st', 'termbin.com', 'bashupload.com', 'temp.sh', 'oshi.at',
102  'anonfiles.com', 'gofile.io', 'webhook.site', 'requestbin.com', 'requestbin.net',
103  'requestcatcher.com', 'm.pipedream.net', 'beeceptor.com', 'hookbin.com', 'postb.in',
104  'ptsv2.com', 'ptsv3.com', 'ngrok.io', 'ngrok.app', 'ngrok-free.app', 'ngrok-free.dev',
105  'trycloudflare.com', 'serveo.net', 'localtunnel.me', 'loca.lt', 'interact.sh', 'oast.fun',
106  'oast.pro', 'oast.live', 'oast.site', 'oast.online', 'oast.me', 'burpcollaborator.net',
107  'oastify.com', 'dnslog.cn', 'ceye.io', 'discord.com/api/webhooks', 'discordapp.com/api/webhooks',
108  'api.telegram.org/bot',
109]
110

1// What to do about one request: no `$`, pure.
2
3import { DEFAULT_ALLOW, DEFAULT_DENY, isLocal, isPrivate, matches, parseList } from './hosts'
4import { carriesData, type Request } from './requests'
5
6export type Mode = 'ask' | 'allow' | 'deny'
7export type Action = 'allow' | 'ask' | 'deny'
8
9export type Policy = {
10  userAllow: string[]
11  userDeny: string[]
12  allow: string[]
13  deny: string[]
14  unknown: Mode
15  fetchUnknown: Mode
16  askUploads: 'unlisted' | 'always' | 'never'
17  allowPrivate: boolean
18}
19
20export type Decision = { action: Action; why: string; host: string | null }
21
22const mode = (value: unknown, fallback: Mode): Mode => (value === 'ask' || value === 'allow' || value === 'deny' ? value : fallback)
23
24/** The policy the plugin's options describe. */
25export function policyFrom(options: Readonly<Record<string, unknown>>): Policy {
26  const useDefaults = options.useDefaultLists !== false
27  const uploads = options.askUploads
28  return {
29    userAllow: parseList(String(options.allow ?? '')),
30    userDeny: parseList(String(options.deny ?? '')),
31    allow: useDefaults ? DEFAULT_ALLOW : [],
32    deny: useDefaults ? DEFAULT_DENY : [],
33    unknown: mode(options.unknown, 'ask'),
34    fetchUnknown: mode(options.fetchUnknown, 'allow'),
35    askUploads: uploads === 'always' || uploads === 'never' ? uploads : 'unlisted',
36    allowPrivate: options.allowPrivate !== false,
37  }
38}
39
40/**
41 * The verdict for one request. Order: your deny list, your allow list, the
42 * built-in deny list, then this machine, the built-in allow list and hosts
43 * allowed this session, private networks, and last the unknown-host modes.
44 */
45export function decide(request: Request, policy: Policy, sessionHosts: ReadonlySet<string>): Decision {
46  const target = request.target
47  if (target === null) {
48    const action = policy.unknown === 'allow' && !request.isUpload ? 'allow' : policy.unknown === 'deny' ? 'deny' : 'ask'
49    return { action, why: `connects to a host only known when it runs (${request.raw})`, host: null }
50  }
51  const host = target.host
52  const uploadVerb = request.isUpload ? 'sends data to' : 'connects to'
53
54  if (policy.userDeny.some(p => matches(target, p))) return { action: 'deny', why: `${uploadVerb} ${host}, which is on your deny list`, host }
55  const isUserAllowed = policy.userAllow.some(p => matches(target, p))
56  if (!isUserAllowed && policy.deny.some(p => matches(target, p))) {
57    return { action: 'deny', why: `${uploadVerb} ${host}, a paste, request-catcher or tunnel service often used to smuggle data out`, host }
58  }
59  if (isLocal(host)) return { action: 'allow', why: 'this machine', host }
60
61  const isListed = isUserAllowed || sessionHosts.has(host) || policy.allow.some(p => matches(target, p)) || (policy.allowPrivate && isPrivate(host))
62  if (request.isUpload && policy.askUploads === 'always') return { action: 'ask', why: `sends data to ${host}`, host }
63  if (isListed) return { action: 'allow', why: 'allowed', host }
64
65  if (request.isUpload && policy.askUploads === 'unlisted') {
66    return { action: policy.unknown === 'deny' ? 'deny' : 'ask', why: `sends data to ${host}, which isn't on the allow list`, host }
67  }
68  if (request.tool === 'WebFetch') {
69    if (policy.fetchUnknown !== 'deny' && carriesData(target)) return { action: 'ask', why: `fetches ${host} with what looks like data packed into the URL`, host }
70    return { action: policy.fetchUnknown, why: `fetches ${host}, which isn't on the allow list`, host }
71  }
72  return { action: policy.unknown, why: `connects to ${host}, which isn't on the allow list`, host }
73}
74
75const RANK: Record<Action, number> = { allow: 0, ask: 1, deny: 2 }
76
77/** The decisions for every request in a call, worst first. */
78export function judge(requests: readonly Request[], policy: Policy, sessionHosts: ReadonlySet<string>): Array<{ request: Request; decision: Decision }> {
79  return requests
80    .map(request => ({ request, decision: decide(request, policy, sessionHosts) }))
81    .sort((a, b) => RANK[b.decision.action] - RANK[a.decision.action])
82}
83

1// Finds the network requests a command line or a fetch would make: no `$`, pure.
2
3import { parseTarget, type Target } from './hosts'
4import { commandsIn } from './shell'
5
6export type Request = {
7  /** What makes the request: `curl`, `ssh`, `git push`, `WebFetch`... */
8  tool: string
9  /** Where it goes; `null` when only known at run time. */
10  target: Target | null
11  /** Whether it sends data (a body, a file, a push, a remote shell). */
12  isUpload: boolean
13  /** The word it came from, for messages. */
14  raw: string
15}
16
17const UPLOAD_METHODS = /^(POST|PUT|PATCH|DELETE)$/i
18
19/** Reads one command's flags: which take a value, and which of those mean "sends data". */
20function scan(args: readonly string[], valueLong: ReadonlySet<string>, valueShort: string) {
21  const operands: string[] = []
22  const values: Array<[flag: string, value: string]> = []
23  const flags: string[] = []
24  for (let i = 0; i < args.length; i++) {
25    const arg = args[i]!
26    if (arg === '--') {
27      operands.push(...args.slice(i + 1))
28      break
29    }
30    if (arg.startsWith('--')) {
31      const eq = arg.indexOf('=')
32      if (eq > 0) values.push([arg.slice(0, eq), arg.slice(eq + 1)])
33      else if (valueLong.has(arg) && i + 1 < args.length) values.push([arg, args[++i]!])
34      else flags.push(arg)
35      continue
36    }
37    if (arg.startsWith('-') && arg.length > 1) {
38      // A cluster like -sSLX POST or -d@body.json: a value flag takes the rest, or the next word.
39      for (let j = 1; j < arg.length; j++) {
40        const letter = arg[j]!
41        if (valueShort.includes(letter)) {
42          const rest = arg.slice(j + 1)
43          if (rest !== '') values.push([`-${letter}`, rest])
44          else if (i + 1 < args.length) values.push([`-${letter}`, args[++i]!])
45          break
46        }
47        flags.push(`-${letter}`)
48      }
49      continue
50    }
51    operands.push(arg)
52  }
53  const valueOf = (...names: string[]) => values.filter(([flag]) => names.includes(flag)).map(([, value]) => value)
54  const has = (...names: string[]) => flags.some(f => names.includes(f)) || values.some(([f]) => names.includes(f))
55  return { operands, valueOf, has }
56}
57
58const request = (tool: string, raw: string, isUpload: boolean): Request | undefined => {
59  const target = parseTarget(raw)
60  return target === undefined ? undefined : { tool, target, isUpload, raw }
61}
62
63const CURL_LONG = new Set([
64  '--request', '--header', '--data', '--data-ascii', '--data-binary', '--data-raw', '--data-urlencode', '--json',
65  '--form', '--form-string', '--output', '--user', '--user-agent', '--referer', '--cookie', '--cookie-jar',
66  '--upload-file', '--connect-timeout', '--max-time', '--write-out', '--proxy', '--resolve', '--connect-to',
67  '--config', '--cacert', '--capath', '--cert', '--key', '--range', '--continue-at', '--retry', '--retry-delay',
68  '--retry-max-time', '--limit-rate', '--time-cond', '--proxy-user', '--quote', '--url', '--max-filesize',
69  '--interface', '--dns-servers', '--output-dir', '--max-redirs', '--noproxy', '--oauth2-bearer', '--pass',
70  '--proxy-header', '--socks5', '--socks5-hostname', '--socks4', '--socks4a', '--preproxy', '--trace',
71  '--trace-ascii', '--stderr', '--variable', '--aws-sigv4', '--unix-socket', '--abstract-unix-socket',
72  '--mail-from', '--mail-rcpt', '--local-port', '--keepalive-time', '--expect100-timeout', '--ciphers',
73])
74
75function curl(args: readonly string[]): Request[] {
76  const { operands, valueOf, has } = scan(args, CURL_LONG, 'XHdFouAebcTmwxKErCYyzUQtPD')
77  if (has('--unix-socket', '--abstract-unix-socket')) return []
78  const isUpload =
79    has('-d', '--data', '--data-ascii', '--data-binary', '--data-raw', '--data-urlencode', '--json', '-F', '--form', '--form-string', '-T', '--upload-file') ||
80    valueOf('-X', '--request').some(method => UPLOAD_METHODS.test(method))
81  const urls = [...operands, ...valueOf('--url')]
82  const out = urls.map(url => request('curl', url, isUpload))
83  // A proxy sees everything the request carries.
84  for (const proxy of valueOf('-x', '--proxy', '--socks5', '--socks5-hostname', '--socks4', '--socks4a', '--preproxy')) out.push(request('curl proxy', proxy, isUpload))
85  return out.filter((r): r is Request => r !== undefined)
86}
87
88const WGET_LONG = new Set([
89  '--output-document', '--output-file', '--append-output', '--directory-prefix', '--user-agent', '--header',
90  '--post-data', '--post-file', '--body-data', '--body-file', '--method', '--user', '--password', '--http-user',
91  '--http-password', '--tries', '--timeout', '--wait', '--execute', '--input-file', '--base', '--load-cookies',
92  '--save-cookies', '--quota', '--limit-rate', '--level', '--accept', '--reject', '--domains', '--exclude-domains',
93  '--referer', '--ca-certificate', '--certificate', '--private-key', '--proxy-user', '--proxy-password',
94])
95
96function wget(args: readonly string[]): Request[] {
97  const { operands, valueOf, has } = scan(args, WGET_LONG, 'OoaPUtTweiBQlARDXI')
98  const isUpload = has('--post-data', '--post-file', '--body-data', '--body-file') || valueOf('--method').some(m => UPLOAD_METHODS.test(m))
99  const out = operands.map(url => request('wget', url, isUpload)).filter((r): r is Request => r !== undefined)
100  if (has('-i', '--input-file')) out.push({ tool: 'wget', target: null, isUpload, raw: 'URLs read from a file' })
101  return out
102}
103
104const HTTPIE_LONG = new Set(['--auth', '--auth-type', '--session', '--session-read-only', '--output', '--verify', '--cert', '--cert-key', '--timeout', '--proxy', '--pretty', '--style', '--print', '--format-options', '--boundary', '--raw', '--default-scheme', '--max-redirects', '--max-headers', '--response-charset', '--response-mime'])
105
106function httpie(name: string, args: readonly string[]): Request[] {
107  const { operands, has } = scan(args, HTTPIE_LONG, 'aospA')
108  let rest = operands
109  let method = ''
110  if (rest[0] !== undefined && /^[A-Z]+$/.test(rest[0])) {
111    method = rest[0]
112    rest = rest.slice(1)
113  }
114  const url = rest[0]
115  if (url === undefined) return []
116  const items = rest.slice(1)
117  // `name=value`, `name:=json` and `field@file` are a body; `Header:value` and `param==value` aren't.
118  const hasBody = has('--raw') || items.some(item => /^[^=:@\s]*(:=|=(?!=)|@)/.test(item) && !/^[^=:@\s]*==/.test(item))
119  const isUpload = UPLOAD_METHODS.test(method) || hasBody
120  // `http :3000/api` is localhost shorthand.
121  const raw = url.startsWith(':') ? `localhost${url}` : url
122  const r = request(name, raw, isUpload)
123  return r === undefined ? [] : [r]
124}
125
126function netcat(name: string, args: readonly string[]): Request[] {
127  const { operands, has } = scan(args, new Set(['--source', '--wait', '--exec', '--sh-exec', '--proxy', '--proxy-type']), 'pswxXeciqIOTVgGPo')
128  if (has('-l', '--listen')) return []
129  const host = operands[0]
130  if (host === undefined) return []
131  const r = request(name, host, !has('-z'))
132  return r === undefined ? [] : [r]
133}
134
135function ssh(args: readonly string[]): Request[] {
136  const { operands, valueOf } = scan(args, new Set(), 'bcDEeFIiJLlmOopQRSWwB')
137  const out: Request[] = []
138  const host = operands[0]
139  if (host !== undefined) {
140    const r = request('ssh', host.includes('://') ? host : `ssh://${host}`, true)
141    if (r !== undefined) out.push(r)
142  }
143  for (const jump of valueOf('-J').flatMap(v => v.split(','))) {
144    const r = request('ssh jump host', `ssh://${jump}`, true)
145    if (r !== undefined) out.push(r)
146  }
147  return out
148}
149
150/** `user@host:path`, `host:path` (with a dot or user, so `C:` and `a:b` files stay files) or `rsync://`. */
151function remoteSpec(word: string): string | undefined {
152  if (/^(rsync|sftp|scp|ssh):\/\//i.test(word)) return word
153  const m = word.match(/^(?:([^@/\s:]+)@)?([^:/\s@]+)::?(.*)$/)
154  if (m === null || word.startsWith('/') || word.startsWith('.')) return undefined
155  const [, user, host] = m
156  if (user === undefined && !host!.includes('.') && host !== 'localhost') return undefined
157  return `ssh://${user === undefined ? '' : `${user}@`}${host}`
158}
159
160const RSYNC_LONG = new Set(['--rsh', '--exclude', '--include', '--filter', '--files-from', '--password-file', '--port', '--temp-dir', '--chmod', '--chown', '--backup-dir', '--suffix', '--log-file', '--partial-dir', '--compare-dest', '--link-dest', '--copy-dest', '--timeout', '--contimeout', '--bwlimit', '--max-size', '--min-size', '--modify-window', '--out-format', '--iconv'])
161
162function copy(name: 'scp' | 'rsync', args: readonly string[]): Request[] {
163  const { operands } = name === 'scp' ? scan(args, new Set(), 'cFiJloPSX') : scan(args, RSYNC_LONG, 'efT')
164  const out: Request[] = []
165  operands.forEach((word, i) => {
166    const spec = remoteSpec(word)
167    if (spec === undefined) return
168    // The last operand is the destination: a remote one receives your files.
169    const r = request(name, spec, i === operands.length - 1 && operands.length > 1)
170    if (r !== undefined) out.push({ ...r, raw: word })
171  })
172  return out
173}
174
175/** A git remote URL (https, ssh, git or scp-like); a path or a remote's name isn't one. */
176function gitUrl(word: string): string | undefined {
177  if (/^(https?|ssh|git|git\+ssh):\/\//i.test(word)) return word
178  return remoteSpec(word)
179}
180
181function git(args: readonly string[]): Request[] {
182  let i = 0
183  while (args[i] !== undefined && args[i]!.startsWith('-')) i += args[i] === '-C' || args[i] === '-c' ? 2 : 1
184  const sub = args[i]
185  const rest = args.slice(i + 1).filter(a => !a.startsWith('-'))
186  const make = (word: string | undefined, tool: string, isUpload: boolean): Request[] => {
187    const url = word === undefined ? undefined : gitUrl(word)
188    const r = url === undefined ? undefined : request(tool, url, isUpload)
189    return r === undefined ? [] : [{ ...r, raw: word! }]
190  }
191  switch (sub) {
192    case 'clone':
193      return make(rest[0], 'git clone', false)
194    case 'fetch':
195    case 'pull':
196    case 'ls-remote':
197      return make(rest[0], `git ${sub}`, false)
198    case 'push':
199      return make(rest[0], 'git push', true)
200    case 'remote':
201      // A remote added now is pushed to later by name, which this can't follow, so check it here.
202      if (rest[0] === 'add') return make(rest[2], 'git remote add', true)
203      if (rest[0] === 'set-url') return make(rest[rest.length - 1], 'git remote set-url', true)
204      return []
205    case 'submodule':
206      return rest[0] === 'add' ? make(rest[1], 'git submodule add', false) : []
207    default:
208      return []
209  }
210}
211
212const INLINE_CODE: Record<string, readonly string[]> = {
213  python: ['-c'], python3: ['-c'], node: ['-e', '--eval', '-p', '--print'], bun: ['-e', '--eval'],
214  ruby: ['-e'], perl: ['-e', '-E'], php: ['-r'], deno: ['eval'],
215}
216
217/** Best effort: URL literals in `python -c`, `node -e` and friends. */
218function inlineCode(name: string, args: readonly string[]): Request[] {
219  const flags = INLINE_CODE[name.replace(/\d+(\.\d+)*$/, '') === 'python' ? 'python' : name]
220  if (flags === undefined) return []
221  const at = args.findIndex(a => flags.includes(a))
222  const code = at >= 0 ? args[at + 1] : undefined
223  if (code === undefined) return []
224  const isUpload = /\.(post|put|patch)\s*\(|method\s*[:=]\s*['"](POST|PUT|PATCH|DELETE)|\bdata\s*=|\bbody\s*:|urlopen\([^)]*,\s*\w/i.test(code)
225  const urls = code.match(/\b(?:https?|wss?):\/\/[^\s'"`)\]}>,]+/gi) ?? []
226  const out = urls.map(url => request(`${name} code`, url, isUpload)).filter((r): r is Request => r !== undefined)
227  if (out.length === 0 && /\b(requests|urllib|httpx|aiohttp|fetch|axios|http\.request|socket)\b/.test(code) && /\b(get|post|put|urlopen|fetch|request|connect)\s*\(/.test(code)) {
228    out.push({ tool: `${name} code`, target: null, isUpload, raw: 'a URL the code builds' })
229  }
230  return out
231}
232
233/** Every network request one Bash command line would make, as far as its words say. */
234export function requestsIn(line: string): Request[] {
235  const out: Request[] = []
236  for (const argv of commandsIn(line)) {
237    const name = argv[0]!.split('/').pop() ?? ''
238    const args = argv.slice(1)
239    if (name === 'curl') out.push(...curl(args))
240    else if (name === 'wget' || name === 'wget2') out.push(...wget(args))
241    else if (['http', 'https', 'xh', 'xhs'].includes(name)) out.push(...httpie(name, args))
242    else if (['nc', 'ncat', 'netcat', 'telnet'].includes(name)) out.push(...netcat(name, args))
243    else if (name === 'ssh' || name === 'mosh') out.push(...ssh(args))
244    else if (name === 'sftp' || name === 'ftp') {
245      const host = args.filter(a => !a.startsWith('-')).pop()
246      const r = host === undefined ? undefined : request(name, host.includes('://') ? host : `ssh://${host}`, true)
247      if (r !== undefined) out.push(r)
248    } else if (name === 'scp' || name === 'rsync') out.push(...copy(name, args))
249    else if (name === 'git') out.push(...git(args))
250    else out.push(...inlineCode(name, args))
251  }
252  return out
253}
254
255/** The request a WebFetch makes. */
256export function fetchRequest(url: string): Request[] {
257  const target = parseTarget(url)
258  return target === undefined ? [] : [{ tool: 'WebFetch', target, isUpload: false, raw: url }]
259}
260
261/**
262 * Whether a URL's path or query looks like it carries data out: a long
263 * opaque token (base64 with upper, lower and digits, or 40+ hex), not a slug.
264 */
265export function carriesData(target: Target): boolean {
266  return target.path.split(/[/?&=#;,]/).some(chunk => {
267    if (chunk.length < 32) return false
268    if (/^[0-9a-f]{40,}$/i.test(chunk)) return true
269    const classes = [/[a-z]/, /[A-Z]/, /\d/].filter(re => re.test(chunk)).length
270    return /^[A-Za-z0-9+/=_%.~-]+$/.test(chunk) && classes === 3 && !/^([A-Za-z]+-){3,}/.test(chunk)
271  })
272}
273

1// Just enough shell to find the commands in a command line: no `$`, pure.
2
3/** Splits one shell segment into words, honouring quotes and backslashes. */
4export function words(segment: string): string[] {
5  const out: string[] = []
6  let current = ''
7  let quote: '"' | "'" | null = null
8  let hasWord = false
9
10  for (let i = 0; i < segment.length; i++) {
11    const ch = segment[i] ?? ''
12    if (quote !== null) {
13      if (ch === quote) quote = null
14      else if (ch === '\\' && quote === '"' && i + 1 < segment.length) current += segment[++i]
15      else current += ch
16      continue
17    }
18    if (ch === '"' || ch === "'") {
19      quote = ch
20      hasWord = true
21    } else if (ch === '\\' && i + 1 < segment.length) {
22      current += segment[++i]
23      hasWord = true
24    } else if (/\s/.test(ch)) {
25      if (hasWord) out.push(current)
26      current = ''
27      hasWord = false
28    } else {
29      current += ch
30      hasWord = true
31    }
32  }
33  if (hasWord) out.push(current)
34
35  return out
36}
37
38/**
39 * Splits a command line at `;`, `&&`, `||`, `|`, `&` and newlines outside
40 * quotes, and lifts out `$(...)` and backtick substitutions, which run too.
41 */
42export function segments(command: string): { parts: string[]; inner: string[] } {
43  const parts: string[] = []
44  const inner: string[] = []
45  let current = ''
46  let quote: '"' | "'" | null = null
47
48  for (let i = 0; i < command.length; i++) {
49    const ch = command[i] ?? ''
50    const next = command[i + 1] ?? ''
51    if (ch === '\\' && quote !== "'") {
52      current += ch + next
53      i++
54      continue
55    }
56    if (quote === "'") {
57      if (ch === "'") quote = null
58      current += ch
59      continue
60    }
61    if (ch === '$' && next === '(' && command[i + 2] !== '(') {
62      let depth = 1
63      let j = i + 2
64      for (; j < command.length && depth > 0; j++) {
65        if (command[j] === '(') depth++
66        else if (command[j] === ')') depth--
67      }
68      inner.push(command.slice(i + 2, j - 1))
69      current += command.slice(i, j)
70      i = j - 1
71      continue
72    }
73    if (ch === '`') {
74      const end = command.indexOf('`', i + 1)
75      const stop = end < 0 ? command.length : end
76      inner.push(command.slice(i + 1, stop))
77      current += command.slice(i, stop + 1)
78      i = stop
79      continue
80    }
81    if (quote === '"') {
82      if (ch === '"') quote = null
83      current += ch
84      continue
85    }
86    if (ch === '"' || ch === "'") {
87      quote = ch
88      current += ch
89      continue
90    }
91    const isAmp = ch === '&' && next !== '>' && command[i - 1] !== '>' && command[i - 1] !== '<'
92    if (ch === ';' || ch === '\n' || ch === '|' || isAmp) {
93      parts.push(current)
94      current = ''
95      if ((ch === '|' && next === '|') || (ch === '&' && next === '&')) i++
96      continue
97    }
98    current += ch
99  }
100  parts.push(current)
101
102  return { parts: parts.map(p => p.trim()).filter(p => p !== ''), inner }
103}
104
105// Commands that run the rest of their words as a command.
106const WRAPPERS = new Set(['sudo', 'doas', 'command', 'exec', 'nohup', 'time', 'nice', 'env', 'xargs', 'builtin', 'timeout', 'stdbuf', 'caffeinate', 'proxychains', 'proxychains4', 'torsocks'])
107
108/** Drops leading `VAR=value` words and wrapper commands, so argv[0] is the real command. */
109export function unwrap(argv: readonly string[]): string[] {
110  let rest = [...argv]
111  for (;;) {
112    const head = rest[0]
113    if (head === undefined) break
114    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(head)) {
115      rest = rest.slice(1)
116      continue
117    }
118    const name = head.split('/').pop() ?? head
119    if (!WRAPPERS.has(name)) break
120    rest = rest.slice(1)
121    while (rest[0] !== undefined && (rest[0].startsWith('-') || /^\d+[smhd]?$/.test(rest[0]))) {
122      const flag = rest[0]
123      rest = rest.slice(1)
124      if (['-u', '-n', '-g', '-I', '-s'].includes(flag) && rest[0] !== undefined) rest = rest.slice(1)
125    }
126  }
127  return rest
128}
129
130/** Every command a command line runs, as argv lists, substitutions included. */
131export function commandsIn(line: string, depth = 0): string[][] {
132  const { parts, inner } = segments(line)
133  const out: string[][] = []
134  for (const part of parts) {
135    const argv = unwrap(words(part.replace(/^[({\s!]+|[)}\s]+$/g, '')))
136    if (argv.length === 0) continue
137    out.push(argv)
138    // `bash -c "..."` and `eval "..."` run their argument as a command line.
139    const name = argv[0]!.split('/').pop() ?? ''
140    if (depth < 3 && ['bash', 'sh', 'zsh', 'dash', 'ksh'].includes(name)) {
141      const at = argv.indexOf('-c')
142      const script = at >= 0 ? argv[at + 1] : undefined
143      if (script !== undefined) out.push(...commandsIn(script, depth + 1))
144    }
145    if (depth < 3 && name === 'eval' && argv.length > 1) out.push(...commandsIn(argv.slice(1).join(' '), depth + 1))
146  }
147  if (depth < 3) for (const sub of inner) out.push(...commandsIn(sub, depth + 1))
148  return out
149}
150