ODbgScript - 帮助文档（2.01）

FromOllyScript plugin v0.92 by SHaG

1. About OllyScript
2. Status

2.1 What’s new ?

1. Documentation

3.1 Language
3.1.1 Reserved variables
3.1.2 Commands
3.2 Labels
3.3 Comments
3.4 Menus
3.5 Script Window

1. Integration with other plugins
2. Contact me
3. License and source code
4. Thanks!

About ODbgScript

ODbgScript is a plugin for OllyDbg, which is, in our opinion,
the best application-mode debugger out there. One of the best
features of this debugger is the plugin architecture which allows
users to extend its functionality. ODbgScript is a plugin
meant to let you automate OllyDbg by writing scripts in an
assembly-like language. Many tasks involve a lot of repetitive
work just to get to some point in the debugged application. By
using my plugin you can write a script once and for all.
ODbgScript english plugin by E3
site : http://odbgscript.sf.net

Status

v1.0
OllyScript becomes ODbgScript with the new GUI Window

v0.9
OllyScript has now been downloaded more then 10000 times! That means more then 2Gb of raw
scripting power flowing down the optic cable veins of the Internet. Not bad if you ask me!
The development of the plugin has been a bit slow, I’ve got a job programming xray systems
which has taken a lot of time. Sorry about that.

Documentation

Example script (sample.osc) is available with this release.
The script will break on LoadLibray call to debug a SHELL32.DLL function.
Try it on mspaint.exe

3.1 Language

The scripting language of OllyScript is an assembly-like language.

In the document below, src and dest can be (unless stated otherwise):

• Constant in the form of a hex number withot prefixes and suffixes (i.e. 00FF, not 0x00FF or 00FFh)
  For decimal values, use the point (i.e. 100. 128.)
• Variable previously declared by VAR, or are declared with MOV
• A 32-bit register (one of EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, EIP).
  A 16-bit register (one of AX, BX, CX, DX, SI, DI, BP, SP)
  A 8-bit register (one of AL, AH, … DL, DH)
• A memory reference in square brackets (i.e. [401000] points to the memory at address 401000,
  [ecx] points to the memory at address ecx).
• A flag with an exclamation mark in front (one of !CF, !PF, !AF, !ZF, !SF, !DF, !OF)
• Sometimes byte strings are required. those are scripted as #6A0000# (values between two #) and
  must have an even number of characters.
  Some byte strings can contain the wildcard ‘?’, for exampla #6A??00# or #6?0000#
• A combinaison of this values with operators :

You can use operators in your scripts, +-*/&|^>< for dword and + to concatenate strings.

• Operators > and < are shr and shl (>> and << in C/C++)
• Operator ^ is XOR
• Operator & is AND
• Operator | is OR

3.1.1 Reserved variables

$RESULT

Return value for some functions like FIND etc.
$RESULT_1 and $RESULT_2 are available for some commands.

$VERSION

Contains current version of OllyScript
Example
cmp $VERSION, “0.8”
ja version_above_08

3.1.2 Commands

#INC file

Includes a script file in another script file
Example:
#inc “anotherscript.txt”

#LOG

Enables logging of executed commands.
The commands will appear in OllyDbg log window, and will be prefixed with —>
Example:
#log

ADD dest, src

Adds src to dest and stores result in dest
Example:
add x, 0F
add eax, x
add [401000], 5
add y, “ times” // If y was 1000 before this command then y is “1000 times” after it

AI

Executes “Animate into” in OllyDbg
Example:
ai

ALLOC size

Allocate new memory page, you can read/write and execute.
Example
alloc 1000
free $RESULT, 1000

AN addr

Analyze module which contains the address addr.
Example:
an eip // Same as pressing CTRL-A

AND dest, src

ANDs src and dest and stores result in dest
Example:
and x, 0F
and eax, x
and [401000], 5

AO

Executes “Animate over” in OllyDbg
Example:
ao

