ROSE  0.9.9.139
Classes | Public Member Functions | List of all members
Rose::BinaryAnalysis::Strings::StringFinder Class Reference

Description

Analysis to find encoded strings.

This analysis searches user-specified parts of a binary specimen's memory space to find strings encoded in various formats specfieid by the user.

See the Strings namespace for details.

Definition at line 802 of file BinaryString.h.

#include <BinaryString.h>

Classes

struct  Settings
 Settings and properties. More...
 

Public Member Functions

 StringFinder ()
 Constructor. More...
 
StringFinderinsertCommonEncoders (ByteOrder::Endianness)
 Inserts common encodings. More...
 
StringFinderinsertUncommonEncoders (ByteOrder::Endianness)
 Inserts less common encodings. More...
 
StringFinderreset ()
 Reset analysis results. More...
 
StringFinderfind (const MemoryMap::ConstConstraints &, Sawyer::Container::MatchFlags flags=0)
 Finds strings by searching memory. More...
 
std::ostream & print (std::ostream &) const
 Print results. More...
 
const Settingssettings () const
 Property: Analysis settings often set from a command-line.
 
Settingssettings ()
 Property: Analysis settings often set from a command-line.
 
bool discardingCodePoints () const
 Property: Whether to discard code points. More...
 
StringFinderdiscardingCodePoints (bool b)
 Property: Whether to discard code points. More...
 
const std::vector< StringEncodingScheme::Ptr > & encoders () const
 Property: List of string encodings. More...
 
std::vector< StringEncodingScheme::Ptr > & encoders ()
 Property: List of string encodings. More...
 
const std::vector< EncodedString > & strings () const
 Obtain strings that were found.
 
std::vector< EncodedString > & strings ()
 Obtain strings that were found.
 
Sawyer::CommandLine::SwitchGroup commandLineSwitches ()
 Command-line parser for analysis settings. More...
 
static Sawyer::CommandLine::SwitchGroup commandLineSwitches (Settings &)
 Command-line parser for analysis settings. More...
 

Constructor & Destructor Documentation

Rose::BinaryAnalysis::Strings::StringFinder::StringFinder ( )
inline

Constructor.

Initializes the analysis with default settings but no encoders. Encoders will need to be added before this analysis can be used to find any strings.

Definition at line 857 of file BinaryString.h.

Member Function Documentation

bool Rose::BinaryAnalysis::Strings::StringFinder::discardingCodePoints ( ) const
inline

Property: Whether to discard code points.

If this property is set, then the process of decoding strings does not actually store the code points (characters) of the string. This is useful when searching for lots of strings to reduce the amount of memory required. A string can be decoded again later if the code points are needed.

Definition at line 873 of file BinaryString.h.

StringFinder& Rose::BinaryAnalysis::Strings::StringFinder::discardingCodePoints ( bool  b)
inline

Property: Whether to discard code points.

If this property is set, then the process of decoding strings does not actually store the code points (characters) of the string. This is useful when searching for lots of strings to reduce the amount of memory required. A string can be decoded again later if the code points are needed.

Definition at line 874 of file BinaryString.h.

const std::vector<StringEncodingScheme::Ptr>& Rose::BinaryAnalysis::Strings::StringFinder::encoders ( ) const
inline

Property: List of string encodings.

When searching for strings, this analysis must know what kinds of strings to look for, and does that with a vector of pointers to encoders. The default is an empty vector, in which no strings will be found.

Definition at line 883 of file BinaryString.h.

std::vector<StringEncodingScheme::Ptr>& Rose::BinaryAnalysis::Strings::StringFinder::encoders ( )
inline

Property: List of string encodings.

When searching for strings, this analysis must know what kinds of strings to look for, and does that with a vector of pointers to encoders. The default is an empty vector, in which no strings will be found.

Definition at line 884 of file BinaryString.h.

static Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Strings::StringFinder::commandLineSwitches ( Settings )
static

Command-line parser for analysis settings.

Returns the switch group that describes the command-line switches for this analysis. The caller can provide a Settings object that will be adjusted when the command-line is parsed and applied; if no argument is supplied then the settings of this analysis are affected. In either case, the settings or analysis object must still be allocated when the command-line is parsed.

Sawyer::CommandLine::SwitchGroup Rose::BinaryAnalysis::Strings::StringFinder::commandLineSwitches ( )

Command-line parser for analysis settings.

Returns the switch group that describes the command-line switches for this analysis. The caller can provide a Settings object that will be adjusted when the command-line is parsed and applied; if no argument is supplied then the settings of this analysis are affected. In either case, the settings or analysis object must still be allocated when the command-line is parsed.

StringFinder& Rose::BinaryAnalysis::Strings::StringFinder::insertCommonEncoders ( ByteOrder::Endianness  )

Inserts common encodings.

Inserts the following string encodings into the analysis:

  • NUL-terminated, byte-encoded, printable ASCII characters.
  • NUL-terminated, 16-bit encoded, printable ASCII characters.
  • NUL-terminated, 32-bit encoded, printable ASCII characters.
  • 2-byte length-prefixed, byte encoded, printable ASCII characters.
  • 4-byte length-prefixed, byte encoded, printable ASCII characters.
  • 2-byte length-prefixed, 16-bit encoded, printable ASCII characters.
  • 4-byte length-prefixed, 16-bit encoded, printable ASCII characters.
  • 4-byte length-prefixed, 32-bit encoded, printable ASCII characters.

The specified endianness is used for all multi-byte values.

StringFinder& Rose::BinaryAnalysis::Strings::StringFinder::insertUncommonEncoders ( ByteOrder::Endianness  )

Inserts less common encodings.

Inserts the following string encodings into the analyses:

  • Printable ASCII terminated by other code points or non-readable memory.
StringFinder& Rose::BinaryAnalysis::Strings::StringFinder::reset ( )
inline

Reset analysis results.

Clears analysis results but does not change settings or properties.

Definition at line 925 of file BinaryString.h.

StringFinder& Rose::BinaryAnalysis::Strings::StringFinder::find ( const MemoryMap::ConstConstraints ,
Sawyer::Container::MatchFlags  flags = 0 
)

Finds strings by searching memory.

Clears previous analysis results (e.g., reset) and then searches for new strings. The resulting strings can be obtained from the strings method.

The memory constraints indicate where to search for strings, and the properties of this StringFinder class determine how to find strings. Specifically, this class must have at least one encoding registered in order to find anything (see encoders).

The search progresses by looking at each possible starting address using each registered encoding. The algorithm reads each byte from memory only one time, simultaneously attempting all encoders. If the MemoryMap constraint contains an anchor point (e.g., MemoryMap::at) then only strings starting at the specified address are returned.

Example 1: Find all C-style, NUL-terminated, ASCII strings contaiing only printable characters (no control characters) and containing at least five characters but not more than 31 (not counting the NUL terminator). Make sure that the string is in memory that is readable but not writable, and don't allow strings to overlap one another (i.e., "foobar" and "bar" cannot share their last for bytes):

using namespace Rose::BinaryAnalysis::String;
MemoryMap map = ...;
sf.settings().minLength = 5;
sf.settings().maxLength = 31;
sf.settings().allowOverlap = false;
std::vector<EncodedString> strings = sf.find(map.require(MemoryMap::READABLE).prohibit(MemoryMap::WRITABLE)).strings();
std::ostream& Rose::BinaryAnalysis::Strings::StringFinder::print ( std::ostream &  ) const

Print results.

Print information about each string, one string per line. Strings are displayed with C/C++ string syntax.


The documentation for this class was generated from the following file: