В этой статье мы расскажем, как внешние приложения и сервисы могут взаимодействовать с DLP-системой InfoWatch Traffic Monitor (далее ТМ) через API. API-интерфейс в TM разработан уже давно, но в последний год интерес к нему со стороны сторонних разработчиков значительно вырос. Интеграторы и вендоры обычно хотят интегрировать DLP- системы с нуля в ИТ-ландшафт организации, импортозаместить прежние иностранные системы, расширить количество контролируемых DLP-системой каналов и аккумулировать информацию из нескольких систем в одной. Мы анализируем кросс-продуктовые сценарии и видим, что API является наиболее эффективным и современным средством решения подобных задач. Поэтому мы решили рассказать про наш API-интерфейс и продемонстрировать его работу на практических примерах. Сценариев интеграции довольно много, поэтому мы рассмотрим самую популярную задачу - отправку событий из корпоративного мессенджера в DLP TM на контентный анализ. Для пущей сложности мы взяли самописный мессенджер Stack chat, а еще решили отправлять в DLP не только переписку, но и пересылаемые корпоративные файлы.  Не секрет, что корпоративный мессенджер - это основное оперативное средство коммуникации любой динамичной организации. А благодаря своим интеграциям со средствами телефонии, сетевыми каталогами, CRM и корпоративными порталами, он же - канал утечки конфиденциальной информации. Далее мы расскажем, как сделать плагин, выписать для него лицензию, выбрать или собрать утилиту для отправки в API. Приведем примеры отправки синтетических событий и кода, а также опишем результат. Топик будет полезен интеграторам и разработчикам бизнес-приложений при создании подобного плагина. Итак, для интеграции с DLP TM нужно всего 3 вещи: По сути, это просто zip-архив с manifest-файлом и иконками, загружаемый в систему. Он позволяет регистрировать новые неизвестные ранее типы событий. Что регистрировать, от какого источника и с какими атрибутами, вы вольны описать в плагине. InfoWatch предоставляет типовые плагины под разные классы событий, например… По ряду полей совпадает с плагином. Сопоставляет поля и проверяет, может ли DLP загружать данный тип событий в соответствии с лицензированием. Способ отправки события из ПО в API DLP-системы. В IW API за получение событий отвечает Push API. Он реализован с использованием библиотеки Apache thrift. Thrift - это фреймворк для работы с клиентской и серверной частью. Он формирует и преобразует события под наш API.  Нам необходимо написать и зарегистрировать плагин в InfoWatch Traffic Monitor. Сам плагин несложный, в минимальном виде это json-файл манифеста (utf-8 без BOM) в zip-архиве. В нашем случае это будет манифест и иконка для событий. Для примера иконку позаимствуем из пака иконок FatCow (https://www.fatcow.com/free-icons). В итоговом виде архив будет содержать: Для примеров плагина и событий используем данные: Название компании: MY_COMPANY Домен: mycompany  Сайт: mycompany.com Сотрудники: Николай Смирнов Телефон: +1234567890 Логин: smirnov Валерия Иванова Телефон: +4926666 Логин: viva Страничка в телефонной книге компании: https://phones.mycompany.com/viva Петр Петров Телефон: +777555 Архив с примерами Push API идет вместе с поставкой InfoWatch Traffic Monitor. В этом архиве есть каталог pushapi_example\pushapi\plugin, в котором лежит json-схема манифеста и архив с примером. Если написать манифест с тестовыми данными выше, то получим: Вторым шагом не забудем выписать нужную лицензию. Пример лицензии: «protocol»: «*» — лучше указывать * а не none. Хотя возможны оба варианта, в случае «*» в событиях протокол можно не указывать в атрибутах} Есть еще одна тонкость – в файле лицензии используется именование объектов ТМ, а в манифесте JSON именование объектов в нотации PushApi.  У разработчиков часто возникает вопрос - как назвать сервис в плагине и почему он отличается от класса?  В InfoWatch исторически сервис - это именованные типы / группы классов, или то, как указывать те типы классов, которые используются. Например, имя сервиса может быть - Мой любимый сервис. В нем можно описать те классы, которые в нем присутствуют.  Классы - это поддерживаемые типы данных. Класс описывает только те форматы событий, которые поддерживает Traffic Monitor. Варианты: ) - собственные типы данных DLP из них сделать нельзя  Важно корректно интерпретировать наши сущности. Пример: В манифесте есть обязательные корневые поля PLUGIN_ID – уникальный идентификатор плагина в ТМ размерностью от 32х до 40 символов. Поддерживаются цифры 0-9 и буквы A-F Если лицензия в плагине есть, то указывается: Для корректного отображения лицензирования плагина в интерфейсе ТМ необходимо указать в плагине, как искать лицензию: После загрузки лицензии и плагина в советующий раздел InfoWatch Traffic Monitor, плагин отображает зарегистрированный тип события. Кроме того, в разделе «События» при создании запросов уже можно указать тип зарегистрированного события. Для нашего примера: В полях хорошо зарекомендовала себя уже скомпилированная тестовая thrift-утилита в поставке опциональных DLP-пакетов - PushAPI util. Недавно появился ее Windows-вариант. Утилиту на первом этапе используют многие, с нее можно начинать разработку. Она простая и доступная.  Другие варианты: 1) Взять готовую скомпилированную thrift-утилиту, например, из наших пакетов QAtools. 2) Собрать самостоятельно. Thrift поддерживает C#, C++, Cappuccino, Cocoa, Delphi, Erlang, Go, Haskell, Java, OCaml, Perl, PHP, Python, Ruby, Rust, Smalltalk и JavaScript. Под  C#, C++, Go, Python у InfoWatch уже есть примеры сборки. Для Python 3 потребуется еще одна библиотека https://github.com/Thriftpy/thriftpy2 Пример отправки в мессенджер: Пример передачи файла: Здесь мы видим следующие атрибуты: --host – адрес источника событий --token – автоматически генерируется при установке плагина. Его можно скопировать из веб-консоли DLP (Управление - плагины) --class – класс события, который вы хотите присвоить (в утилите наименования классов также отличны от манифеста pushApi); --service – а это сервис; --evtattr – возможность задавать атрибуты событиям в консоли, по которым можно их искать группировать и применять политики; --sender – адрес отправителя, по которому произойдет идентификация и приклеится карточка сотрудника из AD; --receiver – здесь ресурс и каталог для загрузки файла; --data – файл-вложение, передаваемый в событии. Как только мы понимаем, какие классы и с какими параметрами нам нужны для разработки, и умеем с ними работать, мы определяемся с деталями и можем дополнить плагин, указав: как назвать сервис; как описать классы, которые в нем присутствуют; как описать manifes-файл, содержащий все это. Подготовительную часть и тестирование отправки мы выполнили, теперь приступим к формированию событий с помощью собственного приложения.  Если мы заглянем в файл с описанием pushAPI-протокола (pushapi_example\pushapi\pushapi.thrift), в нем будет описание всех необходимых методов протокола и требуемых объектов. Сам алгоритм вызовов методов протокола pushAPI для отправки события в InfoWatch Тraffic Мonitor можно представить следующими вызовами: VerifyCredentials(Credentials(или компании, Токен авторизации)) – Данный вызов не обязателен, он лишь проверяет, что в ТМ есть зарегистрированный плагин с нужным Vendor, и существует указанный токен). Никакие лицензии при вызове данного метода ТМ не проверяет. eventId = BeginEvent(thriftEvent, Credentials(или компании, Токен авторизации)) – Вызов метода сообщает ТМ о начале передачи события. При этом объект thriftEvent представляет собой заполненное описание события. При вызове данного метода ТМ проверяет предоставленные учетные данные (Credentials) и наличие необходимой лицензии. Если отправляемое событие в ТМ содержит дополнительные бинарные данные (например, сопутствующая теневая копия), то необходимо вызвать: streamId = BeginStream(eventId, data.Id) – Начать передачу экземпляра данных события. Где eventId – идентификатор события полученного в результате вызова BeginEvent, а data.Id идентификатор объекта данных в thriftEvent. Указание идентификатора объекта данных необходимо, т.к. в событии может содержаться более одного файла теневой копии SendStreamData(eventId, streamId, buffer) – Передать кусок данных события. Данный метод допускает множественные вызовы, до тех пор, пока нужный файл теневой копии не будет полностью передан в ТМ; EndStream(eventId, streamId) - закончить передачу указанного потока данных события. EndEvent(event_id, abort: false) - Закончить обработку события. Если флажок abort выставлен, то событие не попадает в БД и не обрабатывается дальше. А для любителей кода, это же - на C#     Заранее прошу прощения за костыль с «Dictionary<int, byte[]> someData» в  целях  небольшого упрощения кода. С отправкой разобрались, а теперь перейдем к заполнению структуры события. Но прежде чем положим пальцы на клавиатуру, для большей визуализации данных представим его в виде json  А теперь заполним то же самое, но уже программно: После вызова данного метода в InfoWatch Traffic Monitor появится наше событие: Cразу заполним и сгенерируем  второе событие – передача файла. А теперь посмотрим на наше событие в интерфейсе InfoWatch Traffic Monitor. Можно заметить, что контакты отображаются немного по-разному. Это связано с тем, что для пользователя Валерия в событии был заполнен контакт с расширенной метаинформацией. И если щелкнуть по контакту, то отобразится карточка контакта: Дополнительно стоит отметить, что в тестовом InfoWatch Traffic Monitor, на момент получения событий не содержится каких-либо персон, поэтому контакты не проходят идентификацию и не привязываются к каким-либо пользователям. С помощью плагина можно зарегистрировать собственные контакты (например, если у пользователей системы заказчика есть какие-либо собственные уникальные идентификаторы). Но в подавляющем большинстве случаев этого не требуется, т.к. в InfoWatch Traffic Monitor есть достаточное количество предустановленных типов: Мнемо контакта Описание email Почтовый адрес auth Информация об авторизации   пользователя dnshostname Доменное имя машины icq ICQ UIN skype Skype ID phone Номер телефона ip IP-адрес sid Идентификатор безопасности   Windows NT webaccount Название учётной записи на   ресурсе lotus Адрес в Lotus Domino domain Домен Немного возвращаясь в начало примера, вспомним, что в плагин мы с вами добавляли иконку. А вот, где она отображаются в событии: В статье мы рассмотрели создание плагина и загрузки валидной лицензии, генерацию синтетических событий в систему с целью проверки, а также написание собственного приложения для отправки событий заданной структуры. На выходе мы получили полноценно структурированное событие с идентификацией и атрибутами для поиска и анализа. Теперь вся переписка в компании под контролем. При этом API позволил сделать универсальное и простое решение, сэкономив ресурсы разработки. Данный пример является только частью API DLP TM, предназначенной для приема сторонних событий. Про иные задачи и способы их решения в DLP Traffic Monitor расскажем в следующий раз. Менеджер по развитию продуктов