ASK question

Displays an input box with the specified question and lets user enter a response.
Sets the reserved $RESULT variable (0 if cancel button was pressed).
You have also the length in $RESULT_1 (divised by 2 for hex entries)
Example:
ask “Enter new EIP”
cmp $RESULT, 0
je cancel_pressed
mov eip, $RESULT

ASM addr, command

Assemble a command at some address.
Returns bytes assembled in the reserved $RESULT variable
Example:
asm eip, “mov eax, ecx”

ATOI str [, base=16.]

Converts a string to integer
Returns the integer in the reserved $RESULT variable
Example:
itoa “F”
itoa “10”, 10.

BC addr

Clear unconditional breakpoint at addr.
Example:
bc 401000
bc x
bc eip

BP addr

Set unconditional breakpoint at addr.
Example:
bp 401000
bp x
bp eip

BPCND addr, cond

Set breakpoint on address addr with condition cond.
Example:
bpcnd 401000, “ECX==1”

BPL addr, expr

Sets logging breakpoint at address addr that logs expression expr
Example:
bpl 401000, “eax” // logs the value of eax everytime this line is passed

BPLCND addr, expr, cond

Sets logging breakpoint at address addr that logs expression expr if condition cond is true
Example:
bplcnd 401000, “eax”, “eax > 1” // logs the value of eax everytime this line is passed and eax > 1

BPMC

Clear memory breakpoint.
Example:
bpmc

BPHWC addr

Delete hardware breakpoint at a specified address
Example:
bphwc 401000

BPHWS addr, mode

Set hardware breakpoint. Mode can be “r” - read, “w” - write or “x” - execute.
Example:
bphws 401000, “x”

BPRM addr, size

Set memory breakpoint on read. Size is size of memory in bytes.
Example:
bprm 401000, FF

BPWM addr, size

Set memory breakpoint on write. Size is size of memory in bytes.
Example:
bpwm 401000, FF

CMP dest, src

Compares dest to src. Works like it’s ASM counterpart.
Works with strings too (case sensitive)
Example:
cmp y, x
cmp eip, 401000

CMT addr, text

Inserts a comment at the specified address
Example:
cmt eip, “This is the entry point”

COB

Makes script continue execution after a breakpoint has occured (removes EOB)
Example:
COB

COE

Makes script continue execution after an exception has occured (removes EOE)
Example:
COE

DBH

Hides debugger
Example:
dbh

DBS

Unhides debugger
Example:
dbs

DEC var

Substracts 1 from variable
Example:
dec v

DM addr, size, file

Dumps memory of specified size from specified address to specified file (default path set from opened app.)
Example:
dm 401000, 1F, “c:\dump.bin”

DMA addr, size, file

Dumps memory of specified size from specified address to specified file appending to that file if it exists
Example:
dma 401000, 1F, “c:\dump.bin”

DPE filename, ep

Dumps the executable to file with specified name.
Entry point is set to ep.
Example:
dpe “c:\test.exe”, eip

EOB label

Transfer execution to some label on next breakpoint.
Example:
eob SOME_LABEL

EOE label

Transfer execution to some label on next exception.
Example:
eob SOME_LABEL

ESTI

Executes SHIFT-F7 in OllyDbg.
Example:
esti

ESTO

Executes SHIFT-F9 in OllyDbg.
Example:
esto

EVAL

Evaluates a string expression that contains variables.
The variables that are declared in the current script can be enclosed in curly braces {} to be inserted.
Sets the reserved $RESULT variable
Example:
var x
mov x, 1000
eval “The value of x is {x}” // after this $RESULT is “The value of x is 00001000”

EXEC/ENDE

