=head2 PHAROS OPTIONS

The following options are common to most pharos tools.

=over 4

=item B<--help>, B<-h>

Output program option help information and exit.

=item B<--verbose>=I<NUMBER>, B<-v>=I<NUMBER>

Set the verbosity of logging, 1-14.  (Default: 3) Level one is
additional warnings.  Level two is informational messages about
analysis progress.  Level three is the coarsest level of debugging.
Level four enables warnings during the analysis of functions.  Higher
numbers result in additional debugging messages.

=item B<--timing>

Print a running duration field in log messages.

=item B<--threads>=I<INTEGER>

Sets the number of threads the tool is allowed to use when analyzing
the program.  Whether any threads are actually used can vary by the
program in question.  If I<INTEGER> is positive, it declares the
number of threads to use.  If I<INTEGER> is zero, it will use one
thread per available processor.  If I<INTEGER> is negative, it will
use one thread per available processor less the absolute value of
I<INTEGER>.  At least one thread will always be used.  The default is
to run with only one thread.

When the number of threads is not one, per function memory limits are
disabled.

=item B<--batch>, B<-b>

Suppress terminal-based magic in output, such as colors, progress
bars, etc.

=item B<--allow-64bit>

Allow the analysis of 64-bit executables.  This option is currently
required as a "safety switch" to ensure that the user knows that
64-bit analysis has been tested less thoroughly than 32-bit analysis.

=item B<--include-func>=I<ADDRESS> B<-i>=I<ADDRESS>,

When analyzing an executable, only consider functions at location
I<ADDRESS>, which should be a hexadecimal number.  This option can be
specified multiple times.

=item B<--exclude-func>=I<ADDRESS>, B<-e>=I<ADDRESS>

When analyzing an executable, specifically do not consider any
function at location I<ADDRESS>, which should be a hexadecimal number.
This option can be specified multiple times.

=item B<--config>=I<PHAROS_CONFIG_FILE>, B<-C>=I<PHAROS_CONFIG_FILE>

Read configuration options from I<PHAROS_CONFIG_FILE> after reading
config options from the usual locations.  The usual locations are
C<I<$PHAROS_ROOT>/etc/pharos.yaml>, from any file contained
in the C<PHAROS_CONFIG> environment variable, and from
C<~/.pharos.yaml>.  This option can be specified multiple times.

Documentation for the format of I<PHAROS_CONFIG_FILE> can be found at
L<pharos.yaml(5)>.

=item B<--option>=I<KEY>=I<VALUE>

Set a pharos configuration file option from the command line.  The
I<KEY> value should be a dotted set of names describing the tree
structure to the value.  Example: C<--option pharos.timeout=900>

=item B<--dump-config>

After reading and merging configuration files, output the resulting
configuration information to stdout, then exit.

=item B<--no-user-file>

Do not read C<~/.pharos.yaml> when determining configuration options.

=item B<--no-site-file>

Do not read C<I<$PHAROS_ROOT>/etc/pharos.yaml> when
determining configuration options.

=item B<--apidb>=I<APIDB_FILE>

Use the specified SQLite database or JSON file in I<APIDB_FILE> as a
repository of API and type information.  This is a repeatable option,
with earlier files searched before later ones.  The built-in databases
will be checked after these.  If I<APIDB_FILE> is a relative file name
and does not exist relative to the current working directory, it will be
searched for relative to C<I<$PHAROS_ROOT>/share/pharos>.

=item B<--library>=I<DIR>, B<-l>=I<DIR>

Set the primary location that Pharos programs look for configuration
and API data.

=item B<--timeout>=I<TIMEOUT>

Set the execution timeout in seconds.  The pharos tool will usually exit
shortly after this limit is reached.  The default value is C<0>, which
indicates that there should be no timout.

=item B<--per-function-timeout>=I<TIMEOUT>

Set the maximum amount of CPU time in seconds that should be allocated
to the analysis of each function.  The Pharos tool will usually abort
the analysis of the current function and proceed to the next function
shortly after this limit is reached.  Skipping the analysis of
functions obviously reduces the accuracy of the results, but a few
functions are often the cause of the majority of analysis time.
Setting this value to a small value (tens of seconds) is often
preferable to setting an overall time limit since it allows the Pharos
tool to complete and produce incomplete results rather than nothing at
all when given limited resources.  The default value is 20 seconds.

=item B<--partitioner-timeout>=I<TIMEOUT>

Set the time limit in seconds for the function partitioning phase of the
analysis.  The default value is 0, which idicates that there should be
no limit.  This value should be smaller than the overall timeout to
leave time for function analysis.

=item B<--maximum-memory>=I<MEMSIZE>

Set the maximum memory usage in mibibytes.  The Pharos tool will
usually exit shortly after this limit is reached.  The default value
is 8000 mibibytes (about 8 gigabytes).

=item B<--per-function-maximum-memory>=I<MEMSIZE>

Set the maximum memory usage that should be permitted for each
function.  The Pharos tool will usually abort the analysis of the
current function and proceed to the next function shortly after this
limit is reached.  Skipping the analysis of functions obviously
reduces the accuracy of the results, but a few functions are often the
cause of the majority of the memory consumption.  Setting this value
to a small value (tens of mibibytes) is often preferable to setting an
overall memory limit since it allows the Pharos tool to complete and
produce incomplete results rather than nothing at all when given
limited resources.  The default value is 100 mibibytes.

