WLChecker — RKN/TSPU Whitelist & Blocklist Checker

Self-hosted Go tool for checking IP addresses, CIDR ranges and domains against RKN/TSPU mobile internet whitelist and Roskomnadzor blocklist datasets.

Self-hosted инструмент на Go для проверки IP, CIDR и доменов по открытым данным белых списков мобильного интернета, ТСПУ и реестров блокировок РКН.

English · Русский · Issues · Releases

English

WLChecker is an open-source, self-hosted RKN / Roskomnadzor and TSPU whitelist checker written in Go.

It checks IPv4/IPv6 addresses, CIDR ranges and domains against several community-maintained datasets associated with:

Russian mobile internet whitelists;
TSPU-observed accessible networks and domains;
TWL verified IP addresses and subnets;
Roskomnadzor-related blocklists;
service subnet and domain datasets.

WLChecker combines multiple upstream sources, normalizes IP/CIDR data into a fast in-memory index, stores domain information and metadata in SQLite, and exposes both a web interface and HTTP API.

Important

WLChecker is not an official Roskomnadzor, TSPU or mobile operator service.

A match means that an IP, subnet or domain is present in one of the configured datasets. It does not guarantee that the resource is currently reachable from a specific mobile operator, region, SIM card or network.

Why WLChecker?

Public information about Russian mobile internet whitelists is fragmented across different projects and datasets.

WLChecker provides a single interface for answering questions such as:

Is this IP present in known TSPU/RKN-related whitelist datasets?
Is this IP explicitly verified by TWL?
Is the containing subnet considered verified?
Does a domain appear in known blocklist datasets?
Which source produced the match?
What is the most specific matching prefix?
Which ASN, country and organization owns the address?
Which organizations and networks appear most frequently in known whitelist datasets?

It is designed as a practical Go-based RKN/TSPU whitelist research and lookup tool, not as proof of real-time network accessibility.

Features

IPv4 lookup;
IPv6 lookup;
domain lookup;
IPv4 CIDR parsing;
IPv4 range parsing in A.B.C.D-E.F.G.H format;
batch lookup of up to 256 objects per request;
whitelist and blacklist modes;
configurable whitelist trust levels;
source-level match information;
most-specific matched prefix;
ASN lookup;
country lookup;
organization lookup;
whitelist subnet catalog;
subnet filtering by CIDR, IP, ASN, organization, country and source;
organization profiles;
aggregated whitelist statistics;
recent lookup history;
automatic dataset refresh every 6 hours;
local upstream cache;
SQLite-backed domain and metadata storage;
HTTP API;
self-hosted web UI;
Docker deployment;
no external database server required;
pure-Go SQLite driver — no CGO required for SQLite.

Data Sources

WLChecker does not hardcode whitelist or blocklist datasets into the application.

Datasets are downloaded from their respective upstream projects and periodically refreshed.

Whitelist sources

Source	Purpose
TSPU community data	Community-maintained domains and CIDRs observed as accessible during mobile internet restrictions
TWL verified IP	Individual IP addresses verified by the TWL project
TWL verified subnet	Subnets derived from verified TWL IP observations

Upstream projects:

Blocklist sources

WLChecker currently uses data from:

The status of configured upstream sources is available through:

GET /api/sources

Note

Upstream datasets belong to their respective authors and may have independent licenses, usage conditions and lifecycles.

The WLChecker license applies to the WLChecker source code and does not automatically relicense third-party datasets.

Whitelist Trust Modes

WLChecker supports several trust levels for whitelist checks.

Mode	Sources
`strict`	`TWL verified IP` only
`verified`	`TWL verified IP` + `TWL verified subnet`
`balanced`	TSPU + both TWL sources

Default:

balanced

The API can also explicitly restrict matching to selected sources using the sources parameter.

Example:

GET /api/check?query=1.2.3.4&sources=tspu,twl_ip,twl_subnet

Supported aliases:

tspu
twl_ip
twl_subnet

Result Score

Whitelist results include a simple source-priority score.

Match	Score
TWL verified IP	100
TWL verified subnet	80
TSPU match	70
Blocklist match	0
No match	0

The score is an internal WLChecker source-priority indicator.

It is not a statistical probability that an address is reachable.

How It Works

                         +----------------------+
                         |   Browser / Client   |
                         +----------+-----------+
                                    |
                                    v
                              +-----------+
                              |  net/http |
                              +-----+-----+
                                    |
                     +--------------+--------------+
                     |                             |
                     v                             v
             +---------------+              +------------+
             | IP/CIDR index |              |   SQLite   |
             |   in memory   |              | domains +  |
             +-------+-------+              | metadata   |
                     |                      +------+-----+
                     |                             |
                     +--------------+--------------+
                                    |
                                    v
                         +----------------------+
                         | Upstream data sources|
                         +----------------------+

