Конектор на Matrix

Конекторът на Matrix (entrosity-matrix-connector) е програма на Go, която работи като Windows услуга на компютър в мрежата на училището. Той комуникира с Matrix по HTTPS и WebSocket (Протокол на конектора на Matrix) и с REST API на защитните стени FortiGate в LAN. За страната на потребителя вижте Конектори.

Конекторът е окончателният арбитър за това какво може да бъде записано: всяка проверка на шаблона, направлението, VDOM, защитата и версиите се прави в него и при съмнение отказва. Проверките му са пренесени от панела за едно училище, който Matrix заменя.

Инсталиране

matrix-connector.msi (WiX, за машината, 64-битово), от изданията на конектора в GitHub (проверете го спрямо matrix-connector.msi.sha256) или от Изтегляне на конектора в Matrix:

msiexec /i matrix-connector.msi /qn ENROLLMENT_TOKEN=<token> SERVER_URL=https://hub.entrosity.com/matrix

Свойство	Значение
SERVER_URL	Адресът на Matrix (https://hub.entrosity.com/matrix).
ENROLLMENT_TOKEN	Токен за регистриране на конектор на Matrix (скрит в списъка със свойства в журнала на MSI, но подробният журнал пак съдържа командния ред: изтрийте го).

MSI инсталира matrix-connector.exe в %ProgramFiles%\Entrosity\Matrix Connector, регистрира конектора, когато са зададени и двете свойства (неуспешно регистриране връща инсталацията назад), и инсталира услугата EntrosityMatrixConnector (Entrosity Matrix Connector, LocalSystem, автоматично стартиране, рестартира се при неуспех). Без свойствата услугата чака matrix-connector enroll.

• Обновяване: изпълнете новия MSI; данните и защитата се запазват.
• Деинсталиране: премахва услугата, програмата, регистрацията (connector.dat), защитните стени с техните ключове (firewalls.json), state.json, журнала на записите и защитата; журналите остават.

Команден ред

matrix-connector run [--server URL --token T] [--dev]   run (foreground, or as the service); enroll first when given a token
matrix-connector enroll --server URL --token T [--force] enroll this computer and exit
matrix-connector status                                 enrollment state and firewalls with their guard state
matrix-connector guard show [firewall_id]               the local guard
matrix-connector guard accept <firewall_id> [--yes]     accept a firewall's scope (elevated)
matrix-connector guard set <firewall_id> [--policy-writes on|off] [--address-writes on|off] [--site-writes on|off] [--max-writes-per-minute N]
matrix-connector guard reset <firewall_id>              withdraw the acceptance (elevated)
matrix-connector check --config local.json              read-only check of a FortiGate
matrix-connector install | uninstall                    manage the Windows service
matrix-connector version                                print the version

--dev управлява и защитни стени с драйвер simulator (Изпробване на Matrix със симулатора). enroll отказва, когато конекторът вече е регистриран, освен с --force.

Локална защита

guard.json в папката с данни пази за всеки идентификатор на защитна стена:

{
  "firewalls": {
    "7c0e…": {
      "scope": {"host": "192.0.2.1", "port": 443, "vdom": "root",
                "source_interface": "Students", "destination_interface": "INTERNET",
                "policy_pattern": "…", "hostname_suffix": ".coding.local",
                "marker_prefix": "Entrosity Matrix operation"},
      "pending_scope": null,
      "accepted": true,
      "allow_policy_writes": true,
      "allow_address_writes": false,
      "allow_site_writes": false,
      "max_writes_per_minute": 60,
      "accepted_at": "…", "updated_at": "…"
    }
  }
}

• Услугата само записва: първото прилагане на защитна стена я съхранява като неприета (pending); по-късно прилагане с друг обхват запазва приетия обхват и съхранява новия като pending_scope (mismatch). Само guard accept (на компютъра, с администраторски права) приема; сървърът никога не може да промени защитата.
• Записът изисква accepted, текущият обхват да е равен на приетия, видът да е разрешен (allow_policy_writes / allow_address_writes / allow_site_writes за списъците с разрешени сайтове) и през последната минута да има по-малко от max_writes_per_minute записа (по подразбиране 60, най-много 600). Иначе guard_pending, guard_mismatch, writes_disabled или rate_limited.
• Файлът се чете отново при всяка проверка (не е нужно рестартиране). В Windows собственици и единствени с право на запис трябва да са SYSTEM и Administrators; на други системи групата и останалите не трябва да могат да пишат в него. Иначе той се пренебрегва и всеки запис се отказва.
• Премахването на защитна стена (matrix.firewall.remove) забравя записа ѝ в защитата.
• Записите на разрешени сайтове са изключени, докато не се изпълни guard set <id> --site-writes on; това не променя обхвата. allow_service_writes (премахнатите услуги на Entrosity) в по-стар файл се пренебрегва и отпада при следващата промяна; защитната стена остава приета.

Офлайн проверка

matrix-connector check --config local.json е проверката само за четене на една FortiGate без Matrix. Клиентът ѝ отказва всяка заявка освен GET, преди да бъде изпратена. Конфигурационният файл е описание на защитната стена плюс локални файлове за ключа и за CA (непознатите ключове се отказват):

{
  "host": "192.0.2.1",
  "port": 443,
  "vdom": "root",
  "source_interface": "Students",
  "destination_interface": "INTERNET",
  "policy_pattern": "Internet Access for (?P<room>(?:SB[0-9]+|FB|HAC)-[0-9]{3})",
  "hostname_suffix": ".coding.local",
  "verify_tls": true,
  "ca_file": "C:\\Entrosity\\fortigate-ca.pem",
  "expected_version": "7.4.11",
  "token_file": "C:\\Entrosity\\fortigate-api-token.txt"
}

192.0.2.1 е примерен адрес. token_file съдържа само API ключа (той никога не се извежда); пазете го като парола и го изтрийте, когато приключите. Изход:

HTTPS 192.0.2.1:443; VDOM root; TLS verification on
FortiOS v7.4.11
Direction Students → INTERNET: confirmed
Room policies: 8
  SB1-102 (building SB1): policy 102, enable
  …
Address groups: 8, members: 24
  SB1-102-Students address (SB1-102): 3 members, editable
  …
Policies with this direction: 10
Warnings:
  later_accept_policy: policy 1 "Internet Access for Students" after room SB1-102 accepts the room's computers when the room is disabled (source "all")
Nothing was changed. The effect on traffic was not verified.

При всяка грешка завършва с ненулев код (недостъпна, tls, auth_failed, version_mismatch, direction_invalid, …). Има общо ограничение от пет минути.

Променливи на средата

Променлива	Значение
MATRIX_CONNECTOR_DATA_DIR	Папка с данни (по подразбиране %ProgramData%\Entrosity\Matrix Connector, ~/.matrix-connector на други системи).
MATRIX_LOG_LEVEL	debug, info, warn, error.

Файлове

В папката с данни:

Файл	Какво
connector.dat	Идентификаторът, ключът и адресът на сървъра на конектора (защитени с DPAPI в Windows).
firewalls.json	Приложените защитни стени (FirewallRef) с техните API ключове и версии на идентификационните данни (ключовете са защитени с DPAPI).
guard.json	Локалната защита.
journal.json	Журналът на записите: намерението на всеки запис, отбелязано преди записа.
state.json	Задачите в ход.
update\	Изтеглените издания и result.json от последното самообновяване.
logs\connector.log	Журнал с ротация. Предупрежденията и грешките отиват и в журнала на събитията Application (източник EntrosityMatrixConnector).

При стартиране конекторът отчита всяка задача, която е била в ход, когато е спрял: когато журналът ѝ показва запис, който може да е бил изпратен, като unconfirmed с отбелязаните подробности (PolicySetResult с wrote: true или етапът на AddressOpResult); иначе като interrupted (нищо не е записано).

Мрежа

Само изходящи връзки:

Към	Порт	За
hub.entrosity.com	443	API и WebSocket на Matrix (HTTPS)
FortiGate в LAN	нейният HTTPS порт за управление	REST API на FortiOS (/api/v2/cmdb/…)

Клиент за FortiGate

• Заявките отиват към https://{host}:{port}/api/v2/cmdb/… с Authorization: Bearer <token>, Accept: application/json и винаги vdom=<vdom>. Без прокси от средата, без пренасочвания, таймаути от 4 секунди (свързване) и 8 секунди (общо). TLS се проверява спрямо зададения CA или системните коренни сертификати, освен ако verify_tls не е изключено.
• Приемани HTTP отговори: 200 (и 201 за POST). 404 е not_found, 401/403 – auth_failed, всичко друго – грешка. Пликът трябва да съдържа status: success, същия http_status, зададения vdom и, когато версията е фиксирана, тази версия (version_mismatch).
• Грешките никога не съдържат ключа или суровия отговор.
• Списъците се четат по 200 наведнъж (най-много 100 страници) и трябва да останат последователни: еднакви size и revision на всяка страница и наличен limit_reached. FortiOS 7.4.11 може да отговори с limit_reached: false и по-малко редове от size; тогава клиентът следва next_idx, който трябва да расте. Списък, който се променя, докато се чете, се отказва (invalid_response) и се чете отново следващия път.
• Крайни точки: system/interface, system/zone, system/sdwan (направлението), firewall/policy (залите; PUT само на {"status"}), firewall/address (GET, PUT на подмрежата, POST на нови обекти /32 и FQDN обекти, DELETE на неизползвани FQDN обекти, притежавани от Matrix), firewall/addrgrp (GET, PUT на member).

Какво позволяват проверките

Едно правило е зала само когато името му напълно съвпада с шаблона (с непразна група room), неговият policyid е от 1 до 4294967295, VDOM му е зададеният, srcintf е точно [{name: <source>}] и dstintf – точно [{name: <destination>}] (нищо друго), а status е enable или disable. Повтарящи се идентификатори на правила правят цялото прочитане невалидно.

Превключването на зала (matrix.policy.set) взима заключване за правилото (busy, когато е заето), прочита правилото отново (точно един резултат с този идентификатор), изисква то да е зала и същата зала като в задачата (room_mismatch), иска разрешение от Matrix (policy.status с предишното и желаното състояние) и само ако състоянието е различно, отбелязва намерението в журнала, изпраща PUT {"status": …} и го прочита обратно (същия идентификатор и име, желаното състояние; иначе unconfirmed). Правило, което вече е в желаното състояние, е успех без запис.

Промените на адреси прочитат правилото на залата, групата му, обекта и всяко използване на обекта и групата във всички IPv4 правила и групи и отказват всичко извън залата (Адреси и групи → Какво може да се редактира). Новите обекти са ipmask с маска 255.255.255.255 и коментар <marker_prefix> <operation id>. Версиите на групите са SHA-256 отпечатъци, съвместими с тези на стария панел.

Разрешените сайтове променят само членовете на фиксираните групи Matrix allowed sites и Matrix allowed sites <room>, създават fqdn обекти matrix-site:<domain> с коментар <marker_prefix> site и изтриват само такива обекти, когато вече никоя група или правило не ги използва; всеки друг член се запазва и се показва само за преглед (протокол). Списъкът изисква своята група и ACCEPT правило с точното направление на защитната стена и групата в dstaddr (sites_not_set_up). Такова правило (всеки dstaddr е група за разрешени сайтове или старата група Matrix Entrosity services, в която Matrix никога не записва) може да използва групите на залите като източници: те остават редактируеми и то не е later_accept_policy. Задача matrix.services.sync (премахнатите услуги на Entrosity) завършва неуспешно като неподдържан тип задача, а полетата services_enabled / service_domains при прилагане се пренебрегват.

Задачи и ленти

Лента	Задачи	Паралелност
config	matrix.firewall.apply, matrix.firewall.remove	1
read	matrix.firewall.check, matrix.refresh	2
policy	matrix.policy.set (различни зали паралелно; същата зала е busy)	4
address	matrix.address.update, matrix.address.create, matrix.sites.set	1
update	update_agent	1

Интервали

Какво	Кога
Отчет за залите	Според интервала за отчет на всяка защитна стена (по подразбиране 30 с, 15–300) и веднага след всеки запис
Адресни групи, разрешени сайтове	На всеки 5 минути, при обновяване (addresses, all) и след записи на адреси или сайтове; изпращат се само когато хешът им се е променил
Сигнал за активност	Всяка минута
Разрешаване в момента на записа	Точно преди всеки запис; всеки отговор освен allowed: true до 5 секунди го блокира
Заявка към FortiGate	4 с за свързване, 8 с общо

Самообновяване

Matrix предлага по-нова версия като задача update_agent (компонент matrix-connector); как изданията стигат дотам: Работа с Entrosity Matrix → Издания на конектора.

1. Задачата носи изданието (target) и, когато Matrix го има, MSI на текущата версия (rollback), всяко с подпис Ed25519. Конекторът проверява подписите с публичния ключ, вграден в него (RELEASE_PUBLIC_KEY при компилиране), преди да изтегли каквото и да е: компилация без ключа отговаря с update_unsigned, грешен подпис – със signature_invalid.
2. Изтегля двата MSI в <data dir>\update\, проверява SHA-256 и размера им (download_failed, hash_mismatch) и регистрира еднократна планирана задача като SYSTEM, MatrixConnectorUpdate, която стартира минута по-късно (със собствено име, така че другите конектори на Entrosity на същия компютър запазват своите).
3. Планираната задача изпълнява msiexec /i <нов MSI> /qn /norestart, чака услугата EntrosityMatrixConnector да работи и да продължава да работи, а иначе инсталира отново предишния MSI. Накрая планираната задача се премахва.
4. Резултатът се записва в update\result.json и в журнала при следващото стартиране (connector update finished); новата версия се отчита в hello.

Конекторите, компилирани без RELEASE_PUBLIC_KEY, не обявяват update и никога не получават обновявания.

Разработка

make build-local
dist/matrix-connector enroll --server http://localhost:8085/matrix --token <token from Matrix → Connectors>
make dev          # run --dev: simulated firewalls
make lint vet test

За да изпробвате истинския драйвер fortigate без FortiGate, пуснете go run ./cmd/fortigate-sim --dir /tmp/fgsim (HTTPS на 127.0.0.1:18443; ca.pem и token.txt в директорията) и насочете към него защитна стена с драйвер fortigate. Контролният му API на 127.0.0.1:18444: GET /state, GET /writes, POST /fault?match=S&count=N (следващите съвпадащи записи се изпълняват, но никога не получават отговор), DELETE /fault и POST /cli, който прилага командите за настройка на разрешените сайтове (config firewall addrgrp / config firewall policy с edit, set, append, next, end), както би го направил администратор. Както FortiOS, симулаторът познава вградените адреси all и none, отказва празни групи и отказва да изтрие обект, който група или правило използва.

Хранилището има нужда от entrosity-shared-go до него и от go.work, игнориран от git (use . ../entrosity-shared-go), докато таг на shared-go не съдържа proto/matrix. Винаги проверявайте GOOS=windows go vet ./... (make vet). Тестовете пускат клиента за FortiGate срещу тестова FortiGate (пликове, страниране със съкращаването на 7.4.11, пренасочвания, проксита, TLS, скриване на ключа), пренасят тестовете от страната на конектора на стария панел към симулатора и пускат целия конектор срещу фалшив бекенд.

Издания: таг vX.Y.Z (-suffix го прави pre-release) компилира MSI и EXE и ги публикува в издание в GitHub; всяко качване в main обновява плъзгащото се pre-release издание dev.