README.md

   1 # Ma Liang (马良)
   2
   3 Transmit Python objects over a *trusted* connection (such as SSH) simply and easily, without *any* external dependencies.
   4
   5 ## Caution
   6
   7 **THIS TOOL INVOLVES UNPICKLING UNVALIDATED STREAMS FROM THE NETWORK. REMOTE CODE EXECUTION IS POSSIBLE WHEN THE TRAFFIC IS UNINSPECTED ON THE RECEIVING END.**
   8
   9 **DO NOT USE IT OVER UNTRUSTED CONNECTIONS. DO NOT USE IT IF YOU DO NOT KNOW WHAT THIS TOOL IS FOR.**
  10
  11 ## Usage
  12
  13 Suppose we transmit an object from `server` to `wimp`. `wimp` has the port 8848 open to `server`, either by WireGuard virtual LAN or SSH port forwarding.
  14
  15 In their Python REPLs:
  16
  17 ```
  18 wimp >>> server = maliang.Server('0.0.0.0', 8848)
  19 wimp >>> obj = server.recv()
  20 server >>> client = maliang.Client('0.0.0.0', 8848)
  21 server >>> client.send(obj)
  22 ```
  23
  24 Et voila! Now do anything you want with `obj` on `wimp`.
  25
  26 ### Multiple values?
  27
  28 Use tuples.
  29
  30 ```
  31 wimp >>> server = maliang.Server('0.0.0.0', 8848)
  32 wimp >>> mouse, cow, tiger, rabbit = server.recv()
  33 server >>> client = maliang.Client('0.0.0.0', 8848)
  34 server >>> client.send((mouse, cow, tiger, rabbit))
  35 ```
  36
  37 ## Why?
  38
  39 Ma Liang (马良 in Simplified Chinese) is a figure from Chinese folklore with magical painting talent, which was purportedly sent to him by a god of arts. In one version of this folklore, he eventually constructed an ideal world using his paint alone under threat of life from a local landowner, never returning.
  40
  41 This project is originally developed for sending data on a beefy, remote machine to a weaker client for analysis, without which the client cannot visualize. Hence the name.
  42