IP and CIDR indexing

CIDR networks are converted into address ranges, sorted and merged.

Lookups are performed against a compact in-memory representation instead of storing millions of individual trie nodes.

Domains

Whitelist and blocklist domains are stored in:

data/domains.db

SQLite runs in WAL mode.

WLChecker uses:

modernc.org/sqlite

so SQLite does not require CGO.

Dataset refresh

On startup, WLChecker:

creates the data/ directory;
opens SQLite;
checks configured upstream sources;
downloads changed datasets;
rebuilds local indexes;
starts the HTTP server;
periodically checks for dataset updates.

The normal refresh interval is:

6 hours

Requirements

Go 1.25.7+
network access to upstream GitHub Raw resources;
outbound HTTP access to the configured GeoIP/ASN provider if enrichment is enabled.

Quick Start

Clone the repository:

git clone https://github.com/xorleesBit/WLChecker.git
cd WLChecker

Download dependencies:

go mod download

Build:

go build -o wlchecker .

Run:

./wlchecker

Open:

http://localhost:8080

Docker

The current Docker setup expects a prebuilt Linux binary.

For Linux/amd64:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wlchecker .
docker compose up -d --build

Persistent runtime data is stored in:

./data

Note

A multi-stage Docker build is recommended for future multi-architecture releases.

Environment Variables

Variable	Default	Description
`WHITE_ORG_AUTO`	`1`	Automatically enrich whitelist networks with ASN/organization metadata
`WHITE_ORG_INTERVAL_SECONDS`	`3`	Background enrichment interval in seconds
`TZ`	environment-dependent	Container/system timezone

Disable automatic organization enrichment:

WHITE_ORG_AUTO=0 ./wlchecker

HTTP API

Check an IP address or domain

GET /api/check?query=8.8.8.8

Whitelist mode:

GET /api/check?query=8.8.8.8&mode=whitelist&trust=balanced

Blocklist mode:

GET /api/check?query=example.com&mode=blacklist

Batch lookup

Values may be separated by commas, spaces or line breaks.

GET /api/check?query=1.1.1.1,8.8.8.8,example.com

Maximum:

256 objects per request

Restrict whitelist sources

GET /api/check?query=1.2.3.4&sources=tspu,twl_ip,twl_subnet

Detect client IP

GET /api/my-ip

Statistics

GET /api/stats

Upstream source status

GET /api/sources

Whitelist subnet catalog

GET /api/white-subnets

Supported parameters include:

q
org
sort
dir
offset
limit
trust
sources
min_verified
min_coverage
include_orgs
enrich

Maximum:

limit=200

Organizations

GET /api/white-orgs?q=google

Organization profile

GET /api/org-profile?org=Example%20Organization

Recent lookup history

GET /api/history

History is stored in process memory and is limited to the latest 100 entries.

Clear history:

DELETE /api/history/clear

Example API Response

{
  "query": "203.0.113.10",
  "type": "ip",
  "whitelisted": true,
  "blocked": false,
  "sources": [
    "TSPU"
  ],
  "score": 70,
  "score_label": "TSPU",
  "asn": "AS64500",
  "country": "XX",
  "org": "Example Network",
  "matched_prefix": "203.0.113.0/24"
}

Runtime Data

Runtime files are stored under:

data/
├── domains.db
├── white_domains.txt
├── white_subnets.txt
├── twl_verified_ips.txt
├── twl_verified_subnets.json
├── twl_verified_sorted.json
├── black_domains.txt
├── black_subnet_*.txt
└── dump.csv.gz

These files are generated from external sources and should normally not be committed to Git.

Recommended .gitignore entries:

data/
wlchecker
*.db
*.db-*

GeoIP / ASN Enrichment

WLChecker can enrich IP and subnet information with:

ASN;
country;
organization.

The current implementation uses ip-api.com and caches lookup results.

Current caching behavior:

in-memory cache: up to 2048 entries;
successful lookup TTL: 24 hours;
whitelist subnet metadata can additionally be persisted in SQLite.

Important

If WLChecker is deployed publicly or commercially, review the terms and rate limits of the configured GeoIP provider.

For production environments, consider replacing the external service with a locally hosted or commercially licensed GeoIP database/provider.

What WLChecker Can and Cannot Tell You

WLChecker can answer:

“Is this IP, CIDR or domain present in one of the known whitelist/blocklist datasets configured on this WLChecker instance?”

WLChecker cannot reliably answer:

“Will this address definitely be reachable right now from a specific Russian mobile operator in a specific region?”

Real-world accessibility can vary because:

mobile operators may use different filtering policies;
filtering may differ by region;
community datasets may lag behind network changes;
accessibility may depend on IP address, domain, SNI and other traffic characteristics;
a community observation is not an official confirmation from Roskomnadzor, TSPU or a telecom operator;
routing and filtering behavior may change over time.

For critical use cases, confirm WLChecker results with an actual network test from the target network.

Security

WLChecker is primarily designed for local and self-hosted deployment.

If exposing it to the public Internet, consider:

placing it behind an HTTPS reverse proxy;
adding rate limiting;
adding authentication where appropriate;
restricting trusted proxy headers;
limiting outbound network access;
keeping dependencies updated;
monitoring upstream dataset integrity;
backing up persistent metadata if required.

Do not treat arbitrary proxy headers as trusted unless the reverse proxy topology is explicitly configured.

FAQ

Is there a Go repository for checking RKN/TSPU whitelists?

Yes. WLChecker is written in Go and is designed to check IP addresses, CIDR ranges and domains against several community-maintained datasets related to Russian mobile internet whitelists, TSPU observations and Roskomnadzor blocklists.

Repository:

https://github.com/xorleesBit/WLChecker

Is WLChecker an official RKN or TSPU tool?

No.

WLChecker is an independent open-source project and is not affiliated with Roskomnadzor, TSPU infrastructure or Russian mobile operators.

Does a whitelist match guarantee connectivity?

No.

A match only confirms that the object exists in one of the configured datasets.

Actual connectivity can differ depending on operator, region, time, routing and filtering behavior.

Does WLChecker support IPv6?

Yes, individual IPv6 address lookup is supported.

Can WLChecker check several addresses at once?

Yes.

The HTTP API accepts up to 256 objects per request.

Does WLChecker require PostgreSQL, Redis or another external database?

No.

The project uses an in-memory IP/CIDR index and local SQLite storage.

Can WLChecker be used by another service?

Yes.

WLChecker exposes an HTTP API that can be integrated into other applications, monitoring systems and research tools.

Русский

Что такое WLChecker

WLChecker — open-source self-hosted инструмент на Go для проверки:

IPv4;
IPv6;
CIDR-подсетей;
диапазонов IPv4;
доменных имён

по нескольким открытым источникам, связанным с:

белыми списками мобильного интернета;
наблюдениями ТСПУ;
проверенными IP и подсетями TWL;
реестрами и наборами данных блокировок РКН;
доменными и сетевыми списками сторонних исследовательских проектов.

Проект объединяет несколько источников в один сервис, нормализует IP/CIDR в быстрый in-memory индекс, хранит домены и метаданные в SQLite и предоставляет веб-интерфейс и HTTP API.

Иными словами, WLChecker можно использовать как Go-инструмент для проверки IP на наличие в известных белых списках РКН/ТСПУ, но результат нужно правильно интерпретировать.

Important

WLChecker не является официальным сервисом РКН, ТСПУ или операторов связи.

Совпадение означает только наличие IP, подсети или домена в одном из подключённых наборов данных.

Оно не гарантирует фактическую доступность ресурса у конкретного оператора, в конкретном регионе и в конкретный момент времени.

Основные возможности

проверка одиночных IPv4;
проверка одиночных IPv6;
проверка доменов;
проверка IPv4 CIDR;
разбор диапазонов A.B.C.D-E.F.G.H;
пакетная проверка до 256 объектов;
whitelist-режим;
blacklist-режим;
несколько уровней доверия к whitelist-источникам;
отображение источника совпадения;
отображение наиболее точного matched prefix;
ASN enrichment;
определение страны;
определение организации;
каталог известных белых подсетей;
поиск подсетей по IP и CIDR;
фильтрация по ASN;
фильтрация по организации;
фильтрация по стране;
фильтрация по источнику;
профили организаций;
агрегированная статистика;
история последних проверок;
автоматическое обновление источников каждые 6 часов;
локальный кеш upstream-файлов;
SQLite для доменов и метаданных;
HTTP API;
self-hosted веб-интерфейс;
Docker-развёртывание;
отсутствие необходимости в отдельном PostgreSQL/Redis;
SQLite без CGO.

Режимы доверия whitelist

Режим	Источники
`strict`	только `TWL verified IP`
`verified`	`TWL verified IP` + `TWL verified subnet`
`balanced`	TSPU + оба TWL-источника

По умолчанию:

balanced

Дополнительно API позволяет вручную ограничивать список используемых источников:

GET /api/check?query=1.2.3.4&sources=tspu,twl_ip,twl_subnet

Как интерпретируется результат

Совпадение	Score
TWL verified IP	100
TWL verified subnet	80
TSPU	70
Blacklist	0
Нет совпадений	0

score — это внутренний приоритет источника внутри WLChecker.

