Package: ussl
USSL - USSC SOAR SCRIPT LIBОглавление1. ОписаниеУстановка2. Взаимодействие с внешними системамиДоступные методы модуля ussl.transportДоступные на данный момент транспорты3. Взаимодействие с USSC SOARИспользование форматирования и переназначенияКлючи расширения__SOAR.input__SOAR.secrets__SOAR.formatИспользование ussl.postprocessing в скриптахОписание:Библиотека разработана для упрощения работы с сетевыми устройствами, а также для расширения возможностей USSC SOAR.УстановкаУстановка через PyPI:pip install usslВзаимодействие с внешними системами:Для упрощения взаимодействия с различными системами в модуле ussl.transport реализован единый интерфейс. На вход он принимает объект Protocol, содержащий данные о подключении и объект (или список объектов) Query, содержащий данные о команде, которую необходимо выполнить; в качестве ответа возвращается объект Responce.Поля объекта ProtocolОбщие для всех интерфейсов поля:
    host: ip-адрес или имя хоста, к которому необходимо подключиться;
    username: имя пользователя, под которым необходимо подключиться;
    password: пароль от указанного пользователя;
    interface: интерфейс, к которому необходимо подключиться (ssh, winrm, и т.д.);
    port: порт, на котором работает интерфейс;
    query: команда или набор команд, которые необходимо выполнить;
    encoding: кодировка запроса;
    decoding: кодировка ответа;
    window_width: ширина окна консоли (влияет на форматирование ответа).

Поля, специфичные для winrm:
    domain: имя домена к которому необходимо подключиться;
    scheme: схема подключения (http или https);
    path: путь до WS-Management;
    transport: протокол аутентификации.

Поля, специфичные для ssh:
    clean_timeout: таймаут очищения канала;
    look_for_keys: включить или отключить аутентификацию по ключам;
    auth_timeout: таймаут авторизации;
    timeout: таймаут соединения;
    pem_file: значение закрытого ключа авторизации от указанного пользователя.Поля объекта Querycommand: содержит командe, которую необходимо выполнить;
timeout: содержит время, отведенное на выпонение команды;
expects: содержит регулярные выражения, которые описывают
ожидаемый ответ от конечной системы;
sudo: содержит пароль от супер пользователя или enable.Поля объекта Responceresult: содержит исходный ответ от целевой системы;
text: содержится форматированный ответ от целевой системы;
status: содержится статус выполнения переданной команды.Из особенностей поведения можно выделить следующее:При передаче списка Query в Responce попадёт вывод последней команды или, если в ходе выполнения произошла ошибка, вывод ошибки с соответствующим статусом;...Доступные методы модуля ussl.transport:fromussl.transportimportTransportfromussl.modelimportProtocol,QueryTransport.connect(Protocol(...))# Устанавливает соединение с указанными параметрами, ничего не возвращает. В этом случае Protocol может не содержать Query.Transport.execute(...,query=[Query(...)])# Выполняет команды (или команду) в случае, если было установлено соединение.Transport.connect_and_execute(Protocol(...,query=[Query(...)]))# Устанавливает подключение и выполняет команды (или команду).Доступные на данный момент транспорты:WinRMSSHLDAPВзаимодействие с USSC SOAR:Для упрощения взаимодействия с USSC SOAR были разработан модуль ussl.postprocessing. Он берёт на себя работу с вводом/выводом данных в скриптах, переназначение ключей объектов, а также форматирование значений объектов, передаваемых в скрипт стандратным образом.Использование форматирования и переназначенияДля того чтобы использовать возможности расширения, необходимо чтобы выполнялись следующие условия:На вход скрипта подаетсяобъектJSON (не массив);В объекте содержится как минимум один изключей расширения;Полезная информация* передаётся в ключеdefault_input;* под полезной информацией подразумевается объект json, который передаётся на вход плейбука, а также между его шагами.Изначально использование расширений задумывалась через полеParameters.Ключи расширения__SOAR.inputКлюч предназначен для замены ключей в default_input. Ключ должен содержать объект, ключи которого являютсязаменяемымиключами, а значениязаменяющими. В результате на вход скрипта придёт JSON с уже замененными ключами.Пример использования{"default_input":{"input":{"some_key":"some_value"}},"__SOAR.input":{"some_key":"new_some_key"}}При передаче через Parameters значения в поле default_input должно иметь следующий вид.{"default_input.$":".$"}__SOAR.secretsКлюч предназначен для замены ключей в secrets. Этот ключ может быть полезен при использовании одинаковых секретов на нескольких разных устройствах, без создания новых секретов. Логика работы аналогична__SOAR.input.Пример использованияОбъект secret невозможно сформировать из вне, поэтому, для примера, будет использоваться следующий объект:{"secrets":{"passwd":"1234567890"}}Тогда замена будет выглядеть следующим образом.{"default_input":{"input":{"some_key":"some_value"}},"__SOAR.secrets":{"passwd":"password"}}При передаче через Parameters значения в поле default_input должно иметь следующий вид.{"default_input.$":".$"}__SOAR.formatКлюч предназначен для форматирования текста, без изменения кода скриптов. Ключ должен содержать объект, ключи которого являются новыми полями default_input (в случае, если такое поле уже существует, его значение будет заменено), а значение - строка, в которую можно подставлять значения переменных, существующих в объекте default_json. В случае, если такой переменной не найдено место подстановки останется без изменений. Для подстановки переменной необходимо использовать фигурные скобики.Ключ __SOAR.format применяется после выполнения скрипта, т.е. если до этого применялся ключ __SOAR.input, то нужно использовать ужезамененныезначения ключейПример использования{"default_input":{"input":{"some_key":"some_value"}},"__SOAR.format":{"new_key":"Строка, содержащая {some_key}"}}В результате выполнения преобразований, скрипт вернёт следующий JSON{"some_key":"some_value","new_key":"Строка, содержащая some_value"}При передаче через Parameters значения в поле default_input должно иметь следующий вид.{"default_input.$":".$"}Использование ussl.postprocessing в скриптахДля того чтобы использовать возможности ussl.postprocessing достаточно при создании скрипта выполнить несколько условий, а именно:Создать класс с произвольным именемУнаследоваться от класса ussl.posprocessing.base.BaseFunctionРеализовать методыvalidate_input,validate_secretsили передать классы-схемы в параметрыinput_schemaиsecrets_modelвашего класса для валидации входных данныхРеализовать методfunctionДля вывода ошибок использовать исключения из модуля exceptionsВывести из метода словарь с результатом выполнения и сообщениеВ конце скрипта создать экземпляр созданного классаfromussl.postprocessing.baseimportBaseFunctionfrommarshmallowimportSchema,fieldsclassInputSchema(Schema):name:str=fields.String(required=True)classNewFunction(BaseFunction):def__init__(self):super().__init__(inputs_model=InputSchema)deffunction(self)->(dict,str):...result_key=self.input_json.get('name')return{"reslut_key":result_key},"Успешно"defvalidate_input(self,input_json:dict):# Валидация входных данных...returninput_jsondefvalidate_secrets(self,secrets:dict):# Валидация секретов...returnsecretsNewFunction()