Route coverage

For Assess users, route coverage associates vulnerabilities with the originating web request.

With route coverage, you can see detailed information on the components of your application, such as which routes were exercised and which ones were not. This information can help you decide where to focus testing and remediation.

Web request example

Web requests are the primary interface of web applications. A request may be handled by one function with many subsequent functions coordinating interactions with other services, databases, or files.

During the request handling process, Contrast monitors data flows across the application to identify vulnerabilities. A single web request may be vulnerable to multiple types of attacks. Contrast associates these vulnerabilities with the original request.

This example shows a web request:

GET /users?active=true
Host: YourDomain.com
Accept: application/json

This example shows how a function might handle the web request:

@Controller
public class UserController {
    @GetMapping("/users")
    public String users(@RequestParam(name="active", required=false, defaultValue=true) Bool active) {
        ...
    }
}

How route coverage works

An application route is a combination of three parts:

  • An HTTP verb (for example: GET)

  • The resource path (for example: /users)

  • The method signature of the controller (for example: UserController.users(Bool active))

When a Contrast agent starts, it instruments functions in the application so that the agent can assess web requests for vulnerabilities while the application is running. If a function implements a framework to handle web requests, Contrast can identify the route before a request is handled. In Contrast, the status for these routes is Discovered .

When your application is handling a request, Contrast tracks the activity as an Exercised route.

Frameworks

Contrast supports route discovery for these frameworks:

Note

The Java agent only reports routes from supported frameworks.

To ensure that route coverage data includes discovered routes as well as observed routes, the Java agent also requires the setting -Dcontrast.agent.java.standalone_app_name=<example_name> be defined in the agent configuration file.

If you do not provide a value for this setting, the agent reports data from observed routes only.

Using the standalone_app_name setting results in the agent treating all code in the JVM as part of the application.

You do not need -Dcontrast.agent.java.standalone_app_name=<example_name> if your application is deployed on any of the following servers:

  • Websphere (traditional)

  • jetty

  • Resin

  • Weblogic

  • Tomcat

  • JBoss

If the framework you are using is unsupported, contact Support . For unsupported frameworks, Contrast will attempt to infer the routes based on observed requests, but you will not see any routes discovered within Contrast.

Exclusion of built-in routes and applications

Contrast route coverage excludes built-in routes in select web frameworks and applications. For example:

  • The Jersey framework for Java applications includes a built-in route for serving a WADL file. Contrast does not include this route in its route coverage. Other web frameworks have similar built-in routes.

  • The Contrast Java agent does not report routes from built-in applications such as the Tomcat Manager Application.