@capybara-hq/device 0.1.0-rc.17 → 0.1.0-rc.19

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.
Files changed (107) hide show
  1. package/README.md +143 -32
  2. package/dist/activity.d.ts +31 -0
  3. package/dist/activity.js +62 -0
  4. package/dist/api.d.ts +3 -3
  5. package/dist/args.d.ts +25 -4
  6. package/dist/args.js +82 -21
  7. package/dist/cli.js +14 -3
  8. package/dist/client.js +1 -1
  9. package/dist/commands/ceiling.d.ts +3 -2
  10. package/dist/commands/ceiling.js +60 -20
  11. package/dist/commands/keep-awake.d.ts +19 -0
  12. package/dist/commands/keep-awake.js +77 -0
  13. package/dist/commands/login.d.ts +15 -11
  14. package/dist/commands/login.js +75 -49
  15. package/dist/commands/policy.js +16 -10
  16. package/dist/commands/service.d.ts +3 -1
  17. package/dist/commands/service.js +35 -2
  18. package/dist/commands/start.d.ts +18 -3
  19. package/dist/commands/start.js +144 -9
  20. package/dist/commands/status.d.ts +8 -1
  21. package/dist/commands/status.js +59 -7
  22. package/dist/control/client.d.ts +12 -0
  23. package/dist/control/client.js +63 -0
  24. package/dist/control/protocol.d.ts +58 -0
  25. package/dist/control/protocol.js +16 -0
  26. package/dist/control/server.d.ts +28 -0
  27. package/dist/control/server.js +254 -0
  28. package/dist/exec/docker-operations.d.ts +14 -2
  29. package/dist/exec/docker-operations.js +32 -5
  30. package/dist/exec/linux-agent.d.ts +13 -3
  31. package/dist/exec/linux-agent.js +450 -43
  32. package/dist/exec/linux-operation-backend.d.ts +27 -6
  33. package/dist/exec/linux-operation-backend.js +30 -9
  34. package/dist/exec/linux-operation-worker.d.ts +51 -3
  35. package/dist/exec/linux-operation-worker.js +55 -3
  36. package/dist/exec/linux-runtime.d.ts +3 -2
  37. package/dist/exec/linux-runtime.js +4 -2
  38. package/dist/exec/mac-operation-backend.d.ts +12 -2
  39. package/dist/exec/mac-operation-backend.js +19 -10
  40. package/dist/exec/mac-write-policy.d.ts +2 -0
  41. package/dist/exec/mac-write-policy.js +1 -1
  42. package/dist/exec/operation-supervisor.d.ts +6 -0
  43. package/dist/exec/operation-supervisor.js +10 -0
  44. package/dist/exec/operation-types.d.ts +35 -5
  45. package/dist/exec/operation-types.js +73 -23
  46. package/dist/exec/operation-worker.d.ts +80 -1
  47. package/dist/exec/operation-worker.js +197 -14
  48. package/dist/exec/protected-targets.d.ts +16 -0
  49. package/dist/exec/protected-targets.js +53 -0
  50. package/dist/exec/shared.d.ts +7 -3
  51. package/dist/exec/shared.js +7 -5
  52. package/dist/index.d.ts +2 -0
  53. package/dist/index.js +1 -0
  54. package/dist/keep-awake.d.ts +39 -0
  55. package/dist/keep-awake.js +104 -0
  56. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +343 -7
  57. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/resolved-address-guard.js +220 -6
  58. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +17 -0
  59. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +11 -0
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +77 -46
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +206 -83
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +5 -2
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +5 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.d.ts +98 -0
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.js +291 -0
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-linux-runtime-source.js +460 -28
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-native-runtime-source.js +143 -3
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +36 -4
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.js +21 -4
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-runtime-source.js +2 -2
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.d.ts +87 -8
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.js +249 -10
  74. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox.d.ts +11 -22
  75. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
  76. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
  77. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
  78. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
  79. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
  80. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
  81. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
  82. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  83. package/dist/owner-report.d.ts +1 -1
  84. package/dist/owner-report.js +5 -4
  85. package/dist/policy-store.d.ts +2 -1
  86. package/dist/policy-store.js +2 -1
  87. package/dist/policy.d.ts +23 -14
  88. package/dist/policy.js +28 -21
  89. package/dist/runtime-manifest.json +1 -1
  90. package/dist/server-ops.d.ts +33 -5
  91. package/dist/server-ops.js +138 -85
  92. package/dist/service/launchd.d.ts +2 -0
  93. package/dist/service/launchd.js +10 -4
  94. package/dist/service/manager.d.ts +2 -0
  95. package/dist/service/manager.js +16 -2
  96. package/dist/service/systemd.d.ts +2 -0
  97. package/dist/service/systemd.js +8 -2
  98. package/dist/staged-connect.d.ts +10 -1
  99. package/dist/staged-connect.js +25 -3
  100. package/dist/staged-device.d.ts +1 -1
  101. package/dist/staged-device.js +13 -5
  102. package/dist/staged-session.d.ts +1 -1
  103. package/dist/state.d.ts +50 -21
  104. package/dist/state.js +111 -46
  105. package/dist/wake.d.ts +23 -0
  106. package/dist/wake.js +29 -0
  107. package/package.json +2 -2