Executes instructions between EXEC and ENDE in the context of the target process.
Values in curly braces {} are replaced by their values.
Example:
// This does some movs
var x
var y
mov x, “eax”
mov y, “0DEADBEEF”
exec
mov {x}, {y} // mov eax, 0DEADBEEF will be executed
mov ecx, {x} // mov ecx, eax will be executed
ende
// This calls ExitProcess in the debugged application
exec
push 0
call ExitProcess
ende
ret

FILL addr, len, value

Fills len bytes of memory at addr with value
Example:
fill 401000, 10, 90 // NOP 10h bytes

FIND addr, what

Searches memory starting at addr for the specified value.
When found sets the reserved $RESULT variable. $RESULT == 0 if nothing found.
The search string can also use the wildcard “??” (see below).

Example:
find eip, #6A00E8# // find a PUSH 0 followed by some kind of call
find eip, #6A??E8# // find a PUSH 0 followed by some kind of call

FINDOP addr, what

Searches code starting at addr for an instruction that begins with the specified bytes.
When found sets the reserved $RESULT variable. $RESULT == 0 if nothing found.
The search string can also use the wildcard “??” (see below).
Example:
findop 401000, #61# // find next POPAD
findop 401000, #6A??# // find next PUSH of something
findop 401000, “1” // = #61#

FINDMEM what [, StartAddr]

Searches whole memory for the specified value.
When found sets the reserved $RESULT variable. $RESULT == 0 if nothing found.
The search string can also use the wildcard “??” (see below).
Example:
findmem #6A00E8# // find a PUSH 0 followed by some kind of call
findmem #6A00E8#, 00400000 // search it after address 0040.0000

FREE addr, size

Free memory allocated by ALLOC.
Example
alloc 1000
free $RESULT, 1000

GCMT addr

Gets the comment, automatic comment or analyse’s comment at specified code address

GN addr

Gets the symbolic name of specified address (ex the API it poits to)
Sets the reserved RESULT_1 is set to the library (ex kernel32) and $RESULT_2 to the name of the API (ex ExitProcess).
Example:
gn 401000

GMEMI addr, info

Gets information about a memory block to which the specified address belongs.
“info” can be MEMORYBASE, MEMORYSIZE or MEMORYOWNER (if you want other info in the future versions plz tell me).
Sets the reserved $RESULT variable (0 if data not found).
Example:
GMEMI addr, MEMORYBASE // After this $RESULT is the address to the memory base of the memory block to which addr belongs

GMI addr, info

Gets information about a module to which the specified address belongs.
“info” can be MODULEBASE, MODULESIZE, CODEBASE, CODESIZE, MEMBASE or MEMSIZE
(if you want other info in the future versions plz tell me).
Sets the reserved $RESULT variable (0 if data not found).
Example:
GMI eip, CODEBASE // After this $RESULT is the address to the codebase of the module to which eip belongs

GO addr

Executes to specified address (like G in SoftIce)
Example:
go 401005

GPA proc, lib

Gets the address of the specified procedure in the specified library.
When found sets the reserved $RESULT variable. $RESULT == 0 if nothing found.
Useful for setting breakpoints on APIs.
Example:
gpa “MessageBoxA”, “user32.dll” // After this $RESULT is the address of MessageBoxA and you can do “bp $RESULT”.

GPI key

Gets process information, one of :
HPROCESS,PROCESSID,HMAINTHREAD,MAINTHREADID,MAINBASE,PROCESSNAME,EXEFILENAME,CURRENTDIR,SYSTEMDIR

HANDLE x, y, class

Returns the handle of child window of specified class at point x,y (remember: in hex values).

INC var

Adds 1 to variable
Example:
inc v

ITOA n [, base=16.]

Converts an integer to string
Returns the string in the reserved $RESULT variable
Example:
itoa F
itoa 10., 10.

JA label

Use this after cmp. Works like it’s asm counterpart.
Example:
ja SOME_LABEL

JAE label

Use this after cmp. Works like it’s asm counterpart.
Example:
jae SOME_LABEL

JB label

