sota-jvm

name

sota-jvm

description

State-of-the-art JVM engineering rules (2026 baseline) for Java and Kotlin that Claude applies when writing or auditing JVM code. Baseline Java 25 LTS (virtual threads final since 21; structured concurrency still preview), Kotlin 2.x. Covers modern idioms (records, sealed types, pattern matching, Kotlin null-safety/coroutines), API/null/immutability design, concurrency (virtual threads, JMM, java.util.concurrent, coroutines), security (deserialization/gadget chains, XXE, JNDI/Log4Shell-class, injection, JCA crypto; SEI CERT Oracle Java + OWASP), performance (G1/ZGC, JFR, GraalVM), and build/tooling/CI (Maven/Gradle, dependency-check, Error Prone/NullAway, SpotBugs, ktlint/detekt). Trigger keywords - Java, Kotlin, JVM, JDK, Spring, record, sealed, virtual thread, Loom, coroutine, suspend, ObjectInputStream, deserialization, XXE, JNDI, Log4Shell, Maven, Gradle, G1, ZGC, GraalVM, JMH, Optional, null-safety. Use for BOTH building JVM services/libraries and reviewing or auditing them.

SOTA JVM — Java & Kotlin (2026)

Expert-level rules for producing and auditing production JVM code. The JVM is memory-safe (no buffer overflows/UAF), so the risk shifts to deserialization and injection RCE, concurrency correctness, and dependency supply chain. Baseline: Java 25 LTS (records, sealed types, pattern matching, virtual threads finalized in 21 via JEP 444; scoped values finalized in 25 via JEP 506; structured concurrency is still preview — JEP 505 in 25 — don't present it as final), Kotlin 2.x. Per-language idioms differ; shared concerns (the JMM, the JCA, the build/ supply-chain story) are unified here. Every rule states the why; every rules file ends with an audit checklist of grep/analyzer patterns.

Purpose

Two consumers, one source of truth:

• BUILD mode — generating Java/Kotlin: follow the rules as defaults. Prefer immutability, null-safety, and the standard concurrency primitives. Deviate only with a comment justifying it.
• AUDIT mode — reviewing existing code: hunt violations with the audit checklists, classify by severity, report in the finding format below. Deserialization of untrusted data and string-built queries are presumed exploitable.

BUILD mode

1. Before writing, read the rules files relevant to the task (see index). A web service handling untrusted input + threads + a DB needs 02, 03, 04.
2. Apply the top-10 non-negotiables (below) unconditionally.
3. New projects: target the current LTS (Java 25), Maven or Gradle with a lockfile, Error Prone + NullAway (Java) or detekt + ktlint (Kotlin), SpotBugs/Find-Sec-Bugs, OWASP dependency-check/OSV-Scanner, and CI running all of it from day one (rules/06).
4. Prefer immutability (records, final, Kotlin val/data class, unmodifiable collections) and the type system (sealed hierarchies, no raw types, Optional/Kotlin nullable types) over runtime checks.
5. Never let untrusted bytes reach a deserializer, an XML parser with DTDs on, a JNDI lookup, or a string-built query/EL expression (rules/04).
6. When you must use a sharp tool (reflection, ObjectInputStream, Unsafe, a @SuppressWarnings), leave a // NOTE(sota): comment explaining why and what bounds it.

AUDIT mode

Work each relevant rules file's audit checklist against the target. Run the greps and analyzers (SpotBugs/Find-Sec-Bugs, Error Prone, detekt); confirm hits manually. Check the dependency tree against known-CVE databases.

Severity conventions

Severity	Meaning	Examples
CRITICAL	Exploitable on reachable input	ObjectInputStream.readObject on untrusted data, JNDI lookup of attacker URL (Log4Shell), SpEL/OGNL/ScriptEngine eval of input, SQL via string concat, XXE with DTD enabled
HIGH	Likely incident or security weakness	Runtime.exec/ProcessBuilder with a shell + interpolation, missing TLS verification, MessageDigest MD5/SHA-1 or Cipher ECB/DES for security, SecureRandom seeded predictably, synchronized+blocking pinning a carrier thread under load (JDK 21–23 only; fixed in 24+ via JEP 491)
MEDIUM	Correctness/maintainability hazard	Data race on shared mutable state, equals without hashCode, mutable static state, swallowed exceptions, Kotlin platform-type NPE, resource not in try-with-resources/use
LOW	Idiom/perf debt	Mutable collections returned from APIs, raw types, Optional fields/params, needless boxing on hot path, synchronized where j.u.c fits
INFO	Style/doc/hygiene	Formatting, naming, missing @Override/@Nullable annotations

Finding format

[SEVERITY] File.java:LINE — short title
  Rule: rules/NN-name.md § section
  Evidence: the offending line(s), verbatim
  Impact: one sentence — what executes/leaks/races, under what input
  Fix: concrete replacement code or action
  Effort: trivial | small | medium | large

Group findings by severity, CRITICAL first. End with: counts per severity, the three highest-leverage fixes, and which checklists/analyzers were run.

Rules index

File	Read this when...
rules/01-idioms.md	Writing/reviewing any Java/Kotlin: records, sealed types, pattern matching, switch expressions, text blocks, var; Kotlin null-safety, data/value classes, when, scope functions, immutability, Java↔Kotlin interop, error handling
rules/02-design-api.md	Designing types/APIs: nullability discipline (Optional, @Nullable, Kotlin types, platform types), immutability, equals/hashCode/toString, exceptions (checked vs unchecked, Kotlin), AutoCloseable/try-with-resources/use, JPMS/package layout, DI
rules/03-concurrency.md	Anything with threads, executors, or shared state: virtual threads and pinning, structured concurrency (preview), ExecutorService, CompletableFuture, the Java Memory Model (volatile/final/happens-before), concurrent collections, Kotlin coroutines/structured concurrency/cancellation
rules/04-security.md	Any input crossing a trust boundary: Java deserialization + gadget chains + serialization filters, XXE, JNDI/LDAP (Log4Shell-class), expression-language/ScriptEngine injection, SQL/Runtime.exec, path traversal, JCA crypto (AES-GCM, SecureRandom, no MD5/ECB), TLS, secrets; SEI CERT Oracle Java + OWASP
rules/05-performance.md	Latency/throughput/memory work: GC choice (G1 default, Generational ZGC for low pause, Parallel for throughput), heap/-Xmx and container awareness, JIT/tiered/-XX basics, JFR + async-profiler, allocation/escape analysis, GraalVM native image trade-offs, JMH benchmarking
rules/06-build-tooling-ci.md	Setting up or auditing build/CI: Maven vs Gradle, dependency locking + supply chain (dependency-check/OSV-Scanner, signing, reproducible builds, SBOM), Error Prone/NullAway, SpotBugs/Find-Sec-Bugs, PMD, ktlint/detekt, spotless, JaCoCo. Test strategy lives in sota-testing; this file owns JVM build/test mechanics (JUnit 5, Testcontainers wiring).

Top-10 non-negotiables

1. Never deserialize untrusted data with Java native serialization. ObjectInputStream.readObject on attacker-controlled bytes is RCE via gadget chains. Use JSON/protobuf with a schema; if unavoidable, apply a strict ObjectInputFilter allowlist (JEP 290). (rules/04)
2. No string-built queries or commands. Parameterized JDBC/JPA only; ProcessBuilder with an argument list and no shell. String concat into SQL/HQL/JPQL/LDAP/OS commands is CRITICAL. (rules/04)
3. XML parsers disable DTDs/external entities; no JNDI lookups or EL/script eval of input. XXE, Log4Shell-class JNDI, and SpEL/OGNL/ScriptEngine injection are CRITICAL. (rules/04)
4. Shared mutable state is correctly synchronized. Respect the JMM: publish via volatile/final/j.u.c; prefer immutability and concurrent collections over hand-rolled locking. A data race is a real bug, not a nondeterministic annoyance. (rules/03)
5. Virtual threads for blocking I/O concurrency (Java 21+); don't pin. On JDK 21–23 synchronized around blocking calls pins the carrier (use ReentrantLock); JDK 24+ removes most pinning (JEP 491). Never pool virtual threads. (rules/03)
6. Resources are closed deterministically — try-with-resources (Java) or use {} (Kotlin) for everything AutoCloseable. A leak on the exception path is the default failure of manual finally. (rules/02)
7. Crypto uses the JCA correctly. AES-GCM (not ECB/CBC-without-MAC), SecureRandom (never Random/Math.random) for keys/tokens/IVs, no MD5/SHA-1 for security, constant-time compare for secrets. Don't roll your own. (rules/04)
8. Null is designed, not hoped. Kotlin: lean on non-null types, guard platform types from Java; Java: Optional for return values (not fields/ params), @Nullable/NullAway to make nullness checked. (rules/01, rules/02)
9. Exceptions are handled or propagated, never swallowed. No empty catch; don't catch Exception/Throwable to hide errors; preserve the cause when wrapping. (rules/01, rules/02)
10. Dependencies are locked, scanned, and minimal. Lockfile committed, OWASP dependency-check/OSV-Scanner gates CI, transitive CVEs triaged, plugins/artifacts from trusted repos. (rules/06)