tessl/maven-net-bytebuddy--byte-buddy-agent

Byte Buddy Agent is a Java instrumentation agent library that provides convenient APIs for attaching Java agents to local or remote virtual machines.

—

Pending

Overview

Eval results

Files

Agent Attachment

Name: tessl/maven-net-bytebuddy--byte-buddy-agent
Author: tessl

Remote attachment capabilities for deploying Java agents to other JVM processes. Supports both JAR-based agents and native agent libraries with flexible process targeting and cross-platform compatibility.

Capabilities

JAR Agent Attachment

Attach Java agent JAR files to remote JVM processes. The agent JAR must contain proper manifest headers and implement the Java agent specification (premain/agentmain methods).

/**
 * Attaches the given agent JAR to the target process. The agent is not provided an argument.
 * @param agentJar The agent jar file
 * @param processId The target process id
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attach(File agentJar, String processId);

/**
 * Attaches the given agent JAR to the target process with an argument.
 * @param agentJar The agent jar file
 * @param processId The target process id
 * @param argument The argument to provide to the agent (may be null)
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attach(File agentJar, String processId, @MaybeNull String argument);

/**
 * Attaches the given agent JAR using a custom attachment provider.
 * @param agentJar The agent jar file
 * @param processId The target process id
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attach(File agentJar, String processId, AttachmentProvider attachmentProvider);

/**
 * Attaches the given agent JAR with argument using a custom attachment provider.
 * @param agentJar The agent jar file
 * @param processId The target process id
 * @param argument The argument to provide to the agent (may be null)
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attach(File agentJar, String processId, @MaybeNull String argument, AttachmentProvider attachmentProvider);

Process Provider Based Attachment

Attach agents using process providers for more flexible process targeting and discovery.

/**
 * Attaches the given agent JAR using a process provider to resolve the target process.
 * @param agentJar The agent jar file
 * @param processProvider A provider of the target process id
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attach(File agentJar, ProcessProvider processProvider);

/**
 * Attaches the given agent JAR with argument using a process provider.
 * @param agentJar The agent jar file
 * @param processProvider A provider of the target process id
 * @param argument The argument to provide to the agent (may be null)
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attach(File agentJar, ProcessProvider processProvider, @MaybeNull String argument);

/**
 * Attaches the given agent JAR using process provider and custom attachment provider.
 * @param agentJar The agent jar file
 * @param processProvider A provider of the target process id
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attach(File agentJar, ProcessProvider processProvider, AttachmentProvider attachmentProvider);

/**
 * Attaches the given agent JAR with all custom options.
 * @param agentJar The agent jar file
 * @param processProvider A provider of the target process id
 * @param argument The argument to provide to the agent (may be null)
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attach(File agentJar, ProcessProvider processProvider, @MaybeNull String argument, AttachmentProvider attachmentProvider);

Native Agent Attachment

Attach native agent libraries to remote JVM processes. Native agents are platform-specific shared libraries that implement the JVMTI interface.

/**
 * Attaches the given native agent library to the target process.
 * @param agentLibrary The agent library
 * @param processId The target process id
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attachNative(File agentLibrary, String processId);

/**
 * Attaches the given native agent library with an argument.
 * @param agentLibrary The agent library
 * @param processId The target process id
 * @param argument The argument to provide to the agent (may be null)
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attachNative(File agentLibrary, String processId, @MaybeNull String argument);

/**
 * Attaches the given native agent library using a custom attachment provider.
 * @param agentLibrary The agent library
 * @param processId The target process id
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attachNative(File agentLibrary, String processId, AttachmentProvider attachmentProvider);

/**
 * Attaches the given native agent library with all options.
 * @param agentLibrary The agent library
 * @param processId The target process id
 * @param argument The argument to provide to the agent (may be null)
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attachNative(File agentLibrary, String processId, @MaybeNull String argument, AttachmentProvider attachmentProvider);

/**
 * Attaches the given native agent library using a process provider to resolve the target process.
 * @param agentLibrary The agent library
 * @param processProvider A provider of the target process id
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attachNative(File agentLibrary, ProcessProvider processProvider);

/**
 * Attaches the given native agent library with argument using a process provider.
 * @param agentLibrary The agent library
 * @param processProvider A provider of the target process id
 * @param argument The argument to provide to the agent (may be null)
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
 */
public static void attachNative(File agentLibrary, ProcessProvider processProvider, @MaybeNull String argument);

/**
 * Attaches the given native agent library using process provider and custom attachment provider.
 * @param agentLibrary The agent library
 * @param processProvider A provider of the target process id
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attachNative(File agentLibrary, ProcessProvider processProvider, AttachmentProvider attachmentProvider);

/**
 * Attaches the given native agent library with all custom options.
 * @param agentLibrary The agent library
 * @param processProvider A provider of the target process id
 * @param argument The argument to provide to the agent (may be null)
 * @param attachmentProvider The attachment provider to use
 * @throws IllegalStateException If attachment fails
 */
public static void attachNative(File agentLibrary, ProcessProvider processProvider, @MaybeNull String argument, AttachmentProvider attachmentProvider);

Usage Examples

Basic JAR Agent Attachment

