JVMXRay: Java Application Security Monitoring

Documentation | Changes from Upstream | Project Blog

JVMXRay monitors Java applications in real-time via bytecode injection, detecting vulnerabilities and suspicious activity without code changes. 19 modular sensors track file access, network connections, SQL queries, cryptographic operations, authentication, process execution, and more — generating structured, machine-readable security events with automatic cross-sensor correlation.

Quick Start

git clone https://github.com/spoofzu/jvmxray.git
cd jvmxray
mvn clean install

During Maven's test phase a small program called Turtle runs under the freshly built JVMXRay agent. Turtle performs file I/O, cryptography, process execution, serialization, reflection, and other activities that trigger the sensors — so a successful build already gives you real security event logs to explore in ./target/test-jvmxray/. A SQLite database is also created at ./target/test-jvmxray/common/data/jvmxray-test.db for quick experimentation. See the docs for further details.

Deploy as a Java agent in your own applications:

java -javaagent:target/jvmxray-0.0.1-agent.jar -jar yourapp.jar

Benefits

Zero code changes — Attaches to any Java application at launch, like a debugger. No source modifications, no recompilation, no library dependencies to add.
AI-ready structured events — Sensors generate machine-readable security events, not unstructured log lines. Use your AI tools to analyze application behavior like you application logs.
Fits your logging infrastructure — Events are Logback log messages. Route them to Splunk, ELK, DataDog, Kafka, or any destination the Logback ecosystem supports.
Attack chain reconstruction — Correlated events with trace_id and scope_chain let SOC teams trace an incident from HTTP request through SQL injection to data exfiltration in a single query.
Tunable overhead — Standard Logback log-level properties control which sensors fire and at what verbosity. Turn sensors on or off per environment without rebuilding.

Keep in mind, JVMXRay is a source of truth for what a Java application is doing, not an analysis engine. Analysis is provided by your centralized logging solution and/or your AI tooling projects.

Sensors

Event Correlation

Every sensor event includes correlation fields for reconstructing attack chains:

A scope chain like HTTP>Serialization>Reflection>Process is a deserialization attack signature at a glance. The TRACE_ID column is indexed in the database for fast correlation queries.

Architecture

java -javaagent:jvmxray-agent.jar -jar app.jar
         |
    AgentBootstrap (isolated classloader)
         |
    ByteBuddy installs sensor interceptors
         |
    Sensors fire on method entry/exit
         |
    LogProxy merges MCC correlation context
         |
    +----------+----------+----------+
    | SQLite   | File     | Socket   |
    | Appender | Appender | Appender |
    +----------+----------+----------+

Java 17, ByteBuddy 1.14.17 for bytecode injection
Logback + SLF4J for enterprise logging (Splunk, ELK, DataDog compatible)
Multi-database: SQLite (dev), MySQL, Cassandra (production)
MCC (Mapped Correlation Context): thread-local scope tracking with TTL cleanup

Documentation

Agent Reference — Sensor configuration, event fields, database schema
Common Components — Database setup and utilities
Changelog — Detailed release changes
News Archive — Project history

Acknowledgements

This project was developed using ideas, architecture, and code in some cases from the following,

Claude Code CLI by Anthropic, Anthropic
Byte-code architecture based in part from ideas by Terse Systems, Terse Systems
Logback logging framework by QOS.ch Sarl Sweitzerland, QOS.ch
Apache Software Foundation, Apache Software Foundation

Contributor(s)

Milton Smith — Project creator, leader

Disclosure: JVMXRay is not approved, endorsed by, or affiliated with Oracle Corporation.

File I/O	File reads, writes, deletes, permissions, symlinks with path resolution and aggregate I/O stats
Network	Socket connect/accept/bind/close with TLS detection, private IP classification, timing
SQL	Query capture with parameterization detection, operation type, duration, connection metadata
HTTP	Request/response with security header analysis, user/session correlation
Process	ProcessBuilder.start() and Runtime.exec() with command args, duration, exit status
Crypto	Cipher/KeyStore/MessageDigest/SSL with weak algorithm detection and key strength validation
Authentication	Session operations, JAAS login, Spring Security authenticate, principal queries with success/failure tracking
API Call	HttpClient.send() with URI, method, host, TLS, response status, timing
Script Engine	ScriptEngine.eval() with engine identification, content hashing, suspicious pattern detection, risk level
Serialization	Java native, Jackson, Gson, XStream deserialization with gadget chain detection
Reflection	Class.forName, Method.invoke, Field access, setAccessible with threat classification
Configuration	System properties, env vars, Properties files, Preferences with security annotations
Library	Static and dynamic JAR loading with SHA-256, Maven coordinates, package inventory
Monitor	JVM health: memory, threads, GC, CPU, open files, deadlock detection (60s interval)
Uncaught Exception	Crash diagnostics: full stack, memory state, thread dump, cause chain, incident ID
App Init	One-time startup capture: JVM version, OS, container detection, env vars (redacted)
Data Transfer	InputStream.read() byte counting (currently disabled — too broad)
Thread	Thread lifecycle monitoring (currently disabled — recursive logging fix needed)
Memory	Memory allocation tracking (currently disabled — recursive logging fix needed)

`trace_id`	`a1b2c3d4e5f6`	Links all events in the same execution context
`scope_chain`	`HTTP>SQL>FileIO`	Nested sensor path — the "security stacktrace"
`parent_scope`	`SQL`	Immediate parent for tree reconstruction
`scope_depth`	`3`	Nesting level — depth 6+ warrants investigation

jvmxray

Most Popular