Per function memory limits are disabled when running with more than
one thread.

=item B<--maximum-instructions-per-block>=I<NUMBER>

Set the maximum number of instructions allowed in a basic block before
aborting the analysis of a function.  This limit is primarily a safety
setting for degenerate situations where large blocks of data are
incorrectly interpreted as thousands of instructions.  The default
value is 3000 instructions.

=item B<--maximum-iterations-per-function>=I<NUMBER>

Set the maximum number of iterations over the control flow graph in a
function before aborting analysis of the function.  This limit is
primarily a safety setting for situations where the control flow graph
is malformed.  The default value is 3000 iterations.

=item B<--maximum-nodes-per-condition>=I<NUMBER>

Set the maximum number of nodes to handle in expressions before giving
up on keeping track of individual nodes.  This is primarily a safety
setting for degenerate situations when extremely large expressions are
generated.  The default value is 500 nodes.

=item B<--file>=I<EXECUTABLE_FILE>, B<-f>=I<EXECUTABLE_FILE>

Provides an alternative way to specify the executable to be analyzed
instead of using positional parameters.

=back

=head2 ROSE OPTIONS

These options are common to most Pharos tools, and configure
components present in ROSE, such as the function partitioner.

=over 4

=item B<--partitioner>=I<{pharos, rose, or superset}>

Use the specified function partitioning algorithm.  The supported
partitioners are "pharos", "rose", and "superset".

I<pharos>: This is the default and recommended partitioner.  It
extends the standard ROSE partitioner to make code speculatively in
undefined gaps between existing instructions.  This partitioner may
not be required if the program being analyzed is "normal software".

I<rose>: Use the stock (built into ROSE) version of the partitioner.
This will generally give less complete results, but will also take
less time to process the file.  The Pharos customized partitioner
sometimes takes very much longer than the stock ROSE partitioner, so
this option can be used to speed analysis if accuracy is not the top
priority.  This option can also be used to troubleshoot problems in
either partitioner by comparing the results from each.

I<superset>: This is an experimental disassembly algorithm that will
create an instruction for every byte in the program image.  It is not
generally suitable for analyzing programs at the current time because
it does not partition instructions into functions.

=item B<--serialize>=I<SERIALIZED_FILE>

Causes the results of the function partitioning step (including
disassembly) to be serialized to or from a file.  If
I<SERIALIZED_FILE> does not exit, the file will be written after the
function partitioning step completes.  If I<SERIALIZED_FILE> does
exist, it will be read instead of the usual function partitioning
analysis.  Because reading from a serialized file is usually much
faster than performing the analysis, this option can be used to reduce
processing times on files that are analyzed multiple times.

=item B<--ignore-serialize-version>

Process the file specified by B<--serialize>, even if the version
number of ROSE has changed since the serialization file was created.
By default, the Pharos tools will refuse to load files with mismatched
versions.  Because the version number is currently just a commit hash
and not a true version number for the serialization file format, this
option can be used to avoid needlessly regenerating serialization
files.  The recommended course of action is to remove the
serialization file and regenerate it with B<--serialize>.

=item B<--no-semantics>

Disable semantic analysis during partitioning.  By default the
function partitioner performs a limited semantic analysis to determine
which branches are never taken and propagate constants in limited
contexts.  This analysis typically increases the accuracy of the
disassembly and function partitioning.  These improvements are the
most dramatic when the analyzed executable contains assembly level
control flow obfuscations.  This analysis pass also increases the time
required to perform function partitioning.  Usually the increase is
reasonably small, but it can sometimes take a very long time.

=item B<--pdebug>

Enable debugging messages from the function partitioner.

=item B<--no-executable-entry>

Do B<not> automatically mark the segment containing the program entry
point as an executable segment.  By default Pharos tools will respect
the segment permissions in the analyzed executable file header except
that it will always mark the segment containing the program entry
point as executable.  When this option is specified and the segment
is not marked as executable in the file header, very little code is
likely to be found in the program.  Specifying this option will more
accurately reflect the file header segment permissions however.

=item B<--mark-executable>

Mark B<all> segments in the analyzed executable as possibly containing
code.  In other words, set the executable bit on all segments, even if
they are not set in the executable file header.  This option is
sometimes required for malformed executables that set their segment
permissions dynamically at run time.  Using this option in cases were
the segments are not correctly marked executable will reveal
additional legitimate code, but in the more usual cases will just
result in additional incorrect code detection.

=item B<--log>=I<LOG_CONTROL_STRING>

Use I<LOG_CONTROL_STRING> to determine what log messages are output.
These strings are documented in the Sawyer C++ library documentation,
under C<Message::Facilities::control()>.  While the full capability of
the log control string requires a BNF language specification to
describe, a useful example is:

  --log="APID(>=where),PLOG(all)"

This option enables messages at the "where" level and above in the API
database logging facility and all Prolog messages.  Logging facility
names are the first four characters (case sensitive) of log lines in
Pharos tools.  The logging levels are: error, warn, info, where,
debug, and trace.

=item B<--stockpart>

This option has been deprecated.  Please use B<--partitioner>=I<rose>
instead.

=item B<--rose-version>

Output the version of ROSE that the program was compiled against, and exit.

=back