@@ -1,3 +1,4 @@
1
+ import { SANDBOX_FAKE_IP_DNS } from "@capybara-hq/plugin-sdk";
1
2
  /**
2
3
  * The trusted Linux operation agent of capybara-device, run as `python3 -I -c <source>` (never from
3
4
  * a file another process could change). One agent process runs one operation; it never decides
@@ -12,9 +13,19 @@
12
13
  * base64, at most 64 KiB), `native`, `probe`, `reaped`, `refused`, `exit`.
13
14
  *
14
15
  * - restricted exec: pins every granted root once (no-follow, canonical), runs the SDK launcher on
15
- * those descriptors (Landlock rules, the seccomp broker), and for an allowlist gives it exactly
16
- * one endpoint, a loopback proxy owned by this operation that tunnels only the allowlisted names.
17
- * Whatever ends the launcher, the agent then reaps its closed session (exact SID plus start time).
16
+ * those descriptors (Landlock rules, the seccomp broker), and for an allowlist or the open
17
+ * network gives it exactly one endpoint, a loopback proxy owned by this operation: it tunnels
18
+ * only the allowlisted names, or (open) any name and address literal on any port, and dials only
19
+ * resolved addresses the SDK's address-class table calls public (a copy kept equal by a test),
20
+ * never this host's own nor one of the request's extra closed addresses (a local-Docker
21
+ * device's host), re-resolving a fake-IP resolver's answers through encrypted DNS. A command
22
+ * connects to nothing else, not even its own loopback listener. Whatever ends the launcher, the agent then reaps its closed session (exact SID plus
23
+ * start time). Write denies the device resolved for this operation (protected home locations
24
+ * reached through links) go to the launcher and to native work. The agent opens the device's
25
+ * files lock (a private file at the path the device chose, outside every sandbox) and hands its
26
+ * descriptor to the launcher only, so every operation of the device shares one write lock.
27
+ * A restricted native write takes the same lock in this process (shared, from its check to its
28
+ * effect), and the native helper checks each entry it creates again where it landed.
18
29
  * - Full exec: no restricted filters; the command runs as the OS user in a session of its own, and
19
30
  * the agent ends that session (exact SID plus start time) when it exits, is cancelled or times out.
20
31
  * - native: the SDK native helper on pinned descriptors (descriptor-relative, no-follow), in this
@@ -46,6 +57,7 @@ import errno
46
57
  import fcntl
47
58
  import hashlib
48
59
  import hmac
60
+ import http.client
49
61
  import importlib.machinery
50
62
  import importlib.util
51
63
  import ipaddress
@@ -54,13 +66,17 @@ import os
54
66
  import select
55
67
  import signal
56
68
  import socket
69
+ import ssl
57
70
  import stat
71
+ import struct
58
72
  import subprocess
59
73
  import threading
60
74
  import time
75
+ import urllib.parse
61
76
 
62
77
  CHUNK = 65536
63
- NAT64 = ipaddress.ip_network("64:ff9b::/96")
78
+ # Concurrent proxy connections per operation (each holds two threads); more get a 503.
79
+ MAX_PROXY_CONNECTIONS = 128
64
80
  RUNTIME_FILES = ("linux-sandbox.py", "native-files.py")
65
81
  NR_PIDFD_OPEN = 434
66
82
  NR_PIDFD_SEND_SIGNAL = 424
@@ -330,7 +346,286 @@ def pin_roots(request, create_for=None):
330
346
  return read, write, missing
331
347
 
332
348
 
333
- # ---- per-operation allowlist proxy --------------------------------------------------------
349
+ # ---- address classes (a copy of the SDK's network-classes.ts) ------------------------------
350
+ # ADDRESS_CLASS_RANGES is the SDK's table, copied exactly, and classify_address its lookup: an
351
+ # address has the class of the first (most specific) range containing it; an embedded range
352
+ # classifies the IPv4 address at its bit offset. A device test (linux-agent-network.test.ts)
353
+ # compares this copy with the SDK's table and this lookup with classifyAddress, so the classes
354
+ # cannot drift between the SDK, the macOS worker, the cloud proxies and this forwarder.
355
+ ADDRESS_CLASS_RANGES = json.loads(r'''
356
+ [
357
+ {"family":"ipv4","cidr":"100.100.100.200/32","class":"metadata"},
358
+ {"family":"ipv4","cidr":"168.63.129.16/32","class":"metadata"},
359
+ {"family":"ipv4","cidr":"169.254.169.254/32","class":"metadata"},
360
+ {"family":"ipv4","cidr":"255.255.255.255/32","class":"broadcast"},
361
+ {"family":"ipv4","cidr":"192.0.0.0/24","class":"reserved"},
362
+ {"family":"ipv4","cidr":"192.0.2.0/24","class":"reserved"},
363
+ {"family":"ipv4","cidr":"192.88.99.0/24","class":"reserved"},
364
+ {"family":"ipv4","cidr":"198.51.100.0/24","class":"reserved"},
365
+ {"family":"ipv4","cidr":"203.0.113.0/24","class":"reserved"},
366
+ {"family":"ipv4","cidr":"169.254.0.0/16","class":"link-local"},
367
+ {"family":"ipv4","cidr":"192.168.0.0/16","class":"private"},
368
+ {"family":"ipv4","cidr":"198.18.0.0/15","class":"reserved"},
369
+ {"family":"ipv4","cidr":"172.16.0.0/12","class":"private"},
370
+ {"family":"ipv4","cidr":"100.64.0.0/10","class":"cgnat"},
371
+ {"family":"ipv4","cidr":"0.0.0.0/8","class":"unspecified"},
372
+ {"family":"ipv4","cidr":"10.0.0.0/8","class":"private"},
373
+ {"family":"ipv4","cidr":"127.0.0.0/8","class":"loopback"},
374
+ {"family":"ipv4","cidr":"224.0.0.0/4","class":"multicast"},
375
+ {"family":"ipv4","cidr":"240.0.0.0/4","class":"reserved"},
376
+ {"family":"ipv4","cidr":"0.0.0.0/0","class":"public"},
377
+ {"family":"ipv6","cidr":"::/128","class":"unspecified"},
378
+ {"family":"ipv6","cidr":"::1/128","class":"loopback"},
379
+ {"family":"ipv6","cidr":"fd00:ec2::254/128","class":"metadata"},
380
+ {"family":"ipv6","cidr":"::ffff:0:0/96","embeddedIpv4At":96},
381
+ {"family":"ipv6","cidr":"::ffff:0:0:0/96","embeddedIpv4At":96},
382
+ {"family":"ipv6","cidr":"64:ff9b::/96","class":"nat64"},
383
+ {"family":"ipv6","cidr":"::/96","embeddedIpv4At":96},
384
+ {"family":"ipv6","cidr":"100::/64","class":"reserved"},
385
+ {"family":"ipv6","cidr":"64:ff9b:1::/48","class":"nat64"},
386
+ {"family":"ipv6","cidr":"2001:db8::/32","class":"reserved"},
387
+ {"family":"ipv6","cidr":"2001::/23","class":"reserved"},
388
+ {"family":"ipv6","cidr":"3fff::/20","class":"reserved"},
389
+ {"family":"ipv6","cidr":"2002::/16","embeddedIpv4At":16},
390
+ {"family":"ipv6","cidr":"fe80::/10","class":"link-local"},
391
+ {"family":"ipv6","cidr":"fec0::/10","class":"reserved"},
392
+ {"family":"ipv6","cidr":"ff00::/8","class":"multicast"},
393
+ {"family":"ipv6","cidr":"fc00::/7","class":"ula"},
394
+ {"family":"ipv6","cidr":"2000::/3","class":"public"},
395
+ {"family":"ipv6","cidr":"::/0","class":"reserved"}
396
+ ]
397
+ ''')
398
+ _CLASS_RANGES = [(ipaddress.ip_network(r["cidr"]), r.get("class"), r.get("embeddedIpv4At"))
399
+ for r in ADDRESS_CLASS_RANGES]
400
+
401
+
402
+ def classify_address(address):
403
+ """The class of an IPv4 or IPv6 address (a string, optionally with a zone, or an address)."""
404
+ if isinstance(address, str):
405
+ address = ipaddress.ip_address(address.split("%")[0])
406
+ for network, cls, at in _CLASS_RANGES:
407
+ if network.version != address.version or address not in network:
408
+ continue
409
+ if cls is not None:
410
+ return cls
411
+ return classify_address(ipaddress.IPv4Address((int(address) >> (96 - at)) & 0xFFFFFFFF))
412
+ raise ValueError("The address-class table is not total")
413
+ # ---- end of address classes ----------------------------------------------------------------
414
+
415
+
416
+ # ---- resolution ----------------------------------------------------------------------------
417
+ # Which resolved addresses the forwarder may dial, and the encrypted DNS it uses when the network's
418
+ # resolver answers with fake IPs. Self-contained (a device test runs it with the class block).
419
+
420
+ def local_address(address):
421
+ """Whether address is one of this host's own (a socket can bind to it). Any answer but "not
422
+ available" counts as own, so a host that allows binding any address (ip_nonlocal_bind) closes
423
+ every address instead of opening its own."""
424
+ probe = socket.socket(socket.AF_INET6 if ":" in address else socket.AF_INET,
425
+ socket.SOCK_STREAM)
426
+ try:
427
+ probe.bind((address, 0))
428
+ return True
429
+ except OSError as error:
430
+ return error.errno != errno.EADDRNOTAVAIL
431
+ finally:
432
+ probe.close()
433
+
434
+
435
+ def closed_set(addresses):
436
+ """Extra closed addresses (a local-Docker device's host addresses), normalized: an IPv4-mapped
437
+ form is its IPv4 address."""
438
+ out = set()
439
+ for address in addresses:
440
+ ip = ipaddress.ip_address(address.split("%")[0])
441
+ out.add(ip.ipv4_mapped if ip.version == 6 and ip.ipv4_mapped else ip)
442
+ return frozenset(out)
443
+
444
+
445
+ def public_address(address, closed=frozenset()):
446
+ """Whether the forwarder may dial a resolved address: the class table calls it public,
447
+ Python's own registry calls it global too (a stricter second opinion: Python versions differ
448
+ at the edges, which can only refuse more), it is not this host's own, and not one of the extra
449
+ closed addresses (the host of a device's container: its own addresses are not the
450
+ container's)."""
451
+ ip = ipaddress.ip_address(address.split("%")[0])
452
+ if classify_address(ip) != "public":
453
+ return False
454
+ plain = ip.ipv4_mapped if ip.version == 6 and ip.ipv4_mapped else ip
455
+ return plain.is_global and plain not in closed and not local_address(str(ip))
456
+
457
+
458
+ # The SDK's SANDBOX_FAKE_IP_DNS (the macOS worker uses the same endpoints and limits).
459
+ FAKE_IP_DNS = json.loads(r"""${JSON.stringify(SANDBOX_FAKE_IP_DNS)}""")
460
+ FAKE_IP_NETWORK = ipaddress.ip_network(FAKE_IP_DNS["fakeIpCidr"])
461
+ FAKE_IP_REFUSAL = ("The network's DNS resolver answers with fake IPs (198.18.0.0/15, a fake-IP "
462
+ "resolver such as a router's proxy) and encrypted DNS did not answer; the fake "
463
+ "address is never dialled")
464
+
465
+
466
+ class FakeIpUnresolved(PermissionError):
467
+ """The system resolver gave a fake IP and encrypted DNS failed: refused, never dialled."""
468
+
469
+
470
+ def fake_ip(address):
471
+ ip = ipaddress.ip_address(address.split("%")[0])
472
+ if ip.version == 6 and ip.ipv4_mapped:
473
+ ip = ip.ipv4_mapped
474
+ return ip in FAKE_IP_NETWORK
475
+
476
+
477
+ def dns_query(name, qtype):
478
+ """A recursive DNS query in wire format (ID 0, as RFC 8484 recommends) for name and qtype."""
479
+ out = struct.pack(">HHHHHH", 0, 0x0100, 1, 0, 0, 0)
480
+ for label in name.rstrip(".").split("."):
481
+ data = label.encode("ascii")
482
+ if not 0 < len(data) < 64:
483
+ raise ValueError("Not a DNS name")
484
+ out += bytes([len(data)]) + data
485
+ return out + b"\0" + struct.pack(">HH", qtype, 1)
486
+
487
+
488
+ def _skip_name(data, at):
489
+ while True:
490
+ length = data[at]
491
+ if length == 0:
492
+ return at + 1
493
+ if length & 0xC0 == 0xC0:
494
+ return at + 2
495
+ at += 1 + length
496
+
497
+
498
+ def dns_answers(data, qtype):
499
+ """(addresses, smallest TTL) of a DNS response's records of qtype (A or AAAA, class IN). An
500
+ error response or a malformed message raises ValueError; a missing name answers nothing."""
501
+ try:
502
+ _, flags, questions, answers, _, _ = struct.unpack_from(">HHHHHH", data)
503
+ if not flags & 0x8000 or flags & 0xF not in (0, 3):
504
+ raise ValueError("DNS error response")
505
+ at = 12
506
+ for _ in range(questions):
507
+ at = _skip_name(data, at) + 4
508
+ found, ttl = [], None
509
+ for _ in range(answers):
510
+ at = _skip_name(data, at)
511
+ rtype, rclass, record_ttl, length = struct.unpack_from(">HHIH", data, at)
512
+ at += 10
513
+ record = data[at:at + length]
514
+ at += length
515
+ if len(record) != length:
516
+ raise ValueError("Truncated DNS answer")
517
+ if rclass == 1 and rtype == qtype and length == (4 if qtype == 1 else 16):
518
+ found.append(str(ipaddress.ip_address(record)))
519
+ ttl = record_ttl if ttl is None else min(ttl, record_ttl)
520
+ return found, ttl
521
+ except (struct.error, IndexError):
522
+ raise ValueError("Malformed DNS message")
523
+
524
+
525
+ class EncryptedDns:
526
+ """DNS-over-HTTPS (RFC 8484, GET, wire format) at FAKE_IP_DNS's IP-literal endpoints, in order;
527
+ TLS is verified against the endpoint's IP SAN, so reaching it needs no DNS. One deadline per
528
+ name covers A and AAAA at every endpoint; each endpoint gets an equal share of the time left,
529
+ which its two queries share. An answer is cached only when both queries succeeded at one
530
+ endpoint, for its TTL (capped), at most cacheMaxNames names (the oldest goes first). Raises
531
+ FakeIpUnresolved when no endpoint answers in time. A test fixture's seam replaces the endpoints
532
+ and the trusted certificate (or fetch itself)."""
533
+
534
+ def __init__(self, endpoints=None, ca_pem=None, fetch=None, clock=time.monotonic):
535
+ self.endpoints = list(endpoints or FAKE_IP_DNS["endpoints"])
536
+ self.deadline = FAKE_IP_DNS["timeoutMs"] / 1000
537
+ self.cap = FAKE_IP_DNS["cacheTtlCapSeconds"]
538
+ self.max_names = FAKE_IP_DNS["cacheMaxNames"]
539
+ self.ca_pem = ca_pem
540
+ self.fetch = fetch or self.https
541
+ self.clock = clock
542
+ self.cache = {}
543
+ self.lock = threading.Lock()
544
+
545
+ def https(self, url, query, timeout):
546
+ parts = urllib.parse.urlsplit(url)
547
+ context = ssl.create_default_context(cadata=self.ca_pem) if self.ca_pem \
548
+ else ssl.create_default_context()
549
+ connection = http.client.HTTPSConnection(parts.hostname, parts.port or 443,
550
+ timeout=timeout, context=context)
551
+ try:
552
+ dns = base64.urlsafe_b64encode(query).decode().rstrip("=")
553
+ connection.request("GET", "%s?dns=%s" % (parts.path, dns),
554
+ headers={"Accept": "application/dns-message"})
555
+ response = connection.getresponse()
556
+ body = response.read(65536)
557
+ if response.status != 200:
558
+ raise OSError(errno.EPROTO, "DoH answered %d" % response.status)
559
+ return body
560
+ finally:
561
+ connection.close()
562
+
563
+ def resolve(self, name):
564
+ key = name.lower().rstrip(".")
565
+ with self.lock:
566
+ cached = self.cache.get(key)
567
+ if cached and cached[0] > self.clock():
568
+ return list(cached[1])
569
+ end = self.clock() + self.deadline
570
+ for index, url in enumerate(self.endpoints):
571
+ share_end = self.clock() + (end - self.clock()) / (len(self.endpoints) - index)
572
+ try:
573
+ addresses, ttl = [], self.cap
574
+ for qtype in (1, 28):
575
+ left = share_end - self.clock()
576
+ if left <= 0:
577
+ raise OSError(errno.ETIMEDOUT, "The endpoint's share of the deadline ran out")
578
+ answer = self.fetch(url, dns_query(key, qtype), left)
579
+ found, record_ttl = dns_answers(answer, qtype)
580
+ addresses += found
581
+ if record_ttl is not None:
582
+ ttl = min(ttl, record_ttl)
583
+ except (OSError, ValueError, http.client.HTTPException):
584
+ continue
585
+ with self.lock:
586
+ self.cache.pop(key, None)
587
+ while len(self.cache) >= self.max_names:
588
+ del self.cache[next(iter(self.cache))]
589
+ self.cache[key] = (self.clock() + ttl, list(addresses))
590
+ return addresses
591
+ raise FakeIpUnresolved(errno.EACCES, FAKE_IP_REFUSAL)
592
+
593
+
594
+ def vetted_addresses(host, port, doh, allow_private=False, resolve=socket.getaddrinfo,
595
+ closed=frozenset()):
596
+ """The getaddrinfo entries of host the forwarder may dial. When the system resolver answers a
597
+ name with a fake IP, the name is resolved again through encrypted DNS (doh) and only those
598
+ answers count: the fake address is never dialled. Raises PermissionError when every address
599
+ is refused (FakeIpUnresolved when encrypted DNS failed)."""
600
+ entries = resolve(host, port, 0, socket.SOCK_STREAM)
601
+ literal = True
602
+ try:
603
+ ipaddress.ip_address(host.split("%")[0])
604
+ except ValueError:
605
+ literal = False
606
+ if not literal and any(fake_ip(e[4][0]) for e in entries):
607
+ try:
608
+ answers = doh.resolve(host)
609
+ except PermissionError:
610
+ raise
611
+ except (OSError, ValueError):
612
+ raise FakeIpUnresolved(errno.EACCES, FAKE_IP_REFUSAL)
613
+ entries = []
614
+ for address in answers:
615
+ if ":" in address:
616
+ entries.append((socket.AF_INET6, socket.SOCK_STREAM, 6, "", (address, port, 0, 0)))
617
+ else:
618
+ entries.append((socket.AF_INET, socket.SOCK_STREAM, 6, "", (address, port)))
619
+ if not entries:
620
+ raise OSError(errno.EHOSTUNREACH, "Encrypted DNS has no address for the name")
621
+ permitted = [e for e in entries if allow_private or public_address(e[4][0], closed)]
622
+ if not permitted:
623
+ raise PermissionError(errno.EACCES, "No permitted address")
624
+ return permitted
625
+ # ---- end of resolution ---------------------------------------------------------------------
626
+
627
+
628
+ # ---- per-operation proxy (allowlist or open) ----------------------------------------------
334
629
 
335
630
  def host_allowed(host, hosts):
336
631
  host = host.lower().rstrip(".")
@@ -343,10 +638,21 @@ def host_allowed(host, hosts):
343
638
  return False
344
639
 
345
640
 
346
- def split_target(target, default_port):
641
+ def split_target(target, default_port, literals=False):
642
+ """(host, port) of a request target; an IPv6 literal in brackets only when literals is set
643
+ (allowlist hosts are names, never address literals)."""
347
644
  if target.startswith("["):
348
- return None, None # allowlist hosts are names, never address literals
349
- host, _, port = target.partition(":")
645
+ end = target.find("]")
646
+ if not literals or end < 0 or (len(target) > end + 1 and target[end + 1] != ":"):
647
+ return None, None
648
+ host, port = target[1:end], target[end + 2:]
649
+ try:
650
+ if ipaddress.ip_address(host).version != 6:
651
+ return None, None
652
+ except ValueError:
653
+ return None, None
654
+ else:
655
+ host, _, port = target.partition(":")
350
656
  try:
351
657
  number = int(port) if port else default_port
352
658
  except ValueError:
@@ -357,16 +663,27 @@ def split_target(target, default_port):
357
663
 
358
664
 
359
665
  class Forwarder:
360
- """A loopback HTTP proxy owned by one operation: CONNECT and absolute http:// requests for the
361
- operation's allowlisted names are tunnelled; every other name is refused without connecting.
362
- The launcher's broker grants the restricted command this endpoint and nothing else. Clients
363
- authenticate with the operation's token; CONNECT reaches ports 80 and 443 and plain requests
364
- port 80 only (allowlist entries name no port); a name is reached only at a globally routable
365
- address. A test fixture's seam (allow_private) lifts the address and port rules."""
366
-
367
- def __init__(self, hosts, allow_private=False):
666
+ """A loopback HTTP proxy owned by one operation. Allowlist: CONNECT and absolute http://
667
+ requests for the operation's allowlisted names are tunnelled, CONNECT to ports 80 and 443 and
668
+ plain requests to port 80 only (allowlist entries name no port); every other name is refused
669
+ without connecting. Open (the open public network): any name or address literal, on any
670
+ port. Either way a connection is made only to a resolved address public_address allows,
671
+ checked on the address dialled, which is never resolved again (so never rebound); when every
672
+ address is refused the answer is 403, before any connect. The launcher's broker grants the
673
+ restricted command this endpoint and nothing else. At most MAX_PROXY_CONNECTIONS connections
674
+ are served at once (more get a 503). Clients
675
+ authenticate with the operation's token. A test fixture's seam (allow_private) lifts the
676
+ address and port rules."""
677
+
678
+ def __init__(self, hosts, allow_private=False, open_network=False, doh=None,
679
+ closed=frozenset()):
368
680
  self.hosts = hosts
681
+ self.closed = closed
682
+ self.slots = threading.BoundedSemaphore(MAX_PROXY_CONNECTIONS)
369
683
  self.allow_private = allow_private
684
+ self.open = open_network
685
+ # encrypted DNS for a network whose resolver answers with fake IPs (one per operation)
686
+ self.doh = doh or EncryptedDns()
370
687
  # Only this operation knows the token: another local process cannot use the proxy.
371
688
  self.token = os.urandom(16).hex()
372
689
  self.authorization = "Basic " + base64.b64encode(
@@ -383,7 +700,22 @@ class Forwarder:
383
700
  client, _ = self.server.accept()
384
701
  except OSError:
385
702
  return
386
- threading.Thread(target=self.handle, args=(client,), daemon=True).start()
703
+ # a bounded number of connections per operation (each holds two threads)
704
+ if not self.slots.acquire(blocking=False):
705
+ try:
706
+ client.sendall(b"HTTP/1.1 503 Service Unavailable\r\nContent-Length: 0\r\n"
707
+ b"Connection: close\r\n\r\n")
708
+ except OSError:
709
+ pass
710
+ client.close()
711
+ continue
712
+ threading.Thread(target=self.serve, args=(client,), daemon=True).start()
713
+
714
+ def serve(self, client):
715
+ try:
716
+ self.handle(client)
717
+ finally:
718
+ self.slots.release()
387
719
 
388
720
  @staticmethod
389
721
  def splice(a, b):
@@ -429,15 +761,17 @@ class Forwarder:
429
761
  client.close()
430
762
  return
431
763
  rewritten = None
764
+ any_port = self.open or self.allow_private
432
765
  if method == "CONNECT":
433
- host, port = split_target(target, 443)
434
- # allowlist entries name no port: web ports only (any port for a test fixture)
435
- if port not in (80, 443) and not self.allow_private:
766
+ host, port = split_target(target, 443, self.open)
767
+ # allowlist entries name no port: web ports only (any port when open, or for a
768
+ # test fixture)
769
+ if port not in (80, 443) and not any_port:
436
770
  host = None
437
771
  elif target.startswith("http://"):
438
772
  authority, _, path = target[7:].partition("/")
439
- host, port = split_target(authority, 80)
440
- if port != 80 and not self.allow_private:
773
+ host, port = split_target(authority, 80, self.open)
774
+ if port != 80 and not any_port:
441
775
  host = None
442
776
  headers = [line for line in lines[1:]
443
777
  if not line.lower().startswith((b"proxy-", b"connection:"))]
@@ -445,14 +779,24 @@ class Forwarder:
445
779
  headers + [b"Connection: close"]) + b"\r\n\r\n"
446
780
  else:
447
781
  host, port = None, None
448
- if host is None or not host_allowed(host, self.hosts):
782
+ if host is None or not (self.open or host_allowed(host, self.hosts)):
449
783
  client.sendall(b"HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\n"
450
784
  b"Connection: close\r\n\r\n")
451
785
  client.close()
452
786
  return
453
787
  try:
454
788
  up = self.connect(host, port)
455
- except OSError:
789
+ except PermissionError as error:
790
+ # every address of the name is closed: refused before any connect (a fake-IP
791
+ # resolver without an encrypted DNS answer says so)
792
+ reason = FAKE_IP_REFUSAL.encode() if isinstance(error, FakeIpUnresolved) else b""
793
+ client.sendall(b"HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\n"
794
+ b"Content-Length: %d\r\nConnection: close\r\n\r\n"
795
+ % len(reason) + reason)
796
+ client.close()
797
+ return
798
+ except (OSError, ValueError):
799
+ # a failed lookup or dial; ValueError: a name the resolver cannot encode (IDNA)
456
800
  client.sendall(b"HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\n"
457
801
  b"Connection: close\r\n\r\n")
458
802
  client.close()
@@ -466,23 +810,18 @@ class Forwarder:
466
810
  else:
467
811
  up.sendall(rewritten + body)
468
812
  self.splice(client, up)
469
- except OSError:
813
+ except (OSError, ValueError):
470
814
  try:
471
815
  client.close()
472
816
  except OSError:
473
817
  pass
474
818
 
475
819
  def connect(self, host, port):
476
- """Connects to a vetted address of host (never resolved again, so never rebound)."""
477
- for family, kind, proto, _, address in socket.getaddrinfo(host, port, 0,
478
- socket.SOCK_STREAM):
479
- ip = ipaddress.ip_address(address[0].split("%")[0])
480
- if getattr(ip, "ipv4_mapped", None):
481
- ip = ip.ipv4_mapped
482
- # only globally routable addresses (not loopback, private, link-local, shared
483
- # 100.64/10, unique-local or NAT64) unless a test fixture allows its local endpoints
484
- if not self.allow_private and (not ip.is_global or ip in NAT64):
485
- continue
820
+ """Connects to a vetted address of host (never resolved again, so never rebound). Raises
821
+ PermissionError when every address is refused (none is dialled); see vetted_addresses."""
822
+ candidates = vetted_addresses(host, port, self.doh, self.allow_private,
823
+ closed=self.closed)
824
+ for family, kind, proto, _, address in candidates:
486
825
  sock = socket.socket(family, kind, proto)
487
826
  try:
488
827
  sock.settimeout(30)
@@ -634,20 +973,61 @@ def run_restricted(request, control):
634
973
  close_fds(runtime.values())
635
974
 
636
975
 
976
+ def write_denies(request):
977
+ """The write denies the device resolved for this operation: absolute, normalized paths."""
978
+ paths = request.get("writeDenies", [])
979
+ if not isinstance(paths, list) or not all(
980
+ isinstance(p, str) and p.startswith("/") and os.path.normpath(p) == p for p in paths):
981
+ raise Refused("INVALID_REQUEST", "Supply absolute normalized write denies")
982
+ return list(paths)
983
+
984
+
985
+ def files_lock(request):
986
+ """Opens the device's files lock (created on first use): a private regular file of this user
987
+ outside every sandbox, at the path the device chose ("filesLock"). The launcher takes it shared
988
+ for every brokered write and exclusively for a guarded directory move, so that exclusion spans
989
+ every operation of the device, and refuses it inside a granted root."""
990
+ path = request.get("filesLock")
991
+ if not isinstance(path, str) or not path.startswith("/") or os.path.normpath(path) != path:
992
+ raise Refused("INVALID_REQUEST", "Supply the device's files lock as an absolute path")
993
+ try:
994
+ fd = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
995
+ except OSError as error:
996
+ raise Refused("UNAVAILABLE", "The device's files lock cannot be opened: %s"
997
+ % error.strerror)
998
+ info = os.fstat(fd)
999
+ if not stat.S_ISREG(info.st_mode) or info.st_uid != os.geteuid() or info.st_mode & 0o077:
1000
+ os.close(fd)
1001
+ raise Refused("UNAVAILABLE", "The device's files lock is not a private regular file")
1002
+ return fd
1003
+
1004
+
637
1005
  def run_sealed(request, control, runtime):
638
1006
  env = dict(validated_env(request["env"]))
639
1007
  for key in PROXY_KEYS:
640
1008
  env.pop(key, None)
1009
+ denies = write_denies(request)
641
1010
  read, write, _ = pin_roots(request)
642
1011
  forwarder = None
1012
+ lock = None
643
1013
  try:
1014
+ lock = files_lock(request)
644
1015
  if not write:
645
1016
  raise Refused("SCOPE_DENIED", "Restricted execution needs an existing writable root")
646
1017
  network = request["network"]
647
- if network.get("kind") != "allowlist" or not network.get("hosts"):
1018
+ kind = network.get("kind")
1019
+ if kind != "open" and (kind != "allowlist" or not network.get("hosts")):
648
1020
  launcher_network = {"kind": "none"}
649
1021
  else:
650
- forwarder = Forwarder(list(network["hosts"]), request.get("allowPrivate") is True)
1022
+ seam = request.get("dohTest") # a test fixture's DoH server and certificate
1023
+ doh = EncryptedDns(seam["endpoints"], seam["caPem"]) if isinstance(seam, dict) \
1024
+ else EncryptedDns()
1025
+ try:
1026
+ closed = closed_set(request.get("closedAddresses", []))
1027
+ except (TypeError, ValueError, AttributeError):
1028
+ raise Refused("INVALID_REQUEST", "Supply closed addresses as IP addresses")
1029
+ forwarder = Forwarder(list(network["hosts"]) if kind == "allowlist" else [],
1030
+ request.get("allowPrivate") is True, kind == "open", doh, closed)
651
1031
  proxy = "http://capybara:%s@127.0.0.1:%d" % (forwarder.token, forwarder.port)
652
1032
  for key in ("HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy", "ALL_PROXY",
653
1033
  "all_proxy"):
@@ -660,7 +1040,10 @@ def run_sealed(request, control, runtime):
660
1040
  body = {"mode": "exec", "roots": {"read": read, "write": write},
661
1041
  "network": launcher_network, "reportFd": report_w, "env": env,
662
1042
  "cwd": request["cwd"], "argv": ["/bin/bash", "-c", request["command"]],
663
- "timeoutMs": request["timeoutMs"], "nativeFd": runtime["native-files.py"]}
1043
+ "timeoutMs": request["timeoutMs"], "nativeFd": runtime["native-files.py"],
1044
+ "writeDenies": denies, "filesLockFd": lock}
1045
+ if isinstance(request.get("faultInjection"), dict):
1046
+ body["faultInjection"] = request["faultInjection"] # a test fixture's seam
664
1047
  if files:
665
1048
  body["systemRoots"] = list(LAUNCHER_SYSTEM_ROOTS) + files
666
1049
  if control.cancel is not None:
@@ -671,16 +1054,21 @@ def run_sealed(request, control, runtime):
671
1054
  launcher = subprocess.Popen(
672
1055
  [sys.executable, "-I", "/proc/self/fd/%d" % runtime["linux-sandbox.py"]],
673
1056
  stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
674
- pass_fds=[report_w, runtime["linux-sandbox.py"], runtime["native-files.py"]]
1057
+ pass_fds=[report_w, runtime["linux-sandbox.py"], runtime["native-files.py"], lock]
675
1058
  + [e["fd"] for e in read + write],
676
1059
  env=LAUNCHER_ENV, preexec_fn=pdeathsig)
677
1060
  finally:
678
1061
  os.close(report_w)
679
1062
  close_pinned(read + write)
680
1063
  read, write = [], []
1064
+ # only the launcher holds the lock from here on (and never hands it to the command)
1065
+ os.close(lock)
1066
+ lock = None
681
1067
  return supervise(launcher, report_r, body, request, control)
682
1068
  finally:
683
1069
  close_pinned(read + write)
1070
+ if lock is not None:
1071
+ os.close(lock)
684
1072
  if forwarder is not None:
685
1073
  forwarder.close()
686
1074
 
@@ -760,8 +1148,13 @@ def supervise(launcher, report_r, body, request, control):
760
1148
  "cancelled": state["cancelled"], "supervisorLost": not state["cancelled"]})
761
1149
  return
762
1150
  stopped = exit_event.get("exitCode") is None or exit_event.get("cancelled")
763
- send({"event": "exit", "exitCode": None if stopped or state["cancelled"] else exit_event["exitCode"],
764
- "timedOut": bool(exit_event.get("timedOut")), "cancelled": state["cancelled"]})
1151
+ final = {"event": "exit",
1152
+ "exitCode": None if stopped or state["cancelled"] else exit_event["exitCode"],
1153
+ "timedOut": bool(exit_event.get("timedOut")), "cancelled": state["cancelled"]}
1154
+ if isinstance(exit_event.get("fatal"), str):
1155
+ # the broker could not undo a refused change and ended the operation
1156
+ final["fatal"] = exit_event["fatal"]
1157
+ send(final)
765
1158
 
766
1159
 
767
1160
  # ---- native -------------------------------------------------------------------------------
@@ -789,7 +1182,11 @@ def run_native(request):
789
1182
  # The permitted root does not exist yet, so neither does anything below it.
790
1183
  send({"event": "native", "response": {"result": [] if body["method"] == "scan" else None}})
791
1184
  return
792
- # restricted native writes honour the mandatory write denies (as the broker does)
1185
+ # restricted native writes honour the mandatory write denies (as the broker does) and
1186
+ # the operation's resolved ones (this agent serves one operation)
1187
+ folded = [native._fold_parts(p) for p in write_denies(request)]
1188
+ native.SYSTEM_WRITE_DENIES.extend(folded)
1189
+ native.PREFIX_GUARDED.extend((names, True) for names in folded)
793
1190
  roots = {"read": [{"path": e["path"], "fd": e["fd"]} for e in read],
794
1191
  "write": [{"path": e["path"], "fd": e["fd"]} for e in write],
795
1192
  "denyWrites": True}
@@ -807,8 +1204,18 @@ def run_native(request):
807
1204
  raise native.ScopeDenied("Native path is denied by the owner")
808
1205
  return result
809
1206
  send({"event": "launched", "pid": os.getpid()})
1207
+ fault = request.get("faultInjection")
810
1208
  try:
811
- response = {"result": (native.NativeFiles if request["full"] else Bounded)(roots).run(body)}
1209
+ files = (native.NativeFiles if request["full"] else Bounded)(roots)
1210
+ if isinstance(fault, dict) and isinstance(fault.get("pauseBeforeMkdir"), str):
1211
+ files.pause_mkdir = fault["pauseBeforeMkdir"] # a test fixture's seam
1212
+ if not request["full"] and body.get("method") == "writeFile":
1213
+ # a restricted write holds the device's files lock shared from check to effect,
1214
+ # like every brokered write, so no guarded move of the device slips in between
1215
+ lock = files_lock(request)
1216
+ pinned.append({"fd": lock})
1217
+ files.files_lock = native.DeviceFilesLock(lock)
1218
+ response = {"result": files.run(body)}
812
1219
  except Exception as error:
813
1220
  code = ("SCOPE_DENIED" if isinstance(error, native.ScopeDenied)
814
1221
  else errno.errorcode.get(getattr(error, "errno", None), "INVALID_NATIVE_REQUEST"))