Huge news!Announcing our $20M Series A led by Andreessen Horowitz.Learn more
Log inDemoInstall

Package Overview
File Explorer


Version published




A self-contained GoLang library that is capable of blocking ads,malwares and trackers using DNS Sinkholing. This libray can be integrated with different pre-existing cross-platform applications.

You can learn more about the project from the blogs at

Table of Contents



The detailed download and installation guide can be found at official website of Go.

For Linux:

# 1. Download Go Binary Archive

# 2. Extract it
tar -xzf go1.18.4.linux-amd64.tar.gz -C /usr/local/

# 3. Add PATH Variables
sudo nano /etc/profile
export PATH=$PATH:/usr/local/go/bin
source /etc/profile

# 4. Check Go Version
go version

You can refer to the official documentation for setting GOPATH.

GoMobile & Gobind

After installing Go, we need gobind. Gobind is a tool that generates language bindings that make it possible to call Go functions from Java and Objective-C. It is called internally by gomobile which can help us build cross-platform applications.

go install

# To compile Android APK and IOS Apps
gomobile bind [-target android|ios|iossimulator|macos|maccatalyst] [-bootclasspath <path>] [-classpath <path>] [-o output] [build flags] [package]


To clone and build VPN-Hole Library:

git clone

cd vpn-hole


To load all of the packages in the main module:

# If go.mod and go.sum are present then,
# Run 
go mod tidy

If go.mod and go.sum are missing from the cloned repository, then:

# go mod init [module-path]
go mod init

Build & Run

To build the library and use it as a standalone:

# navigate to app/vpnhole

cd app/vpnhole

# build the library

go build

An executable binary file would be generated for the library.

On MacOSX Monterey you may encounter an build error like this

/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/pthread.h:328:6: error: macro expansion producing 
'defined' has undefined behavior [-Werror,-Wexpansion-to-defined]
/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/pthread.h:197:2: note: expanded from macro 

You can fix it by adapting the compiler flags, e.g. by prefixing go build with CGO_CPPFLAGS="-Wno-error -Wno-nullability-completeness -Wno-expansion-to-defined -Wbuiltin-requires-header".

On Ubuntu if you face an error saying:"Failed to serve DNS server: listen udp :53: bind: permission denied"

# see the services listening on port 53
sudo ss -lp "sport = :domain"
sudo lsof -i :53

You can see that Ubuntu has systemd-resolved listening on port 53 by default. This will prevent us from running our own DNS server To disable it temporarily and run our own server

# stop
sudo systemctl stop systemd-resolved
# disable
sudo systemctl disable systemd-resolved

To disable it permanently, uncomment and change DNSStubListener to no in /etc/systemd/resolved.conf; you can revert back everything to default if you stop using the vpn-hole library as a standalone. Also stop any other service which prevents from listening on port 53. Then, you can simply execute the binary file.

In Windows, an executable named- vpnhole.exe would be created.

# executing the binary

This would start the network wide DNS-level blocker on port 53.

Test the blocker

To check if the blocker is blocking malicious domains from the provided blacklist, run nslookup command and see the response:

# For example: '' is one of the domain in the blacklist

nslookup -port=53 localhost

Server:  UnKnown
Address:  ::1

Non-authoritative answer:
Addresses:  ::


To integrate the VPN-Hole Library with existing cross-platform applications, we will be using gomobile to compile and bind it.

# For binding with Android Platforms:

cd vpn-hole/vpnhole

# use gomobile to generate .aar:

gomobile bind -target='android' -o path/for/the/output/filename.aar -v path/for/vpnhole.go

For example: 
# Here pwd is path/vpn-hole/vpnhole

gomobile bind -target='android' -o vpn-hole.aar -v

# Similarly, GoMobile can be used to compile for other platforms like iOS (XCode is required):

gomobile bind -target='ios' -o path/for/the/output/filename.framework -v path/for/vpnhole.go

Adapting to Bitmask_core


This project is released under GNU GPLv3 License.See LICENSE file for details.


Last updated on 24 Oct 2022

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

SocketSocket SOC 2 Logo


  • Package Issues
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc