{"id":36631874,"url":"https://github.com/fish-not-phish/open-vbrowser","last_synced_at":"2026-01-12T09:38:50.527Z","repository":{"id":300136239,"uuid":"1005119261","full_name":"fish-not-phish/open-vbrowser","owner":"fish-not-phish","description":"vBrowser is a secure, containerized browser platform designed for covert web investigations. Originally created to support deep and dark web analysis by cybersecurity professionals, it enables users to safely browse the internet, without exposing their identity or environment.","archived":false,"fork":false,"pushed_at":"2026-01-11T16:32:54.000Z","size":11922,"stargazers_count":20,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T19:44:03.933Z","etag":null,"topics":["cybersecurity","darkweb","deepweb","docker","docker-compose","docker-image","ecs-fargate","investigation","secure-browser","soc","threat-hunting","threat-intelligence","threatintel","virtualization"],"latest_commit_sha":null,"homepage":"https://docs.vbrowser.io","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fish-not-phish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-19T17:43:51.000Z","updated_at":"2026-01-11T16:32:57.000Z","dependencies_parsed_at":"2025-07-19T16:28:08.835Z","dependency_job_id":null,"html_url":"https://github.com/fish-not-phish/open-vbrowser","commit_stats":null,"previous_names":["fish-not-phish/open-vbrowser"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fish-not-phish/open-vbrowser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fish-not-phish%2Fopen-vbrowser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fish-not-phish%2Fopen-vbrowser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fish-not-phish%2Fopen-vbrowser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fish-not-phish%2Fopen-vbrowser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fish-not-phish","download_url":"https://codeload.github.com/fish-not-phish/open-vbrowser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fish-not-phish%2Fopen-vbrowser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cybersecurity","darkweb","deepweb","docker","docker-compose","docker-image","ecs-fargate","investigation","secure-browser","soc","threat-hunting","threat-intelligence","threatintel","virtualization"],"created_at":"2026-01-12T09:38:50.008Z","updated_at":"2026-01-12T09:38:50.519Z","avatar_url":"https://github.com/fish-not-phish.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Open vBrowser - OvB\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/vbrowser/logos/refs/heads/main/logo-vbrowser-transparent.png\" alt=\"vBrowser Logo\" width=\"400\"/\u003e\n\u003c/p\u003e\n\n[![Stars](https://img.shields.io/github/stars/fish-not-phish/open-vbrowser?style=social)](https://github.com/fish-not-phish/open-vbrowser/stargazers)\n[![Forks](https://img.shields.io/github/forks/fish-not-phish/open-vbrowser?style=social)](https://github.com/fish-not-phish/open-vbrowser/network/members)\n\n[![License](https://img.shields.io/github/license/fish-not-phish/open-vbrowser?color=green)](LICENSE) \n![Status](https://img.shields.io/badge/status-Alpha-red)\n\nVisit https://docs.vbrowser.io/ for official and in-depth documentation.\n\nvBrowser was initially created by **Joseph Fisher**, a Cyber Threat Intelligence manager, to assist with deep and dark web investigations while not exposing identity and remaining covert. The vBrowser team realized that many SOCs lack the tools or sandboxed environments needed for proper investigations. vBrowser provides companies and individuals access to this infrastructure at a minimal price, lowering the barrier for those who cannot afford expensive subscription services with paywalled features. Our ultimate goal is to give back to the community-enhancing cyber investigations and helping keep people safe.\n\n\n## Table of Contents\n\n- [Supported Architecture \u0026 Platforms](#supported-architecture-and-platforms)  \n- [Installing Terraform (Linux)](#installing-terraform-linux)  \n- [AWS Credentials Setup (Root User)](#aws-credentials-setup-root-user)  \n  - [1. Sign in to AWS](#1-sign-in-to-aws)  \n  - [2. Create Access Keys (for root)](#2-create-access-keys-for-root)  \n  - [3. Configure the environment for Terraform](#3-configure-the-environment-for-terraform)  \n- [Cloudflare Setup](#cloudflare-setup)  \n  - [1. Create a Cloudflare Account](#1-create-a-cloudflare-account)  \n  - [2. Add Your Domain to Cloudflare](#2-add-your-domain-to-cloudflare)  \n  - [3. Copy Your Zone ID](#3-copy-your-zone-id)  \n  - [4. Create an API Token](#4-create-an-api-token)  \n- [Getting Started](#getting-started)  \n  - [1. Clone the Repository](#1-clone-the-repository)  \n  - [2. Change directory into terraform folder](#2-change-directory-into-terraform-folder)  \n  - [3. Run the setup script](#3-run-the-setup-script)  \n- [What `setup.sh` Does](#what-setupsh-does) \n  - [1. Image Selection](#1-image-selection)  \n  - [2. Environment Setup (`.env`)](#2-environment-setup-env)  \n  - [3. Terraform Patching](#3-terraform-patching)  \n  - [4. Infrastructure Provisioning](#4-infrastructure-provisioning)  \n  - [5. Environment Propagation](#5-environment-propagation)  \n  - [6. Docker Image Builds](#6-docker-image-builds)  \n  - [7. Service Startup](#7-service-startup)  \n- [Destroying the Deployment](#destroying-the-deployment) \n- [API Special Key](#api-special-key)\n   - [Purpose](#purpose)  \n- [License](#license) \n\n## 🧪 Supported Architecture and Platforms\n\n| Architecture | Platform | Supported | Notes                            |\n|--------------|----------|-----------|----------------------------------|\n| `amd64`      | Linux    | ✅ Yes     | Fully tested and supported       |\n| `amd64`      | Windows  | ⚠️ Likely  | Not tested, but expected to work |\n| `aarch64`    | Linux    | ⚠️ Likely     | Not tested, but expected to work      |\n| `arm64`      | Linux    | ⚠️ Likely      | Not tested, but expected to work      |\n\n\u003e ℹ️ OvB has only been tested on **Linux (amd64)** systems. Windows support is **expected** but not verified. All documentation currently assumes a Linux environment.\n\n## 📦 Installing Terraform (Linux)\n\nTo run OvB's infrastructure components, you’ll need [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli). Here's how to install it on a Debian-based Linux system (e.g. Ubuntu):\n\n**1. Update and install prerequisites**\n```bash\nsudo apt-get update -y \u0026\u0026 sudo apt-get install -y gnupg software-properties-common\n```\n**2. Install the HashiCorp GPG Key**\n```bash\nwget -O- https://apt.releases.hashicorp.com/gpg | \\\ngpg --dearmor | \\\nsudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg \u003e /dev/null\n```\n**3. Add the official HashiCorp repository to your linux system.**\n```bash\necho \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \\\nhttps://apt.releases.hashicorp.com $(grep -oP '(?\u003c=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main\" | \\\nsudo tee /etc/apt/sources.list.d/hashicorp.list\n```\n**4. Download the package information**\n```bash\nsudo apt update -y\n```\n**5. Install Terraform**\n```bash\nsudo apt-get install -y terraform\n```\n## 🔐 AWS Credentials Setup (Root User)\n\nTo allow Terraform to authenticate with AWS, you need to provide your **Access Key ID** and **Secret Access Key**. Here's how to obtain them from your AWS Root Account (IAM user is also sufficient):\n\n---\n\n### 1. Sign in to AWS\n\nGo to [https://aws.amazon.com/console/](https://aws.amazon.com/console/) and log in as the **root user** (email + password). Feel free to use an IAM user instead as long as the permissions are correct.\n\n---\n\n### 2. Create Access Keys (for root)\n\n1. Navigate to **My Security Credentials** (top-right dropdown → _“My Security Credentials”_).  \n2. Scroll down to the **Access keys** section.  \n3. Click **Create access key**.  \n4. **Download** or **copy** the credentials safely:\n   - `AWS_ACCESS_KEY_ID`\n   - `AWS_SECRET_ACCESS_KEY`\n\n\u003e ⚠️ You will only see the secret key **once**. Store it securely.\n\n---\n\n### 3. Configure the environment for Terraform\n\nYou can pass the credentials via environment variables:\n\n```bash\nexport AWS_ACCESS_KEY_ID=\"your-access-key-id\"\nexport AWS_SECRET_ACCESS_KEY=\"your-secret-access-key\"\nexport AWS_DEFAULT_REGION=\"us-east-2\"  # must be the same region you wish to deploy the stack to\n```\n## 🌐 Cloudflare Setup\n\nOvB uses Cloudflare to manage DNS records dynamically. Follow these steps to configure your Cloudflare account:\n\n---\n\n### 1. Create a Cloudflare Account\n\nIf you don’t already have one, sign up at:  \n🔗 [https://dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up)\n\n---\n\n### 2. Add Your Domain to Cloudflare\n\n- Add a domain you own (e.g. `example.com`) to your Cloudflare account.\n- Update your domain registrar to point your nameservers to the Cloudflare-provided ones.\n- Wait for DNS propagation to complete (can take several minutes to hours).\n\n\u003e ✅ A **free-tier account** is sufficient.\n\n---\n\n### 3. Copy Your Zone ID\n\n1. Go to your domain’s **Overview** page in the Cloudflare dashboard.  \n2. Locate the **Zone ID** at the bottom-right of the page.  \n3. **Copy** and store this - you’ll need it for the OvB setup process.\n\n---\n\n### 4. Create an API Token\n\n1. Visit: [https://dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens)  \n2. Click **“Create Token”**\n3. Choose **“Edit zone DNS”** template  \n4. Set the following:\n   - **Token name**: `Terraform DNS Access` (or any descriptive name)\n   - **Permissions**: `Zone.DNS:Edit`\n   - **Resources**: Select **Specific Zone** and choose your domain (e.g. `example.com`)\n\n5. Create the token and **copy it**. You will only see it once.\n\n\u003e ❗️Do **not** use the Global API Key unless absolutely necessary. It grants broad account access.\n\n---\n\n## 🚀 Getting Started\n\nOnce your environment is ready (Terraform, AWS credentials, and Cloudflare API token), follow the steps below to deploy OvB:\n\n---\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/fish-not-phish/open-vbrowser.git\n```\n### 2. Change directory into terraform folder\n```bash\ncd open-vbrowser/terraform\n```\n### 3. Run the setup script\n```bash\n./setup.sh\n```\n## 🔧 What `setup.sh` Does\n\nThe `setup.sh` script automates the full initialization process for Open vBrowser. Here’s what it handles:\n\n### 1. **Image Selection**  \n   Prompts the user to choose default or custom browser containers (e.g. Chrome, Remnux). It moves unused images into a separate `unused/` folder and restores any selected images.\n\n\u003e ⚠️ Open vBrowser pre-selects Chrome, Terminal, Remnux, Mullvad and Tor by default.\n\n#### ✅ Example\n\nTo enable **Chrome**, **Microsoft Edge**, and **IceCat**, enter:\n\n```bash\nchrome,edge,icecat\n```\n\u003e ⚠️ Input must be comma-separated, with no spaces.\n\n| Icon | Browser         | Name for Selection |\n|------|------------------|--------------------|\n| \u003cimg src=\"django/static/images/brave.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Brave            | `brave`            |\n| \u003cimg src=\"django/static/images/chrome.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Chrome           | `chrome`           |\n| \u003cimg src=\"django/static/images/chromium.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Chromium         | `chromium`         |\n| \u003cimg src=\"django/static/images/discord.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Discord          | `discord`          |\n| \u003cimg src=\"django/static/images/edge.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Microsoft Edge   | `edge`             |\n| \u003cimg src=\"django/static/images/falkon.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Falkon           | `falkon`           |\n| \u003cimg src=\"django/static/images/firefox.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Firefox          | `firefox`          |\n| \u003cimg src=\"django/static/images/librewolf.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | LibreWolf        | `librewolf`        |\n| \u003cimg src=\"django/static/images/mullvad.png\"  width=\"20\" alt=\"Brave logo\"/\u003e | Mullvad Browser  | `mullvad`          |\n| \u003cimg src=\"django/static/images/palemoon.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Pale Moon        | `palemoon`         |\n| \u003cimg src=\"django/static/images/pulse.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Pulse Secure     | `pulse`            |\n| \u003cimg src=\"django/static/images/kali.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Kali           | `kali`           |\n| \u003cimg src=\"django/static/images/seamonkey.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | SeaMonkey        | `seamonkey`        |\n| \u003cimg src=\"django/static/images/signal.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Signal           | `signal`           |\n| \u003cimg src=\"django/static/images/slack.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Slack            | `slack`            |\n| \u003cimg src=\"django/static/images/telegram.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Telegram         | `telegram`         |\n| \u003cimg src=\"django/static/images/tor.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Tor Browser      | `tor`              |\n| \u003cimg src=\"django/static/images/ungoogled.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Ungoogled Chrome | `ungoogled`        |\n| \u003cimg src=\"django/static/images/waterfox.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Waterfox         | `waterfox`         |\n| \u003cimg src=\"django/static/images/zen.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Zen Browser      | `zen`              |\n| \u003cimg src=\"django/static/images/zoom.png\"  width=\"20\" alt=\"Brave logo\"/\u003e   | Zoom             | `zoom`             |\n\n🗃️ All unused images will be automatically moved to the `unused/` folder.\n\n### 2. **Environment Setup (`.env`)**  \n\u003e NOTE: DEBUG should be set to False or 0 for production environments.\n\n\u003e NOTE: LOGGER_ENABLED set to True may generate lots of output. Recommened to have off unless you are troubleshooting.\n\n\u003e NOTE: DEFAULT_IDLE_THRESHOLD is the amount of time you want sessions to auto-close during an idle period.\n\nRecommend changing the following:\n\n   - `CUSTOM_DOMAIN` (required to change)\n   - `DJANGO_SUPERUSER_USERNAME`\n   - `DJANGO_SUPERUSER_EMAIL`\n   - `DJANGO_SUPERUSER_PASSWORD`\n   - `CF_Zone_ID` (required to change)\n   - `CF_Token` (required to change)\n   - Ensure `AWS_DEFAULT_REGION` is set to your desired region\n   - The rest of the variables are configured to work by default. Change at your own risk.\n\n### What Does It Generate?\n   - Generates a secure Django `SECRET_KEY`\n   - Prompts for required environment variables (database, Redis, AWS, Cloudflare, etc.)\n   - Saves all values to a `.env` file\n   - Auto-generates key fields like `ALLOWED_HOSTS` and `USER_EMAIL`\n\n### 3. **Terraform Patching**  \n   Updates any `region` and `awslogs-region` values in Terraform files to match the selected `AWS_DEFAULT_REGION`.\n\n### 4. **Infrastructure Provisioning**  \n   Runs `terraform init` and `terraform apply -auto-approve` to automatically create the necessary AWS infrastructure.\n\n### 5. **Environment Propagation**  \n   Copies the `.env` file to:\n   - `../django/`\n   - `../docker/containers-update/`\n   - `../docker/vbrowser-stack/`\n\n### 6. **Docker Image Builds**  \n   Builds Docker images for:\n   - The Django backend (`vbrowser`)\n   - The container manager (`containers-updater`)\n\n### 7. **Service Startup**  \n   Uses Docker Compose to bring up:\n   - `containers-update` stack\n   - `vbrowser-stack`\n\n\u003e 🛠️ This script ensures that by the time it's finished, all required infrastructure is configured properly and initializing their startup process(es).\n\n\u003e ⚠️ **Important:**  \n\u003e After running `setup.sh`, you **must wait** for the `containers-updater` container to finish its build and push process **before starting any sessions**.  \n\u003e Run the following to monitor its progress:\n```bash\ndocker logs containers-updater -f\n```\n\u003e ⚠️ **Important:** \n\u003e \n\u003e If you receive the error shown below, please roll your Cloudflare API Token, destroy the stack using `destroy.sh` (wait for it to finish building before destroying), and redploy using `setup.sh`.\n\n```bash\ninvalid domain\nError adding TXT record to domain: ...\n```\n\nOtherwise, please wait until it stops producing output and says `All done.`. Once this occurrs, the entire setup process has been completed.\n\n---\n\n## 🧨 Destroying the Deployment\n\nTo tear everything down cleanly, including AWS resources and local containers, run the following:\n\n```bash\ncd open-vbrowser/terraform\n./destroy.sh\n```\nThis script requires no input. It will:\n\n- Destroy all AWS infrastructure created by Terraform (ECS, networking, ECR, etc.)\n- Remove all Docker containers and associated volumes\n\nThis gives you a fresh slate. To redeploy, just run `./setup.sh` again.\n\n## API Special Key\n\n`API_SPECIAL_KEY` is automatically generated based on your `CUSTOM_DOMAIN`. It is the Base64-encoded version of the domain you provide in the environment variable `CUSTOM_DOMAIN`.\n\n### Purpose\n\nThe `API_SPECIAL_KEY` is used to **cross-verify the integrity of API requests**.  \nAny client attempting to use your API must provide:\n- Their own **API key**\n- The corresponding **API Special Key** (Base64-encoded version of their registered `CUSTOM_DOMAIN`)\n\nThis dual verification ensures that only authorized clients with a valid domain and API key can interact with the API, protecting against unauthorized access and domain spoofing.\n\n\n## License\n\nThis project is licensed under a custom **Non-Commercial License**.  \nYou may use, modify, and distribute the software for **personal and educational use only**.\n\n**Commercial use and resale are strictly prohibited** without express written permission from the author.\n\nFor licensing questions, contact jfisher@vbrowser.io.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffish-not-phish%2Fopen-vbrowser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffish-not-phish%2Fopen-vbrowser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffish-not-phish%2Fopen-vbrowser/lists"}