JCapsLock provides static analysis of Java libraries and their capabilities, but users should understand several important constraints.
False Positives: The analysis assumes all code paths execute, even conditional branches. For example, a method may contain an if statement where Files.readAllBytes is called if one of the method's parameters is true, potentially reporting capabilities that never actually occur.
Reflection Challenges: Use of java.lang.reflect creates analysis difficulties. The tool flags reflection usage as its own capability to avoid missing potential capabilities without notification. In Java, reflection is commonly used by dependency injection frameworks (Spring, Guice) and serialization libraries (Jackson, Gson).
External Program Execution: When code uses Runtime.exec, ProcessBuilder, or loads classes dynamically, the analysis cannot determine what capabilities these might have, so it is reported to the user as a capability of its own.
Unsafe Pointer Operations: Although typically used simply, sun.misc.Unsafe theoretically enables arbitrary behavior. The tool treats this as a reportable capability.
Dynamic Class Loading: Classes loaded via Class.forName or custom classloaders cannot be fully analyzed, so dynamic loading is flagged as a capability.
Native Code: JCapsLock cannot analyze native code called via JNI or JNA, reporting these as CGO capabilities.
Dependency Resolution: Run JCapsLock from your project directory to ensure dependency resolution matches your Maven build. Active profiles and dependency mediation affect which versions are analyzed.
Optional Dependencies: Libraries often declare optional dependencies for features you may not use. Use -Dcapslock.includeOptional=false to exclude them from analysis.
JCapsLock includes an experimental runtime agent that can monitor and block capabilities at runtime. While functional, there are unresolved issues being actively worked on:
Performance Impact: The instrumentation adds overhead to capability-checked methods. The impact varies depending on how frequently these methods are called.
Multithreading: Execution paths can escape enforcement checks in multithreaded scenarios. Thread handoffs and asynchronous callbacks may not be fully traced.
See agent/README.md for current usage and limitations.
- Go Capslock Caveats - Caveats for the original Go implementation