Library `jdwp`

JDWP (Java Debug Wire Protocol) library implementing a set of commands needed to use remote debugging port and inject java bytecode.

There are two basic packet types in JDWP protocol. Command packet and reply packet. Command packets are sent by a debugger to a remote port which replies with a reply packet.

Simple handshake is needed to start the communication. The debugger sends a "JDWP-Handshake" string and gets the same as a reply. Each (command and reply packet) has an id field since communication can be asynchronous. Packet id can be monotonicaly increasing. Although communication can be asynchronous, it is not (at least in my tests) so the same packet id can be used for all communication.

To start the connection, script should call jdwp.connect() which returns success status and a socket. All other protocol functions require a socket as their first parameter.

Example of initiating connection:

local status,socket = jdwp.connect(host,port)
if not status then
  stdnse.debug1("error, %s",socket)
end
local version_info
status, version_info = jdwp.getVersion(socket,0)

References:

http://docs.oracle.com/javase/6/docs/technotes/guides/jpda/jdwp-spec.html

Author:

Aleksandar Nikolic Version 0.1 Created 08/10/2012 - v0.1 - Created by Aleksandar Nikolic

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/jdwp.lua

Functions

clearThreadSinglestep (socket, id, eventID): Uses Clear Command (2) to unset singlesteping from a thread by specified event.
connect (host, port): Negotiates the initial debugger-debuggee handshake.
createString (socket, id, ascii_string): CreateString Command (11) Creates new string object in the debuggee VM.
executeCommand (socket, command): Helper function that sends the Command packet and parses the reply.
findMethod (socket, class, methodName, skipFirst): Helper function to find a method ID by its name.
getAllClassesWithGeneric (socket, id): AllClassesWithGeneric Command (20) Returns reference types and signatures for all classes currently loaded by the target VM.
getAllThreads (socket, id): AllThreads Command (4) Returns all threads currently running in the target VM .
getClassBySignature (socket, id, signature): Classes by Signature command (2) Returns reference types for all the classes loaded by the target VM which match the given signature.
getMethodsWithGeneric (socket, id, classID): MethodsWithGeneric Command (15) Returns information, including the generic signature if any, for each method in a reference type.
getReflectedType (socket, id, classObjectID): ReflectedType Command (1) Returns the reference type reflected by this class object.
getRuntimeType (socket, id, objectID): ReferenceType Command (1) Returns the runtime type of the object. The runtime type will be a class or an array.
getSignatureWithGeneric (socket, id, classID): SignatureWithGeneric Command (13) Returns the JNI signature of a reference type.
getThreadName (socket, id, threadID): Name Command (1) Returns the thread name.
getVersion (socket, id): Version Command (1) Returns the JDWP version implemented by the target VM as a table.
injectClass (socket, class_bytes): Tries to inject specified bytes as a java class and create its instance.
invokeObjectMethod (socket, id, objectID, threadID, classID, methodID, numberOfArguments, arguments): InvokeMethod Command (6) Invokes a instance method with specified parameters.
invokeStaticMethod (socket, id, classID, methodID, numberOfArguments, arguments, options): InvokeMethod Command (3) Invokes a class' static method and returns the reply data.
newArrayInstance (socket, id, arrayType, length): NewInstance Command (1) Creates a new array object of the specified type with a given length.
newClassInstance (socket, id, classID, threadID, methodID, numberOfArguments, arguments): NewInstance Command (4)
readString (socket, id, stringID): Value Command (1) Returns the characters contained in the string.
receive_all (socket): Helper function to read all Reply packed data which might be fragmented over multiple packets.
resumeVM (socket, id): Resume Command (9) Resumes execution of the application after the suspend command or an event has stopped it.
setArrayValues (socket, id, objectID, idx, values): SetValues Command (3) Sets a range of array components.
setThreadSinglestep (socket, id, threadID): Uses Set Command (1) to set singlesteping to specified thread.
suspendThread (socket, id, threadID): Suspend Command (2) Suspends the thread.
threadStatus (socket, id, threadID): Status Command (4) Returns the current status of a thread.
toUTF8 (data): Helper function to pack regular string into UTF-8 string.

Functions

clearThreadSinglestep (socket, id, eventID)

Uses Clear Command (2) to unset singlesteping from a thread by specified event.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_EventRequest_Clear

Parameters

socket: Socket to use to send the command.
id: Packet id.
eventID: The ID of the thread.

Return value:

(status, requestID) If status is false an error string is returned, else it's nil.

connect (host, port)

Negotiates the initial debugger-debuggee handshake.

Parameters

host: Host to connect to.
port: Port to connect to.

Return value:

(status,socket) If status is false, socket is error message, otherwise socket is a newly created socket with initial handshake finished.

createString (socket, id, ascii_string)

CreateString Command (11) Creates new string object in the debuggee VM.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_CreateString

Parameters

socket: Socket to use to send the command.
id: Packet id.
ascii_string: String to create.

Return value:

