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 806 of file String.h.

#include <Rose/BinaryAnalysis/String.h>

Classes
struct	Settings
	Settings and properties. More...

Public Member Functions
	StringFinder ()
	Constructor.
StringFinder &	insertCommonEncoders (ByteOrder::Endianness)
	Inserts common encodings.
StringFinder &	insertUncommonEncoders (ByteOrder::Endianness)
	Inserts less common encodings.
StringFinder &	reset ()
	Reset analysis results.
StringFinder &	find (const MemoryMap::ConstConstraints &, Sawyer::Container::MatchFlags flags=0)
	Finds strings by searching memory.
std::ostream &	print (std::ostream &) const
	Print results.
const Settings &	settings () const
	Property: Analysis settings often set from a command-line.
Settings &	settings ()
	Property: Analysis settings often set from a command-line.
bool	discardingCodePoints () const
	Property: Whether to discard code points.
StringFinder &	discardingCodePoints (bool b)
	Property: Whether to discard code points.
const std::vector< StringEncodingScheme::Ptr > &	encoders () const
	Property: List of string encodings.
std::vector< StringEncodingScheme::Ptr > &	encoders ()
	Property: List of string encodings.
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.
static Sawyer::CommandLine::SwitchGroup	commandLineSwitches (Settings &)
	Command-line parser for analysis settings.

Constructor & Destructor Documentation

StringFinder()

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 861 of file String.h.

Member Function Documentation

settings() [1/2]

const Settings & Rose::BinaryAnalysis::Strings::StringFinder::settings ( ) const

inline

Property: Analysis settings often set from a command-line.

Definition at line 866 of file String.h.

settings() [2/2]

Settings & Rose::BinaryAnalysis::Strings::StringFinder::settings ( )

inline

Property: Analysis settings often set from a command-line.

Definition at line 867 of file String.h.

discardingCodePoints() [1/2]

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 877 of file String.h.

discardingCodePoints() [2/2]

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 878 of file String.h.

encoders() [1/2]

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 887 of file String.h.

encoders() [2/2]

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 888 of file String.h.

commandLineSwitches() [1/2]

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.

commandLineSwitches() [2/2]

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.

insertCommonEncoders()

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.

insertUncommonEncoders()

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.

reset()

StringFinder & Rose::BinaryAnalysis::Strings::StringFinder::reset ( )

inline

Reset analysis results.

Clears analysis results but does not change settings or properties.

Definition at line 929 of file String.h.

find()

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 = ...;
StringFinder sf;
sf.encoder(nulTerminatedPrintableAscii());
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();

strings() [1/2]

const std::vector< EncodedString > & Rose::BinaryAnalysis::Strings::StringFinder::strings ( ) const

inline

Obtain strings that were found.

Definition at line 964 of file String.h.

strings() [2/2]

std::vector< EncodedString > & Rose::BinaryAnalysis::Strings::StringFinder::strings ( )

inline

Obtain strings that were found.

Definition at line 965 of file String.h.

print()

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:

• String.h