- В общем про api и методы взаимодействия с ними (soap, rest, yang, soap, xml, json, restconf/netconf, etc) в отдельной статье
- О применении разных современных протоколов и инструментов для мониторинга отдельная статья
- Использование json в разных языках php, ruby
Пример почему API это нужно и важно – большая часть современных Security продуктов Cisco имеют API (ISE, FirePower, Stealthwatch, AMP, CloudLock, DUO) для поддержки мониторинга/конфигурации с использованием API.
SOAP
SOAP (Simple Object Access Protocol) – очень много использовался раньше и до сих пор можно встретить в “старых” приложениях, изначально разработан Microsoft. SOAP для своей работы использует XML, который в свою очередь определяется XML схемой. Спецификация SOAP. SOAP и REST используются HTTP protocol как транспорт. SOAP был создан для замены старых решений на основе DCOM и CORBA.
Simple Object Access Protocol (SOAP): This standards-based web services access protocol was originally developed by Microsoft and has been used by numerous legacy applications for many years. SOAP exclusively uses XML to provide API services.
Soap exlusively uses XML to provide API services. XML- based specifications are governed by XML Schema Definition (XSD) documents. SOAP was created to replace older solutions such as the Distributed Component Object Model (DCOM) and Common Object Request Broker Architecture (CORBA).
YAML & JSON
Общая практика: json для машин, yaml для людей
REST (json)
REST (restful) API проще использовать в сравнении с SOAP. Самый популярный сейчас способ работы с API и по сути industry standard для взаимодействия application to application. В том числе сетевом облорудовании – Cisco, Mellanox (ниже), Arista (EOS API). Считается проще и более гибким в сравнении с SOAP.
rest (restful) apis used in many implementations nowadays.
Вместо XML используется JSON. SOAP и REST используются HTTP protocol как транспорт. Representational State Transfer (REST): This API standard is easier to use than SOAP. It uses JSON instead of XML, and it uses standards such as Swagger and the OpenAPI Specification (https://www.openapis.org) for ease of documentation and to encourage adoption.
Swagger (OpenAPI): Swagger is a modern framework of API documentation and development that is the basis of the OpenAPI Specification (OAS).
JSON появился позже XML, но во многом заменил его т.к. он проще и быстрее. XML требует больше ресурсов и его сложнее использовать для представления данных. JSON изначально “родился” из JavaScript – использовался для взаимодействия между программами на JavaScript и серверами на Java, но в последующем (после упрощения и “стандартизации”) начал применяться в разных языках.
JSON интересен тем, что не имеет версии и это считается плюсом – он не поменяется и на него можно всегда полагаться.
JSON используется даже в сетевом оборудовании – у Mellanox помимо CLI (странно похожего на Cisco IOS ;)) есть json api, в который можно делать запросы с командами. В том числе для запросов, которые обрабатываются долго, есть вариант запроса с json в варианте async – отправляешь запрос, тебе возвращается job id, потом по этому job id ты можешь получить с устройства результат. Блеск.
{ "commands": [ "show 1/1", "show 1/2" ] }
{ "execution_type":"async", "cmd": "show 1/1" }
Asynchronous requests will return immediately after sending the request with a reply containing a “job_id” key. The user can use the given job ID to later query for request status and execution results. Queries for asynchronous request results are guaranteed to be accessible up to 60 seconds after the request has been completed.
{"execution_type":"async",
"commands": ["interface ib 1/1 description test description",
"show interfaces ib 1/1 status"]}
{
"executed_command": "",
"status": "OK",
"status_message": "",
"data": "",
"job_id": "91329386"
}
curl -b /tmp/cookie -X GET "https://10.10.10.10/admin/
launch?script=json&job_id=91329386"
{
"results": [
{
"status": "OK",
"executed_command": "interface ib 1/1 description test description",
"status_message": "",
"data": ""
},
{
"status": "OK",
"executed_command": "show interfaces ib 1/1 status",
"status_message": "",
"data": {
"IB1/1": [
{
"Description": "test description",
"Speed": "fdr",
"Logical port state": "Initialize",
"Physical port state": "LinkUp",
"Current line rate": "56.0 Gbps",
"IB Subnet": "infiniband-default"
}
]
}
}
]
}
GRAphql
GraphQL – популярный в современных приложениях/дашбордах, но не в сетевом оборудовании язык разметки.
GraphQL is a query language for APIs that provides many developer tools. GraphQL is now used for many mobile applications and online dashboards.
Protocol Buffers
Wiki
Protocol Buffers — протокол сериализации (передачи) структурированных данных, предложенный Google как эффективная бинарная альтернатива текстовому формату XML. Разработчики сообщают, что Protocol Buffers проще, компактнее и быстрее, чем XML, поскольку осуществляется передача бинарных данных, оптимизированных под минимальный размер сообщения.
По заявлениям Google, Protocol Buffers по сравнению с XML:
- проще;
- от 3 до 10 раз меньше;
- от 20 до 100 раз быстрее;
- более однозначный;
- позволяет создавать классы, которые в дальнейшем легче использовать программно.
Protocol Buffers не предназначен для чтения пользователем и представляет собой двоичный формат. Для десериализации данных необходим отдельный .proto-файл, в котором определяется формат сообщения.
YANG
- YANG описан в RFC 6020
- Спецификация, описанная на YANG часто называется YANG module, а набор YANG module называют yang set или YANG model
- В NETCONF и RESTCONF реализациях YANG
- контроллером YANG выступает client (по сути NMA, Network Management Application)
- сервером YANG выступает сервер/сетевое устройство (управляемое устройство, например роутер/свич)
YANG – признанный лидер для замещения snmp как языка, представляющего данные (tail-f). Имеет разные преимущества – читаемость человеком, версионность, иерархичность, etc.
-
Конфигурация – напр. включение протокола маршрутизации на устройстве
-
Получение нотификаций – уведомления безопасности по превышению количества попыток аутентификации, падение интерфейсов и проч
-
Мониторинг – получение информации о загрузке CPU/памяти, счетчиках
-
Действия – сброс счетчиков, перезагрузка системы, сохранение конфига и проч.
- Configure: for example, enabling a routing protocol on a particular interface
- Receive notifications: an example of notification can be repeated login failures, interface failures, and so on
- Monitor status: for example, retrieving information about CPU and memory utilization, packet counters, and so on
- Invoke actions: for instance, resetting packet counter, rebooting the system, and so on
The YANG model of a device is often called a “schema” defining the structure and content of messages exchanged between the application and the device.
-
Когда вы создаете новую YANG model, вы можете использовать иерархии данных из других модулей
-
Yang модель может легко масштабироваться – язык позволяет создавать новые параметры
When you create new YANG modules, you can leverage the data hierarchies defined in other modules.
YANG also permits new statements to be defined, allowing the language itself to be expanded in a consistent way.
NETCONF
-
Изначально был создан для преодоления проблем протокола SNMP
Netconf is defined in RFCs 6241 and 6242.
Netconf was created to overcome the challenges in legacy Simple Network Management Protocol (SNMP) implementations.
- Важным фактом является то, что NETCONF придуман до YANG. Поэтому другие языки (напр. XML) использовались для работы NETCONF ранее. Сейчас по факту работа NETCONF широко поддерживается с использованием YANG.
- На сайте devnet есть sandbox’ы Cisco образов, с которыми можно попрактиковаться для работы с netconf (да и в целом с кучей других вещей)
- ncclient – open source python библиотека для netconf
- scrapli_netconf – еще одна open source python библиотека для netconf, лучше Ncclient тем, что async
pip3 install ncclient
pip3 install scrapli_netconf
NETCONF протокол реализует возможность CRUD работы с сетевыми устройствами.
NETCONF provides a mechanism to install, manipulate, and delete the configuration of network devices. It uses an ((по факту так же и YANG см. выше)) Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. NETCONF uses a simple Remote Procedure Call (RPC) based mechanism to facilitate communication between a client and a server.
- The first step is to enable NETCONF on the Cisco IOS XE device
- The second and final step is set the subscription between the collector and the device, along with the subscripton type (either cadence or on-change) and eventually the cadence frequency.
-
-
Для клиентов (NMA, Network Management Application) он работает как сервер
-
Для серверов (сетевых устройств) он работает как клиент
-
-
клиент отправляет hello с указанием поддерживаемой версии NETCONF
-
сервер отправляет hello с указанием поддерживаемой версии NETCONF и поддерживаемыми «capabilities»
RESTCONF
-
Многие администраторы хотели реализацию функционала netconf поверх REST API (используя http протокол и его методы для взаимодействия с сетевым устройством) – в итоге появился такой вариант в виде RESTCONF
-
Описан он в RFC 8040
-
Сейчас поддерживается на многих сетевых устройствах
Many network administrators wanted to have the capabilities of netconf over “REST”. This is why a REST-based variant of NETCONF (RESTCONF) was created. Defined in RFC 8040.
-
RESTCONF требует от сервера частичного сохранения состояния клиента.
-
Любой запрос, который отправляет RESTCONF client исполняется на сервере сразу. Невозможно отправить несколько связных транзакций – эта фича NETCONF не поддерживается.
RESTCONF requires the server to keep some client state. Any request the RESTCONF client sends is acted upon by the server immediately. You cannot send any transactions that span multiple RESTCONF messages.
deckofcards
SWAGGER, WSDL, WADL
SWAGGER – framework API документации, основа OpenAPI спецификации. Помимо Swagger так же есть еще WSDL и WADL.
- Swagger (OpenAPI): Swagger is a modern framework of API documentation and development that is the basis of the OpenAPI Specification (OAS).
- Web Services Description Language (WSDL) documents: WSDL is an XML-based language that is used to document the functionality of a web service.
- Web Application Description Language (WADL) documents: WADL is an XML-based language for describing web applications.
PxGRID, threat response API
- У Cisco есть threat response API – для интеграции security продуктов Cisco с системами других вендоров. По сути pxGrid для решения задачи ИБ. В итоге ускоряется процесс реагирования на инциденты. Для ознакомления с этим api на devnet есть несколько лаб.
- Legacy версия pxGrid поддерживала XMPP для взаимодействия – реализация старая и имела множество недостатков
- published-subscribe model (pub/sub) модель требовала модификации всех XML сообщений между клиентом и сервером
- серверная часть XMPP изначально создана для пользовательских чатов, а не взаимодействия machine to machine (MtM) or application to application (может требоваться передача большого количества сообщений долгое время)
- Current версия pxGrid поддерживает REST/websocket (industry standard) для взаимодействия
- websocket – обеспечивает двунаправленную передачу данных быстро и масштабируемо, так же websocket используется для pub/sub
- rest – предоставляет сервисы API (подробнее выше), сообщения кодируются json
- Cisco на git выложила примеры rest/websocket работы с pxGrid на java/go/python
Cisco pxGrid provides a unified ecosystem to integrate multivendor tools to exchange information either unidirectionally or bidirectionally.
Integrate your security products
With Cisco pxGrid (Platform Exchange Grid), your multiple security products can now share data and work together. This open, scalable, and IETF standards-driven platform helps you automate security to get answers and contain threats faster.
-
pxGrid service consumer – потребитель сервиса, должен аутентифицироваться клиентским сертификатом на сервере (более безопасно, рекомендуемый Cisco способ) или с использованием username/password (менее безопасно)
-
pxGrid service provider – хостер сервиса
The are two different types of pxgrid clients: a pxgrid service consumer and a pxgrid service provider.
You can generate passwords via the pxgrid account create API, however, certificate-based SSL authentication is far more secure and is the recommended way to authenticate pxgrid clients.
Pxgrid clients poll on this REST API call until a “enabled” message is received from the server.
Service providers use the Register/Unregister Service APIs to provide and update the necessary URLs from which their sevices are accessible for other pxgrid clients.
All pxgrid clients use the service lookup api to dynamically discover all available provider services and their locations.
Pxgrid clients can then perform rest-based queries (via the service query/subscribe api) or build websocket connections to receive information.