(status, stringID) If status is false error string is returned, else stringID is newly created string.

executeCommand (socket, command)

Helper function that sends the Command packet and parses the reply.

Parameters

socket: Socket to use to send the command.
command: JDWPCommandPacket to send.

Return value:

(status,data) If status is false, data contains specified error code message. If true, data contains data from the reply.

findMethod (socket, class, methodName, skipFirst)

Helper function to find a method ID by its name.

Parameters

socket: Socket to use for communication.
class: ID of the class whose method we seek.
methodName: Name of the method.
skipFirst: Skip first found method.

getAllClassesWithGeneric (socket, id)

AllClassesWithGeneric Command (20) Returns reference types and signatures for all classes currently loaded by the target VM.

Returns a list of tables containing following info: * 'refTypeTag' Kind of following reference type. * 'typeID' Loaded reference type * 'signature' The JNI signature of the loaded reference type. * 'genericSignature' The generic signature of the loaded reference type or an empty string if there is none. * 'status' The current class status. http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_AllClassesWithGeneric

Parameters

socket: Socket to use to send the command.
id: Packet id.

Return value:

(status, all_classes) If status is false all_classes contains an error string, else it is a list of loaded classes information.

getAllThreads (socket, id)

AllThreads Command (4) Returns all threads currently running in the target VM .

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_AllThreads

Parameters

socket: Socket to use to send the command.
id: Packet id.

Return value:

(status, threads) If status is false threads contains an error string, else it contains a list of all threads in the debuggee VM.

getClassBySignature (socket, id, signature)

Classes by Signature command (2) Returns reference types for all the classes loaded by the target VM which match the given signature.

Given the class signature (like "Ljava/lang/Class") returns its reference ID which can be used to reference that class in other commands. Returns a list of tables containing following values: * 'refTypeTag' JNI type tag * 'referenceTypeID' Reference type of the class * 'status' Current class status. http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_ClassesBySignature

Parameters

socket: Socket to use to send the command.
id: Packet id.
signature: Signature of the class.

Return value:

(status,classes) If status is false, classes is an error string, else it contains list of found classes.

getMethodsWithGeneric (socket, id, classID)

MethodsWithGeneric Command (15) Returns information, including the generic signature if any, for each method in a reference type.

Returns a list of tables containing following fields for each method: * 'methodID' Method ID which can be used to call the method. * 'name' The name of the method. * 'signature' The JNI signature of the method. * 'generic_signature' The generic signature of the method, or an empty string if there is none. * 'modBits' The modifier bit flags (also known as access flags) which provide additional information on the method declaration. http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ReferenceType_MethodsWithGeneric

Parameters

socket: Socket to use to send the command.
id: Packet id.
classID: Reference type id of the class to get the list of methods.

Return value:

(status, signature) If status is false methods contains an error string, else it a list of methods information.

getReflectedType (socket, id, classObjectID)

ReflectedType Command (1) Returns the reference type reflected by this class object.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ClassObjectReference_ReflectedType

Parameters

socket: Socket to use to send the command.
id: Packet id.
classObjectID: The ID of the object.

Return value:

(status, reflected_type) If status is false an error string is returned, else reflected_type is object's reference type.

getRuntimeType (socket, id, objectID)

ReferenceType Command (1) Returns the runtime type of the object. The runtime type will be a class or an array.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ObjectReference_ReferenceType

Parameters

socket: Socket to use to send the command.
id: Packet id.
objectID: The ID of an object.

Return value:

(status, runtime_type) If status is false runtime_type contains an error string, else it contains runtime type of an object.

getSignatureWithGeneric (socket, id, classID)

SignatureWithGeneric Command (13) Returns the JNI signature of a reference type.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ReferenceType_SignatureWithGeneric

Parameters

socket: Socket to use to send the command.
id: Packet id.
classID: Reference type id of the class to get the signature from.

Return value:

(status, signature) If status is false signature contains an error string, else it is class signature (like "Ljava/lang/Class").

getThreadName (socket, id, threadID)

Name Command (1) Returns the thread name.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ThreadReference_Name

Parameters

socket: Socket to use to send the command.
id: Packet id.
threadID: The ID of a thread.

Return value:

(status, thread_name) If status is false thread_name contains an error string, else it contains thread's name.

getVersion (socket, id)

Version Command (1) Returns the JDWP version implemented by the target VM as a table.

Returns a table with following values: * 'description' Debugger vm verbose description. * 'jdwpMajor' Number representing major JDWP version. * 'jdwpMinor' Number representing minor JDWP version. * 'vmVersion' String representing version of the debuggee VM. * 'vmName' Name of the debuggee VM. http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_Version

Parameters

socket: Socket to use to send the command.
id: Packet id.

Return value:

(status,version_info) If status is false, version_info is an error string, else it contains remote VM version info.

injectClass (socket, class_bytes)

Tries to inject specified bytes as a java class and create its instance.

