
Нативный C++ доступ к Active Directory через ADWS, без .NET, без WCF, без HTTP стека.
Нативный C++ доступ к Active Directory через ADWS, без .NET, без WCF, без стека HTTP.
BridgeHead — это статическая библиотека C++20, реализующая полный стек протоколов Active Directory Web Services (ADWS) напрямую через TCP. Названная в честь сервера-моста AD (bridgehead server), шлюза, через который проходит трафик каталога, она предоставляет вашему C++ коду такой же низкоуровневый доступ к порту 9389, который PowerShell's Get-ADUser и Get-ADComputer используют под капотом.
Транспортные уровни оборачивают нижележащий через общий интерфейс bridgehead::transport::IByteStream. NbfseCodec — это утилита кодека, вызываемая AdwsClient для кодирования/декодирования SOAP-сообщений до и после фреймирования:```
AdwsClient WS-Enumeration + WS-Transfer [MS-ADDM]
├── NbfseCodec .NET Binary Format for SOAP [MC-NBFSE] (encode/decode)
└── NmfFramer .NET Message Framing [MC-NMF] (send/receive frames)
└── NnsSession .NET NegotiateStream [MS-NNS]
└── TcpSocket raw TCP/IP
Точка входа для пользователей — `bridgehead::adws::AdwsClient`.
---
## Быстрый старт
### Запрос, перечисление всех пользователей```cpp
#include "bridgehead/adws/AdwsClient.hpp"
// NTLM (works on any host)
auto client = bridgehead::adws::AdwsClient::EnumerationClient(
"192.168.1.10", // DC IP or hostname
"DC01.corp.local", // DC FQDN, used in NMF Via header and Kerberos SPN
"CORP", // NetBIOS domain name
"Administrator", // username
"Passw0rd" // password
);
// Kerberos (username hidden on the wire; requires DC reachable on port 88)
auto client = bridgehead::adws::AdwsClient::EnumerationClient(
"192.168.1.10", "DC01.corp.local", "CORP",
"Administrator", "Passw0rd",
bridgehead::adws::AuthPackage::Kerberos
);
auto users = client.Query(
"(objectClass=user)",
{"sAMAccountName", "distinguishedName", "memberOf"}
);
for (auto& obj : users)
std::cout << obj.FirstValue("sAMAccountName") << '\n';
client.Enumerate( "(objectClass=computer)", {"dNSHostName", "operatingSystem"}, "", // empty = domain root base DN [](const bridgehead::adws::LdapObject& obj) { std::cout << obj.FirstValue("dNSHostName") << '\n'; return true; // return false to stop early (sends wsen:Release) } );
### Область и пагинация```cpp
// OneLevel scope, 50 objects per Pull round-trip
client.Query(
"(objectClass=user)",
{"sAMAccountName"},
"OU=Admins,DC=corp,DC=local",
50,
bridgehead::adws::SearchScope::OneLevel
);
auto objs = client.Query("(objectClass=user)", {"objectGUID", "objectSid"}); for (auto& obj : objs) { if (auto* b = obj.FirstBytes("objectGUID")) std::cout << bridgehead::adws::ParseGuid(b) << '\n'; // {XXXXXXXX-...} if (auto b = obj.FirstBytes("objectSid")) std::cout << bridgehead::adws::ParseSid(*b) << '\n'; // S-1-5-... }
### Декодирование дескриптора безопасности```cpp
#include "bridgehead/adws/SecurityDescriptor.hpp"
auto objs = client.Query("(objectClass=user)", {"nTSecurityDescriptor"});
if (auto* raw = objs[0].FirstBytes("nTSecurityDescriptor")) {
auto sd = bridgehead::adws::ParseSecurityDescriptor(*raw);
std::cout << "Owner: " << sd.ownerSid << '\n';
for (auto& ace : sd.dacl.aces)
std::cout << " type=" << (int)ace.type
<< " mask=0x" << std::hex << ace.mask
<< " sid=" << ace.sid << '\n';
}
auto rc = bridgehead::adws::AdwsClient::ResourceClient( "192.168.1.10", "DC01.corp.local", "CORP", "Administrator", "Passw0rd");
// Modify attributes rc.Put("CN=Alice,OU=Users,DC=corp,DC=local", { {"description", {"managed by bridgehead"}}, {"telephoneNumber", {"555-1234"}}, });
// Clear an attribute (both values and bytes empty = delete) rc.Put("CN=Alice,OU=Users,DC=corp,DC=local", { {"telephoneNumber", {}}, });
// Read back auto obj = rc.Get("CN=Alice,OU=Users,DC=corp,DC=local", {"description", "telephoneNumber"});
// Delete object rc.Delete("CN=TempUser,OU=Users,DC=corp,DC=local");
### Типы модификации LDAP: Add / Replace / Delete
`Put` по умолчанию выполняет `Replace` (перезаписывает все существующие значения). Используйте `ModifyOperation` для точного контроля над многозначными атрибутами:```cpp
using bridgehead::adws::LdapModification;
using bridgehead::adws::ModifyOperation;
rc.Put("CN=Alice,OU=Users,DC=corp,DC=local", {
// Append a value to an existing multi-valued attribute
LdapModification{"otherTelephone", {"555-9999"}, {}, ModifyOperation::Add},
// Remove one specific value (leave others intact)
LdapModification{"otherTelephone", {"555-0000"}, {}, ModifyOperation::Delete},
// Replace is the default, explicit here for clarity
LdapModification{"description", {"updated"}, {}, ModifyOperation::Replace},
});
// Move to a different OU rc.Move( "CN=Alice,OU=OldOU,DC=corp,DC=local", // current DN "CN=Alice,OU=NewOU,DC=corp,DC=local" // new DN );
// Rename in place (same parent, new CN) rc.Move( "CN=Alice,OU=Users,DC=corp,DC=local", "CN=AliceSmith,OU=Users,DC=corp,DC=local" );
### Запись бинарных атрибутов
Указывайте бинарные значения в поле `bytes` объекта `LdapModification`. Они автоматически кодируются в base64 при передаче по сети:```cpp
std::vector<uint8_t> thumbnail = loadFile("photo.jpg");
rc.Put("CN=Alice,OU=Users,DC=corp,DC=local", {
LdapModification{"thumbnailPhoto", {}, {thumbnail}},
});
auto rf = bridgehead::adws::AdwsClient::ResourceFactoryClient( "192.168.1.10", "DC01.corp.local", "CORP", "Administrator", "Passw0rd");
rf.Create( "CN=NewUser,OU=Users,DC=corp,DC=local", "user", {{"sAMAccountName", {"newuser"}}, {"userAccountControl", {"512"}}} );
### Асинхронные операции```cpp
#include "bridgehead/adws/AdwsClientAsync.hpp"
auto ac = bridgehead::adws::AdwsClientAsync::EnumerationClient(
"192.168.1.10", "DC01.corp.local", "CORP", "Administrator", "Passw0rd");
auto future = ac.QueryAsync("(objectClass=user)", {"sAMAccountName"});
// ... do other work while the query runs ...
auto users = future.get(); // blocks until complete; re-throws any exception
Тайм-аут на медленном DC:```cpp if (future.wait_for(std::chrono::seconds(5)) == std::future_status::timeout) { // query is still running }
### Пул соединений (высокочастотные / многопоточные нагрузки)
Все операции имеют асинхронные варианты: `QueryAsync`, `EnumerateAsync`, `GetAsync`, `PutAsync`, `DeleteAsync`, `CreateAsync`, `MoveAsync`.```cpp
#include "bridgehead/adws/AdwsClientPool.hpp"
// Enumeration pool, Query / Enumerate
bridgehead::adws::AdwsClientPool pool({
.host = "192.168.1.10", .fqdn = "DC01.corp.local",
.domain = "CORP", .username = "Administrator", .password = "Passw0rd",
.maxSize = 4, // up to 4 concurrent authenticated sessions
});
auto users = pool.Query("(objectClass=user)", {"sAMAccountName"});
// Resource pool, Get / Put / Delete
bridgehead::adws::AdwsClientPool resPool({
.host = "192.168.1.10", .fqdn = "DC01.corp.local",
.domain = "CORP", .username = "Administrator", .password = "Passw0rd",
.maxSize = 4,
.endpoint = bridgehead::adws::PoolEndpoint::Resource,
});
auto obj = resPool.Get("CN=Alice,OU=Users,DC=corp,DC=local", {"mail"});
resPool.Put("CN=Alice,OU=Users,DC=corp,DC=local", {{"mail", {"[email protected]"}}});
// ResourceFactory pool, Create
bridgehead::adws::AdwsClientPool rfPool({
.host = "192.168.1.10", .fqdn = "DC01.corp.local",
.domain = "CORP", .username = "Administrator", .password = "Passw0rd",
.endpoint = bridgehead::adws::PoolEndpoint::ResourceFactory,
});
rfPool.Create("CN=NewUser,OU=Users,DC=corp,DC=local", "user",
{{"sAMAccountName", {"newuser"}}});
Все публичные заголовки находятся в директории include/bridgehead/. Полная документация по API может быть сгенерирована с помощью Doxygen (см. Сборка).
bridgehead::adws::AdwsClientbridgehead::adws::AdwsClientAsyncАсинхронная обёртка на основе std::future. Те же фабричные методы, что и у AdwsClient; каждая операция возвращает std::future<T>:```cpp
std::future<std::vector> f = ac.QueryAsync(...);
std::future e = ac.EnumerateAsync(filter, attrs, baseDN, callback);
std::future g = ac.GetAsync(...);
std::future h = ac.PutAsync(...);
std::future i = ac.DeleteAsync(...);
std::future j = ac.CreateAsync(...);
std::future k = ac.MoveAsync(...);
Для параллельных запросов через несколько соединений используйте `AdwsClientPool`.
### `bridgehead::adws::AdwsClientPool`
Потокобезопасный пул предварительно аутентифицированных сеансов. Соединения создаются лениво и используются повторно при вызовах.```cpp
pool.IdleCount(); // sessions currently idle
pool.TotalCount(); // idle + checked-out
pool.MaxSize(); // configured maximum pool size
pool.Move(dn, newDn); // Move/rename (Resource pool)
enum class SearchScope { Base, OneLevel, Subtree /default/ };
### `bridgehead::adws::LdapObject` / `LdapAttribute````cpp
struct LdapAttribute {
std::string name;
std::string syntax; // LdapSyntax OID, empty if absent
std::vector<std::string> values; // text values (raw base64 for binary)
std::vector<std::vector<uint8_t>> bytes; // decoded binary; parallel to values
};
struct LdapObject {
std::vector<LdapAttribute> attributes; // all returned attributes
const LdapAttribute* Find(const std::string& name) const; // case-insensitive
std::string FirstValue(const std::string& name) const;
const std::vector<uint8_t>* FirstBytes(const std::string& name) const;
};
std::string ParseGuid(const std::vector<uint8_t>& bytes); // → "{XXXXXXXX-XXXX-...}" std::string ParseSid (const std::vector<uint8_t>& bytes); // → "S-1-5-..."
### `FilterValue` и помощники построения фильтров
`FilterValue` — это типобезопасная обёртка, которая экранирует метасимволы RFC 4515 §3 (`\`, `*`, `(`, `)`, NUL) при конструировании. Используйте её с помощниками построения, чтобы сделать LDAP-инъекцию структурно невозможной:```cpp
// UNSAFE, raw string concatenation, easy to forget escaping
client.Query("(sAMAccountName=" + username + ")", ...);
// SAFE, FilterValue escapes on construction; FilterEq composes the assertion
FilterValue user = username;
client.Query(FilterEq("sAMAccountName", user), ...);
// Compose complex filters
client.Query(
FilterAnd({
FilterEq("objectClass", FilterValue::Raw("user")), // Raw() for safe literals
FilterOr({
FilterEq("sAMAccountName", user),
FilterEq("mail", FilterValue(email)),
}),
FilterNot(FilterPresent("userAccountControl")),
}), {"sAMAccountName", "mail"}
);
EscapeLdapFilter(str) по-прежнему доступна как низкоуровневая примитивная функция, когда вам нужно вручную собирать строки фильтра.
DnValue и помощники для построения DNТакая же схема, как у FilterValue, но для значений RDN отличительных имен (Distinguished Name) (RFC 4514 §2.4). Экранирует ,, +, ", \, <, >, ;, NUL, а также начальные и конечные # и пробел:```cpp
// UNSAFE, comma injection breaks the DN structure
rc.Get("CN=" + username + ",OU=Users,DC=corp,DC=local", attrs);
// SAFE DnValue cn = username; // auto-escaped auto dn = BuildDn({DnAttr("CN", cn), "OU=Users", "DC=corp", "DC=local"}); rc.Get(dn, attrs);
// DnValue::Raw() for values you control auto dn2 = BuildDn({DnAttr("CN", DnValue::Raw("Service Account")), "OU=SvcAccounts", "DC=corp", "DC=local"});
### `bridgehead::adws::SecurityDescriptor````cpp
SecurityDescriptor ParseSecurityDescriptor(const std::vector<uint8_t>& bytes);
struct SecurityDescriptor {
uint16_t control; // SdControl::* flags
std::string ownerSid;
std::string groupSid;
bool hasDacl; Acl dacl;
bool hasSacl; Acl sacl;
};
struct Acl { std::vector<Ace> aces; };
struct Ace {
uint8_t type; // AceType::*
uint8_t flags; // AceFlags::*
uint32_t mask;
std::string sid;
std::string objectType; // GUID string, object ACEs only
std::string inheritedObjectType; // GUID string, object ACEs only
};
Постоянные пространства имён: AceType::*, AceFlags::*, SdControl::*.
bridgehead::ConnectionError / AuthenticationError / ProtocolErrorОпределены в include/bridgehead/Exceptions.hpp (включается транзитивно через AdwsClient.hpp). Все три наследуют std::runtime_error:
| Тип | Возникает при |
|---|---|
ConnectionError | Ошибка на уровне TCP: отказ в соединении, тайм-аут, ошибка ввода-вывода |
AuthenticationError | Сбой переговоров NTLM/Kerberos |
ProtocolError | Некорректный ответ сервера на любом уровне протокола |
auto client = bridgehead::adws::AdwsClient::EnumerationClient(...);
auto users = client.Query(...);
} catch (const bridgehead::ConnectionError& e) { // unreachable DC, wrong port, timeout } catch (const bridgehead::AuthenticationError& e) { // bad credentials, KDC unreachable } catch (const bridgehead::ProtocolError& e) { // unexpected server response } catch (const bridgehead::adws::SoapFault& e) { // DC returned a SOAP fault (e.g. invalid filter) } // or coarse-grained: // } catch (const std::runtime_error& e) { ... }
### `bridgehead::adws::SoapFault`
Выбрасывается при любом ответе `s:Fault` от DC вместо обычного `std::runtime_error`:```cpp
struct SoapFault : std::runtime_error {
std::string code; // e.g. "Sender"
std::string subcode; // e.g. "InvalidEnumerationContext", empty if absent
std::string reason; // human-readable text
};
bridgehead::adws::LdapModificationИспользуется Put и Create:```cpp
enum class ModifyOperation { Replace /default/, Add, Delete };
struct LdapModification { std::string name; std::vectorstd::string values; // text values std::vector<std::vector<uint8_t>> bytes; // binary values (base64-encoded on the wire) ModifyOperation operation = ModifyOperation::Replace; };
Когда оба поля `values` и `bytes` пусты, атрибут очищается/удаляется независимо от `operation`.
### `bridgehead::adws::ProtocolLimits`
Необязательный последний параметр во всех фабричных методах, фабриках `AdwsClientAsync` и `AdwsClientPool::Config::limits`. Все поля имеют безопасные значения по умолчанию, изменяйте их только при наличии особых требований:```cpp
struct ProtocolLimits {
uint32_t nmfMaxFrameBytes = 64 * 1024 * 1024; // max NMF frame (default 64 MiB)
uint32_t nnsMaxPayloadBytes = 16 * 1024 * 1024; // max NNS packet (default 16 MB)
int tcpKeepaliveIdleSec = 60; // idle seconds before first probe
int tcpKeepaliveIntervalSec = 10; // seconds between probes
int tcpKeepaliveProbeCount = 5; // probes before declaring dead (POSIX only)
};
Повышайте nmfMaxFrameBytes / nnsMaxPayloadBytes только если вы читаете объекты с необычно большими двоичными атрибутами (например, nTSecurityDescriptor со множеством ACE, или большой thumbnailPhoto). Уменьшайте поля keepalive в облачных/NAT-средах, где неактивные соединения агрессивно обрываются.
Именованные вспомогательные конструкторы (встроенные статические фабрики):```cpp LdapModification::Replace(name, values) // Replace with text values (default) LdapModification::ReplaceBinary(name, bytes) // Replace with binary values LdapModification::Append(name, values) // Add to multi-valued attribute LdapModification::Remove(name, values={}) // Remove specific values (or all) LdapModification::Clear(name) // Delete the attribute entirely
## Сборка
**Требования:** CMake 3.25+ and a C++20-capable compiler (MSVC 2022+, GCC 12+, Clang 15+).```bash
# Configure and build (unit tests only, no live AD needed)
cmake -B build -A x64
cmake --build build --config Release
# Run unit tests
ctest --test-dir build -C Release --output-on-failure
# With integration tests (requires a live Domain Controller)
cmake -B build -A x64 -DBRIDGEHEAD_INTEGRATION_TESTS=ON
cmake --build build --config Release
./build/tests/Release/bridgehead_integration_tests.exe
# With CLI tool (adws_list, browse AD objects from the command line)
cmake -B build -A x64 -DBRIDGEHEAD_BUILD_TOOLS=ON
cmake --build build --config Release --target adws_list
./build/tools/Release/adws_list.exe --host <dc-ip> --fqdn <dc-fqdn> --domain <domain> --user <user>
# Generate API reference docs (requires Doxygen)
cmake --build build --target docs
# or directly:
doxygen Doxyfile
# Output: docs/doxygen/html/index.html
add_subdirectory(bridgehead) target_link_libraries(my_target PRIVATE bridgehead::bridgehead)
### Вариант B, установленный пакет (`find_package`)```bash
cmake --install build --prefix /usr/local # or any install prefix
| Флаг | Значение |
|---|---|
-h | Отобразить справку |
-l | Список языков |
-s | Запрашивать подтверждение перед каждым запуском |
./shelly -s ./path/to/script.sh
# or
./shelly -x ./path/to/script.sh
Файл конфигурации должен называться .shellyrc и должен быть размещён в домашнем каталоге пользователя.
./shelly -s ./path/to/script.sh arg1 arg2
``````cmake
find_package(bridgehead REQUIRED)
target_link_libraries(my_target PRIVATE bridgehead::bridgehead)
pugixml, ws2_32 и secur32 (Windows) / gssapi_krb5 (Linux/macOS) подтягиваются транзитивно.
| Платформа | Бэкенд аутентификации | Статус |
|---|---|---|
| Windows | SSPI (secur32.dll), NTLM и Kerberos | Работает |
| Linux / macOS | GSSAPI (libgssapi_krb5), SPNEGO / Kerberos | Скомпилировано; интеграционное тестирование пока не проводилось |
Оба AuthPackage::Ntlm и AuthPackage::Kerberos работают в Windows. Kerberos скрывает имя пользователя в сети и предпочтителен в продакшене; NTLM — запасной вариант, когда KDC (порт 88) недоступен.
В Linux/macOS бэкенд GSSAPI использует SPNEGO с Kerberos. Для поддержки NTLM установите плагин gss-ntlmssp:```bash
apt install libgss-ntlmssp # Debian / Ubuntu
dnf install gssntlmssp # Fedora / RHEL
Без плагина сервер будет согласовывать Kerberos. Явные учетные данные пользователя/пароля используют `gss_acquire_cred_with_password` (MIT Kerberos 1.9+); передайте пустые строки для использования кэша учетных данных по умолчанию (`kinit`). Путь GSSAPI компилируется чисто и корректен по замыслу, но еще не проверен от начала до конца на живом контроллере домена; поддержка Linux/macOS считается бета-версией.
> **Примечание по шифрованию:** ADWS на порту 9389 зашифрован на уровне NNS (сеансовый ключ NTLM или Kerberos AES-256), а не TLS. Это сделано намеренно, DC не предлагает TLS на этом порту. Если требуется аутентификация сервера на основе сертификата, альтернативой является LDAPS (порт 636).
---
## Зависимости
Извлекаются автоматически во время настройки через `cmake/Dependencies.cmake`, ручная установка не требуется:
| Библиотека | Версия | Назначение |
|------------|--------|------------|
| [Catch2](https://github.com/catchorg/Catch2) | v3.5.2 | Фреймворк модульного тестирования (только цели тестирования) |
| [pugixml](https://github.com/zeux/pugixml) | v1.14 | XML DOM (только разбор ответов ADWS) |
Нет OpenSSL. Нет Asio. Нет Boost.
---
## Известные ограничения
- **NTLM на Linux/macOS** требует плагин GSSAPI `gss-ntlmssp` (см. [Поддержка платформ](#platform-support)). Без него сервер вместо этого будет согласовывать Kerberos. NTLM на Windows работает нативно через SSPI.
- **pugixml DOM**, каждый ответ SOAP полностью анализируется в XML-дерево в памяти перед возвратом каких-либо результатов. Это ограничено размером страницы `maxElements` (по умолчанию 256 объектов на Pull), поэтому полный набор результатов никогда не удерживается в памяти одновременно. Память становится проблемой только при очень больших размерах страниц или объектах, несущих большие двоичные атрибуты (например, `nTSecurityDescriptor` на объектах со многими ACE). Потоковый подход SAX/streaming устранил бы это, но в настоящее время не планируется.
---
## Ссылки на протоколы
- **[MS-ADDM]**, Active Directory Web Services: модель данных и общие элементы
- **[MS-NNS]**, протокол .NET NegotiateStream
- **[MC-NMF]**, фрейминг сообщений .NET
- **[MC-NBFSE]**, двоичный формат .NET: расширение SOAP
- **[MS-DTYP]**, типы данных Windows (SECURITY_DESCRIPTOR, ACL, ACE, SID, GUID)
- **[MS-ADTS]**, техническая спецификация Active Directory (фильтры / атрибуты LDAP)
Все спецификации доступны в [документации Microsoft Open Specifications](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-winprotlp/).
---
## Особая благодарность
Особая благодарность IBM X-Force и проекту SoaPy за их вдохновение, исследования и публично опубликованные работы, которые помогли в создании этого проекта. Я также хотел бы отметить Логана Гойнса (Logan Goins), создателя SoaPy в IBM X-Force Red, за усилия и понимание, которые сделали возможной эту работу.
---
## Лицензия
См. [LICENSE](https://github.com/zakipedio/bridgehead/blob/main/LICENSE) для получения подробной информации.
| Метод | Конечная точка | Описание |
|---|
EnumerationClient(host, fqdn, domain, user, pass [, auth, timeoutMs, opTimeoutMs, limits]) | /Enumeration | Фабрика, подключение и аутентификация |
ResourceClient(...) | /Resource | Фабрика для Get / Put / Delete / Move |
ResourceFactoryClient(...) | /ResourceFactory | Фабрика для Create |
Query(filter, attrs [, baseDN, maxElems, scope]) | Enumeration | Собрать все результаты в vector |
Enumerate(filter, attrs, baseDN, callback [, maxElems, scope]) | Enumeration | Потоковая передача результатов через callback |
Get(dn, attrs) | Resource | Чтение атрибутов одного объекта |
Put(dn, modifications) | Resource | Изменение атрибутов |
Delete(dn) | Resource | Удаление объекта |
Create(dn, objectClass, attrs) | ResourceFactory | Создание нового объекта |
Move(dn, newDn) | Resource | Перемещение или переименование существующего объекта |
| try { |
| Опция | По умолчанию | Описание |
|---|
BRIDGEHEAD_BUILD_TESTS | ON | Сборка набора модульных тестов |
BRIDGEHEAD_INTEGRATION_TESTS | OFF | Сборка интеграционных тестов (требуется работающий DC) |
BRIDGEHEAD_BUILD_TOOLS | OFF | Сборка CLI-инструмента adws_list |
-x | Отображать команды и выполнять их |