1scanmem(1) General Commands Manual scanmem(1)
2
6 scanmem - locate and modify variables in an executing process.
7
10 scanmem [options] [target-program-pid]
11
15 scanmem is an interactive debugging utility that can be used to isolate
16 the address of a variable in an executing process by successively scan‐
17 ning the process' address space looking for matching values.
18 By informing scanmem how the value of the variable changes over time,
19 it can determine the actual location (or locations) of the variable by
20 successively eliminating non-matches.
21 scanmem determines where to look by searching for mappings with
22 read/write permission, these are referred to as regions. Users can
23 eliminate regions they believe are likely unrelated to the target vari‐
24 able (for example, located in a shared library unrelated to the vari‐
25 able in question), this will improve the speed of the scan, which can
26 initially be quite slow in large programs.
27 Once a variable has been found, scanmem can monitor the variable, or
29 change it to a user specified value, either once, or continually over a
30 period of time.
31 scanmem works similarly to the "pokefinders" once commonly used to
33 cheat at video games, this function is a good demonstration of how to
34 use scanmem, and is used in the documentation.
35
38 scanmem should be invoked with the process id of the program you wish
39 to debug as an argument. Once started, scanmem accepts interactive
40 commands. These are described below, however entering help at the >
41 prompt will allow you to access scanmem's online documentation.
42 The target-program-pid can be specified in decimal, hexadecimal, or
44 octal using the standard C language notation (leading 0x for hexadeci‐
45 mal, leading 0 for octal, anything else is assumed to be decimal).
46 -p, --pid=pid
49 Set the target-program-pid.
50 -c, --command=cmd1[;cmd2][;...]
53 Run given commands (separated by ";") before starting the inter‐
54 active shell.
55 -v, --version
58 Print version and exit.
59 -h, --help
62 Print a short description of command line options then exit.
63 -d, --debug
66 Run in debug mode, more information will be outputted.
67 -e, --errexit
70 Exit on initial commands error, ignored during interactive mode.
71
74 While in interactive mode, scanmem prints a decimal number followed by
75 >, the number is the current number of possible candidates for the tar‐
76 get variable that are known. The absence of said number indicates that
77 no possible variables have been eliminated yet.
78 The default scan data type is "int". It can be changed with the option
79 command.
80 n Where n represents any number in decimal, octal or hexadecimal,
83 this command tells scanmem that the current value of the target
84 variable is exactly n. scanmem will begin a search of the
85 entire address space, or the existing known matches (if any),
86 eliminating any variable that does not have this value.
87 n..m This is like the n command but scanmem searches for a range of
90 numbers between n and m inclusive instead.
91 >, <, +, -, =, !=
94 The following commands are extremely useful for locating a vari‐
95 able whose exact value we cannot see, but we can see how it
96 changes over time, e.g. an health bar. These commands usually
97 cannot be used for the first scan but there are some exceptions:
98 > n, < n, = n and != n.
99 > [n] If n is given, match values that are greater than n.
102 Otherwise match all values that have increased.
103 < [n] If n is given, match values that are less than n. Other‐
106 wise match all values that have decreased.
107 + [n] If n is given, match values that have been increased by
110 n. Otherwise match all values that have increased (same
111 as >).
112 - [n] If n is given, match values that have been decreased by
115 n. Otherwise match all values that have decreased (same
116 as <).
117 = [n] If n is given, match values that are equal to n (same as
120 n). Otherwise match all values that have not changed.
121 != [n] If n is given, match values that are different from n.
124 Otherwise match all values that have changed.
125 snapshot
128 Match any value. This is useful when an initial value or range
129 is not known for subsequent scans with >, <, +, -, =, and !=.
130 " text Search for the provided text in memory if the scan data type is
133 set to "string".
134 update Scans the current process, getting the current values of all
137 matches. These values can be viewed with list, and are also the
138 old values that scanmem compares to when using >, <, or =. This
139 command is equivalent to a search command that all current
140 results match.
141 list [max_to_print]
144 List up to max_to_print (default: 10k) possible candidates cur‐
145 rently known, including their address, region id, match offset,
146 region type, last known value and possible value types. The
147 value in the first column is the match id, and can be used in
148 conjunction with the delete command to eliminate matches.
149 The match offset is determined by subtracting the load address
151 of the associated ELF file or region from the address. It can be
152 used to bypass Address Space Layout Randomization (ASLR).
153 delete match-id_set
156 Delete matches in the match-id_set. The match-ids can be found
157 from the output of the list command. Set notation:
158 [!][..a](,b..c | d, ...)[e..].
159 To delete all known matches, see the reset command.
160 To delete all the matches associated with a particular library,
161 see the dregion command, which also removes any associated
162 matches.
163 Please note that match-ids may be recalculated after matches are
164 removed or added.
165 watch match-id
168 Monitor the value of match-id, and print its value as it
169 changes. Every change is printed along with a timestamp, you can
170 interrupt this command with ^C to stop monitoring.
171 set [match-id_set=]value[/delay] [...]
174 Set the value value into the match numbers specified in match-
175 id_set, or if just value is specified, all known matches. value
176 can be specified in standard C language notation. All known
177 matches, along with their match-id's can be displayed using the
178 list command. Multiple match-id_sets can be specified, termi‐
179 nated with an = sign. Set notation: [!][..a](,b..c | d,
180 ...)[e..].
181 To set a value continually, suffix the command with / followed
182 by the number of seconds to wait between sets. You can interrupt
183 the set command with ^C to return to the scanmem prompt. This
184 can be used to sustain the value of a variable which decreases
185 over time, for example a timer that is decremented every second
186 can be set to 100 every 10 seconds to prevent some property from
187 ever changing.
188 This command is used to change the value of the variable(s) once
190 found by elimination. Please note, some applications will store
191 values in multiple locations.
192 write value_type address value
195 Manually set the value of the variable at the specified address.
196 Names of value_type are subject to change in different versions
197 of scanmem, see more info using the `help write` command.
198 dump address length [filename]
201 Dump the memory region starting from address of length length in
202 a human-readable format.
203 If filename is given, data will be saved into the file, other‐
205 wise data will be displayed on stdout.
206 pid [new-pid]
209 Print out the process id of the current target program, or
210 change the target to new-pid, which will reset existing regions
211 and matches.
212 reset Forget all known regions and matches and start again.
215 lregions
218 List all the known regions, this can be used in combination with
219 the dregion command to eliminate regions that the user believes
220 are not related to the variable in question, thus reducing the
221 address space required to search in. The value in the first col‐
222 umn is the region-id which must be passed to the dregion com‐
223 mand. Besides the start address, the size and path (if applica‐
224 ble) are also printed. This can be used to eliminate regions
225 located in shared libraries that are unlikely to be relevant to
226 the variable required.
227 For experts: Also the region type and the load address are dis‐
229 played. The types are "exe" (executable) "code" (library),
230 "heap", "stack" or "misc" (everything else). The load address is
231 the memory location where an ELF file (exe/lib) has been loaded
232 to. This helps to convert between the addresses in memory and in
233 the associated ELF file. If the region does not belong to an ELF
234 file, then it is the same as the start address.
235 dregion region-id_set
238 Delete the regions in region-id_set, along with any matches from
239 the match list. Set notation: [!][..a](,b..c | d, ...)[e..].
240 The region-id's can be found in the output of the lregions com‐
241 mand.
242 option name value
245 Change options at runtime. E.g. the scan data type can be
246 changed. See `help option` for all possible names/values.
247 shell shell-command
250 Execute shell-command using /bin/sh, then return.
251 show info
254 Display information relating to info - see `help show` for
255 details.
256 version
259 Print the version of scanmem in use.
260 help Print a short summary of available commands.
263 exit Detach from the target program and exit immediately.
266
269 Cheat at nethack, on systems where nethack is not installed sgid.
270 ATTENTION: scanmem usually requires root privileges. See KNOWN ISSUES
272 for details.
273 $ sudo scanmem `pgrep nethack`
275 info: maps file located at /proc/14658/maps opened.
276 info: 9 suitable regions found.
277 Please enter current value, or "help" for other commands.
278 >
279 I enter how much gold I currently have (58 pieces) and let scanmem find
281 the potential candidates.
282 > 58
285 01/09 searching 0x79f000 - 0x7b0000..........ok
286 02/09 searching 0x7b0000 - 0x7cc000..........ok
287 03/09 searching 0x24d2000 - 0x24f3000..........ok
288 04/09 searching 0x7fcc04baa000 - 0x7fcc04bae000..........ok
289 05/09 searching 0x7fcc04de1000 - 0x7fcc04de2000..........ok
290 06/09 searching 0x7fcc051f7000 - 0x7fcc051fb000..........ok
291 07/09 searching 0x7fcc05227000 - 0x7fcc0522a000..........ok
292 08/09 searching 0x7fcc0522c000 - 0x7fcc0522d000..........ok
293 09/09 searching 0x7ffc8c113000 - 0x7ffc8c134000..........ok
294 info: we currently have 16 matches.
295 16> list
296 [ 0] 7b09e0, 1 + 3b09e0, exe, 58, [I64 I32 I16 I8 ]
297 [ 1] 7b907a, 1 + 3b907a, exe, 58, [I8 ]
298 [ 2] 24d4b6c, 2 + 2b6c, heap, 58, [I16 I8 ]
299 [ 3] 24d567e, 2 + 367e, heap, 58, [I16 I8 ]
300 [ 4] 24d5740, 2 + 3740, heap, 58, [I8 ]
301 [ 5] 7fcc05229951, 6 + 2951, misc, 58, [I8 ]
302 [ 6] 7ffc8c12ee28, 8 + 1be28, stack, 58, [I16 I8 ]
303 [ 7] 7ffc8c132381, 8 + 1f381, stack, 58, [I8 ]
304 [ 8] 7ffc8c132389, 8 + 1f389, stack, 58, [I8 ]
305 [ 9] 7ffc8c132391, 8 + 1f391, stack, 58, [I8 ]
306 [10] 7ffc8c132399, 8 + 1f399, stack, 58, [I8 ]
307 [11] 7ffc8c1323a1, 8 + 1f3a1, stack, 58, [I8 ]
308 [12] 7ffc8c1323a9, 8 + 1f3a9, stack, 58, [I8 ]
309 [13] 7ffc8c1331a3, 8 + 201a3, stack, 58, [I8 ]
310 [14] 7ffc8c13325f, 8 + 2025f, stack, 58, [I8 ]
311 [15] 7ffc8c133264, 8 + 20264, stack, 58, [I8 ]
312 16>
313 16 potential matches were found. This is also displayed in the prompt.
315 Many of them are quite unrelated, as they are part of the stack, belong
316 to libraries or miscellaneous memory-mapped files. Even the heap is
317 unlikely for a very old command line game. We could make scanmem elimi‐
318 nate these manually using the delete command, however just waiting
319 until the amount of gold changes and telling scanmem the new value
320 should be enough. I find some more gold, and tell scanmem the new
321 value, 83.
322 16> 83
324 ..........info: we currently have 1 matches.
325 info: match identified, use "set" to modify value.
326 info: enter "help" for other commands.
327 1> list
328 [ 0] 7b09e0, 1 + 3b09e0, exe, 83, [I64 I32 I16 I8 ]
329 Only one of the 16 original candidates now has the value 83, so this
331 must be where the amount of gold is stored. I'll try setting it to
332 10,000 pieces.
333 1> set 10000
335 info: setting *0x7b09e0 to 0x2710...
336 1>
337 The resulting nethack status:
339 Dlvl:1 $:10000 HP:15(15) Pw:2(2) AC:7 Exp:1
341 Conclusion: We've found and modified the gold value as I32 in static
343 memory of the executable at virtual memory address 0x7b09e0. This
344 address belongs to the region with id 1.
345 Now it is important to know if this is a position-independent exe‐
347 cutable (PIE). We list the regions for this and check the load address
348 of the executable.
349 1> lregions
351 [ 0] 79f000, 69632 bytes, exe, 400000, rw-, /usr/lib/nethack/nethack.tty
352 [ 1] 7b0000, 114688 bytes, exe, 400000, rw-, unassociated
353 [ 2] 24d2000, 135168 bytes, heap, 24d2000, rw-, [heap]
354 [ 3] 7fcc04baa000, 16384 bytes, misc, 7fcc04baa000, rw-, unassociated
355 [ 4] 7fcc04de1000, 4096 bytes, misc, 7fcc04de1000, rw-, unassociated
356 [ 5] 7fcc051f7000, 16384 bytes, misc, 7fcc051f7000, rw-, unassociated
357 [ 6] 7fcc05227000, 12288 bytes, misc, 7fcc05227000, rw-, unassociated
358 [ 7] 7fcc0522c000, 4096 bytes, misc, 7fcc0522c000, rw-, unassociated
359 [ 8] 7ffc8c113000, 135168 bytes, stack, 7ffc8c113000, rw-, [stack]
360 We are on x86_64 and 0x400000 is the static load address for executa‐
362 bles there. This means that this is not a PIE and the gold is always
363 stored at 0x7b09e0. This makes it easy to use a game trainer like Game‐
364 Conqueror which refills the gold value periodically.
365 With a PIE we have to use the match offset (0x3b09e0 here) instead and
367 an advanced game trainer with PIE support has to determine and add the
368 current load address to it to get the current memory address of the
369 gold value of the current game run.
370
373 scanmem has been tested on multiple large programs, including the 3d
374 shoot-em-up quake3 linux. scanmem is also tested on ARM platforms and
375 comes with Android support since version 0.16.
376 Obviously, scanmem can crash your program if used incorrectly.
378 Some programs store values in multiple locations, this is why set will
380 change all known matches.
381 Address Space Layout Randomization (ASLR) together with position-inde‐
383 pendent executables (PIE), position-independent code (PIC) or dynamic
384 memory on the heap causes variables to be loaded to different memory
385 addresses at every game start. Advanced game trainers like ugtrain are
386 required to periodically refill variables is such memory regions.
387
390 scanmem usually requires root privileges for ptrace(2) because security
391 modules control ptrace() capabilities. On x86 and x86_64 there is usu‐
392 ally the Yama security module providing the file /proc/sys/ker‐
393 nel/yama/ptrace_scope. It is available since Linux 3.4. If this file
394 contains "1", then only parents may ptrace() their children without
395 root privileges. This means that scanmem would have to run the game.
396 This is not possible as this would require major design changes. So we
397 run scanmem as root.
398 The first scan can be very slow on large programs, this is not a prob‐
400 lem for subsequent scans as huge portions of the address space are usu‐
401 ally eliminated. This could be improved in future, perhaps by assuming
402 all integers are aligned by default. Suggestions welcome.
403 The snapshot command uses memory inefficiently, and should probably not
405 be used on large programs.
406
409 https://github.com/scanmem/scanmem
410
413 Tavis Ormandy <taviso(a)sdf.lonestar.org> http://taviso.decsystem.org/
414 Eli Dupree <elidupree(a)charter.net>
415 WANG Lu <coolwanglu(a)gmail.com>
416 Sebastian Parschauer <s.parschauer(a)gmx.de>
417 Andrea Stacchiotti <andreastacchiotti(a)gmail.com>
418 All bug reports, suggestions or feedback welcome.
420
423 gameconqueror(1) ptrace(2) proc(5) nethack(6) pidof(8)
424scanmem-0.17 2017-10-11 scanmem(1)