Edge for Private Cloud 4.54.00 Change Detection Tool

Change detection tool

A change detection tool has been built to identify Apigee proxies, policies, shared flows, and resource JARs (at the proxy, environment, or organization level) that may be impacted during and after the transition to Edge for Private Cloud 4.54.00. This tool generates a report detailing deployed proxies, shared flows, and resource JARs affected by the changes and provides direction to specific guides and strategies relevant to those identified proxies or shared flows.

Warning: Testing in lower environments is critical:

Java callouts are custom proprietary Java code that belong to you, which execute as part of the larger API proxy. While the change detection tool has been made available, and should cover a variety of scenarios, it has some key limitations:

The tool cannot detect dynamic runtime behavior such as reflection or dynamically loaded libraries.
The tool may not be able to detect issues in completely proprietary libraries or code that you have created or are using.

Additionally, a proxy containing Java Callouts may successfully deploy in the newer version of Edge for Private Cloud but may exhibit failures only when executing as part of processing an API.

Because of these limitations, it is critical that you thoroughly test all your Java Callout-based proxies in lower environments before applying upgrades to production. When testing in lower environments, in addition to deploying such proxies, send API traffic through such proxies to validate that your Java Callout is indeed executing with Apigee running on Java 21.

Prerequisites

An RHEL-based or Rocky Linux machine is required to run this tool (see Edge installation requirements).
JRE 8 or higher must be installed and correctly configured on the host machine to allow the tool's scripts to run.
The tool requires network access to the endpoint (URL) of the Management Server and valid administrative credentials for authentication and data retrieval.
The tool requires access to a designated working directory (for example, /tmp) with sufficient disk space and appropriate read/write permissions for downloading bundles, generating logs, and storing output.
(Optional) When upgrading from version 4.53.00, the tool requires an LDIF file generated using the ldapsearch command in the OpenLDAP change - Extract LDAP data section to detect long RDNs exceeding 241 characters/bytes.

Running the tool

After all prerequisites are met, download the tool from the Apigee repository using your Apigee credentials, and extract the downloaded archive:

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

Once the download is complete, you can run the following command to see all available options for the tool:

./change-detector --help

To run the tool, use the following command and replace the placeholders with your information:

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

Specify --source-version 4.53.01 when upgrading directly from Edge for Private Cloud 4.53.01 to scan for Java 21 changes. If upgrading from version 4.53.00, specify --source-version 4.53.00 to perform a cumulative scan covering both version 4.53.01 policy deprecations and Java 21 changes.

The tool generates output in CSV or JSON format that can be directly reviewed or imported into spreadsheet applications such as Google Sheets.

Understand the tool output

The report contains the following columns:

Organization

The name of the organization where the artifact is located. For OpenLDAP changes, this is None.

Environment

The specific environment (for example, dev, test, prod) within the organization. For organization-level JARs, this field is N/A. For OpenLDAP changes, this is None.

Proxy Name

The name of the API proxy or shared flow. For organization-level JAR resources, this displays the organization name. For environment-level JAR resources, this displays the environment name. For OpenLDAP changes, this field shows the LDAP entity of the RDN.

Scope

Specifies the scope and level of the scanned artifact:

proxy-level-jar: JAR resource file uploaded at the proxy level (under /resources/java).
env-level-jar: JAR resource file uploaded at the environment level (see Resource files).
org-level-jar: JAR resource file uploaded at the organization level.
proxy: Policy or configuration within an API proxy revision.
sharedflow: Policy or configuration within a shared flow revision.
ldif: OpenLDAP LDIF file (for OpenLDAP checks).

Revision

The specific revision number of the API proxy or shared flow. For environment- or organization-level JARs, this field is N/A. For OpenLDAP changes, this is None.

Policy Name

The name of the specific policy that has been identified as a potential issue (for example, JavaCallout-ValidateAccount or OASValidation-1). For organization-level resources, this field displays N/A (Organization Resource). For environment-level resources, this field displays N/A (Environment Resource). For OpenLDAP changes, this is None.

Policy Type

The type of policy (for example, java-callout or OASValidation). For OpenLDAP changes, this is None.

Source Version

The source OPDK version configured for the scan (4.53.00 or 4.53.01).

Impacted Resource

Describes the specific resource or library detected:

For Java 21 callout detections: The exact name of the impacted JAR file (for example, order-transform.jar or corba-callout.jar).
For legacy 4.53 deprecations: deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR.
For OAS, JSONPath, or OpenLDAP detections: The specific policy element or resource (for example, oas content type handling, wildcard expression, or LDAP RDN exceeds 241 characters).

Reason for Detection

Provides detailed diagnostic information about why the item was flagged:

For Java 21 callout detections: The specific class, target replacement library (if applicable), and root cause (for example, 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)). If multiple issues are detected within the same JAR, they are consolidated separated by ;.
For legacy 4.53 deprecations: A list of referenced classes from deprecated libraries (for example, ['Detected use of class CLASS_NAME from JAR_NAME']).
For OAS validations: The variable specified in the Source tag (for example, Source=response).
For JSONPath: The exact expression flagged.
For OpenLDAP: The specific LDAP entity's RDN that exceeded 241 bytes or characters.

Impact Certainty

This field indicates the degree of confidence with which the tool has identified an upgrade blocker. Values are standardized in uppercase:

HIGH: The tool has detected an incompatible change (such as a call to a permanently removed class like javax.xml.bind.JAXBContext or sun.misc.BASE64Encoder, or an OpenLDAP RDN exceeding 241 bytes). There is near-certain probability of runtime failure (ClassNotFoundException or NoClassDefFoundError) unless remediated.
MEDIUM: The tool has detected a pattern requiring developer inspection and functional verification:
- For Java Callouts: Flagged under METHOD_SIGNATURE_MODIFICATION (for example, org.w3c.dom.Document), where the class exists in Java 21 but specific methods may have been altered or deprecated.
- For OASValidation policies: Flagged when dynamic runtime variables are used in the <Source> element (for example, Source=response), which requires capturing Trace to observe resolved variables during proxy execution.

Sample detection reports

Targeted Java 21 scan report (`--source-version 4.53.01`)

The following sample illustrates report output for an upgrade from OPDK 4.53.01 to 4.54.00:

Organization	Environment	Proxy Name	Scope	Revision	Policy Name	Policy Type	Source Version	Impacted Resource	Reason for detection	Impact Certainty
`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`

Cumulative scan report (`--source-version 4.53.00`)

The following sample illustrates report output for an upgrade from OPDK 4.53.00 to 4.54.00:

Organization	Environment	Proxy Name	Scope	Revision	Policy Name	Policy Type	Source Version	Impacted Resource	Reason for detection	Impact Certainty
`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`

For guidance on remediating identified issues, see Remediation strategies.