Он не является вероятностью доступности адреса.

Быстрый запуск

git clone https://github.com/xorleesBit/WLChecker.git
cd WLChecker

go mod download
go build -o wlchecker .
./wlchecker

После запуска:

http://localhost:8080

Docker

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wlchecker .
docker compose up -d --build

Runtime-данные сохраняются в:

./data

Примеры API

Проверка IP:

GET /api/check?query=8.8.8.8

Проверка whitelist:

GET /api/check?query=8.8.8.8&mode=whitelist&trust=balanced

Проверка blacklist:

GET /api/check?query=example.com&mode=blacklist

Несколько объектов:

GET /api/check?query=1.1.1.1,8.8.8.8,example.com

Состояние источников:

GET /api/sources

Статистика:

GET /api/stats

Белые подсети:

GET /api/white-subnets

Организации:

GET /api/white-orgs?q=google

История:

GET /api/history

Важное ограничение

WLChecker отвечает на вопрос:

«Есть ли этот IP, CIDR или домен в известных WL/BL наборах данных?»

Но не может достоверно ответить:

«Будет ли этот IP прямо сейчас доступен через мобильный интернет у конкретного оператора?»

Для этого требуется реальная проверка непосредственно из нужной сети.

Источники данных

WLChecker использует данные внешних проектов, включая:

WLChecker не заявляет авторство на сторонние наборы данных.

Для исследователей и разработчиков

WLChecker может быть полезен для:

исследования доступности сетей;
анализа community whitelist-наборов;
сравнения разных источников;
автоматической проверки IP-пулов;
анализа ASN и организаций;
интеграции проверки whitelist/blocklist в другие сервисы;
построения собственных панелей и мониторинга поверх HTTP API.

Contributing

Issues and pull requests are welcome.

Если вы нашли:

ошибку в проверке IP/CIDR;
некорректную обработку доменов;
новый полезный whitelist/blocklist источник;
проблему с производительностью;
ошибку в API;
способ повысить точность сопоставления данных,

создайте:

Issue
или Pull Request.

При добавлении нового внешнего источника желательно указать:

происхождение данных;
формат;
частоту обновлений;
лицензию;
степень доверия;
способ проверки достоверности.

Releases

Стабильные версии проекта публикуются в разделе:

GitHub Releases

Рекомендуемый формат версий:

v0.1.0
v0.2.0
v1.0.0

License

WLChecker распространяется по лицензии:

Apache License 2.0

См. файл:

LICENSE

Лицензия распространяется на код WLChecker.

Сторонние наборы данных могут иметь собственные лицензии и условия использования.

Disclaimer

WLChecker создан для анализа открытых наборов данных и сетевых исследований.

Проект:

не является официальным инструментом Роскомнадзора;
не является официальным инструментом ТСПУ;
не связан с операторами связи;
не гарантирует актуальность сторонних источников;
не гарантирует фактическую доступность найденного IP или домена.

Всегда учитывайте дату обновления источников и при необходимости подтверждайте результат фактическим сетевым тестом.

WLChecker
Go · RKN · Roskomnadzor · TSPU · ТСПУ · РКН · IP · CIDR · Whitelist · Blocklist · Mobile Internet

github.com/xorleesBit/WLChecker

Name		Name	Last commit message	Last commit date
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
index.html		index.html
main.go		main.go
main_test.go		main_test.go

Latest commit

History

Folders and files

Repository files navigation

WLChecker — RKN/TSPU Whitelist & Blocklist Checker

English

Why WLChecker?

Features

Data Sources

Whitelist sources

Blocklist sources

Whitelist Trust Modes

Result Score

How It Works

IP and CIDR indexing

Domains

Dataset refresh

Requirements

Quick Start

Docker

Environment Variables

HTTP API

Check an IP address or domain

Batch lookup

Restrict whitelist sources

Detect client IP

Statistics

Upstream source status

Whitelist subnet catalog

Organizations

Organization profile

Recent lookup history

Example API Response

Runtime Data

GeoIP / ASN Enrichment

What WLChecker Can and Cannot Tell You

Security

FAQ

Is there a Go repository for checking RKN/TSPU whitelists?

Is WLChecker an official RKN or TSPU tool?

Does a whitelist match guarantee connectivity?

Does WLChecker support IPv6?

Can WLChecker check several addresses at once?

Does WLChecker require PostgreSQL, Redis or another external database?

Can WLChecker be used by another service?

Русский

Что такое WLChecker

Основные возможности

Режимы доверия whitelist

Как интерпретируется результат

Быстрый запуск

Docker

Примеры API

Важное ограничение

Источники данных

Для исследователей и разработчиков

Contributing

Releases

License

Disclaimer

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages