Я хотел использовать модели OpenRouter в VS Code Agent без входа в GitHub Copilot. VS Code умеет это с помощью пользовательских провайдеров языковых моделей, но на моём компьютере всё заработало только в VS Code Insiders. В этом посте описана настройка VS Code, а также способ понять, нужен ли вам Insiders, и nginx в роли обратного прокси для сетей, где OpenRouter недоступен.

Кратко

1. Сначала попробуйте обычный VS Code. Если увидите описанные ниже симптомы, переходите на VS Code Insiders.
2. Создайте chatLanguageModels.json с провайдером OpenRouter (vendor: "customendpoint") и своими моделями. Используйте точный ID модели с openrouter.ai.
3. Задайте API-ключ через Manage Models → Update API Key. Не оставляйте ключ в JSON в открытом виде: у меня это не сработало.
4. Выберите модель в Models и переключитесь на Agent.
5. Если OpenRouter заблокирован в вашей стране, см. раздел про прокси ниже.

Что понадобится

• Аккаунт OpenRouter с API-ключом и некоторой суммой на балансе. Бесплатные модели приходят и уходят (см. Troubleshooting).
• Модель с поддержкой tool calling. Для режима Agent это необходимо.
• VS Code Insiders, если обычный VS Code у вас не работает (см. следующий раздел).

Нужен ли вам VS Code Insiders?

Возможно, нет, поэтому сначала попробуйте обычный VS Code. На моём компьютере (Stable 1.140) он не заработал:

• С пустым chatLanguageModels.json не было ни кнопки Manage Models, ни команды Chat: Manage Language Models.
• Когда я вручную добавил провайдера в файл и перезапустил VS Code, кнопка и команда появились, но в диалоге Language Models были только модели самого Copilot. Моих моделей OpenRouter там не было, и выбрать их в чате было нельзя.
• Add Models → OpenRouter принимал API-ключ и записывал группу в chatLanguageModels.json, но эта группа не появлялась ни в диалоге, ни в списке моделей, даже после перезапуска.

Почему так, я разбираться не стал. Официальная документация сейчас помечает провайдер Custom endpoint как функцию Insiders, и в Insiders всё описанное ниже работало. Если вы видите те же симптомы, установите VS Code Insiders. Он ставится рядом с обычным VS Code и хранит собственные настройки.

Где находится chatLanguageModels.json

Файл лежит в папке пользовательских данных VS Code Insiders, которая отделена от обычного VS Code (Code - Insiders, а не Code):

• Windows: нажмите Win + R, введите %APPDATA%\Code - Insiders\User и нажмите Enter.
• macOS: в Finder нажмите Cmd + Shift + G и перейдите в ~/Library/Application Support/Code - Insiders/User.
• Linux: перейдите в ~/.config/Code - Insiders/User.

Примечание: в обычном VS Code в этих путях вместо Code - Insiders используется Code. Файл там можно редактировать, но если обычный VS Code не показывает ваши модели, правка не поможет. Редактируйте копию из Insiders.

Создаём провайдера в chatLanguageModels.json

Я не добавлял провайдера через диалог Manage Models. Я написал его в chatLanguageModels.json вручную, и VS Code его подхватил. Вот файл, который я использую:

[{"name": "OpenRouter","vendor": "customendpoint","apiKey": "${input:chat.lm.secret.-32b9a01a}","apiType": "chat-completions","models": [{"id": "qwen/qwen3.8-27b","name": "Qwen3.8 27B","url": "https://openrouter.ai/api/","toolCalling": true,"vision": true,"maxInputTokens": 262000,"maxOutputTokens": 16000},{"id": "deepseek/deepseek-r1","name": "DeepSeek R1","url": "https://openrouter.ai/api/","toolCalling": true,"vision": false,"maxInputTokens": 64000,"maxOutputTokens": 16000}]}]

Значение apiKey VS Code запишет сам после следующего шага. До тех пор о нём можно не беспокоиться.

Что означают поля:

• vendor: "customendpoint" помечает провайдера как пользовательского.
• apiType: "chat-completions" заставляет VS Code использовать Chat Completions API.
• id это ID модели на OpenRouter. Копируйте его со страницы модели.
• url это базовый URL. VS Code строит из него запрос Chat Completions (запрос в итоге уходит на /v1/chat/completions), поэтому здесь .../api/, а не полный адрес эндпоинта.
• toolCalling включает вызов инструментов. Без него Agent работать не может.
• vision указывает, принимает ли модель изображения.
• maxInputTokens и maxOutputTokens это лимиты, которые использует VS Code.

Как выбрать значения для модели

toolCalling и vision берите со страницы модели на OpenRouter. Например, Qwen3.8 27B это vision-language модель с поддержкой инструментов, а DeepSeek R1 только текстовая, поэтому у неё vision равен false.

С лимитами всё менее однозначно. Размер контекста может отличаться у разных провайдеров и источников: для R1 я видел 64K на странице модели и 131K-164K в других местах, для Qwen3.8 27B 262K и 1M. Я беру меньшее значение, оно безопасно с любым провайдером. Не занижайте maxOutputTokens для reasoning-моделей, потому что токены рассуждений тоже считаются выходными. 4096 слишком мало: ответы будут обрезаться.

Если нужна модель Claude, подойдёт тот же блок со slug со страницы модели на OpenRouter (для Sonnet 5 это anthropic/claude-sonnet-5, с vision: true и toolCalling: true).

Задаём API-ключ (этот шаг обязателен)

Кажется естественным записать ключ OpenRouter прямо в apiKey:

"apiKey": "sk-or-v1-..."

Так я и сделал сначала, и это не сработало. OpenRouter отклонял каждый запрос с ошибкой 403. В логе nginx я увидел, что заголовок Authorization содержит только Bearer, без токена после него.

Исправило это следующее: в Manage Models я выбрал провайдера OpenRouter, нажал Update API Key и ввёл ключ там. VS Code заменил значение в файле на ссылку на секрет, который хранит сам:

"apiKey": "${input:chat.lm.secret.-32b9a01a}"

После этого заголовок стал передаваться правильно, и запросы заработали. Бонусом ключ больше не лежит в файле, который может попасть в синхронизацию настроек или в git. Ссылка работает только на том компьютере, где вы выполнили Update API Key, поэтому не копируйте её на другой компьютер. Выполните Update API Key и там.

VS Code сам заменил сырой ключ в файле этой ссылкой, так что ничего дополнительно чистить не нужно.

Используем модель

Вернитесь в Chat view, нажмите Models, выберите модель OpenRouter и переключитесь на Agent. VS Code остаётся интерфейсом и агентом, а OpenRouter поставляет модель, так что модель можно менять правкой одной записи в JSON.

Если OpenRouter недоступен из вашей страны

Если OpenRouter у вас работает, пропустите этот раздел. Иначе запросы можно направлять через обратный прокси nginx на VPS, откуда OpenRouter доступен:

VS Code → https://example.com/openrouter/api/ → nginx → https://openrouter.ai/api/v1/chat/completions

В конфигурации модели замените URL:

"url": "https://example.com/openrouter/api/"

Конфигурация nginx

Вот конфигурация, которая работает у меня (предполагается, что TLS для example.com уже настроен):

location /openrouter/api/v1/chat/completions {    proxy_pass https://openrouter.ai/api/v1/chat/completions;    proxy_ssl_server_name on;    proxy_ssl_name openrouter.ai;    proxy_ssl_protocols TLSv1.2 TLSv1.3;    proxy_ssl_session_reuse on;    proxy_set_header Host openrouter.ai;    proxy_set_header Authorization $http_authorization;    proxy_buffering off;    proxy_cache off;    chunked_transfer_encoding on;    proxy_read_timeout 300s;    proxy_connect_timeout 75s;    proxy_send_timeout 300s;    proxy_buffer_size 32k;    proxy_buffers 8 32k;    proxy_busy_buffers_size 64k;}

Ваш ключ OpenRouter передаётся из заголовка Authorization, который присылает VS Code, поэтому на сервере он не хранится. Location покрывает только путь Chat Completions, поэтому другие эндпоинты, например /v1/models, не проксируются. Здесь это нормально, потому что модели перечислены вручную в JSON.

Замечания по безопасности

• Прокси видит ваш API-ключ и каждый промпт, включая код вашего проекта. Запускайте его только на сервере, который вы контролируете.
• Публичным прокси может воспользоваться любой, кто его найдёт. Ограничьте доступ, например через allow/deny для ваших IP-адресов и limit_req для ограничения частоты запросов. Basic auth здесь не подойдёт, потому что использует тот же заголовок Authorization, в котором передаётся ваш ключ OpenRouter.
• Прежде чем обходить сетевые блокировки, ознакомьтесь с условиями использования OpenRouter и региональными ограничениями, которые к вам относятся.

Troubleshooting

Модель не появляется в списке. Сначала убедитесь, что вы в VS Code Insiders, а не в обычном VS Code, и что правили файл в папке Code - Insiders. Затем проверьте, что JSON корректен и у провайдера задан API-ключ.

403, а заголовок Authorization содержит только Bearer. У меня так было, когда я записал сырой ключ в apiKey. Выполните Update API Key (см. выше), чтобы VS Code сохранил ключ как секрет. Если вы используете прокси nginx, посмотреть, что реально приходит, можно, временно добавив $http_authorization в формат лога. Потом уберите его: он записывает ваш ключ в лог.

404 — This model is unavailable for free. Это я получил, когда попробовал :free-модель:

{"message":"This model is unavailable for free. The paid version is available now - use this slug instead: deepseek/deepseek-r1","code":404}

Бесплатные варианты моделей убирают. В сообщении указан платный slug, подставьте его в id. Эта ошибка также показывает, что запрос дошёл до OpenRouter и ключ принят, так что конфигурация и прокси в порядке.

401. API-ключ отсутствует или неверен. Выполните Update API Key ещё раз.

Agent игнорирует инструменты или падает. Модель или конкретный провайдер, на который OpenRouter направляет запрос, могут не поддерживать tool calling. Проверьте страницу модели и попробуйте другую.

Ответы зависают или приходят сразу целиком (при использовании прокси). Обычно это буферизация. Убедитесь, что задано proxy_buffering off;.

О приватности

В режиме Agent части вашего проекта отправляются провайдеру модели в виде промптов. OpenRouter пересылает их провайдеру, который обслуживает модель, поэтому изучите политику обработки данных у моделей, которые используете, особенно у бесплатных.

I wanted to use OpenRouter models in the VS Code Agent without signing in to GitHub Copilot. VS Code can do this with custom language model providers, but on my machine it only worked in VS Code Insiders. This post shows the setup, how to tell whether you need Insiders, and an nginx reverse proxy for networks where OpenRouter is not reachable.

TL;DR

1. Try the regular VS Code first. If you see the symptoms described below, switch to VS Code Insiders.
2. Create chatLanguageModels.json with an OpenRouter provider (vendor: "customendpoint") and your models. Use the exact model ID from openrouter.ai.
3. Set the API key with Manage Models → Update API Key. Don’t leave the raw key in the JSON: it didn’t work for me.
4. Select the model in Models and switch to Agent.
5. If OpenRouter is blocked in your country, see the proxy section below.

Prerequisites

• An OpenRouter account with an API key and some credit. Free models come and go (see Troubleshooting).
• A model that supports tool calling. Agent mode needs it.
• VS Code Insiders, if the regular VS Code doesn’t work for you (see the next section).

Do you need VS Code Insiders?

Maybe not, so try the regular VS Code first. On my machine (Stable 1.140), it didn’t work:

• With an empty chatLanguageModels.json there was no Manage Models button and no Chat: Manage Language Models command.
• After I added a provider to the file by hand and restarted, the button and the command appeared, but the Language Models dialog showed only Copilot’s own models. My OpenRouter models were nowhere to be found, and I couldn’t select them in the chat.
• Add Models → OpenRouter accepted an API key and wrote a group to chatLanguageModels.json, but the group never showed up in the dialog or in the model picker, even after a restart.

I didn’t dig into why. The official docs currently list the Custom endpoint provider as an Insiders feature, and in Insiders everything below worked. So if you see the same symptoms, install VS Code Insiders. It installs side by side with the regular VS Code and keeps its own settings.

Where is chatLanguageModels.json

The file lives in the user data folder of VS Code Insiders, which is separate from the regular VS Code (Code - Insiders, not Code):

• Windows: press Win + R, enter %APPDATA%\Code - Insiders\User and press Enter.
• macOS: in Finder press Cmd + Shift + G and go to ~/Library/Application Support/Code - Insiders/User.
• Linux: go to ~/.config/Code - Insiders/User.

Note: the regular VS Code uses Code instead of Code - Insiders in these paths. You can edit the file there, but if the regular VS Code doesn’t show your models, editing it won’t help. Edit the Insiders copy.

Create the provider in chatLanguageModels.json

I didn’t add the provider through the Manage Models dialog. I wrote it in chatLanguageModels.json by hand and VS Code picked it up. This is the file I use:

[{"name": "OpenRouter","vendor": "customendpoint","apiKey": "${input:chat.lm.secret.-32b9a01a}","apiType": "chat-completions","models": [{"id": "qwen/qwen3.8-27b","name": "Qwen3.8 27B","url": "https://openrouter.ai/api/","toolCalling": true,"vision": true,"maxInputTokens": 262000,"maxOutputTokens": 16000},{"id": "deepseek/deepseek-r1","name": "DeepSeek R1","url": "https://openrouter.ai/api/","toolCalling": true,"vision": false,"maxInputTokens": 64000,"maxOutputTokens": 16000}]}]

The apiKey value is what VS Code writes after the next step. Until then, don’t worry about it.

What the fields mean:

• vendor: "customendpoint" marks this as a custom model provider.
• apiType: "chat-completions" makes VS Code use the Chat Completions API.
• id is the model ID on OpenRouter. Copy it from the model’s page.
• url is the base URL. VS Code builds the Chat Completions request from it (the request ends up at /v1/chat/completions), which is why it is .../api/ and not the full endpoint.
• toolCalling enables tool calling. Without it the Agent can’t work.
• vision says whether the model accepts images.
• maxInputTokens and maxOutputTokens are the limits VS Code uses.

Choosing values for a model

Take toolCalling and vision from the model’s page on OpenRouter. For example, Qwen3.8 27B is a vision-language model that accepts tools, while DeepSeek R1 is text-only, so vision is false there.

Limits are less clear-cut. The context size can differ between providers and sources: for R1 I’ve seen 64K on the model page and 131K-164K elsewhere, and for Qwen3.8 27B 262K and 1M. I use the smaller figure, which is safe with any provider. Don’t set maxOutputTokens too low for reasoning models, because reasoning tokens count as output. 4096 is too small, since answers get cut off.

If you want a Claude model, the same block works with the slug from its OpenRouter page (for Sonnet 5 it is anthropic/claude-sonnet-5, with vision: true and toolCalling: true).

Set the API key (this step is not optional)

It might seem natural to write your OpenRouter key directly into apiKey:

"apiKey": "sk-or-v1-..."

That is what I did first, and it didn’t work. OpenRouter rejected every request with a 403. I checked the nginx log and found that the Authorization header contained just Bearer, with no token after it.

What fixed it: in Manage Models I selected the OpenRouter provider and chose Update API Key, then entered the key there. VS Code replaced the value in the file with a reference to a secret it stores itself:

"apiKey": "${input:chat.lm.secret.-32b9a01a}"

After that the header was passed correctly and requests went through. As a bonus, the key no longer sits in a file. The reference only works on the machine where you ran Update API Key, so don’t copy it to another machine. Run Update API Key there too.

VS Code replaced the raw key in the file with that reference on its own, so nothing else needs cleaning up.

Using the model

Go back to the Chat view, click Models, pick the OpenRouter model and switch to Agent. VS Code stays the interface and the agent, while OpenRouter provides the model, so you can swap models by editing one entry in the JSON.

If OpenRouter is not reachable from your country

If OpenRouter works for you, skip this section. Otherwise, you can route requests through an nginx reverse proxy on a VPS that can reach it:

VS Code → https://example.com/openrouter/api/ → nginx → https://openrouter.ai/api/v1/chat/completions

In the model config, change the URL:

"url": "https://example.com/openrouter/api/"

nginx configuration

This is the configuration that works for me (TLS for example.com is assumed to be configured already):

location /openrouter/api/v1/chat/completions {    proxy_pass https://openrouter.ai/api/v1/chat/completions;    proxy_ssl_server_name on;    proxy_ssl_name openrouter.ai;    proxy_ssl_protocols TLSv1.2 TLSv1.3;    proxy_ssl_session_reuse on;    proxy_set_header Host openrouter.ai;    proxy_set_header Authorization $http_authorization;    proxy_buffering off;    proxy_cache off;    chunked_transfer_encoding on;    proxy_read_timeout 300s;    proxy_connect_timeout 75s;    proxy_send_timeout 300s;    proxy_buffer_size 32k;    proxy_buffers 8 32k;    proxy_busy_buffers_size 64k;}

Your OpenRouter key is passed through from the Authorization header sent by VS Code, so it is never stored on the server. The location covers only the Chat Completions path, so other endpoints, such as /v1/models, are not proxied. That’s fine here because the models are listed manually in the JSON.

Security notes

• The proxy sees your API key and every prompt, including your project’s code. Only run it on a server you control.
• A public proxy can be used by anyone who finds it. Restrict access, for example with allow/deny for your IP addresses and limit_req for rate limiting. Basic auth won’t work here, because it uses the same Authorization header that carries your OpenRouter key.
• Check OpenRouter’s terms of service and any regional restrictions that apply to you before routing around network blocks.

Troubleshooting

The model doesn’t appear in the picker. First check that you are in VS Code Insiders and not in the regular VS Code, and that you edited the file in the Code - Insiders folder. Then check that the JSON is valid and that the provider has an API key set.

403, and the Authorization header contains only Bearer. I got this when I wrote the raw key into apiKey. Run Update API Key (see above) so that VS Code stores the key as a secret. If you use the nginx proxy, you can see what actually arrives by temporarily logging $http_authorization in your log format. Remove it afterwards, because it puts your key into the log.

404 — This model is unavailable for free. This is what I got when I tried a :free model:

{"message":"This model is unavailable for free. The paid version is available now - use this slug instead: deepseek/deepseek-r1","code":404}

Free variants of models get removed. The message contains the paid slug, so put it into id. The error also tells you that the request reached OpenRouter and the key was accepted, so the config and the proxy are fine.

401. The API key is missing or wrong. Run Update API Key again.

The Agent ignores tools or fails. The model, or the specific provider OpenRouter routes you to, may not support tool calling. Check the model’s page and try another model.

Responses hang or arrive all at once (when using the proxy). This is usually buffering. Make sure proxy_buffering off; is set.

A note on privacy

In Agent mode, parts of your project are sent to the model provider as prompts. OpenRouter forwards them to the provider that serves the model, so check the data policy of the models you use, especially the free ones.

Step-by-Step Instructions

1. Open the settings.json configuration file:
   • Press Ctrl + Shift + P.
   • Type Preferences: Open User Settings (JSON) into the search bar and press Enter.
2. Add the profile configuration:
   Insert the following block of settings inside the main curly braces { … } of your settings.json file:

"terminal.integrated.profiles.windows": {    "Developer PowerShell (x64)": {        "source": "PowerShell",        "overrideName": true,        "args": [            "-NoExit",            "-Command",            "& { Import-Module 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\Tools\\Microsoft.VisualStudio.DevShell.dll'; Enter-VsDevShell 43240475 -SkipAutomaticLocation -DevCmdArguments '-arch=x64' }"        ]    },    "Developer PowerShell (x86)": {        "path": "C:\\Windows\\SysWOW64\\WindowsPowerShell\\v1.0\\powershell.exe",        "overrideName": true,        "args": [            "-NoExit",            "-Command",            "& { Import-Module 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\Tools\\Microsoft.VisualStudio.DevShell.dll'; Enter-VsDevShell 43240475 -SkipAutomaticLocation }"        ]    }}

(Note: The paths are specified for a standard Visual Studio 2022 Community installation. If you are using Professional or Enterprise editions, replace Community in the paths with the corresponding name).

3. Apply the settings:
   • Save the settings.json file.
   • Close active terminal sessions in VS Code using the trash can icon (Kill Terminal) in the terminal panel to refresh the profile list.
4. Launch the terminals:
   • Click the arrow next to the “plus” sign in the upper-right corner of the terminal panel.
   • Select the required architecture from the dropdown list: Developer PowerShell (x64) or Developer PowerShell (x86).

Пошаговая инструкция

1. Откройте конфигурационный файл settings.json:
   • Нажмите комбинацию клавиш Ctrl + Shift + P.
   • Введите в поисковую строку Preferences: Open User Settings (JSON) и нажмите Enter.
2. Добавьте конфигурацию профилей:
   Вставьте следующий блок настроек внутрь основных фигурных скобок { … } вашего файла settings.json:

"terminal.integrated.profiles.windows": {    "Developer PowerShell (x64)": {        "source": "PowerShell",        "overrideName": true,        "args": [            "-NoExit",            "-Command",            "& { Import-Module 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\Tools\\Microsoft.VisualStudio.DevShell.dll'; Enter-VsDevShell 43240475 -SkipAutomaticLocation -DevCmdArguments '-arch=x64' }"        ]    },    "Developer PowerShell (x86)": {        "path": "C:\\Windows\\SysWOW64\\WindowsPowerShell\\v1.0\\powershell.exe",        "overrideName": true,        "args": [            "-NoExit",            "-Command",            "& { Import-Module 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\Tools\\Microsoft.VisualStudio.DevShell.dll'; Enter-VsDevShell 43240475 -SkipAutomaticLocation }"        ]    }}

(Примечание: Пути указаны для стандартной установки Visual Studio 2022 Community. При использовании редакций Professional или Enterprise замените Community в путях на соответствующее наименование).

3. Применение настроек:
   • Сохраните файл settings.json.
   • Закройте активные сессии терминала в VS Code с помощью иконки корзины (Kill Terminal) на панели терминала для обновления списка профилей.
4. Запуск терминалов:
   • Нажмите на стрелку рядом со знаком «плюс» в верхнем правом углу панели терминала.
   • Выберите необходимую архитектуру из выпадающего списка: Developer PowerShell (x64) или Developer PowerShell (x86).

Chrome has its own TLS stack, BoringSSL, Google’s fork of OpenSSL. I built a proof-of-concept BoringSslConsole: a .NET 8 console application and a BoringSslStream wrapper that exposes BoringSSL as an ordinary Stream.

Sources: https://github.com/optinsoft/BoringSslConsole

The main architectural requirement for the wrapper is this: BoringSSL must not perform any network operations. All I/O goes through the managed innerStream. Below I’ll explain why this is needed and how it’s structured.

Why a “networkless” BoringSSL

BoringSSL can work with the network itself: it has socket and file BIOs (BIO_new_socket, BIO_new_fd). If I had used them, the library would drive data through the socket itself, and there would be no way to implement asynchrony or substitute my own transport.

I needed something different: for the TLS layer to work on top of any Stream. This could be a NetworkStream, a tunnel through a proxy (CONNECT, SOCKS), a MemoryStream in tests, or another layer on top of TLS. Therefore the native part is responsible only for TLS state: handshake, encryption, and decryption of records. And C# moves the bytes to and from the network.

Architecture

TcpClient   |NetworkStream  (innerStream)   |BoringSslStream (C#): pumps bytes between the stream and the buffers   |BoringSSL, memory BIO (pure TLS state, no network)   |HTTP/1.1 or HTTP/2

Between C# and BoringSSL there are two in-memory buffers (BIO_s_mem):

• input: C# puts bytes read from innerStream here (pms_ssl_feed_read);
• output: C# takes bytes from here that need to be sent to innerStream (pms_ssl_take_write, the size can be queried via pms_ssl_pending_write).

The native DLL (proxymap_boringssl.dll) exports a small flat C API: pms_ssl_create, pms_ssl_connect, pms_ssl_read, pms_ssl_write, plus buffer-pumping functions and a few getters (protocol version, cipher, selected ALPN, server DER certificate, last error). All ClientHello parameters are passed from C# as strings and numbers.

BoringSslStream inherits from Stream, so it can be substituted anywhere an ordinary stream is expected. Everything is fully asynchronous, with CancellationToken.

The main loop: pumping bytes

The whole mechanism fits into a single pattern. We call a BoringSSL operation, flush the accumulated output to the network, and if the library asks for data, we read it from the network and feed it back. Here is the handshake:

while (true){    int result = Native.pms_ssl_connect(_connection);    await FlushWriteBioAsync(cancellationToken);    switch (result)    {        case Native.PMS_SSL_OK:            ValidateServerCertificate(_hostname);            _authenticated = true;            return;        case Native.PMS_SSL_WANT_READ:            await ReadFromNetworkAsync(cancellationToken);            break;        case Native.PMS_SSL_WANT_WRITE:            break; // output has already been flushed to the network    }}

FlushWriteBioAsync takes everything accumulated in the output buffer and writes it to innerStream. ReadFromNetworkAsync reads from innerStream and feeds the bytes to the input buffer. The same loop is repeated in ReadAsync and WriteAsync.

The output must be flushed after every BoringSSL call, not just during the handshake: even SSL_read can itself generate TLS records (for example, KeyUpdate or alerts).

Buffers are taken from ArrayPool<byte>, and pointers are passed to native code via Memory<T>.Pin(), without unnecessary copies.

Synchronization

The class has four SemaphoreSlims: _readLock and _writeLock serialize reads and writes respectively, while _networkReadLock and _networkWriteLock protect the exchange with innerStream. Thanks to this, concurrent ReadAsync and WriteAsync calls don’t break each other’s work with the stream and buffers. The handshake takes both outer locks at once.

A caveat: this is sufficient for a PoC, but a full-fledged full-duplex over a single SSL* requires care on the native library side as well, not just in C#. I’ll mention this again in the limitations.

The “like Chrome” preset

The BoringSslStream constructor accepts a set of parameters, filled by default with Chrome’s values:

• cipher list: ECDHE variants of AES-GCM and ChaCha20-Poly1305, plus a legacy tail;
• GREASE and ECH GREASE;
• ALPN h2:http/1.1 and ALPS h2;
• signature algorithms, including post-quantum ML-DSA-44/65/87;
• SCT, status_request, Brotli certificate compression;
• trust_anchors as a hex string.

The fine-grained work with extensions (reordering, dynamic formation of ALPN/ALPS, padding of status_request) is done on the C++ side. Brotli is linked statically so that everything builds into a single self-contained DLL and there’s no DllNotFoundException at runtime.

On tls.peet.ws the JA4 fingerprint matched Chrome. But JA3 does not match, and that’s how it should be. Starting with Chrome 110, the browser randomly shuffles the order of TLS extensions in ClientHello on every connection. JA3 is built from the lists of ciphers, extensions, groups, and point formats in the order they arrived, so a real Chrome’s JA3 hash is different every time, and comparing it to some “reference” is meaningless. Our client does the same: the native layer shuffles extensions, and JA3 changes from connection to connection, just like in the browser.

JA4 is structured differently: before hashing, it sorts ciphers and extensions (and discards GREASE), so shuffling doesn’t affect it. That’s exactly why JA4 is stable and suitable for verification: if it matches, then the set of ciphers, extensions, signature algorithms, and ALPN is the same as Chrome’s.

Certificate verification

Here BoringSSL only negotiates the channel, while the trust decision is made by .NET. Immediately after a successful handshake, the native layer returns the server’s DER certificate, and then:

using var certificate = new X509Certificate2(memory.Span);using var chain = new X509Chain();chain.ChainPolicy.RevocationMode = X509RevocationMode.Online;chain.ChainPolicy.RevocationFlag = X509RevocationFlag.ExcludeRoot;chain.ChainPolicy.ApplicationPolicy.Add(new Oid("1.3.6.1.5.5.7.3.1")); // Server Authif (!chain.Build(certificate))    throw new AuthenticationException(...);if (!certificate.MatchesHostname(hostname))    throw new AuthenticationException(...);

The system root certificate store is used, online revocation checking is enabled, and the hostname is verified via MatchesHostname (available in .NET 8, takes SAN and wildcard rules into account).

It’s easy to test on badssl.com: expired.badssl.com fails on chain building, untrusted-root.badssl.com on an unknown root, revoked.badssl.com on revocation checking. The relevant hosts are commented out in Program.cs; just change one constant.

HTTP/2 by hand

Since ALPN negotiates h2, I had to write a minimal HTTP/2 client right in Program.cs, without third-party libraries.

Sending. First a 24-byte connection preface, then an empty SETTINGS. Then the headers: a tiny HpackEncoder writes indexed fields from the static table (:method: GET is index 2, :scheme: https is 7) and literals without indexing for :authority, :path, and the rest. The block is wrapped in a 9-byte HEADERS frame header with flags END_STREAM | END_HEADERS on stream 1.

Receiving. We read strictly 9 bytes of frame header, parse the length (24 bits), type, flags, and stream id, then read exactly that many bytes of payload. Then we parse by type:

• DATA is written to a file and to the console, and on END_STREAM we exit;
• HEADERS prints the status (see below) and also checks for END_STREAM;
• SETTINGS without the ACK flag is acknowledged with SETTINGS ACK, as RFC requires;
• RST_STREAM and GOAWAY are printed with a decoded error code;
• WINDOW_UPDATE is ignored.

There’s no full HPACK decoder, so the response status is determined by a heuristic: we look in the block for bytes 0x88–0x8E, corresponding to indexed statuses from the static table (0x88 is 200, 0x8D is 404). For a demo this is enough, but it’s precisely a hack.

If ALPN returns http/1.1, everything is simpler: an ordinary text request with Connection: close goes out, and the response is read until the stream closes.

Running

git clone --recursive https://github.com/optinsoft/BoringSslConsole.gitcd Nativecmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Releasecmake --build buildcd ..dotnet run --project BoringSslConsole

To build on Windows you need the .NET 8 SDK, Visual Studio 2022 with C++ tools, CMake 3.22+, Ninja, Git, NASM, and Go (the last two are required by BoringSSL itself). BoringSSL and Brotli are included as git submodules; after building, the DLL is copied to the .NET output directory. The response is printed to the console and saved to ./output/<host>.txt.

Results and limitations

The result is a compact asynchronous Stream with a Chrome-like TLS stack inside, with real certificate verification, while the network is entirely in .NET’s hands. On top of it you can build proxies, an HTTP client, or testing tools, and the transport can be swapped without touching the TLS layer.

An honest list of what’s missing here:

• HTTP/2 is minimal: no HPACK decoder, no CONTINUATION, no flow control, no multiplexing.
• The TLS fingerprint matches, not the whole client. HTTP/2 has its own fingerprint (SETTINGS values, WINDOW_UPDATE, pseudo-header order), and here it differs from Chrome’s.
• Thread safety needs separate verification. The locks in C# separate reads, writes, and network operations, but the safety of concurrent SSL_read and SSL_write on a single SSL* also depends on the native layer. Freeing the SSL* in Dispose should also be synchronized with in-flight operations.
• Chain validation: only the leaf certificate is taken from the native layer, so chain building may depend on AIA fetching of intermediates, and online revocation checking blocks the thread inside async code.
• Platform: building requires a heavy toolchain, and the native part is currently Windows x64 only.

This is a PoC, but the architectural idea — “BoringSSL as a pure TLS machine, with I/O outside” — turned out well, in my opinion, and easily transfers to other transports.

The project on GitHub: optinsoft/BoringSslConsole

У Chrome свой TLS-стек, BoringSSL, форк OpenSSL от Google. Я собрал proof-of-concept BoringSslConsole: консольное приложение на .NET 8 и обёртку BoringSslStream, которая даёт доступ к BoringSSL как к обычному Stream.

Исходники: https://github.com/optinsoft/BoringSslConsole

Главное архитектурное требование к обёртке такое: BoringSSL не должен выполнять никаких сетевых операций. Весь ввод-вывод идёт через управляемый innerStream. Ниже объясню, зачем это нужно и как устроено.

Зачем нужен «бессетевой» BoringSSL

BoringSSL умеет сам работать с сетью: у него есть сокетные и файловые BIO (BIO_new_socket, BIO_new_fd). Если бы я их использовал, библиотека сама бы гоняла данные через сокет, и не было бы возможности реализовать асинхронность, а также подставить свой транспорт.

Мне нужно было другое: чтобы TLS-слой работал поверх любого Stream. Это может быть NetworkStream, туннель через прокси (CONNECT, SOCKS), MemoryStream в тестах или другой слой поверх TLS. Поэтому нативная часть отвечает только за состояние TLS: рукопожатие, шифрование и расшифровку записей. А байты в сеть и из сети гоняет C#.

Архитектура

TcpClient   |NetworkStream  (innerStream)   |BoringSslStream (C#): качает байты между потоком и буферами   |BoringSSL, memory BIO (чистое TLS-состояние, без сети)   |HTTP/1.1 или HTTP/2

Между C# и BoringSSL стоят два in-memory буфера (BIO_s_mem):

• входной: сюда C# кладёт байты, прочитанные из innerStream (pms_ssl_feed_read);
• выходной: отсюда C# забирает байты, которые нужно отправить в innerStream (pms_ssl_take_write, размер можно узнать через pms_ssl_pending_write).

Нативная DLL (proxymap_boringssl.dll) экспортирует небольшой плоский C-API: pms_ssl_create, pms_ssl_connect, pms_ssl_read, pms_ssl_write, плюс функции прокачки буферов и несколько геттеров (версия протокола, шифр, выбранный ALPN, DER-сертификат сервера, последняя ошибка). Все параметры ClientHello передаются из C# строками и числами.

BoringSslStream наследуется от Stream, поэтому подставляется везде, где ждут обычный поток. Всё полностью асинхронно, с CancellationToken.

Главный цикл: прокачка байтов

Весь механизм умещается в один паттерн. Вызываем операцию BoringSSL, сбрасываем накопившийся выход в сеть, а если библиотека просит данных, читаем их из сети и отдаём обратно. Вот рукопожатие:

while (true){    int result = Native.pms_ssl_connect(_connection);    await FlushWriteBioAsync(cancellationToken);    switch (result)    {        case Native.PMS_SSL_OK:            ValidateServerCertificate(_hostname);            _authenticated = true;            return;        case Native.PMS_SSL_WANT_READ:            await ReadFromNetworkAsync(cancellationToken);            break;        case Native.PMS_SSL_WANT_WRITE:            break; // выход уже сброшен в сеть    }}

FlushWriteBioAsync забирает из выходного буфера всё накопленное и пишет в innerStream. ReadFromNetworkAsync читает из innerStream и скармливает байты входному буферу. Тот же цикл повторяется в ReadAsync и WriteAsync.

Сбрасывать выход нужно после каждого вызова BoringSSL, а не только во время рукопожатия: даже SSL_read может сам порождать TLS-записи (например, KeyUpdate или алерты).

Буферы берутся из ArrayPool<byte>, а указатели передаются в нативный код через Memory<T>.Pin(), без лишних копирований.

Синхронизация

В классе четыре SemaphoreSlim: _readLock и _writeLock сериализуют соответственно чтения и записи, а _networkReadLock и _networkWriteLock защищают обмен с innerStream. Благодаря этому одновременные вызовы ReadAsync и WriteAsync не ломают друг другу работу с потоком и буферами. Рукопожатие берёт сразу оба внешних лока.

Оговорка: этого достаточно для PoC, но полноценный full-duplex поверх одного SSL* требует аккуратности и на стороне нативной библиотеки, а не только в C#. Об этом ещё скажу в ограничениях.

Пресет «как Chrome»

Конструктор BoringSslStream принимает набор параметров, по умолчанию заполненных значениями Chrome:

• cipher list: ECDHE-варианты AES-GCM и ChaCha20-Poly1305, плюс легаси-хвост;
• GREASE и ECH GREASE;
• ALPN h2:http/1.1 и ALPS h2;
• алгоритмы подписи, включая постквантовые ML-DSA-44/65/87;
• SCT, status_request, сжатие сертификатов Brotli;
• trust_anchors в виде hex-строки.

Тонкая работа с расширениями (перестановка, динамическое формирование ALPN/ALPS, паддинг status_request) выполнена на C++ стороне. Brotli подключён статически, чтобы всё собиралось в одну автономную DLL и не было DllNotFoundException в рантайме.

На tls.peet.ws совпал JA4-отпечаток Chrome. А вот JA3 не совпадает, и так и должно быть. Начиная с Chrome 110 браузер случайно перемешивает порядок TLS-расширений в ClientHello при каждом соединении. JA3 строится из списков шифров, расширений, групп и форматов точек в том порядке, в котором они пришли, поэтому у настоящего Chrome JA3-хеш каждый раз новый, и сравнивать его с каким-то «эталоном» бессмысленно. Наш клиент делает то же самое: нативный слой переставляет расширения, и JA3 меняется от соединения к соединению, как у браузера.

JA4 устроен иначе: перед хешированием он сортирует шифры и расширения (и отбрасывает GREASE), так что перестановка на него не влияет. Именно поэтому JA4 стабилен и годится для проверки: если он совпал, набор шифров, расширений, алгоритмов подписи и ALPN такой же, как у Chrome.

Проверка сертификата

BoringSSL здесь только согласует канал, а решение о доверии принимает .NET. Сразу после успешного рукопожатия нативный слой отдаёт DER-сертификат сервера, и дальше:

using var certificate = new X509Certificate2(memory.Span);using var chain = new X509Chain();chain.ChainPolicy.RevocationMode = X509RevocationMode.Online;chain.ChainPolicy.RevocationFlag = X509RevocationFlag.ExcludeRoot;chain.ChainPolicy.ApplicationPolicy.Add(new Oid("1.3.6.1.5.5.7.3.1")); // Server Authif (!chain.Build(certificate))    throw new AuthenticationException(...);if (!certificate.MatchesHostname(hostname))    throw new AuthenticationException(...);

Используется системное хранилище корневых сертификатов, включена онлайн-проверка отзыва, имя хоста проверяется через MatchesHostname (доступен в .NET 8, учитывает SAN и правила для wildcard).

Легко проверить на badssl.com: expired.badssl.com падает на построении цепочки, untrusted-root.badssl.com на неизвестном корне, revoked.badssl.com на проверке отзыва. Нужные хосты закомментированы в Program.cs, достаточно сменить одну константу.

HTTP/2 руками

Раз ALPN договаривается о h2, пришлось написать минимальный HTTP/2-клиент прямо в Program.cs, без сторонних библиотек.

Отправка. Сначала 24-байтный connection preface, затем пустой SETTINGS. Потом заголовки: крошечный HpackEncoder пишет индексированные поля из статической таблицы (:method: GET это индекс 2, :scheme: https это 7) и литералы без индексирования для :authority, :path и остального. Блок оборачивается в 9-байтный заголовок кадра HEADERS с флагами END_STREAM | END_HEADERS на стриме 1.

Приём. Читаем строго по 9 байт заголовка кадра, парсим длину (24 бита), тип, флаги и stream id, затем читаем ровно столько байт payload. Дальше разбираем по типу:

• DATA пишем в файл и в консоль, на END_STREAM выходим;
• HEADERS выводим статус (см. ниже) и тоже смотрим на END_STREAM;
• SETTINGS без флага ACK подтверждаем SETTINGS ACK, как требует RFC;
• RST_STREAM и GOAWAY печатаем с расшифровкой кода ошибки;
• WINDOW_UPDATE игнорируем.

Полноценного HPACK-декодера нет, поэтому статус ответа определяется эвристикой: ищем в блоке байты 0x88–0x8E, соответствующие индексированным статусам из статической таблицы (0x88 это 200, 0x8D это 404). Для демонстрации хватает, но это именно хак.

Если ALPN вернул http/1.1, всё проще: уходит обычный текстовый запрос с Connection: close, ответ читается до закрытия потока.

Запуск

git clone --recursive https://github.com/optinsoft/BoringSslConsole.gitcd Nativecmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Releasecmake --build buildcd ..dotnet run --project BoringSslConsole

Для сборки на Windows нужны .NET 8 SDK, Visual Studio 2022 с C++ tools, CMake 3.22+, Ninja, Git, NASM и Go (последние два требуются самому BoringSSL). BoringSSL и Brotli подключены как git-submodule, DLL после сборки копируется в выходной каталог .NET. Ответ выводится в консоль и сохраняется в ./output/<host>.txt.

Итоги и ограничения

Получился компактный асинхронный Stream, внутри которого Chrome-подобный TLS-стек с настоящей проверкой сертификата, а сеть полностью в руках .NET. Поверх него можно строить прокси, HTTP-клиент или тестовые инструменты, и транспорт при этом можно менять, не трогая TLS-слой.

Честный список того, чего здесь нет:

• HTTP/2 минимальный: нет HPACK-декодера, CONTINUATION, управления окнами и мультиплексирования.
• Совпадает TLS-отпечаток, а не весь клиент. У HTTP/2 есть собственный отпечаток (значения SETTINGS, WINDOW_UPDATE, порядок псевдозаголовков), и здесь он отличается от Chrome.
• Потокобезопасность требует отдельной проверки. Блокировки в C# разводят чтение, запись и сетевые операции, но безопасность одновременных SSL_read и SSL_write на одном SSL* зависит и от нативного слоя. Освобождение SSL* в Dispose также стоит синхронизировать с идущими операциями.
• Валидация цепочки: из нативного слоя берётся только листовой сертификат, поэтому построение цепочки может зависеть от AIA-загрузки промежуточных, а онлайн-проверка отзыва блокирует поток внутри async-кода.
• Платформа: сборка требует тяжёлого тулчейна, а нативная часть пока только под Windows x64.

Это PoC, но архитектурная идея, то есть «BoringSSL как чистая TLS-машина, а ввод-вывод снаружи», на мой взгляд, получилась удачной и легко переносится на другие транспорты.

Проект на GitHub: optinsoft/BoringSslConsole

Before buying a VPS, contact the hosting provider and ask: “Is outbound SMTP port 25 open?” Many hosting providers block it by default to prevent spam. If the port is blocked, sending email directly to remote mail servers may not be possible.

1. Preparation: Network and DNS Settings

To make sure your mail is delivered correctly, you need to configure several basic DNS records for your domain:

1. Hostname. Set the server hostname to something like mail.yourdomain.com.

2. A record. Point mail.yourdomain.com to the IP address of your VPS.

3. MX record. Specify which server handles email for your domain. The record looks like this:

   @ MX 10 mail.yourdomain.com.

4. PTR record (Reverse DNS). Maps the server’s IP address back to its hostname. It is configured in your VPS provider’s control panel rather than at your domain registrar.

   A PTR record is important for email delivery. Many mail servers check the reverse DNS record of the sending IP address, and a missing or inconsistent PTR record can result in messages being rejected or sent to spam.

   It is recommended to keep the forward and reverse DNS records consistent:

   1.2.3.4 → mail.yourdomain.commail.yourdomain.com → 1.2.3.4

2. Configuring SPF

SPF is a DNS record that specifies which servers are authorized to send email on behalf of your domain.

Create a TXT record:

• Record type: TXT

• Host/Name: @ (or leave it empty, depending on your DNS provider)

• Value:

  v=spf1 ip4:1.2.3.4 ~all

  Replace 1.2.3.4 with the IP address of your server.

What does ~all mean?

~all means SoftFail: messages sent from IP addresses not listed in the SPF record receive a soft-failure result. The receiving server decides how to handle such messages.

After testing your configuration, you can use -all if all legitimate sources that send email for your domain are listed in the SPF record.

3. Generating DKIM Keys with OpenSSL

DKIM is a digital signature mechanism that helps verify the authenticity of the sender and the integrity of an email. The server signs the message with a private key, and the recipient verifies the signature using the public key published in DNS.

To generate a key pair, connect to the server over SSH and run the following commands.

3.1. Generate a 2048-bit private key

openssl genrsa -out dkim.private 2048

3.2. Generate the public key

openssl rsa -in dkim.private -pubout -out dkim.public

3.3. Display the public key

cat dkim.public

The terminal will display something like:

-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...-----END PUBLIC KEY-----

For the DNS record, take only the Base64-encoded content between the headers and combine it into a single line without spaces or line breaks.

Then create a TXT record named dkim._domainkey (dkim is the selector name).

• Record type: TXT

• Host/Name: dkim._domainkey

• Value:

  v=DKIM1; k=rsa; p=YOUR_COPIED_PUBLIC_KEY

If your DNS provider supports splitting long TXT records into multiple strings, use that option for keys that do not fit into a single string.

4. Connecting DKIM to the Mail Server

4.1 Option A: If You Use Exim

In the Exim configuration file (the exact path depends on the distribution and installation method), find the transport responsible for sending mail to external servers. It is usually called remote_smtp.

Example configuration:

remote_smtp:  driver = smtp  dkim_domain = yourdomain.com  dkim_selector = dkim  dkim_private_key = /etc/exim/dkim.private  dkim_canon = relaxed

Copy the private key to the location specified in the Exim configuration:

cp dkim.private /etc/exim/dkim.private

Give the user running Exim permission to read the private key. The username depends on the distribution. For example, some systems use exim, while Debian may use Debian-exim.

Example for a system using the exim user:

chown exim:exim /etc/exim/dkim.privatechmod 600 /etc/exim/dkim.private

Restart the service:

systemctl restart exim4# orsystemctl restart exim

Make sure that the Exim user actually has access to the private key.

4.2 Option B: If You Use Postfix

Postfix uses the external OpenDKIM utility to add DKIM signatures to outgoing messages.

4.2.1. Install the packages

apt install opendkim opendkim-tools

4.2.2. Configure OpenDKIM

Open /etc/opendkim.conf and add or configure the following settings:

Syslog                 yesRequiredHeaders        yesMode                   svSubDomains             noSocket                 inet:8891@localhostKeyTable               /etc/opendkim/KeyTableSigningTable           /etc/opendkim/SigningTableExternalIgnoreList     /etc/opendkim/TrustedHostsInternalHosts          /etc/opendkim/TrustedHosts

4.2.3. Connect OpenDKIM to Postfix

Add the following lines to the end of the main Postfix configuration file, /etc/postfix/main.cf:

milter_protocol = 6milter_default_action = acceptsmtpd_milters = inet:localhost:8891non_smtpd_milters = inet:localhost:8891

4.2.4. Configure the OpenDKIM tables

This example uses a single domain and a single DKIM key. The key name in KeyTable is dkim._domainkey.yourdomain.com.

/etc/opendkim/KeyTable

This file maps the key name to the domain, selector, and private key path:

dkim._domainkey.yourdomain.com yourdomain.com:dkim:/etc/opendkim/keys/dkim.private

Here:

• dkim._domainkey.yourdomain.com — the key name in the table.
• yourdomain.com — the domain that will appear in the DKIM signature (d=).
• dkim — the selector (s=).
• /etc/opendkim/keys/dkim.private — the path to the private key.

/etc/opendkim/SigningTable

This file maps the sender domain to the key name from KeyTable:

yourdomain.com dkim._domainkey.yourdomain.com

If you need to use a pattern for sender addresses from the domain, you can specify:

*@yourdomain.com dkim._domainkey.yourdomain.com

The wildcard form requires the corresponding refile: table type to be configured in the SigningTable directive. This guide uses the simple domain-based mapping without refile.

/etc/opendkim/TrustedHosts

Add localhost and the IP address of your server:

127.0.0.1localhost1.2.3.4

4.2.5. Move the private key and restart the services

Create the directory for the keys:

mkdir -p /etc/opendkim/keys/

Move the private key:

mv dkim.private /etc/opendkim/keys/

Set the owner and permissions:

chown opendkim:opendkim /etc/opendkim/keyschmod 700 /etc/opendkim/keyschown opendkim:opendkim /etc/opendkim/keys/dkim.privatechmod 600 /etc/opendkim/keys/dkim.private

Restart the services:

systemctl restart opendkim postfix

Check their status:

systemctl status opendkimsystemctl status postfix

If necessary, check the OpenDKIM log:

journalctl -u opendkim -n 50 --no-pager

5. Configuring DMARC

DMARC is a mechanism that allows a domain to tell receiving mail servers how to handle messages that fail the required SPF and DKIM checks, including the alignment of the domains involved with the domain in the From header.

Create a TXT record:

• Record type: TXT

• Host/Name: _dmarc

• Initial value:

  v=DMARC1; p=none; rua=mailto:admin@yourdomain.com

What does this mean?

• p=none — monitoring mode. The domain asks the receiving server not to apply a special action to messages that fail DMARC. You can monitor the results and collect reports.
• rua=mailto:... — the address to which mail services can send aggregate reports about authentication checks.
• p=quarantine — asks the receiving server to treat messages that fail DMARC as suspicious, for example by placing them in the spam folder.
• p=reject — asks the receiving server to reject messages that fail DMARC. The actual action is determined by the receiving server.

After testing and fixing the configuration, you can change the policy from p=none to p=quarantine or p=reject.

6. How to Check DNS Records from the Terminal

You can check whether the DNS settings have been updated using dig or nslookup.

Check SPF

dig yourdomain.com TXT +short

Or:

nslookup -type=TXT yourdomain.com

Check DKIM

The query uses the name of your selector:

dig dkim._domainkey.yourdomain.com TXT +short

Or:

nslookup -type=TXT dkim._domainkey.yourdomain.com

Check DMARC

dig _dmarc.yourdomain.com TXT +short

Or:

nslookup -type=TXT _dmarc.yourdomain.com

Check PTR (Reverse DNS)

dig -x 1.2.3.4 +short

Or:

nslookup 1.2.3.4

Check the server hostname:

hostname -f

Make sure that the hostname is consistent with the A and PTR records.

The recommended setup is:

Hostname: mail.yourdomain.comA:        mail.yourdomain.com → 1.2.3.4PTR:      1.2.3.4 → mail.yourdomain.com

The hostname used by the server and the reverse DNS record should be configured consistently.

Перед покупкой VPS обязательно напишите в поддержку хостинга и спросите: «Открыт ли у вас исходящий 25 порт SMTP?». Многие хостеры закрывают его по умолчанию, чтобы защититься от спамеров. Если порт закрыт, отправка почты напрямую на почтовые серверы может быть невозможна.

1. Подготовка: настройки сети и DNS

Чтобы почта корректно доставлялась, нужно настроить несколько базовых параметров DNS вашего домена:

1. Имя хоста (Hostname). Задайте серверу имя в системе, например mail.yourdomain.com.

2. A-запись. Направьте поддомен mail.yourdomain.com на IP-адрес вашей VPS.

3. MX-запись. Укажите, какой сервер принимает почту для домена. Запись выглядит так:

   @ MX 10 mail.yourdomain.com.

4. PTR-запись (Reverse DNS). Связывает IP-адрес сервера обратно с его именем. Она настраивается в панели хостинга VPS, а не у регистратора домена.

   PTR-запись важна для доставки почты. Многие почтовые серверы проверяют обратную DNS-запись IP-адреса, а её отсутствие или несоответствие может привести к отклонению писем или попаданию в спам.

   Рекомендуется согласовать прямую и обратную DNS-записи:

   1.2.3.4 → mail.yourdomain.commail.yourdomain.com → 1.2.3.4

2. Настройка SPF

SPF — это запись в DNS, которая указывает, каким серверам разрешено отправлять почту от имени вашего домена.

Создайте TXT-запись:

• Тип записи: TXT

• Хост/Имя: @ (или пустое поле, в зависимости от DNS-панели)

• Значение:

  v=spf1 ip4:1.2.3.4 ~all

  Вместо 1.2.3.4 подставьте IP-адрес своего сервера.

Что значит ~all

~all означает SoftFail: сообщения с IP-адресов, не перечисленных в SPF, не проходят проверку с мягким результатом. Принимающий сервер самостоятельно решает, как обработать такое письмо.

После проверки конфигурации можно использовать -all, если все легитимные источники отправки перечислены в SPF.

3. Генерация ключей DKIM через OpenSSL

DKIM — это цифровая подпись, которая помогает проверять подлинность отправителя и целостность письма. Сервер подписывает письмо приватным ключом, а получатель проверяет подпись с помощью публичного ключа из DNS.

Для генерации пары ключей зайдите на сервер по SSH и выполните следующие команды.

3.1. Создаём приватный ключ длиной 2048 бит

openssl genrsa -out dkim.private 2048

3.2. Генерируем публичный ключ

openssl rsa -in dkim.private -pubout -out dkim.public

3.3. Выводим публичный ключ на экран

cat dkim.public

В терминале появится текст примерно такого вида:

-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...-----END PUBLIC KEY-----

Для DNS-записи нужно взять только Base64-содержимое ключа между заголовками и объединить его в одну строку без пробелов и переносов.

Затем создайте TXT-запись dkim._domainkey (где dkim — имя вашего селектора).

• Тип записи: TXT

• Хост/Имя: dkim._domainkey

• Значение:

  v=DKIM1; k=rsa; p=ТУТ_ВАШ_СКОПИРОВАННЫЙ_КЛЮЧ

Если DNS-провайдер поддерживает разбиение длинных TXT-записей на несколько строк, используйте эту возможность для ключей, которые не помещаются в одну строку.

4. Подключение DKIM к почтовому серверу

4.1 Вариант А: если у вас Exim

В конфигурационном файле Exim (точный путь зависит от дистрибутива и способа установки) найдите транспорт, который отвечает за отправку почты наружу. Обычно он называется remote_smtp.

Пример конфигурации:

remote_smtp:  driver = smtp  dkim_domain = yourdomain.com  dkim_selector = dkim  dkim_private_key = /etc/exim/dkim.private  dkim_canon = relaxed

Скопируйте закрытый ключ в место, указанное в конфигурации Exim:

cp dkim.private /etc/exim/dkim.private

Выдайте права на чтение файла приватного ключа пользователю, от имени которого работает Exim. Имя пользователя зависит от дистрибутива. Например, в некоторых системах это exim, а в Debian может использоваться Debian-exim.

Пример для системы с пользователем exim:

chown exim:exim /etc/exim/dkim.privatechmod 600 /etc/exim/dkim.private

Перезапустите сервис:

systemctl restart exim4# илиsystemctl restart exim

Проверьте, что используемый пользователь Exim действительно имеет доступ к приватному ключу.

4.2 Вариант Б: если у вас Postfix

Postfix использует внешнюю утилиту OpenDKIM для добавления DKIM-подписей.

4.2.1. Установите пакеты

apt install opendkim opendkim-tools

4.2.2. Настройте OpenDKIM

Откройте конфигурационный файл /etc/opendkim.conf и добавьте или настройте следующие параметры:

Syslog                 yesRequiredHeaders        yesMode                   svSubDomains             noSocket                 inet:8891@localhostKeyTable               /etc/opendkim/KeyTableSigningTable           /etc/opendkim/SigningTableExternalIgnoreList     /etc/opendkim/TrustedHostsInternalHosts          /etc/opendkim/TrustedHosts

4.2.3. Подключите OpenDKIM к Postfix

В конец основного конфига Postfix /etc/postfix/main.cf добавьте:

milter_protocol = 6milter_default_action = acceptsmtpd_milters = inet:localhost:8891non_smtpd_milters = inet:localhost:8891

4.2.4. Настройте таблицы OpenDKIM

В этом примере используется один домен и один ключ DKIM. Имя ключа в KeyTable — dkim._domainkey.yourdomain.com.

/etc/opendkim/KeyTable

Этот файл связывает имя ключа с доменом, селектором и путём к приватному ключу:

dkim._domainkey.yourdomain.com yourdomain.com:dkim:/etc/opendkim/keys/dkim.private

Здесь:

• dkim._domainkey.yourdomain.com — имя ключа в таблице.
• yourdomain.com — домен, который попадёт в DKIM-подпись (d=).
• dkim — селектор (s=).
• /etc/opendkim/keys/dkim.private — путь к приватному ключу.

/etc/opendkim/SigningTable

Этот файл связывает домен отправителя с именем ключа из KeyTable:

yourdomain.com dkim._domainkey.yourdomain.com

Если необходимо использовать шаблон для адресов отправителей домена, можно указать:

*@yourdomain.com dkim._domainkey.yourdomain.com

Для wildcard-варианта необходимо настроить соответствующий тип таблицы refile: в директиве SigningTable. В данной инструкции используется простой вариант сопоставления по домену без refile.

/etc/opendkim/TrustedHosts

Внесите localhost и IP-адрес своего сервера:

127.0.0.1localhost1.2.3.4

4.2.5. Перенесите приватный ключ и перезапустите службы

Создайте каталог для ключей:

mkdir -p /etc/opendkim/keys/

Переместите приватный ключ:

mv dkim.private /etc/opendkim/keys/

Назначьте владельца и права:

chown opendkim:opendkim /etc/opendkim/keyschmod 700 /etc/opendkim/keyschown opendkim:opendkim /etc/opendkim/keys/dkim.privatechmod 600 /etc/opendkim/keys/dkim.private

Перезапустите службы:

systemctl restart opendkim postfix

Проверьте статус:

systemctl status opendkimsystemctl status postfix

При необходимости изучите журнал OpenDKIM:

journalctl -u opendkim -n 50 --no-pager

5. Настройка DMARC

DMARC — это механизм, который позволяет домену сообщить принимающим почтовым серверам, как обрабатывать сообщения, не прошедшие необходимые проверки SPF и DKIM с учётом соответствия домена в поле From.

Создайте TXT-запись:

• Тип записи: TXT

• Хост/Имя: _dmarc

• Значение для начала:

  v=DMARC1; p=none; rua=mailto:admin@yourdomain.com

Что это значит

• p=none — режим мониторинга. Домен просит не применять специальное действие к сообщениям, не прошедшим DMARC. Можно наблюдать за результатами проверок и собирать отчёты.
• rua=mailto:... — адрес, на который почтовые сервисы могут отправлять агрегированные отчёты о проверках.
• p=quarantine — просит принимающий сервер обрабатывать сообщения, не прошедшие DMARC, как подозрительные, например помещать их в спам.
• p=reject — просит отклонять сообщения, не прошедшие DMARC. Реальное действие определяется принимающим сервером.

После проверки и исправления конфигурации можно изменить политику с p=none на p=quarantine или p=reject.

6. Как проверить DNS-записи через терминал

Проверить, что настройки обновились в DNS, можно из консоли с помощью утилит dig или nslookup.

Проверка SPF

dig yourdomain.com TXT +short

Или:

nslookup -type=TXT yourdomain.com

Проверка DKIM

Запрос выполняется по имени вашего селектора:

dig dkim._domainkey.yourdomain.com TXT +short

Или:

nslookup -type=TXT dkim._domainkey.yourdomain.com

Проверка DMARC

dig _dmarc.yourdomain.com TXT +short

Или:

nslookup -type=TXT _dmarc.yourdomain.com

Проверка PTR (обратной записи)

dig -x 1.2.3.4 +short

Или:

nslookup 1.2.3.4

Проверка hostname

hostname -f

Убедитесь, что имя согласовано с A- и PTR-записями.

Рекомендуемая схема:

Hostname: mail.yourdomain.comA:        mail.yourdomain.com → 1.2.3.4PTR:      1.2.3.4 → mail.yourdomain.com

Имя хоста, используемое сервером, и обратная DNS-запись должны быть настроены согласованно.

sshd: error: get_user_token - unable to generate token on 2nd attempt for user administratorsshd: fatal: ga_init, unable to resolve user administrator

These messages indicate that the Windows authentication subsystem either cannot recognize the user at the OS level or is unable to generate a security token for them. Everything seems properly configured, yet the server persistently drops the connection.

Where the Time Goes (False Trails)

If you start googling this error, 90% of the online advice will lead you down two main paths:

1. Key File Permissions: You will be told to configure ACLs via icacls for the administrators_authorized_keys file located in C:\ProgramData\ssh, disable inheritance, and restrict access exclusively to SYSTEM and Administrators.
2. The sshd_config File: You will be advised to comment out the Match Group administrators block at the very bottom of the config to force OpenSSH to read keys from the standard user profile (.ssh/authorized_keys).

I tried everything on that list. Permissions and configs were verified, services were restarted—yet the result was zero. The server stubbornly terminated the session immediately after successfully validating the key.

The Unobvious Answer

The root cause turned out to be trivial, yet hidden behind the specifics of how OpenSSH operates on Windows.
How does SSH work in Linux? If the key matches, you are in.
How does SSH work in Windows? Even if the key matches, the OpenSSH service (running under the SYSTEM account) needs to establish a fully functional Windows workspace session and generate a user security token using the system API (LsaLogonUser).
And that is exactly where Windows denies the request.
I ran a quick check in the server console:

net user Administrator

And there it was: Account Active: Locked.
As it turned out, the Administrator account was locked out! This was likely caused by routine brute-force attempts—bots kept hammering port 22, triggering the Windows password lockout policy, which “froze” the account. Meanwhile, the SSH server successfully verified and confirmed the key (since the file exists on the disk), but the Windows OS refused to generate a token for a locked user. Hence the completely cryptic log about being unable to generate token.

The 5-Second Fix

If you have run into the same issue, the solution is straightforward. Log into the server using another admin account (or log in locally) and unlock the Administrator.

Via PowerShell:

Unlock-LocalUser -Name "Administrator"

Via the good old CMD:

net user Administrator /active:yes

Immediately after, the connection issues disappear, and the client successfully gains SSH access to the server.

sshd: error: get_user_token - unable to generate token on 2nd attempt for user administratorsshd: fatal: ga_init, unable to resolve user administrator

Эти сообщения говорят о том, что подсистема аутентификации Windows вообще не может распознать пользователя на уровне ОС или не способна создать для него маркер безопасности (security token). Вроде бы всё настроено правильно, а сервер упорно сбрасывает соединение.

Куда уходит время (Ложные следы)

Если вы начнете гуглить эту ошибку, 90% советов в интернетах поведут вас по двум путям:

1. Права на файлы ключей. Вам предложат настраивать ACL (права доступа) через icacls для файла administrators_authorized_keys в C:\ProgramData\ssh, убирать наследование и оставлять доступ только для SYSTEM и Administrators.
2. Конфиг sshd_config. Посоветуют закомментировать блок Match Group administrators в самом низу конфига, чтобы заставить OpenSSH читать ключи из стандартного профиля пользователя (.ssh/authorized_keys).

Я перепробовал всё из этого списка. Права и конфиги проверены, службы перезапущены. Результат — ноль. Сервер упорно сбрасывал сессию сразу после успешной проверки ключа.

Неочевидная разгадка

Причина оказалась банальной, но скрытой за спецификой работы OpenSSH в Windows.
Как работает SSH в Linux? Если ключ подошел — ты внутри.
Как работает SSH в Windows? Даже если ключ подошел, службе OpenSSH (которая работает под учеткой SYSTEM) нужно создать полноценную рабочую сессию для Windows и сгенерировать токен безопасности пользователя через системное API (LsaLogonUser).
И вот в этот момент Windows “дает отлуп”.
Вбиваю в консоль сервера проверку:

net user Administrator

И вижу строчку: Account Active: Locked (или Учетная запись заблокирована).
Оказывается, аккаунт Администратора был заблокирован! Скорее всего, из-за банального брутфорса (роботы ломились на 22 порт, сработала Windows-политика блокировки паролей, и учетка «заморозилась»). При этом SSH-сервер ключ-то проверил и подтвердил (ведь файл на диске лежит), а вот сама ОС Windows создать токен для заблокированного юзера не дала. Отсюда и абсолютно невнятный лог про unable to generate token.

Как это лечится за 5 секунд

Если вы наступили на те же грабли, решение простое. Заходим на сервер под другой админской учеткой (или локально) и разблокируем Администратора.

Через PowerShell:

Unlock-LocalUser -Name "Administrator"

Через старый добрый CMD:

net user Administrator /active:yes

После этого чудеса прекращаются, и клиент получает доступ к серверу по SSH.

This is especially noticeable in emails: a link to a question, order, product, or another page first goes through an intermediate service that tracks the click and then redirects you to the actual URL.

But tracking links are not limited to email. You can also encounter them on forums, in comments, communities, and other services — basically anywhere the site owner wants to track clicks on external links.

Sometimes the actual URL is already embedded directly in one of the tracking link’s parameters. For example:

https://tracking.example.com/click?u=https%3A%2F%2Fexample.com%2Forders%2F12345&campaign=email

Here, the u parameter contains the destination URL:

https%3A%2F%2Fexample.com%2Forders%2F12345

You don’t have to copy and decode it manually. You can quickly extract the direct URL right in DevTools.

How to do it

1. Copy the tracking link.
2. Open DevTools by pressing F12.
3. Go to the Console tab.
4. Enter:

const url = new URL("https://tracking.example.com/click?u=https%3A%2F%2Fexample.com%2Forders%2F12345&campaign=email");

5. Then retrieve the value of the parameter:

url.searchParams.get("u");

The Console will display the already decoded direct URL:

https://example.com/orders/12345

You can even click the link directly in the Console.

The URL object provides access to query parameters through searchParams, and URLSearchParams.get() returns the value of a specific parameter. Query parameter values are decoded automatically, so there is no need to call decodeURIComponent() separately.

Of course, the parameter name will not always be u. Depending on the service, it could be url, target, redirect, redirect_url, or something else.

The main thing is to inspect the tracking link and look for a parameter that contains the encoded destination URL.

It’s a simple way to get the direct link without opening the tracking URL and going through the intermediate service.

How to get the URL from a reddit email

Links in emails from reddit look something like this:

https://click.redditmail.com/CL0/https:%2F%2Fwww.reddit.com%2Fr%2Frust%2F%3F%2524deep_link=true%26correlation_id=70d9a...

To get the direct link:

1. In DevTools, enter the following (replace it with the link from your email):

const sourceUrl="https://click.redditmail.com/CL0/https:%2F%2Fwww.reddit.com%2Fr%2Frust%2F%3F%2524deep_link=true%26correlation_id=70d9a..."

2. Run the following to extract the direct link:

decodeURIComponent(sourceUrl.match(/(?<=\/)https?:.*?(?=\/\d\/|$)/)[0])

Это особенно заметно в письмах: ссылка на вопрос, заказ, товар или другую страницу сначала ведёт через промежуточный сервис, который фиксирует переход, а затем перенаправляет на настоящий URL.

Но tracking-ссылки встречаются не только в email. Их можно увидеть на форумах, в комментариях, сообществах и других сервисах — везде, где владельцу сайта нужно учитывать переходы по внешним ссылкам.

Иногда настоящий URL уже находится прямо внутри tracking-ссылки, в одном из её параметров. Например:

https://tracking.example.com/click?u=https%3A%2F%2Fexample.com%2Forders%2F12345&campaign=email

Здесь параметр u содержит URL назначения:

https%3A%2F%2Fexample.com%2Forders%2F12345

Его не обязательно вручную копировать и декодировать. Можно быстро извлечь прямую ссылку прямо в DevTools.

Как это сделать

1. Скопируйте tracking-ссылку.
2. Откройте DevTools клавишей F12.
3. Перейдите на вкладку Console.
4. Введите:

const url = new URL("https://tracking.example.com/click?u=https%3A%2F%2Fexample.com%2Forders%2F12345&campaign=email")

5. Затем получите значение нужного параметра:

url.searchParams.get("u")

В консоли будет выведена уже декодированная прямая ссылка:

https://example.com/orders/12345

На неё можно сразу кликнуть прямо в консоли.

URL предоставляет доступ к параметрам строки запроса через searchParams, а URLSearchParams.get() возвращает значение указанного параметра. При чтении query-параметров значение декодируется автоматически, поэтому отдельный вызов decodeURIComponent() здесь не требуется.

Конечно, имя параметра не всегда будет u. В зависимости от сервиса это может быть url, target, redirect, redirect_url и т. п.

Главное — посмотреть на tracking-ссылку и найти параметр, в котором содержится закодированный URL назначения.

Это простой способ получить прямую ссылку, не открывая tracking URL и не проходя через промежуточный сервис.

Как получить URL из письма от reddit

Ссылки в письмах от reddit выглядят примерно так:

https://click.redditmail.com/CL0/https:%2F%2Fwww.reddit.com%2Fr%2Frust%2F%3F%2524deep_link=true%26correlation_id=70d9a...

Чтобы получить прямую ссылку:

1. В DevTools введите (замените своей ссылкой из письма):

const sourceUrl="https://click.redditmail.com/CL0/https:%2F%2Fwww.reddit.com%2Fr%2Frust%2F%3F%2524deep_link=true%26correlation_id=70d9a..."

2. Введите для получения прямой ссылки:

decodeURIComponent(sourceUrl.match(/(?<=\/)https?:.*?(?=\/\d\/|$)/)[0])

Modern anti-fraud systems (Akamai, Cloudflare, PerimeterX) have long moved past analyzing just IPs and Cookies. Today, identification relies on Browser Fingerprinting — evaluating canvas/WebGL rendering artifacts, audio subsystem entropy, JA3/JA4 network stack hashes, and JS prototype behaviors. 

Top 9 Browser Fingerprint Checkers

• BrowserScan — A comprehensive scanner tracking over 50 parameters. It detects automation frameworks (Puppeteer/Selenium) and scores overall profile consistency (Human Score).
• BrowserLeaks — The go-to tool for low-level analysis. It verifies JA3/JA4 TLS fingerprints, HTTP/2 characteristics, and provides raw Canvas/WebGL hashes.
• CreepJS — An open-source checker designed to expose spoofing. It analyzes Prototype Pollution, hidden anomalies in JS objects, and calculates a baseline Trust Score.
• Pixelscan — A tool focused on logical data consistency. It cross-references environment metrics like system language, browser timezone, and proxy geolocation to catch mismatches.
• Iphey — A simulator modeled after fintech and ad-tech verification engines. It evaluates profiles based on Autonomous System (ASN) reputation and hardware parity.
• Cover Your Tracks (EFF) — A project by the Electronic Frontier Foundation. It measures browser uniqueness in bits of entropy against a live database of real users.
• AmIUnique — A statistics-driven utility. It displays the exact percentage of global users sharing your specific font lists or screen resolution.
• Scrapfly Browser Fingerprint Test — A verification tool developed by a web scraping platform. It simulates popular bot-detection challenges and monitors runtime reactions to script injections.
• Whoer.net — A quick network perimeter assessment tool. It identifies WebRTC IP leaks, references DNSBL blocklists, and detects potential proxy/VPN tunnels using MTU analysis.

Comparative Analysis

Современный антифрод (Akamai, Cloudflare, PerimeterX) давно не смотрит на IP и Cookie. Идентификация строится на базе Browser Fingerprinting — анализе особенностей рендеринга (Canvas/WebGL), энтропии аудиосистемы, JA3/JA4-хэшей сетевого стека и JS-прототипов. 

Топ-9 чекеров цифрового отпечатка

• BrowserScan — комплексный сканер (50+ параметров). Находит следы автоматизации (Puppeteer/Selenium) и оценивает консистентность профиля (Human Score).
• BrowserLeaks — база для низкоуровневого анализа. Проверяет JA3/JA4 отпечатки TLS, особенности HTTP/2 и выдает чистые хэши Canvas/WebGL.
• CreepJS — open-source чекер для выявления подмен. Проверяет Prototype Pollution, аномалии JS-объектов и вычисляет Trust Score.
• Pixelscan — инструмент для проверки логической согласованности данных. Сопоставляет параметры окружения (соответствие языка ОС, таймзоны браузера и геопозиции прокси).
• Iphey — симулятор проверок финтех- и рекламных платформ. Оценивает профиль на основе репутации автономной системы (ASN) провайдера и аппаратных соответствий.
• Cover Your Tracks (EFF) — проект Electronic Frontier Foundation. Измеряет уникальность браузера в битах энтропии относительно базы данных реальных пользователей.
• AmIUnique — инструмент для сбора статистики. Показывает точный процент пользователей с аналогичным набором шрифтов или расширением экрана.
• Scrapfly Browser Fingerprint Test — чекер от платформы веб-скрапинга. Эмулирует проверки антибот-систем и тестирует реакцию браузера на инъекции скриптов.
• Whoer.net — экспресс-тест сетевого периметра. Находит утечки IP через WebRTC, проверяет DNSBL (черные списки) и определяет туннели по значению MTU.

Сравнительный анализ

Web scraping applications frequently require real-time tracking of all currently downloading URLs.

However, achieving this in practice is far from trivial. For instance, if the target application is a web browser, capturing network activity typically requires globally overriding the built-in fetch and XHR (XMLHttpRequest) methods. The situation becomes significantly more complex if the web page contains iframe elements: you must dynamically inject fetch and XHR overrides into them as well, adding a heavy layer of complexity and fragility to the system. Custom injection scripts can easily conflict with Content Security Policies (CSP) or simply miss requests originating from isolated contexts. 

Instead of breaking frontend logic inside the browser and relying on complex script injections, a much more reliable approach is to leverage the proxy layer. To achieve this, an optional WebSocket Session API was implemented in ProxyMapService. It allows external applications to connect directly to the proxy, supply a URL filter, and instantly receive push notifications for all requested resources. 

Configuration and Connection Logistics

The entire mechanism is managed by the SessionAPI section in the appsettings.json configuration file. Here is how it looks by default: 

"SessionAPI": {    "Enabled": false,    "WebSocketsEnabled": false,    "Domain": ""}

As you can see, by default, the entire SessionAPI infrastructure, including WebSockets, is turned off, and the Domain property is left empty. 

Option 1. Working via Local Port (Empty Domain)

When Domain is empty, the control endpoints are accessed like a regular web server on one of the ports that ProxyMapService listens to for incoming connections. For example, if the proxy is running on port 5000: 

• HTTP API Access: http://127.0.0.1:5000/session/
• Browser Configuration: 127.0.0.1:5000 is specified as the HTTP or SOCKS5 proxy.

Option 2. Working via a Dedicated Pseudo-Domain (Recommended)

To fully isolate control traffic from proxied traffic, it is recommended to enable the API and define a special internal domain: 

"SessionAPI": {    "Enabled": true,    "WebSocketsEnabled": true,    "Domain": "proxymapper"}

In this mode, proxymapper acts as a dedicated system domain. When ProxyMapService detects that a client is trying to access the proxymapper host, it intercepts the request locally and handles it as a call to the SessionAPI instead of routing it out to the external network. 

Crucial Nuance for Command-Line Utilities (e.g., cURL):

If you are using curl to route traffic through the proxy, the socks4 protocol will not allow you to call the internal API at all. Furthermore, the socks5:// prefix must be replaced with socks5h:// (e.g., socks5h://127.0.0.1:5000). This ensures that curl does not attempt to resolve the proxymapper domain locally via your OS DNS, but instead delegates the name resolution directly to the proxy server itself. 

With this configuration, the WebSocket Session API endpoint will be accessible via: ws://proxymapper/session/ws

How It Works in Practice

Using the subscription mechanism is straightforward for a developer: 

1. Establishing a Connection: The client opens a persistent WebSocket connection to ws://proxymapper/session/ws.
2. Sending a Filter: Immediately after a successful connection, the client sends a text JSON message containing a subscribe action and a regular expression (Regex) matching the target URLs:

{  "action": "subscribe",  "pattern": "api\\.example\\.com/v1/.*"}

3. Subscription Confirmation and session_id: The server replies with a confirmation message acknowledging the registered filter, which includes vital execution context:

{  "status": "subscribed",  "session_id": ":5000"}

What does session_id mean and how does traffic isolation work? 

• session_id represents a unique session identifier. If your environment utilizes authentication via a Sticky Proxy, this string identifier is explicitly bound to the user upon authentication.
• If a Sticky Proxy is not used, the session_id returns a colon followed by the incoming port number (e.g., :5000). This means that notifications are strictly isolated to the specific port through which the subscription was created.
• Lifecycle Rule: The user is guaranteed to receive notifications for URLs downloaded strictly within the session that was active at the moment of subscription. If the proxy session changes, notifications for the old subscription will cease. Similarly, under port-based isolation (without sticky routing), you will never see traffic passing through another proxy port inside the WebSocket channel for port :5000.

4. Receiving Notifications: When a downloaded URL matches your pattern, the proxy server dispatches a flat, structured event optimized for fast reading:

{  "event_type": "url_matched",  "timestamp": "2026-09-02T10:20:45.0328755Z",  "session_id": ":5000",  "method": "GET",  "url": "https://api.example.com/v1/users/profile"}

Testing Environment: Proxy WebSocket Control Panel

The test web panel is hosted in a dedicated project subdirectory: tests\test-websocket. 

Inside the folder lies a self-contained HTML file, index.html, which implements the diagnostic interface: 

<!-- Located at: \tests\test-websocket\index.html --><div class="card">    <h2>Proxy WebSocket Control Panel</h2>    <div class="form-group">        <input type="text" id="wsUrl" value="ws://proxymapper/session/ws">        <button onclick="toggleConnection()">Connect</button>    </div>    <div class="form-group">        <input type="text" id="filterPattern" value="(google\.com|yandex\.ru)/.*">        <button onclick="sendSubscription()">Set Filter</button>    </div></div>

How to Run the Test and Verify Monitoring:

1. Launch the configured ProxyMapService with WebSockets enabled and the domain set to proxymapper.
2. Open the tests\test-websocket\index.html file in any modern browser whose traffic is being routed through your proxy.
3. Click the Connect button, set your regex filter pattern, and watch live notifications populate the dark console UI with full request details instantly.

Conclusion

Shifting URL tracing logic out of fragile browser scripts and into the ProxyMapService layer provides 100% visibility into network requests. It no longer matters where a request originates—be it the main window, a heavy background iframe, or a hidden service worker—the proxy server reliably intercepts, filters based on the active session (or port), and safely delivers the event to the client via a WebSocket subscription without modifying a single line of original page code.

Часто в приложениях веб-скрапинга необходимо оперативно получать информацию обо всех URL-адресах, которые скачиваются в данный момент. 

Однако на практике это может оказаться далеко не тривиальной задачей. Например, если целевое приложение — браузер, для перехвата сетевой активности обычно требуется глобально переопределить встроенные методы fetch и XHR (XMLHttpRequest). Ситуация сильно усложняется, если на веб-странице присутствуют элементы iframe: в них также необходимо динамически внедрять переопределения для fetch и XHR, что добавляет дополнительный уровень сложности и хрупкости всей системе. Кастомные скрипты могут конфликтовать с политиками безопасности (Content Security Policy) или просто пропускать запросы из изолированных контекстов. 

Вместо того чтобы ломать логику внутри самого браузера и внедрять сложные инъекции, гораздо надежнее использовать возможности прокси-слоя. Для этого в ProxyMapService было реализовано опциональное WebSocket Session API. Оно позволяет внешним приложениям подключаться напрямую к прокси, передавать нужный фильтр URL и мгновенно получать push-сообщения обо всех запрашиваемых ресурсах. 

Конфигурация и особенности подключения

За работу данного механизма отвечает раздел SessionAPI в файле конфигурации appsettings.json. Вот как он выглядит по умолчанию: 

"SessionAPI": {    "Enabled": false,    "WebSocketsEnabled": false,    "Domain": ""}

Как можно видеть, по умолчанию вся инфраструктура SessionAPI, включая веб-сокеты, отключена, а свойство Domain оставлено пустым. 

Вариант 1. Работа через локальный порт (Пустой домен)

Если Domain пустой, доступ к управляющим эндпоинтам осуществляется как к обычному веб-серверу на одном из портов, которые ProxyMapService слушает для входящих соединений. Например, если прокси запущен на порту 5000: 

• Доступ к HTTP API: http://127.0.0.1:5000/session/
• Настройка браузера: в качестве HTTP или SOCKS5 прокси указывается 127.0.0.1:5000.

Вариант 2. Работа через выделенный псевдо-домен (Рекомендуемый)

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

"SessionAPI": {    "Enabled": true,    "WebSocketsEnabled": true,    "Domain": "proxymapper"}

В этом режиме proxymapper становится выделенным системным доменом. Когда ProxyMapService видит, что клиент обращается к хосту proxymapper, он перехватывает этот запрос локально и обрабатывает его как вызов к SessionAPI, вместо того чтобы проксировать его во внешнюю сеть. 

Важный нюанс для консольных утилит (например, cURL):

Если вы используете curl для работы с прокси, протокол socks4 вообще не позволит вызвать внутреннее API. Более того, вместо стандартного префикса socks5:// нужно использовать socks5h:// (например, socks5h://127.0.0.1:5000). Это необходимо для того, чтобы curl не пытался самостоятельно отресолвить домен proxymapper через DNS вашей операционной системы, а делегировал разрешение этого имени самому прокси-серверу. 

При такой конфигурации вызов WebSocket Session API будет осуществляться через веб-сокет по адресу: ws://proxymapper/session/ws

Как это работает на практике

Использование механизма подписок выглядит так: 

1. Установка соединения: Клиент открывает постоянное WebSocket-соединение по адресу ws://proxymapper/session/ws.
2. Передача фильтра: Сразу после успешного подключения клиент отправляет текстовое JSON-сообщение с действием subscribe и регулярным выражением (Regex) для интересующих его URL:

{  "action": "subscribe",  "pattern": "api\\.example\\.com/v1/.*"}

3. Подтверждение подписки и session_id: В ответ сервер присылает подтверждение успешной регистрации фильтра, которое содержит важный контекст:

{  "status": "subscribed",  "session_id": ":5000"}

Что означает session_id и как работает изоляция трафика? 

• session_id — это уникальный идентификатор сессии. Если в вашем окружении используется авторизация через Sticky Proxy, этот строковый идентификатор явно привязывается к пользователю в момент аутентификации.
• Если же Sticky Proxy не используется, то в качестве session_id возвращается двоеточие, за которым следует номер входящего порта (например, :5000). Это означает, что уведомления жестко изолированы конкретным портом, через который была оформлена подписка.
• Важное правило жизненного цикла: Пользователь гарантированно получает уведомления об URL-адресах, скачиваемых строго в рамках той сессии, которая была активна на момент подписки. Если сессия на прокси сменилась, уведомления по старой подписке приходить перестанут. Точно так же, при изоляции портами (без sticky), вы никогда не увидите в веб-сокете порта :5000 трафик, проходящий параллельно через другой настроенный порт прокси.

4. Получение уведомлений: При совпадении скачиваемого URL с вашей маской прокси-сервер отправляет плоское структурированное событие, оптимизированное для быстрого чтения:

{  "event_type": "url_matched",  "timestamp": "2026-09-02T10:20:45.0328755Z",  "session_id": ":5000",  "method": "GET",  "url": "https://api.example.com/v1/users/profile"}

Окружение для тестирования: Proxy WebSocket Control Panel

Тестовая веб-панель размещена в выделенной поддиректории проекта: tests\test-websocket.

Внутри папки находится автономный HTML-файл index.html, реализующий диагностический интерфейс: 

<!-- Located at: \tests\test-websocket\index.html --><div class="card">    <h2>Proxy WebSocket Control Panel</h2>    <div class="form-group">        <input type="text" id="wsUrl" value="ws://proxymapper/session/ws">        <button onclick="toggleConnection()">Connect</button>    </div>    <div class="form-group">        <input type="text" id="filterPattern" value="(google\.com|yandex\.ru)/.*">        <button onclick="sendSubscription()">Set Filter</button>    </div></div>

Как запустить тест и проверить мониторинг:

1. Запустите настроенный ProxyMapService с включенными веб-сокетами и доменом proxymapper.
2. Откройте файл tests\test-websocket\index.html в любом современном браузере, трафик которого идет через ваш прокси.
3. Нажмите кнопку Connect, задайте регулярное выражение для фильтрации и наблюдайте, как в темную консоль интерфейса мгновенно прилетают уведомления со всеми деталями перехваченных запросов.

Заключение

Вынесение логики трейсинга URL из кастомных скриптов браузера на уровень ProxyMapService позволило увидеть все сетевые запросы. Теперь не важно, откуда уходит запрос — из основного окна, тяжелого iframe или вообще из фонового сервис-воркера — прокси-сервер гарантированно перехватит его, отфильтрует с учетом активной сессии (или порта) и безопасно доставит клиенту через WebSocket-подписку без изменения оригинального кода страниц.

I travel a lot — trains, planes, long drives out of town. And I always want to use that time productively: read, listen to podcasts, or learn something new.

The problem is, internet connectivity on the road is rarely reliable. And many educational platforms use the Kinescope player, which doesn’t offer a built-in way to download videos for offline viewing.

Sure, you could open DevTools, find the .m3u8 playlist in the network requests, copy the link, fire up FFmpeg in the terminal… But doing that every single time — especially when there are dozens of videos — is tedious and eats into time better spent actually learning.

I wanted a simple solution: open the video page, click a button, and have everything ready for offline watching.

Why a Browser Extension?

I considered a few options: writing a parser script, using a download manager, or building a browser extension.

I went with an extension because it’s the most natural and convenient approach:

• It works right on the video page — no context switching.
• It can intercept the player’s network requests in real time.
• Everything is controlled with a single button. No extra steps.

The workflow is dead simple: open the lecture, click “Save,” move on to the next one. Repeat for all the materials I plan to watch on the road.

What I Built

The extension does two things:

1. Intercepts all links to video and audio streams requested by the Kinescope player.
2. Saves them to Downloads/kinescope/[Video_Title]/ along with metadata (title, duration, description).

A floating button appears on the page showing how many streams have been found. One click — and all the links are saved to your folder, neatly sorted by video and audio.

After that, I run a Python script that automatically stitches everything together using FFmpeg into a ready-to-watch .mp4 file. And just like that — a library of lectures ready for offline viewing.

The Result

Now preparing for a trip takes just a few minutes:

1. Open all the videos I need → click the button on each page.
2. Run one script → it processes everything automatically.
3. Copy the finished files to my laptop or tablet and hit the road.

No DevTools, no manual copying of links. Just time well spent.

Project Link

The extension is open source and can be installed manually via developer mode in Chrome. All you need are four files from the repository:

👉 Kinescope JSON-LD Extractor PRO on GitHub 👈

Hope you find it useful.

Я часто путешествую — поезда, самолёты, длинные переезды за город. И всегда хочется использовать это время с пользой: почитать, послушать подкасты или позаниматься самообразованием.

Проблема в том, что в дороге интернет — штука нестабильная. А многие образовательные платформы используют плеер Kinescope, который не позволяет просто скачать видео для офлайн-просмотра.

Конечно, можно открыть DevTools, найти в сетевых запросах .m3u8 плейлист, скопировать ссылку, запустить FFmpeg в консоли… Но делать это каждый раз, особенно если материалов много — утомительно и отнимает время, которое лучше потратить на учёбу.

Мне хотелось простого решения: открыл страницу с видео, нажал кнопку — и всё готово для просмотра офлайн.

Почему расширение?

Вариантов было несколько: написать парсер, использовать готовый download-менеджер или сделать браузерное расширение.

Я выбрал расширение, потому что это самый естественный и удобный способ:

• Оно работает прямо на странице с видео, не нужно никуда переключаться.
• Может перехватывать сетевые запросы плеера в реальном времени.
• Всё управление — одной кнопкой. Никаких лишних действий.

В итоге процесс максимально простой: зашёл на страницу лекции, нажал «Сохранить», пошёл дальше. И так для всех материалов, которые планирую посмотреть в дороге.

Что получилось

Расширение делает две вещи:

1. Перехватывает ссылки на видео- и аудиопотоки, которые запрашивает плеер Kinescope.
2. Сохраняет их в папку Загрузки/kinescope/[Название_видео]/ вместе с метаданными (название, длительность, описание).

На странице появляется плавающая кнопка, которая показывает, сколько потоков найдено. Нажал — и все ссылки уже в папке, аккуратно отсортированные по видео и аудио.

Дальше я запускаю Python-скрипт, который автоматически склеивает всё через FFmpeg в готовый .mp4 файл. И вуаля — библиотека лекций готова к просмотру без интернета.

Итог

Теперь подготовка к поездкам занимает пару минут:

1. Открываю все нужные видео → на каждой странице нажимаю кнопку.
2. Запускаю один скрипт → он обрабатывает всё автоматически.
3. Копирую готовые файлы на ноутбук/планшет и в путь.

Никаких DevTools, никакой рутины. Только время, потраченное с пользой.

Ссылка на проект

Расширение открытое, устанавливается вручную через режим разработчика в Chrome. Всё, что нужно — четыре файла из репозитория.

👉 Kinescope JSON-LD Extractor PRO на GitHub 👈

Буду рад, если пригодится и вам.

For this, you can use Chrome for Testing, a Chrome flavor specifically designed for web testing and automation.

The project provides a JSON file containing available versions and download links:

known-good-versions-with-downloads.json

For example, let’s say you need ChromeDriver version 151.0.7922.138. The JSON contains an entry for this version with download URLs for different platforms:

{  "version": "151.0.7922.138",  "revision": "1654411",  "downloads": {    "chromedriver": [      {        "platform": "linux64",        "url": "https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.138/linux64/chromedriver-linux64.zip"      },      {        "platform": "win64",        "url": "https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.138/win64/chromedriver-win64.zip"      }    ]  }}

The downloads.chromedriver section contains download links for different platforms: linux64, mac-arm64, mac-x64, win32, and win64.

Finding the URL using Chrome DevTools

The JSON file is quite large, but you don’t need to browse it manually. You can use Chrome DevTools to find the exact download URL.

Open the JSON file in Chrome, press F12, switch to the Console tab, and run:

JSON.parse(document.body.innerText).versions  .find(x => x.version === '151.0.7922.138')  ?.downloads.chromedriver  .find(x => x.platform === 'win64')  ?.url

The console will return the direct download URL:

https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.138/win64/chromedriver-win64.zip

Simply change the version and platform in the command to get the ChromeDriver you need.

This approach requires no additional software or online JSON tools — everything can be done directly in Chrome DevTools.

Для этого можно использовать Chrome for Testing — специальную версию Chrome, предназначенную для тестирования и автоматизации.

Проект предоставляет JSON-файл со списком доступных версий и ссылками для загрузки:

known-good-versions-with-downloads.json

Например, нам нужна версия ChromeDriver 151.0.7922.138. В JSON есть запись для этой версии со ссылками на загрузку для разных платформ:

{  "version": "151.0.7922.138",  "revision": "1654411",  "downloads": {    "chromedriver": [      {        "platform": "linux64",        "url": "https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.138/linux64/chromedriver-linux64.zip"      },      {        "platform": "win64",        "url": "https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.138/win64/chromedriver-win64.zip"      }    ]  }}

В разделе downloads.chromedriver находятся ссылки для разных платформ: linux64, mac-arm64, mac-x64, win32 и win64.

Поиск URL с помощью Chrome DevTools

JSON-файл довольно большой, но вручную просматривать его не нужно. Можно воспользоваться Chrome DevTools и сразу получить нужную ссылку.

Откройте JSON-файл в Chrome, нажмите F12, перейдите на вкладку Console и выполните:

JSON.parse(document.body.innerText).versions  .find(x => x.version === '151.0.7922.138')  ?.downloads.chromedriver  .find(x => x.platform === 'win64')  ?.url

В консоли будет выведен прямой URL для загрузки:

https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.138/win64/chromedriver-win64.zip

Чтобы получить другую версию или версию для другой платформы, просто измените соответствующие значения в команде.

Таким образом, не требуется устанавливать дополнительное программное обеспечение или использовать сторонние онлайн-сервисы — всё можно сделать непосредственно в Chrome DevTools.