Use this after cmp. Works like it’s asm counterpart.
Example:
jb SOME_LABEL

JBE label

Use this after cmp. Works like it’s asm counterpart.
Example:
jbe SOME_LABEL

JE label

Use this after cmp. Works like it’s asm counterpart.
Example:
je SOME_LABEL

JMP label

Unconditionally jump to a label.
Example:
jmp SOME_LABEL

JNE label

Use this after cmp. Works like it’s asm counterpart.
Example:
jne SOME_LABEL

KEY vkcode [, shift [, ctrl]]

Emulates global keyboard shortcut.
Example:
key 20
key 20, 1 //Shift+space
key 20, 0, 1 //Ctrl+space

LBL addr, text

Inserts a label at the specified address
Example:
lbl eip, “NiceJump”

LC

Clear Main Log Window

LCLR

Clear Script Log Window

LEN str

Get length of a string
Example:
len “NiceJump”
msg $RESULT

LM addr, size, filename

load Dm file to mem
LM is the opposite of the DM command
Example:
lm 0x401000, 0x100, “test.bin”

LOG src [,prefix]

Logs src to OllyDbg log window.
If src is a constant string the string is logged as it is.
If src is a variable or register its logged with its name.
You can replace default prefix with the optional second parameter.
Example:
log “Hello world” // The string “Hello world” is logged
var x
mov x, 10
log x // The string “x: 00000010” is logged.
log x, “” // The string “00000010” is logged.

MOV dest, src [,maxsize]

Move src to dest.
Src can be a long hex string in the format ##, for example #1234#.
Remember that the number of digits in the hex string must be even, i.e. 2, 4, 6, 8 etc.
Example:
mov x, 0F
mov y, “Hello world”
mov eax, ecx
mov [ecx], #00DEAD00BEEF00#
mov !CF, 1
mov !DF, !PF
mov [403000], “Hello world”

MSG message

Display a message box with specified message
Example:
MSG “Script paused”

MSGYN message

Display a message box with specified message and YES and NO buttons.
Sets the reserved $RESULT variable to 1 if YES is selected and 0 otherwise.
Example:
MSGYN “Continue?”

OR dest, src

ORs src and dest and stores result in dest
Example:
or x, 0F
or eax, x
or [401000], 5

OPCODE addr

OPCODE sets the $RESULT variable to the opcode bytes, $RESULT_1 variable to mnemonic opcode (i.e. “MOV ECX,EAX”)
and $RESULT_2 to the length of the opcode.
If an invalid opcode appears, $RESULT_2 should be 0.
addr is increased by the length of the opcode (disassemble command).
With this function you can step forward through code.
Example:
opcode 00401000

PAUSE

Pauses script execution. Script can be resumed from plugin menu.
Example:
pause

PREOP addr

Get asm command line address just before specified address.
Attention: Will not give real executed command eip before the jump.
Example:
preop eip

REF addr

REF addr works as “Find references to .. Selected command” and “Find references”, Ctrl R, in OllyDbg.
RESULT_1 to the opcode (text asm command)
$RESULT_2 to the comment (like reference window).
Repeat “REF addr” until $RESULT=0 to get next refs
Example:
continue:
REF eip
log $RESULT
log $RESULT_1
log $RESULT_2
cmp $RESULT,0
jne continue

REPL addr, find, repl, len

Replace find with repl starting att addr for len bytes.
Wildcards are allowed
Example:
repl eip, #6a00#, #6b00#, 10
repl eip, #??00#, #??01#, 10
repl 401000, #41#, #90#, 1F

RET

Exits script.
Example:
ret

REV

Reverse dword bytes.
Example:
rev 01020304
//$RESULT = 04030201

RTR

Executes “Run to return” in OllyDbg
Example:
rtr

RTU

Executes “Run to user code” in OllyDbg
Example:
rtu

RUN

Executes F9 in OllyDbg
Example:
run

SCMP dest, src

