{"id":15127593,"url":"https://github.com/humphreyboagart/vmask","last_synced_at":"2026-01-24T08:31:17.953Z","repository":{"id":253865440,"uuid":"844766008","full_name":"HumphreyBoaGart/vmask","owner":"HumphreyBoaGart","description":"Docker-based sockpuppetry for the people! (VNC Edition)","archived":false,"fork":false,"pushed_at":"2024-08-20T18:29:14.000Z","size":180,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T19:22:01.871Z","etag":null,"topics":["anonymous","bash","docker","docker-compose","docker-container","docker-image","firefox","firefox-extension","gluetun","kasmvnc","openvpn","platform-manipulation","shell","shell-script","shell-scripting","sockpuppet","sockpuppet-deployment","vnc","vpn","wireguard"],"latest_commit_sha":null,"homepage":"https://bestpoint.institute/diy/identity-management","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HumphreyBoaGart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-19T23:36:34.000Z","updated_at":"2024-10-06T12:54:41.000Z","dependencies_parsed_at":"2024-08-20T03:45:28.246Z","dependency_job_id":"49150a68-afbd-4ef1-9870-cb0f83346114","html_url":"https://github.com/HumphreyBoaGart/vmask","commit_stats":null,"previous_names":["humphreyboagart/vmask"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumphreyBoaGart%2Fvmask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumphreyBoaGart%2Fvmask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumphreyBoaGart%2Fvmask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumphreyBoaGart%2Fvmask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HumphreyBoaGart","download_url":"https://codeload.github.com/HumphreyBoaGart/vmask/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246063239,"owners_count":20717774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anonymous","bash","docker","docker-compose","docker-container","docker-image","firefox","firefox-extension","gluetun","kasmvnc","openvpn","platform-manipulation","shell","shell-script","shell-scripting","sockpuppet","sockpuppet-deployment","vnc","vpn","wireguard"],"created_at":"2024-09-26T02:04:58.362Z","updated_at":"2026-01-24T08:31:17.911Z","avatar_url":"https://github.com/HumphreyBoaGart.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vmask\n![vmask.sh](https://raw.githubusercontent.com/HumphreyBoaGart/vmask/master/banner.png)\n\n**vmask.sh** (short for **v**nc **mask**) is a shell script utility for deploying and managing sockpuppets, which we will also refer to here as ***masks***.\n\nUsing Docker, each mask is given its own dedicated web browser and VPN profile. This lets you easily set aside compartmentalized environments (with their own unique sets of cookies, sessions \u0026 bookmarks) for each of your sockpuppets, ensuring that no two sockpuppets connect to the internet from the same IP address.\n\nThe web browser is [linuxserver.io's Firefox image](https://docs.linuxserver.io/images/docker-firefox/), which is encased in KasmVNC and accessed via the desired port on any other web browser. This means you can store all your masks in the cloud, on any server or VPS that has Docker installed. *(Direct X11/Wayland access not available. I am working on a companion script with a different browser image for that.)*\n\nThe VPN connection is implemented by forcing the browser to go through [Gluetun](https://github.com/qdm12/gluetun). By default, our configuration uses Wireguard, but all other Gluetun-compatible VPN modes are supported as well. (See: [Configuring Wireguard](#wireguard) and [Other VPN Options](#other-vpn-options), below.)\n\nThe way this is set up, it lets us use a single browser image as the base, which in turn is cloned into a unique container environment when the mask is \"put on.\" \nUpon taking the mask off, only the mask's settings/cookies/bookmarks/etc are saved, and the rest of the container is Permanently Erased. Putting the mask back on generates a fresh instance of the browser container, with that masks's personal data preserved. This keeps disk space consumption at a minimum, while still providing the opsec benefits of containerization.\n\n## Dependencies\n- **bash** (or compatible)\n- **sed**\n- **Docker**\n\nDocker should ideally be running in [rootless mode](https://docs.docker.com/engine/security/rootless/), since running a web browser as root is a ***very bad idea***.\n\n## Installation\n```\ncd $HOME/.config\ngit clone https://github.com/HumphreyBoaGart/vmask\nchmod u+rx vmask/vmask.sh\nln -s vmask/vmask.sh $HOME/.local/bin/vmask\n```\n\nMake sure your environment's `$HOME` variable is set to your home directory, or you're going to have a hard time with, well, everything. You can check if it is set by running `printenv HOME`.\n\n## Command Reference\nThe following commands are built into **vmask.sh**:\n\n### List all available masks\n```\nvmask list\n```\n\n### Take a mask out of storage\n```\nvmask on MASKNAME\n```\n\n### Put mask back into storage\n```\nvmask off MASKNAME\n```\n\n### Generate new mask \u0026 save to storage\n```\nvmask new\n```\n\nOr, to bypass interactive mode:\n```\nvmask new MASKNAME PORT\n```\n\nNew masks are saved in an inactive state by default. To use a freshly-generated mask, you will need to first [Configure Wireguard](#wireguard), and then run `vmask on`.\n\n#### Note on ports:\nDo not put two masks on the same port! If you are only pulling one mask out of storage at a time, this is not a big deal. HOWEVER, if you are planning on activating multiple masks at once, you will run into problems if more than one mask is configured to use the same port.\n\n### Delete a mask from storage (requires sudo)\n```\nvmask del MASKNAME\n```\n\nIf you are using rootless Docker *(as you should be)*, the persistent storage directory for the browser will be chown'd to a different userid than your own. This means you need sudo permissions to delete any saved masks. (You do not need to run sudo yourself, it is baked into the script on this one command.)\n\n### Built-in Documentation\n```\nvmask help\n```\n\n(`vmask -h` and `vmask --help` will also work)\n\n## Mask Access\nIf you are running vmask locally, you can access your mask's browser instance by going to http://localhost:PORTNUMBER, where PORTNUMBER is the port you told vmask to use.\n\nFor remote vmask installs, replace localhost with your server's IP address.\n\n**IMPORTANT:** I highly recommend using HTTPS for remote use. (See: [Enabling SSL](#enabling-ssl), below.)\n\n## Configuration\nThe default settings profile for all new masks is stored in `skel/compose.yaml`. When you create a new mask with `vmask new`, it creates a new directory for that mask in `data/`. Then it creates a copy of this file, saves it to that new directory, and populates it with the attibutes you define.\n\nThis means there are **two types** of `compose.yaml` files: One for new masks in `skel/`, and another for existing masks in `data/`.\n\nTo edit the default profile from which all new masks will be derived, just edit `skel/compose.yaml` with your favorite text editor.\n\nTo edit existing profiles on a case-by-case basis, edit `data/MASKNAME/compose.yaml`.\n\nThe following customizations can be made to both types of files:\n\n### Wireguard\nWireguard is only partially configured by default. You will need to edit the following variables on **Lines 13-17** in `compose.yaml` to finish the setup for each mask:\n- WIREGUARD_ENDPOINT_IP\n- WIREGUARD_ENDPOINT_PORT\n- WIREGUARD_PUBLIC_KEY\n- WIREGUARD_PRIVATE_KEY\n- WIREGUARD_ADDRESSES\n\nEventually I may add Wireguard configuration to the `vmask new` command, but I wanted to leave things flexible enough for end-users to implement all the other Gluetun VPN options that I personally do not use. (See: [Other VPN Options](#other-vpn-options), below.)\n\n### Other VPN Options\nGluetun supports a myriad of VPN options and providers, all of which can be implemented in `compose.yaml`. For a full list of other VPN options you can implement, see the [Gluetun wiki](https://github.com/qdm12/gluetun-wiki/blob/main/setup/readme.md).\n\n### Enabling SSL\nBy default, Firefox is accessed via HTTP on a port of your choosing, mapped to port 3000 within the container. However, linuxserver.io provides the option for HTTPS access on internal port 3001, which is **highly recommended** if you are not using this on a local machine.\n\nTo use HTTPS, replace '3000' with '3001' on **Line 8** in `compose.yaml`.\n\n### Timezones\nTimezones for the Gluetun and Firefox containers are defined on **Lines 10 \u0026 25** in `compose.yaml` respectively. By default they are set to `America/New_York` to match the [AMI server](https://github.com/bestpoint) this script is promoted through. To throw off spies and other vultures, you may wish to define different timezones for each of your masks.\n\nSee [this list of valid timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) for a complete list of options.\n\n## Sockpuppet Methodology\nFor an analytical rundown of best practices when engaging in sockpuppetry online, [read my guide about Identity Management at the Anonymous Military Insitute](https://bestpoint.institute/diy/identity-management).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumphreyboagart%2Fvmask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumphreyboagart%2Fvmask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumphreyboagart%2Fvmask/lists"}