Инструмент обнаружения изменений Edge for Private Cloud 4.54.00

Инструмент обнаружения изменений

Мы создали инструмент обнаружения изменений, который позволяет выявлять прокси Apigee, правила, общие потоки и JAR-файлы ресурсов (на уровне прокси, среды или организации), которые могут быть затронуты во время и после перехода на Edge for Private Cloud 4.54.00. Этот инструмент создает отчет, в котором перечислены развернутые прокси, общие потоки и JAR-файлы ресурсов, затронутые изменениями, а также ссылки на руководства и стратегии, относящиеся к этим прокси или общим потокам.

Требования

  1. Для запуска этого инструмента требуется компьютер с RHEL или Rocky Linux (см. требования к установке Edge).
  2. На хост-компьютере должна быть установлена и правильно настроена JRE 8 или более поздней версии, чтобы скрипты инструмента могли выполняться.
  3. Для работы инструмента требуется сетевой доступ к конечной точке (URL) сервера управления и действительные учетные данные администратора для аутентификации и получения данных.
  4. Инструменту требуется доступ к рабочей папке (например, /tmp) с достаточным объемом дискового пространства и разрешениями на чтение и запись, чтобы скачивать пакеты, создавать журналы и сохранять выходные данные.
  5. (Необязательно) При обновлении с версии 4.53.00 инструменту требуется LDIF-файл, созданный с помощью команды ldapsearch в разделе Изменение OpenLDAP – извлечение данных LDAP, чтобы обнаружить длинные RDN, превышающие 241 символ/байт.

Запуск инструмента

После выполнения всех предварительных требований скачайте инструмент из репозитория Apigee, используя свои учетные данные Apigee, и распакуйте скачанный архив:

curl -u uName:pWord https://software.apigee.com/apigee/change-detector/change-detector-for-4.54.00_1.0.0.zip -o /tmp/change-detector-for-4.54.00_1.0.0.zip
 
unzip /tmp/change-detector-for-4.54.00_1.0.0.zip

После завершения скачивания вы можете выполнить следующую команду, чтобы посмотреть все доступные варианты инструмента:

./change-detector --help

Чтобы запустить инструмент, используйте следующую команду, заменив плейсхолдеры своими данными:

export APIGEE_PASSWORD=YOUR_PASSWORD
./change-detector --username YOUR_USERNAME --mgmt-url MGMT_URL --source-version SOURCE_VERSION

Укажите --source-version 4.53.01 при обновлении непосредственно с Edge for Private Cloud 4.53.01, чтобы проверить изменения Java 21. Если вы переходите с версии 4.53.00, укажите --source-version 4.53.00, чтобы выполнить накопительное сканирование, охватывающее как устаревшие правила версии 4.53.01, так и изменения в Java 21.

Инструмент генерирует выходные данные в формате CSV или JSON, которые можно просмотреть напрямую или импортировать в приложения для работы с электронными таблицами, например в Google Таблицы.

Как интерпретировать результаты работы инструмента

В отчете содержатся следующие столбцы:

Организация

Название организации, в которой находится артефакт. Для OpenLDAP это None.

Среда

Определенная среда (например, dev, test, prod) в организации. Для JAR на уровне организации это поле имеет значение N/A. Для OpenLDAP это None.

Название прокси-сервера

Название прокси-сервера API или общего потока. Для ресурсов JAR на уровне организации здесь отображается название организации. Для ресурсов JAR на уровне среды отображается название среды. Для изменений OpenLDAP в этом поле показывается объект LDAP относительного отличительного имени.

Область действия

Указывает область действия и уровень отсканированного артефакта:

  • proxy-level-jar: файл ресурса JAR, загруженный на уровне прокси-сервера (в разделе /resources/java).
  • env-level-jar – JAR-файл ресурсов, загруженный на уровне среды (см. раздел Файлы ресурсов).
  • org-level-jar – файл ресурсов JAR, загруженный на уровне организации.
  • proxy – правило или конфигурация в версии прокси-сервера API.
  • sharedflow – правило или конфигурация в версии общего потока.
  • ldif – LDIF-файл OpenLDAP (для проверок OpenLDAP).

Версия

Номер версии прокси-сервера API или общего потока. Для JAR-файлов на уровне среды или организации это поле имеет значение N/A. Для изменений OpenLDAP это None.

Название политики

Название определенных правил, которые могут быть проблемой (например, JavaCallout-ValidateAccount или OASValidation-1). Для ресурсов уровня организации в этом поле отображается значение N/A (Organization Resource). Для ресурсов на уровне среды в этом поле отображается значение N/A (Environment Resource). Для OpenLDAP это None.

Тип политики

Тип правила (например, java-callout или OASValidation). Для изменений OpenLDAP это None.

Версия источника

Исходная версия OPDK, настроенная для сканирования (4.53.00 или 4.53.01).

Затронутый ресурс

Описывает обнаруженный ресурс или библиотеку:

  • Для обнаружения вызовов Java 21: точное название затронутого JAR-файла (например, order-transform.jar или corba-callout.jar).
  • Прекращение поддержки устаревших функций в версии 4.53: deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR.
  • Для обнаружений OAS, JSONPath или OpenLDAP: определенный элемент политики или ресурс (например, oas content type handling, wildcard expression или LDAP RDN exceeds 241 characters).