Compares strings dest to src. Works like it’s ASM counterpart.
Example:
cmp x, “KERNEL32.DLL”
cmp [eax], “Hello World”

SCMPI dest, src

Compares strings dest to src (case insentitive). Works like it’s ASM counterpart.
Example:
cmp sVar, “KERNEL32.DLL”
cmp [eax], “Hello World”

SHL dest, src

Shifts dest to the left src times and stores the result in dest.
Example:
mov x, 00000010
shl x, 8 // x is now 00001000

SHR dest, src

Shifts dest to the right src times and stores the result in dest.
Example:
mov x, 00001000
shr x, 8 // x is now 00000010

STI

Execute F7 in OllyDbg.
Example:
sti

STO

Execute F8 in OllyDbg.
Example:
sto

SUB dest, src

Substracts src from dest and stores result in dest
Example:
sub x, 0F
sub eax, x
sub [401000], 5

TC

Executes “Close (and delete) Run Trace” in OllyDbg
Example:
tc

TI

Executes “Trace into” in OllyDbg
Example:
ti

TICND cond

Traces into calls until cond is true
Example:
ticnd “eip > 40100A” // will stop when eip > 40100A

TO

Executes “Trace over” in OllyDbg
Example:
to

TOCND cond

Traces over calls until cond is true
Example:
tocnd “eip > 40100A” // will stop when eip > 40100A

VAR

Declare a variable to be used in the script.
Must be done before the variable is used.
Example:
var x

XOR dest, src

XORs src and dest and stores result in dest
Example:
xor x, 0F
xor eax, x
xor [401000], 5

WRT file, data

Write to file (replace existing one) the only accepted symbol is “\r\n”
Numbers are wrote as strings… for the moment
Example:
wrt “out.txt”, “Data:\r\nOk\r\n”
wrt sFile, ebx

WRTA file, data

Append to file
Example:
wrta sFile, “hello world\r\n”

3.2 Labels

Labels are defined bu using the label name followed by a colon.
Example:
SOME_LABEL:

3.3 Comments

Comments can be put anywhere and have to start with “//“.
Block comments between “/“ and “/“

3.4 Menus

The main OllyScript menu consists of the following items:

• Run script…: lets the user select a script file and starts it
• Abort: aborts a running script
• Pause: pauses a running script
• Resume: resumes a paused script
• About: shows information about this plugin

3.5 Script Window

The Script Window was introduced with ODbgScript, it enables you to debug
and see progression of your script.
You can set script breakpoints, debug the script, edit variables and also
execute commands manually.

Integration with other plugins

You can call OllyScript from your plugin and make it execute a script.
Use something like the source code below:

HMODULE hMod = GetModuleHandle(“ODbgScript.dll”);
if(hMod) // Check that the other plugin is present and loaded
{
// Get address of exported function
int (pFunc)(char) = (int ()(char)) GetProcAddress(hMod, “ExecuteScript”);
if(pFunc) // Check that the other plugin exports the correct function
pFunc(“myscript.txt”); // Execute exported function
}

Contact us

To contact us you can post your question in the forum or go on IRC
and message Epsylon3 or SHaG on EFnet.

You can also mail SHaG to shag-at-apsvans-dot-com.

License and source code

Soon I’m going to armadildo this plugin and charge an awful lot of money
for it! :P Seriously, you are free to use this plugin and the source code however
you see fit. However please name me in your documentation/about box and if
the project you need my code for is on a larger scale please also notify
me - I am curious.

Source code for this plugin is available on request only. Please send me
a mail if you need it!

Thanks!

I’d like to thank all the wonderful people who reported bugs, wrote scripts, came
with improvement ideas etc.

R@dier for the great dumping engine.

shERis, nick_name, MetaCore, XanSama, arnix, hila123, bukkake, Human
for ideas and bug report on the new ODbgScript

And of course Olly for developing this great debugger!