Reachability Analysis with Jenkins

Minimal Configuration

The example below shows using the Reachability Analysis with minimal configuration.

reachability: [
  javaAnalysis: [
    enable: true
  ]
]

Selection of Namespaces

Select the methods that should be considered as entry points (points in code where execution begins) for the analysis.

Namespaces are specified at the level of packages. All packages nested under a namespace are considered for entry point selection. If multiple namespaces are specified, all of them will be included.

Reachability Analysis will start with the namespaces specified and subsequently analyze all others in the execution path.

Example:

Consider the following project structure:

	src
	|—main
	|	|—java
	|	|	|—com
	|	|	|	|—example
	|	|	|	|	|—iq
	|	|	|	|	|	|—domain
	|	|	|	|	|	|	|—DomainClassOne.java
	|	|	|	|	|	|—application
	|	|	|	|	|	|—repository
	|	|	|	|	|—wrappers
	|	|	|	|	|	|—OktaLoginWrapper.java
	|	|	|	|	|—configs
	|—test
	|	|—java
	|	|	|—com
	|	|	|	|—example
	|	|	|	|	|—iq
	|	|	|	|	|	|—domain
	|	|	|	|	|	|	|—DomainClassOne.java
	|	|	|	|	|	|—application
	|	|	|	|	|	|—repository
	|	|	|	|	|—wrappers
	|	|	|	|	|	|—OktaLoginWrapper.java
	|	|	|	|	|—configs

The Reachability Analysis feature is configured as follows:

reachability: [
  javaAnalysis: [
    enable: true,
    entrypointStrategy: 'ACCESSIBLE_CONCRETE',
    namespaces: [
      [namespace: 'com.example.iq']
    ]
  ]
]

In the example above, the namespaces property specifies the namespace 'com.example.iq', which will be considered as the entry point for the analysis. This namespace has domain, application, and repository packages under its scope. Methods belonging to DomainClassOne.java class (under the domain package in the 'com.example.iq' namespace) will be analyzed before other methods in the package classes. Similarly, methods belonging to classes under other applications and repository packages will be analyzed at the start of the analysis for the package.

Packages of type wrappers, with namespace 'com.example.wrappers' and config packages with namespace 'com.example.configs' will be omitted when an entry point for the analysis is being established. Similarly, methods belonging to the OktaLoginWrapper class with namespace 'com.example.wrappers.OktaLoginWrapper.java' will be omitted when establishing an entry point.

Notes:

Using the Parameter Includes

Multi-module projects could have several .jar files when built. Many of these .jar files are dependencies of another .jar file, which could be the one containing the main application. By specifying the path to this specific .jar when running reachability analysis, you can avoid multiple evaluations of the same .jar files, which would occur when:

The includes parameter specifies a target path for the artifacts to be analyzed. It limits the scope of the analysis, resulting in better precision and reducing the utilization of system resources.

Example:

reachability: [
  javaAnalysis: [
    enable: true,
    entrypointStrategy: 'ACCESSIBLE_CONCRETE',
    includes: [
      // NOTE: 'target' here is just an example (Maven default). Adjust the pattern so it matches
      // your application binary and its dependencies (i.e. jar, war, ear files).
      [pattern: 'target/**/*.jar']
    ]
  ]
]

If includes is omitted, the target location for the analysis will be the same as specified in the iqScanPatterns of the nexusPolicyEvaluation in the Jenkins file. This may increase the scope of the target analysis, leading to reduced precision.

Entrypoint Strategy

When Reachability Analysis is enabled in Jenkins, you can choose one of the following strategies:

JAVA_MAIN:Selects all methods matching public static void main(String[] args)

PUBLIC_CONCRETE: Selects public non-abstract/synthetic methods from non-interface/annotation classes

ACCESSIBLE_CONCRETE: Selects public/protected non-abstract/synthetic methods from non-interface/annotation classes.

CONCRETE: Selects all non-abstract/synthetic methods from non-interface/annotation classes. This is the default entrypoint strategy.

ALL: Selects all methods from all non-interface/annotation classes.

You can enable the Reachability Analysis feature with the minimal configuration as below:

Example:

The example below shows how to enable the Reachability Analysis feature with the ACCESSIBLE_CONCRETE strategy.

reachability: [
  javaAnalysis: [
    enable: true,
    entrypointStrategy: 'ACCESSIBLE_CONCRETE'
  ]
]

Analysis Algorithm

These are the supported algorithms for Java reachability analysis:

Node.js Executable

Reachability Analysis requires a Node.js executable (v16+) on the pipeline’s PATH. This could be achieved via the Jenkins NodeJS plugin, which allow multiple versions to be configured as global tools in Jenkins. If no Node executable is on the pipeline's PATH, an absolute path can be explicitly specified as below:

reachability: [
  jsAnalysis: [
    enable: true,
    node: [
      executable: '/path/to/node/exec' // absolute path expected; may include env. vars. e.g. "${env.WORKSPACE}/path/to/node"
    ],
    sourceFiles: [
      [pattern: 'src/**/*']
    ]
  ]
]

File Exclusion

If your project contains other JavaScript files (e.g. tests) that shouldn’t be included in Reachability Analysis, they can be excluded in the same way as sourceFiles, via an excludeFiles section:

reachability: [
  jsAnalysis: [
    enable: true,
    sourceFiles: [
      [pattern: 'src/**/*']
    ],
    excludeFiles: [
      [pattern: 'test/**/*']
    ]
  ]
]

Project Directory

By default, reachability analysis considers the workspace root where package.json lives as the project directory. If your source lives elsewhere, set projectDirectory relative to the workspace:

reachability: [
  jsAnalysis: [
    enable: true,
    projectDirectory: 'app/root',   // relative to the workspace directory
    sourceFiles: [
      [pattern: 'src/**/*']
    ]
  ]
]