Execution options - projectbtle/argXtract GitHub Wiki

To use argXtract, navigate to the project folder and execute python start.py <options> from the commandline. All possible options are given below.

usage: start.py [-h] (-d DIRECTORY | -f FILE | -l LIST) [-c [{c,e,w,i,d,t}]] [-b] [-t TIME] [-m MAX_CALL_DEPTH] -M
                [{s,f}] [-v VENDOR] [-p PROCESSES]]

optional arguments:
  -h, --help            show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        directory containing firmware files to be analysed. Provide absolute path to directory as argument.
  -f FILE, --file FILE  individual firmware file to be analysed.
  -l LIST, --list LIST  text file containing absolute paths of firmware files to be analysed.
  -c [{c,e,w,i,d,t}], --console [{c,e,w,i,d,t}]
                        console log level. One of c (critical), e (error), w (warning), i (info), d (debug), t (trace).
  -b, --bypass          bypass all conditional checks.
  -t TIME_PER_TRACE, --time_per_trace TIME_PER_TRACE
                        maximum trace time per file, per start point in seconds.
  -T TIME, --Time TIME  maximum trace time per file in seconds.
  -M [{s,f}], --Mode [{s,f}]
                        analysis mode. Either s (SVC) or f (function).
  -v VENDOR, --vendor VENDOR
                        the vendor/chipset to test against. Vendor-specific files must be added to the repo.
  -p PROCESSES, --processes PROCESSES
                        number of parallel processes ("threads") to use.
  -F FUNCTIONS, --Functions FUNCTIONS
                        save function list to folder and exit.
  -a APP_CODE_BASE, --app_code_base APP_CODE_BASE
                        address at which application should be loaded.
  -m MAX_CALL_DEPTH, --max_call_depth MAX_CALL_DEPTH
                        maximum call depth of a function to be included in trace.
  -n [{n,l,s}], --null [{n,l,s}]
                        mechanism for handling null values (mainly those in LDR). One of n (none - do nothing), l (loose - keep track when LDR attempts to load from outside RAM), s (strict - keep track when LDR attempts to load from any inaccessible memory location).

Most of the commandline options are pretty self-explanatory. But let's explain them all, to be on the safe side :)

Print usage instructions (essentially, what you see above) and exit.

If you want to analyse a single binary file, then use this option and specify the absolute or relative path to the file. Note that this cannot be used in conjunction with the -d or -l options.

If you want to analyse all binaries within a directory, use this option and specify the absolute or relative path to the directory. Note that this cannot be used in conjunction with the -f or -l options.

If you want to analyse a number of binaries whose absolute addresses are specified within a list, use this option and specify the absolute or relative path to the list. Note that this cannot be used in conjunction with the -f or -d options.

The analysis mode. Can be one of s (for Supervisor Call) or f (for normal function calls). Function mode takes a long time due to the need for performing function pattern matching.

The binaries you analyse must match a certain technology/chipset vendor. If they don't, you won't get usable outputs. To use argXtract you must either provide vendor/technology-specific defintion files or use the ones we have provided.

The maximum amount of time in seconds to spend in tracing a single call execution path within a binary. One binary file may have a number of calls to a function of interest. Or there may be different paths to get to a single function call. Each of these will be traced individually, as a call execution path. Sometimes, argXtract can spend a long time trying to trace a single path, which may waste time and resources and may still not produce results. By limiting the time spent on a single trace, you can potentially improve the chances of getting some output within a reasonable timeframe.

The maximum amount of time in seconds to spend analysing a single binary. This is regardless of whether or not --time-per-trace is used. So, if you specify -t 100 -T 1000, the tool will spend at most 100 seconds on a single trace within a file and at most 1000 seconds altogether for a file.

To speed things up, you can run a number of parallel threads and share the workload across the threads. Note that analysis of a single binary will always occur within a single thread.

Many functions call other functions, which in turn may call still more functions. This is denoted within argXtract as call-depth. Analysing a function with a high call-depth can take a very long time as all called functions may also need to be analysed. To speed up execution time, you can specify a low value for the max-call-depth to analyse. We've found 1 and even 0 to work well. However, this will depend very much on the use case. Note that this will not prevent a function that is on a call execution path from being analysed.

By default, we only log messages from INFO and above (i.e., INFO, WARNING, ERROR, CRITICAL). If you want to get additional debugging info, use -c d. For the maximum level of logging, use -c t (trace). This will output the disassembled instructions, etc., and is probably too much logging for most situation.

If you know the application code base (i.e., offset), at which a binary should be loaded, then you can save some processing time by providing argXtract with that information. This can also help when a binary file is complex and argXtract is unable to estimate the code base.

If you only want to know the locations of function boundaries (i.e., the starting addresses of functions) as estimated by argXtract, you can use this option. You need to specify where the output will be saved as the argument.

Occasionally (perhaps more frequently than occasionally), a binary's instructions will indicate loading of data from some source that is not accessible to argXtract, e.g., NVRAM. This will not matter as long as the function of interest is not impacted by this value or by any conditional checks that act upon the value. But if it is, you can use -n with either l (loose) or s (strict) null value handling. Essentially, what happens with these options is, argXtract keeps track of when values are "loaded" from inaccessible locations. If a conditional check is made on such values, argXtract doesn't evaluate the condition, but instead executed both paths. This can increase processing time quite a bit.

By default, argXtract maintains conditional flags, updates them with each instruction execution, and follows conditional branches and instructions based on the outcome of evaluating the conditional check. If you want to instead follow all possible branches regardless of whether the conditions are satisfied, use this option (no argument is needed. Just use -b). This can significantly increase processing time and result in large output files (because the same value may be replicated multiple times).