Skip to content

ExceptionsπŸ”—

Exceptions are used to exclude unwanted information. When an exception is enabled, the identified call will not appear in the dashboard and reports. To preserve the integrity of the cryptographic data, it’s necessary to create an exception that removes only unwanted calls.

Note

To improve system performance and minimize unexpected results, changes in project exceptions only apply to new or updated Java and OpenSSL analyses. Existing analyses will reflect the exceptions that were set when the analysis was originally created.

Once you’ve identified a call to the cryptography library that you don’t want to appear in future results, you may ask yourself:

  • Is this the only call that we want to exclude?
  • Alternatively, are there a group of similar nearby calls?
  • Or would we like to exclude the whole package?

Exceptions best practicesπŸ”—

Here are some best practices to follow when setting an exception:

  • Exceptions should be as specific as possible to avoid removing any calls other than those identified for exclusion.
  • Including both a fully-qualified class name and a method name will reduce the chances of accidentally removing other code.
  • If you want to remove multiple methods from a class, consider adding multiple exceptions rather than excluding the entire class.
  • If you want to remove an entire module, make sure to use its fully-qualified name to avoid accidentally removing other modules.
  • Note that exclusions are only applied as prefixes to the fully qualified class name. For example, Does not contain mypackage.MyClass won’t match (and so won’t exclude) org.mypackage.MyClass.
  • While the Contains term type can be useful to restrict your project to a certain package, Does not contain exceptions are often better for targeting specific portions of your code.
  • You should generally avoid applying Does not contain exceptions to inbuilt Java functions, as this is highly likely to obscure other valid results.
Exception examplesπŸ”—
  • The exception Does not contain javax.crypto.Cipher is not a good exception, as it will remove all calls to ciphers from your reports.
  • The exception Does not contain toString is not a good exception, as it’s highly likely to unintentionally remove other calls.
  • The exception Does not contain org.myorg.mypackage.MyClass.myMethod is a good exception. It’s very unlikely to unintentionally remove calls.

Combining multiple exceptionsπŸ”—

If multiple exceptions are configured, they’re all applied at the same time. This is best demonstrated through examples.

ExampleπŸ”—

Consider a project that has three exceptions configured:

  1. Contains: company.an_interesting_package
  2. Does not contain: company.an_interesting_package.ABoringClass
  3. Does not contain: company.an_interesting_package.AnInterestingClass.a_boring_method

Let’s see how the exceptions work in different scenarios.

Scenario 1πŸ”—

Scenario 1 has 2 calls:

  1. A call from: company.an_interesting_package.Class1.an_interesting_method
  2. A call from: company.a_boring_package.Class2.method1

This instance will be unaffected by either of the Does not contain exceptions, but call 2 will be removed by the Contains exception, as company.an_interesting_package doesn’t appear in the stack trace.

Since some calls are unaffected by the exceptions, the instance will be reported.

Scenario 2πŸ”—

Scenario 2 also has 2 calls:

  1. A call from company.an_interesting_package.ABoringClass.method2
  2. A call from company.an_interesting_package.AnInterestingClass.a_boring_method

This instance will be unaffected by the Contains exception, but call 1 will be removed by the second exception and call 2 will be removed by the third exception.

Since there no calls are left once the exceptions have been applied, the instance will be excluded.