Причина обнаружения

Предоставляет подробную диагностическую информацию о том, почему товар был помечен:

  • Для вызовов Java 21: конкретный класс, целевая библиотека замены (если применимо) и основная причина (например, Class: javax.xml.bind.JAXBContext | Target Library: jakarta.xml.bind-api-2.3.3.jar | Root Cause: ClassNotFoundException: JAXB API was removed from Java SE in Java 11 (JEP 320)). Если в одном JAR-файле обнаружено несколько проблем, они объединяются и разделяются символом ;.
  • Для устаревших функций версии 4.53: список классов, на которые ссылаются устаревшие библиотеки (например, ['Detected use of class CLASS_NAME from JAR_NAME']).
  • Для проверок OAS: переменная, указанная в теге Source (например, Source=response).
  • Для JSONPath: точное выражение, которое было помечено.
  • Для OpenLDAP: RDN определенного объекта LDAP, превышающий 241 байт или символ.

Достоверность влияния

В этом поле указана степень уверенности, с которой инструмент определил блокировщик обновления. Значения стандартизированы и пишутся заглавными буквами:

  • HIGH. Инструмент обнаружил несовместимое изменение, например вызов навсегда удаленного класса, такого как javax.xml.bind.JAXBContext или sun.misc.BASE64Encoder, или относительное отличительное имя OpenLDAP, превышающее 241 байт. Если не устранить проблему, то с высокой вероятностью произойдет сбой во время выполнения (ClassNotFoundException или NoClassDefFoundError).
  • MEDIUM – инструмент обнаружил шаблон, требующий проверки разработчиком и функциональной проверки:
    • Для вызовов Java: помечаются как METHOD_SIGNATURE_MODIFICATION (например, org.w3c.dom.Document), если класс существует в Java 21, но определенные методы могли быть изменены или объявлены устаревшими.
    • Для правил OASValidation: помечается, когда динамические переменные среды выполнения используются в элементе <Source> (например, Source=response), что требует записи трассировки для наблюдения за разрешенными переменными во время выполнения прокси-сервера.

Примеры отчетов об обнаружении

Отчет о целевом сканировании Java 21 (--source-version 4.53.01)

В примере ниже показан отчет об обновлении с версии OPDK 4.53.01 до 4.54.00:

Организация Среда Название прокси-сервера Область действия Версия Название политики Тип политики Версия источника Затронутый ресурс Причина обнаружения Достоверность влияния
my-org prod order-processing proxy-level-jar 12 JavaCallout-ParseXml java-callout 4.53.01 jaxb-callout.jar Class: javax.xml.bind.JAXBContext | Cause: ClassNotFoundException..... HIGH
my-org stage legacy-corba-bridge proxy-level-jar 1 JavaCallout-CorbaClient java-callout 4.53.01 corba-callout.jar Class: org.omg.CORBA.ORB | Cause: ClassNotFoundException..... HIGH
my-org prod prod env-level-jar N/A N/A (Environment Resource) java-callout 4.53.01 env-security-utils.jar Class: sun.misc.BASE64Encoder | Cause: ClassNotFoundException..... HIGH
my-org N/A my-org org-level-jar N/A N/A (Organization Resource) java-callout 4.53.01 cglib-nodep-2.2.jar Class: net.sf.cglib.proxy.Enhancer | Cause: IllegalArgumentException..... HIGH
my-org prod invoice-parser proxy-level-jar 5 JavaCallout-ParseInvoice java-callout 4.53.01 invoice-dom.jar Class: org.w3c.dom.Document | Cause: Modified methods in Java 21..... MEDIUM
my-org prod payment-gateway proxy-level-jar 3 JavaCallout-SignToken java-callout 4.53.01 payment-lib.jar Class: com.mycompany.crypto.OldProvider | Target: custom-crypto-3.0.jar..... HIGH

Отчет о накопительном сканировании (--source-version 4.53.00)

В примере ниже показан отчет об обновлении с версии OPDK 4.53.00 до 4.54.00:

Организация Среда Название прокси-сервера Область действия Версия Название политики Тип политики Версия источника Затронутый ресурс Причина обнаружения Достоверность влияния
my-org prod customer-portal proxy 3 ValidateOpenAPISpec OASValidation 4.53.00 oas content type handling Source=response MEDIUM
my-org prod accounts-api proxy-level-jar 4 JavaCallout-ValidateAccount java-callout 4.53.00 deprecated: custom-validator.jar..... ['Detected use of class org.apache.commons.beanutils.....'] HIGH
my-org prod order-processing proxy-level-jar 12 JavaCallout-ParseXml java-callout 4.53.00 jaxb-callout.jar Class: javax.xml.bind.JAXBContext | Cause: ClassNotFoundException..... HIGH
my-org None None ldif None None None 4.53.00 LDAP RDN exceeds 241 characters cn=very-long-rdn-name-exceeding-limit..... HIGH

Чтобы узнать, как устранить выявленные проблемы, ознакомьтесь со статьей Стратегии исправления.