socketpuppet

v1.0.3

Published

2 years ago

🎭 socketpuppet - connect to running puppeteer instances to see what's going on (or going wrong)--and fix it, live!

Downloads

247

socketpuppet Regular ·

socketpuppet is a full-stack component for a web browser that runs on a remote server, with a UI you can embed on the web.

Powerful: socketpuppet lets your provide controllable access to web resources in a way that's both more sandboxed than, and less restricted than, traditional web <iframe> elements.
General: Build applications that need cross-origin access, while delivering complex user stories that benefit from an encapsulated browser abstraction. Since the whole stack is written in JavaScript you can easily extend it to suit your needs.
Unprecendented: The technology that puts unrestricted browser capabilities within reach of a web app has never before existed in the open.

Get ideas for how you can use socketpuppet in your own project.

Installation

Pre-install Requirements

You need to have Chrome installed, and whatever dependencies your system needs for that. A good way to ensure you're starting from a good place is to install puppeteer.

With containers

If you want to use Docker, the VF docker hub image is your best bet.

Without containers

You can use a binary release or the NPM package and either require/import it or install as a global, or source.

Binary releases are best for a local machine, because they don't support sending sound over the network, so you'll only hear sound if you run it locally and Chrome headless is sending sound to your local machine speakers directly.

If you want to run it on a remote machine, the Docker image is the easier way to get set up, since it requires no configuration or install (but it's best to run it with the run_docker script indicated below to ensure the correct run settings).

You can also easily run it from cloning and installing the repository or via NPM, but those options are going to be easiest on a Debian flavor distribution as VF mostly uses apt to install dependencies.

So you're on a Debian flavor then just dive right in below.

Clone the repo and install dependencies:

$ git clone https://github.com/dosyago/socketpuppet.git
$ cd socketpuppet
$ npm i 
$ ./scripts/setup_machine.sh
$ npm test

or, run, depend on or globally install it from NPM:

$ npx viewfinder-regular@latest
$ npm i --save viewfinder-regular
$ npm i -g viewfinder-regular
$ vf

Note the vf NPM global binary is called 'vf'

or, pull it off DockerHub (and use the run_docker.sh script in the repo to run it):

$ docker pull dosyago/viewfinder-regular:latest
$ git clone https://github.com/dosyago/socketpuppet.git
$ cd socketpuppet/
$ ./scripts/run_docker.sh

In general

In all the above cases you can connect to the following address in a regular browser:

http://<host_ip>:8002/login?token=<token>

For the Docker image, the token is token2 for the NPM and repository copies, the token is bhvNDh6XYZ

You can enable https:// by adding certificates (such as from LetsEncrypt) into the $HOME/sslcerts/ directory if running via Node.

If you want to enable https while using Docker, you'll need to either rebuild a Docker image that copies your certs, or run HTTPS on a reverse-proxy.

To rebuild a Docker image that copies your certs into the correct $HOME/sslcerts/ direcotry, you need to use the script to rebuild docker, which is: ./scripts/build_docker.sh. You'll need to modify the Dockerfile to copy your certs.

Alternately you can put a HTTPS reverse-proxy such as nginx in front of your Docker instance, and handle the certs outside the container.

Installation Troubleshooting

If you encounter problems try running the ./scripts/setup_machine.sh script, and try again.

Applications

socketpuppet enables a number of different applications depending on your problem space:

Product space

Remote browser isolation for security, risk mitigation and privacy
Zero download co-browsing for collaboration and social interaction
Delivery layer for a zero download web scraping app that works on any device format
Alternate browser extension platform with associated app store
An online "internet cafe" with advanced security and privacy features
An alternative to VPNs, DNS blocklists
Email attachment threat mitigation via CDR and automatic opening of links and attachments in the remote browser
An intuitive UI affordance to enable clients to stay in-app while performing 3rd-party processes that normally require them to leave your web site.
A fully skinable and themeable client-customizable online hosted web browser alternative to downloadable browsers
Replay web app interactions to record bugs by recording the even stream and the viewport
Record visual How To guides illustrating key user stories

Internal tooling space

Human-in-the-loop intervention tool to unblock stuck browser automation jobs, and diagnose "selector drift" and script-page mismatch issues
An effective web proxy to easily integrate 3rd-party processes without APIs
An effective, interactive console to inspect, observe and interact with browser automation tasks
An automatable browser that more effectively evades bot detection mechanisms that pure headless Chrome
A scriptable console, and interactive simulator for automation tasks and automation script creation with a great, familiar and intuitive feedback loop

Tech and framework space

A <WebView> tag for the open web
An <iframe> without cross-origin restrictions
A 'head' for headless browsers

Progress & Roadmap

socketpuppet aims for feature-parity with desktop and mobile browsers, but also to push the limits of this technology with extra features like co-browsing. The list below shows our progress toward those goals. Please note that ⭐ features are only available in socketpuppet Pro.

Browser Features

[:heavy_check_mark:] Back and forward history buttons
[:heavy_check_mark:] Multiple tabs
[:heavy_check_mark:] Favicons
[:heavy_check_mark:] Addressbar search
[:heavy_check_mark:] Incognito tabs
[:heavy_check_mark:] Persistent sessions
[:heavy_check_mark:] <select> inputs
[:heavy_check_mark:] Modal dialogs
[:heavy_check_mark:] Copy and paste
[:heavy_check_mark:] Native paste
[:heavy_check_mark:] Touch scroll and touch drag
[:heavy_check_mark:] File upload (including multiple files)
[:heavy_check_mark:] Basic & Digest Auth support
[:heavy_check_mark:] Clear all cookies and cached data during sessions
[:heavy_check_mark:] Sound
[:heavy_check_mark:] Interact with CAPTCHAs
[:heavy_check_mark:] Context-menu (for opening in new tab, copying link address, etc)
[:heavy_check_mark:] Responsive design for any device viewport
[:heavy_check_mark:] Desktop scroll-zoom
[:heavy_check_mark:] Mobile pinch-zoom
[:heavy_check_mark:] mailto:, tel:, sktype: and other app and protocol links
[:heavy_check_mark:] Multiple select
[:heavy_check_mark:] Variable-bitrate rendering ⭐
[:heavy_check_mark:] Flash player (via Ruffle) ⭐
[:hourglass_flowing_sand:] Multi-touch on mobile
[:hourglass_flowing_sand:] Bookmarks
[:hourglass_flowing_sand:] Displayable history
[:hourglass_flowing_sand:] Webcam and microphone support

Security Features

[:heavy_check_mark:] RBI browser isolation security model
[:heavy_check_mark:] Fully clientless, embeds straight into a web page, zero download required for front-end
[:heavy_check_mark:] Evades headless detection
[:heavy_check_mark:] Customizable browser-fingerprinting cross-section
[:heavy_check_mark:] Works with proxies and Tor
[:heavy_check_mark:] DevTools (currently only works on Chrome clients) ⭐
[:heavy_check_mark:] Secure document viewer (CDR) ⭐
[:heavy_check_mark:] cgroups resource control sandboxing ⭐
[:heavy_check_mark:] 1 temporary user account per browser session ⭐
[:heavy_check_mark:] Clean-slate profile directory per browser session ⭐

Application Features

[:heavy_check_mark:] Built-in AdBlocker
[:heavy_check_mark:] Fully remote real-time co-browsing + built-in chat ⭐
[:heavy_check_mark:] Advanced adaptive streaming (with WebRTC + WebSockets) and Shortest path lag reduction ⭐
[:heavy_check_mark:] Run sandboxed puppeteer scripts ⭐
[:heavy_check_mark:] Skinnable browser UI ⭐
[:heavy_check_mark:] Kiosk mode (no UI controls) ⭐
[:hourglass_flowing_sand:] Sync browser cookies & settings from other browser (or, for example, Google account)
[:hourglass_flowing_sand:] Chrome extensions API (or cloned functionality)

Development and Deployment Features

[:heavy_check_mark:] Fully Dockerized / Dockerizable + reproducible startup and install scripts
[:heavy_check_mark:] Cloud-agnostic, runs on any cloud platform
[:heavy_check_mark:] Platform agnostic, and runs on Windows, Linux and Mac
[:heavy_check_mark:] Dependency control and minimal dependencies (only 14 external 1st level deps on back-end--mostly express related--and 0 on front-end)
[:heavy_check_mark:] Many customizable settings (including site blocklist)
[:heavy_check_mark:] Embeddable in an <iframe> ⭐
[:heavy_check_mark:] Vertically scalable (multiple browsers per server) ⭐
[:heavy_check_mark:] Small resource footprint ⭐
[:heavy_check_mark:] Bandwidth, CPU and memory limiting for resource abuse detection and prevention ⭐
[:heavy_check_mark:] Simple API ⭐
[:heavy_check_mark:] Fully white-labelable
[:hourglass_flowing_sand:] White-labeling API
[:hourglass_flowing_sand:] Fully scriptable with comprehensive API

Pro or Regular?

What's the difference between VF Pro and Regular?

The main differences are that VF Pro has more advanced features and more frequent updates than VF Regular.

For example, Pro has much better rendering, higher quality graphics and lower lag than Regular, as a result of many advanced streaming and variable bitrate innovations incorporated there.

Many Pro features are eventually sent down to Regular, but some will likely remain exclusive to Pro. Pro is updated weekly, with major updates shipped every quarter, whereas VF Regular follows a much slower and more haphazard release cycle.

The final main differenece you might want to be aware of is that while VF Regular is source-available (and is the sourcecode in this repository), VF Pro is currently closed-source proprietary software only available commercially, for either use in an Individual server, or for deployment in a Self-hosted package.

More information on these commercial options is below, and take a look at the table of feature comparison between Regular and Pro.

VF Pro vs Regular — Comparison Table

| Feature | Regular | Pro | |-----------------------------------------------|--------------------|--------------------| | Browser features | :heavy_check_mark: | :heavy_check_mark: | | Security features | :heavy_check_mark: | :heavy_check_mark: | | Privacy features | :heavy_check_mark: | :heavy_check_mark: | | Themeable browser UI | :heavy_check_mark: | :heavy_check_mark: | | Docker image | :heavy_check_mark: | :heavy_check_mark: | | Cloud and platform agnostic | :heavy_check_mark: | :heavy_check_mark: | | Multi-user security features | | :heavy_check_mark: | | Auto scaling and resource control | | :heavy_check_mark: | | WebRTC/WebSocket viewport streaming | | :heavy_check_mark: | | Fastest-path lag reduction | | :heavy_check_mark: | | Built-in cobrowsing and instant messaging | | :heavy_check_mark: | | Puppeteer scripting REPL console | | :heavy_check_mark: | | <iframe> embeddable | | :heavy_check_mark: | | Kiosk mode | | :heavy_check_mark: | | Simple API | | :heavy_check_mark: |

Commercial Options

socketpuppet Pro is provided by the Dosyago Corporation as a commercial offering in two flavors: individual, and self-hosted.

Self-hosted

The self-hosted track includes the provision of the VF Pro software, an S license and various tiers of service. The basic cost principle is established on time (not scale): time you want the license for, time of the latest update you want, and time it takes us to service your deployment. Targeted at SMBs up to Enterprise.

If you want to use VF commercially self-hosted is your main option.

To use the self-hosted track, you need to purchase an S license for a self-hosted deployment, which permits non-competing uses. I'll have a new price list up here soon, so stay tuned to this repository or contact me if you'd like first dibs on the new prices. Here's a general overview of where this will go:

Various configurable packages available with either perpetual or yearly licensing, and included service and consulting.
Starts at USD6,700 a year for non-perpetual single year license plus minimal service.
Mid-tier options cost 10K - 16K yearly with a variety of options including perpetual or annual licenses.
Invoiceable service and consulting also available.
BYO cloud or data-center, or on-prem are all available.

If you'd like to license VF for purposes that competete with us, we'll have to negotiate agreements. Reach out to me if that's the case.

Just a reminder that prices and buy links for self-hosted tiers are being published here soon! In the meantime, email me to ask a question.

Individual

Includes provision of a geographically located server wherever you want (or as close to it as possible for us), installed software, credentials to access, and various tiers of service. The basic cost principle is founded on performance (CPU cores, memory, network speed and bandwidth amount).

See the current prices and tiers for the Individual track.

Motivation

I originally created this in 2018 as a layer for a collaborative zero-download clientless web-scraping app I'm working on, but fell in love with this browser layer, and decided it was useful enough and a product category in its own right.

Stats

Visits:

FAQ

In plain language how would you describe what makes this browser stand-out?

You can have multiple people browsing at once, in sync (cobrowsing). It also can be faster than your normal connection (because the server + its network is very fast). You can consider it more secure, because it only runs web content in the cloud, not on your device.

What is VF Individual?

VF Individual—your remote browser in the cloud, powered by socketpuppet Pro.

Why do I want a remote browser?

Can I download files form the web using VF?

By default, for security, VF does not permit downloading of files to the local device, and instead downloads them to the remote server. In VF Pro, the built-in secure document viewer then processes and displays them if they are of a supported format. However, both Pro and Regular lines can be configured to provide a download link to get the file to the local device, although that is not recommended in security applications, at least not without proper scanning or CDR.

You can also link up your own secure document viewer with VF Regular.

Can you rush legacy Flash applications?

There's a customized version of Viewfind Pro with Flash support via two separate paths: Legacy Chrome (pre Chrome 88 ~ Jan 2021) with xvfb, and using latest Chrome with ruffle.

However, there's no guaruntee that your particular application will work, because ruffle still has many missing features and bugs, and because streaming your app over the network in a virtual browser may introduce other issues for your application, or simply be not suitable in your case.

But in the ideal case, yes, it can be done, and you can embed your legacy Flash player app in a VF Pro iframe and put it on your site.

Can VF integrate with our existing secure document viewer or download scanning?

Not out of the box but VF Pro can be configured to pass requests for document viewing to a 3rd-party application and to serve downloaded files. In short, VF can be configured to send downloads to your secure document viewer or download scanner. In the case where VF is configured to allow downloads to the local device, it should not effect your normal download scanners and endpoint protection software.

What sort of multi-profile or "fake profile" privacy options are available to defeat fingerprinting and tracking?

By default VF Pro runs with a clean slate every session, so there are no tracking cookies or data retained from any other session of VF. Even if persistent sessions are enabled, VF can still be configured to transmit various phoney profile information (such as installed plugins, geolocation, platform, device, browser version and so on) in order to attempt to defeat fingerprinting and tracking. However, even with the added layer of protection of an additional remote browser, a separate IP address, and forged browser identification, there's no guaruntee of 100% effectiveness. If someone logs in to an account linked to their other profiles or identities, it may still be possible to track them, even if they are using VF. Technology can only go so far, people must also take sensible precautions in their choices.

Can you white-label VF as the tech for our internal RBI product?

Not us, but you can do it and we can help you. VF can most definitely be fully whitelabelled and customized with a variety of themes, splash pages, styles, design systems, brand look and assets.

Can I use VF tech to make my own commercial RBI product and sell that?

Yes of course. With the proper license this is most definitely a possible use case for VF, and we encourage you to do so.

Where can I get more information on your services, available licenses or pricing?

Eventually I intend to most of that information here, but for now you may email me. The reason is I'm currently revising a lot of positioning, licensing and prices. If you let me know you prefer a voice call that's also available.

Can I donate to support development?

Yes of course. You can see various contribution links on the VF Donations page. When you donate to VF specifically, send me an email if you'd like to be added to the Backers Hall of Fame.

Alternately, you may donate to DosyagoCorp in general to support development across many Dosyago products. Thanks! 😍

Other resources

Click to deploy on GCP, AWS, Heroku
Planned: StackScript for Linode, Vultr Marketplace entry
Learn and solve issues together at the community discussion page.

Contributing

Contributions welcome! But please sign the CLA first. Don't worry, if you open a pull request a bot will automatically let you know what you need to do!

:balance_scale: Licensing

VF Regular

VF Regular (this repository) is licensed under the Polyform Noncommercial License 1.0 (NC license). Any previous licensed versions are also relicensed under this license.

The NC license permits "use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding."

Read the license.

VF Pro

VF Pro (closed-source) is available under the Polyform Shield License 1.0.0 (S license), via a licensing agreement with The Dosyago Corporation. Read the license.

In essence this license permits any use case besides those which compete with Dosyago Corporation (or the rightsholders of VF).

If you'd like to purchase a Pro S license, see the price list here

© Copyright

This project copyright The Rightsholders (currently Cris Stringfellow & The Dosyago Corporation) 2022