import net.bytebuddy.agent.ByteBuddyAgent;
import java.io.File;

// Attach agent to a specific process
File agentJar = new File("/path/to/my-agent.jar");
String targetProcessId = "1234";

ByteBuddyAgent.attach(agentJar, targetProcessId);

// Attach with arguments
String agentArgs = "configuration=debug,output=/tmp/agent.log";
ByteBuddyAgent.attach(agentJar, targetProcessId, agentArgs);

Native Agent Attachment

import net.bytebuddy.agent.ByteBuddyAgent;
import java.io.File;

// Attach native agent library (e.g., profiler)
File nativeAgent = new File("/path/to/libprofiler.so");  // Linux
// File nativeAgent = new File("C:\\path\\to\\profiler.dll");  // Windows

String targetProcessId = "5678";
ByteBuddyAgent.attachNative(nativeAgent, targetProcessId);

// With configuration arguments
String profilerConfig = "sampling-rate=100,output-file=profile.log";
ByteBuddyAgent.attachNative(nativeAgent, targetProcessId, profilerConfig);

Custom Attachment Provider

import net.bytebuddy.agent.ByteBuddyAgent;
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
import java.io.File;

// Use specific attachment mechanism
File agentJar = new File("my-agent.jar");
String processId = "9999";

// Force use of JNA-based attachment
AttachmentProvider jnaProvider = AttachmentProvider.ForEmulatedAttachment.INSTANCE;
ByteBuddyAgent.attach(agentJar, processId, jnaProvider);

// Create custom provider chain
AttachmentProvider customProvider = new AttachmentProvider.Compound(
    AttachmentProvider.ForModularizedVm.INSTANCE,  // Try Java 9+ first
    AttachmentProvider.ForJ9Vm.INSTANCE,           // Then IBM J9
    AttachmentProvider.ForEmulatedAttachment.INSTANCE  // Finally JNA fallback
);
ByteBuddyAgent.attach(agentJar, processId, customProvider);

Process Discovery and Attachment

import net.bytebuddy.agent.ByteBuddyAgent;
import net.bytebuddy.agent.ByteBuddyAgent.ProcessProvider;
import java.io.File;
import java.lang.management.ManagementFactory;

// Get current process ID for self-attachment
ProcessProvider currentProcess = ProcessProvider.ForCurrentVm.INSTANCE;
File agentJar = new File("self-modifying-agent.jar");

// This is equivalent to ByteBuddyAgent.install() but using attach mechanism
ByteBuddyAgent.attach(agentJar, currentProcess);

// Custom process provider implementation
ProcessProvider customProvider = new ProcessProvider() {
    @Override
    public String resolve() {
        // Custom logic to find target process
        return findMyApplicationProcess();
    }
    
    private String findMyApplicationProcess() {
        // Implementation to locate specific application process
        return "1234";
    }
};

ByteBuddyAgent.attach(agentJar, customProvider);

Error Handling and Diagnostics

import net.bytebuddy.agent.ByteBuddyAgent;
import java.io.File;

File agentJar = new File("diagnostic-agent.jar");
String processId = "1234";

try {
    // Enable diagnostic dumping for troubleshooting
    System.setProperty("net.bytebuddy.agent.attacher.dump", "/tmp/attachment-debug.log");
    
    ByteBuddyAgent.attach(agentJar, processId);
    System.out.println("Agent attached successfully");
    
} catch (IllegalStateException e) {
    System.err.println("Attachment failed: " + e.getMessage());
    
    // Common failure reasons:
    // - Target process not found or not accessible
    // - Attachment mechanism not available
    // - Agent JAR malformed or missing manifest
    // - Insufficient permissions
    
    // Try with different provider
    try {
        ByteBuddyAgent.attach(agentJar, processId, 
            AttachmentProvider.ForEmulatedAttachment.INSTANCE);
        System.out.println("Attachment succeeded with JNA provider");
    } catch (IllegalStateException fallbackFailure) {
        System.err.println("All attachment methods failed");
    }
}

Agent JAR Requirements

For successful attachment, agent JAR files must include proper manifest headers:

Manifest-Version: 1.0
Agent-Class: com.example.MyAgent
Can-Redefine-Classes: true
Can-Retransform-Classes: true
Can-Set-Native-Method-Prefix: true

And implement the agent specification:

public class MyAgent {
    public static void agentmain(String agentArgs, Instrumentation inst) {
        // Agent implementation for attach API
    }
    
    public static void premain(String agentArgs, Instrumentation inst) {
        // Agent implementation for command-line loading
    }
}

Security and Limitations

Same-user restriction: Can only attach to processes executed by the same operating system user
JVM compatibility: Attachment mechanisms vary by JVM implementation and version
Platform dependencies: Some attachment methods require JDK tools or JNA library
External processes: Java 9+ may require external process for self-attachment due to security restrictions
Permissions: Target process must allow agent attachment (not all JVMs support this)

Install with Tessl CLI

npx tessl i tessl/maven-net-bytebuddy--byte-buddy-agent

docs

agent-attachment.md

agent-installation.md

tessl/maven-net-bytebuddy--byte-buddy-agent