Returns a table containing following fields: * 'id' Injected class reference ID. * 'instance' Injected calss' instance reference ID. * 'thread' Thread in which the class was injected and instantiated.

Parameters

socket: Socket to use for communication.
class_bytes: String of bytes of a java class file to inject.

Return value:

(status,injectedClass) If status is false, an error message is returned, else returns a table with injected class info.

invokeObjectMethod (socket, id, objectID, threadID, classID, methodID, numberOfArguments, arguments)

InvokeMethod Command (6) Invokes a instance method with specified parameters.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ObjectReference_InvokeMethod

Parameters

socket: Socket to use to send the command.
id: Packet id.
objectID: The ID of an object.
threadID: The thread in which to invoke.
classID: The class type.
methodID: ID of the method to invoke.
numberOfArguments: Number of method arguments.
arguments

Return value:

(status, data) If status is false data contains an error string, else it contains a reply data and needs to be parsed manually.

invokeStaticMethod (socket, id, classID, methodID, numberOfArguments, arguments, options)

InvokeMethod Command (3) Invokes a class' static method and returns the reply data.

Reply data can vary so parsing is left to the function caller. http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ClassType_InvokeMethod

Parameters

socket: Socket to use to send the command.
id: Packet id.
classID: Reference type id of the class.
methodID: ID of the static method to call.
numberOfArguments
arguments
options

Return value:

(status, data) If status is false data contains an error string, else it contains a reply data and needs to be parsed manually.

newArrayInstance (socket, id, arrayType, length)

NewInstance Command (1) Creates a new array object of the specified type with a given length.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ArrayType_NewInstance

Parameters

socket: Socket to use to send the command.
id: Packet id.
arrayType: The array type of the new instance as per JNI (http://docs.oracle.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp9502).
length: Length of the new array.

Return value:

(status, arrayID) If status is false data contains an error string, else it contains a reference ID of the newly created array.

newClassInstance (socket, id, classID, threadID, methodID, numberOfArguments, arguments)

NewInstance Command (4)

Creates a new object of this type, invoking the specified constructor. The constructor method ID must be a member of the class type.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ClassType_NewInstance

Parameters

socket: Socket to use to send the command.
id: Packet id.
classID: Reference type id of the class.
threadID: The thread in which to invoke the constructor.
methodID: The constructor to invoke.
numberOfArguments
arguments

Return value:

(status, objectID) If status is false data contains an error string, else it contains a reference ID of the newly created object.

readString (socket, id, stringID)

Value Command (1) Returns the characters contained in the string.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_StringReference_Value

Parameters

socket: Socket to use to send the command.
id: Packet id.
stringID: The ID of a string to read.

Return value:

(status, data) If status is false result contains an error string, else it contains read string.

receive_all (socket)

Helper function to read all Reply packed data which might be fragmented over multiple packets.

Parameters

socket: Socket to receive from.

Return value:

(status,data) If status is false, error string is returned, else data contains read ReplyPacket bytes.

resumeVM (socket, id)

Resume Command (9) Resumes execution of the application after the suspend command or an event has stopped it.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_Resume

Parameters

socket: Socket to use to send the command.
id: Packet id.

Return value:

(status, nil) If status is false error string is returned, else it's null since this command has no data in the reply.

setArrayValues (socket, id, objectID, idx, values)

SetValues Command (3) Sets a range of array components.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ArrayReference_SetValues

Parameters

socket: Socket to use to send the command.
id: Packet id.
objectID: The ID of an array object.
idx
values

Return value:

(status, data) If status is false an error string is returned, else it's nil.

setThreadSinglestep (socket, id, threadID)

Uses Set Command (1) to set singlesteping to specified thread.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_EventRequest_Set

Parameters

socket: Socket to use to send the command.
id: Packet id.
threadID: The ID of the thread.

Return value:

(status, requestID) If status is false an error string is returned, else it contains assigned request id.

suspendThread (socket, id, threadID)

Suspend Command (2) Suspends the thread.

http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ThreadReference_Suspend

Parameters

socket: Socket to use to send the command.
id: Packet id.
threadID: The ID of a thread.

Return value:

(status, thread_name) If status is false an error string is returned, else it's nil.

threadStatus (socket, id, threadID)

Status Command (4) Returns the current status of a thread.

Thread status is described with ThreadStatus and SuspendStatus constants (http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ThreadStatus). http://docs.oracle.com/javase/1.5.0/docs/guide/jpda/jdwp/jdwp-protocol.html#JDWP_ThreadReference_Status

Parameters

socket: Socket to use to send the command.
id: Packet id.
threadID: The ID of a thread.

Return value:

(status, thread_name) If status is false an error string is returned, else unparsed thread status data.

toUTF8 (data)

Helper function to pack regular string into UTF-8 string.

Parameters

data: String to pack into UTF-8.

Return value:

utf8_string UTF-8 packed string. Four bytes length followed by the string its self.

Library jdwp

Functions

Functions

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Library `jdwp`