Supported Java source code annotations

When using static analysis to scan Java™, @ValidatorMethod, @CallbackMethod, and @SuppressSecurityTrace method-level annotations are supported.

Using annotations

Annotations can be used by following these steps:

  1. Support for annotations is enabled by default. The annotation .jar file is located in the \annotation directory of the extracted SAClientUtil_<version>_<os>.zip file.
  2. If you are scanning precompiled classes, .war files, or .jar files, add \annotation\com.static.analyzer.annotation.jar to the Java project that contains the annotated sources and then rebuild the project.
  3. If you are scanning in an integrated development environment (IDE) that has the static analysis plug-in installed, add \annotation\com.static.analyzer.annotation.jar to the Java class path.
  4. If you are using the static analysis CLI, create a configuration file and, in it, set CustomBuildInfo additional_classpath="dependency_path" so that dependency_path includes the location of the \annotation\com.static.analyzer.annotation.jar file.

Annotations can be added to source code before scanning - or they can be added after scanning and during triage to identify and eliminate false-positives. If you are scanning in an IDE that has the static analysis plug-in installed, a Help Me Fix This button is available in the scan report. When you select this button, you are shown possible points where annotations can be added.

Annotations are provided to allow you to insert your knowledge directly into source code in the form of security annotations. Since annotations may be used to declare portions of code safe, they should be used very carefully. They should not be used for code that should be scanned for security vulnerabilities. If you use annotations, a security analyst can choose to ignore them by disabling the feature in the irgen-engine.apsettings file located in the \config directory of the extracted SAClientUtil_<version>_<os>.zip file. In this file, locate this setting:

<Setting 
  name="process_security_annotations"
  value="true"
  default_value="true"
  description="When turned on, method annotations will be processed - used by DotNet and Java LSPs"
  display_name="Process Security Annotations"
  type="bool"
/>

To disable the feature, change value="true" to value="false".

Note: If the setting is set to value="false", set this to value="true" if you want to use annotations.

@ValidatorMethod

Validators are methods that perform checks on input data and often return a boolean value that indicates if the input is valid or not. Rather than accept or reject input using validators, you can change the user input to an acceptable format. These methods are called sanitizers.

Using the @ValidatorMethod annotation, you can identify all validator and sanitizer methods in the application source code. During static analysis scans, this information will be used to remove data flows that pass through these methods since the data is now considered safe.

Note: Currently, there is no provision to specify which parameters of the annotated method should be considered as validated. During static analysis scans, all input parameters will be assumed to be validated.

@SuppressSecurityTrace

All traces that flow through a method marked with this annotation are removed. This is useful when a certain group of traces are identified as false-positives or less important or interesting than the others. You can use this annotation to filter out these traces or to hide them for the purpose of reducing clutter.

@CallbackMethod

This annotation is used to identify callbacks or entry points to an application. All arguments are considered to be carrying taint.