`Pro.Strings` — API for string detection¶

Overview¶

The Pro.Strings module contains the API for detecting strings in binary data.

The two main classes of this module are Pro.Strings.StringScanner and Pro.Strings.MultiStringScanner. The difference between them is that the former is a low-level scanner capable of scanning strings using a single configuration, while the latter can scan strings using multiple configurations. In addition, it efficiently stores the results in an internal database and provides filtering capabilities.

Generally, it is always preferrable to use Pro.Strings.MultiStringScanner, especially when scanning large blobs of data.

Low-Level String Scanning¶

What follows is an example showing how to use Pro.Strings.StringScanner:

from Pro.Core import *
from Pro.Strings import *

def callback(offset, size, c):
    buf = c.read(offset, size)
    print(buf.decode("utf-8", errors="replace"))
    return 0

def detectStrings(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    sc = StringScanner()
    sc.setMinimumLength(4)
    sc.setCallback(callback, c)
    n = sc.scan(c, "english", "utf-8")
    print("result:", n)

Multi-Configuration String Scanning & Filtering¶

What follows is an example demonstrating how to use Pro.Strings.MultiStringScanner. The example not only scans for strings using multiple configurations, but also filters them with a regular expression for email addresses and retrieves the results from the internal database.

from Pro.Core import *
from Pro.UI import *
from Pro.Strings import *

def detectStrings(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    wo = proContext().startWait("Scanning...")
    sc = MultiStringScanner()
    sc.setData(c)
    sc.addOptions(StringScanOptions(4, "utf-8", "english"))
    sc.addOptions(StringScanOptions(4, "utf-16", "english"))
    sc.setWaitObject(wo)
    sc.scan()
    wo.msg("Filtering...")
    sc.filter(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}", TextFilterOption_RegularExpression)
    wo.stop()
    n = sc.count()
    print("result:", n)
    for i in range(n):
        si = sc.getEntry(i)
        print(si.text)

Module API¶

Pro.Strings module API.

Classes:

MultiStringScanner()

High-level scanner that searches for strings using multiple StringScanOptions configurations and efficiently stores the results into an internal database.

StringScanEntry()

Represents a single string found during scanning.

StringScanOptions(min_len, encoding, lang, flags)

Configuration object describing how strings should be detected.

StringScanner()

Low-level scanner for detecting strings.

class MultiStringScanner¶

High-level scanner that searches for strings using multiple StringScanOptions configurations and efficiently stores the results into an internal database.

Internally this class uses StringScanner.

Methods:

addOptions(options)

Adds a scanning configuration.

count()

Retrieves the number of string entries detected (after scanning and optional filtering).

filter(pattern[, options])

Applies a pattern filter to the scanned strings.

getEntry(i)

Retrieves a specific string entry.

resetFilter()

Clears any previously applied filter so that all scanned string entries become visible again.

scan()

Executes the string scanning process.

setData(data)

Sets the data to scan.

setObject(obj)

Sets an object as a location provider for the scan.

setWaitObject(wo)

Sets a wait object used to support cancellation or progress reporting during long scanning operations.

addOptions(options: Pro.Strings.StringScanOptions) → None¶

Adds a scanning configuration.

Multiple configurations can be added to detect different encodings, languages, or minimum lengths.

Parameters

options (StringScanOptions) – The scanning options to add.

count() → int¶

Retrieves the number of string entries detected (after scanning and optional filtering).

Returns

Returns the number of string results.

Return type

int

See also getEntry().

filter(pattern: str, options: int = 0) → bool¶

Applies a pattern filter to the scanned strings.

Only strings matching the provided pattern remain visible after filtering.

Parameters

pattern (str) – The search pattern or substring to match.

options (int) – Optional pattern matching flags (e.g., Pro.Core.TextFilterOption_CaseSensitive).

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also resetFilter().

getEntry(i: int) → Pro.Strings.StringScanEntry ¶

Retrieves a specific string entry.

Parameters

i (int) – Zero-based index of the entry.

Returns

Returns the string scan entry.

Return type

StringScanEntry

See also count() and StringScanEntry.

resetFilter() → None¶

Clears any previously applied filter so that all scanned string entries become visible again.

See also filter().

scan() → bool¶

Executes the string scanning process.

The scan uses all previously added StringScanOptions configurations.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also count() and getEntry().

setData(data: Pro.Core.NTContainer) → None¶

Sets the data to scan.

Parameters

data (NTContainer) – The container containing binary data.

setObject(obj: Pro.Core.CFFObject) → None¶

Sets an object as a location provider for the scan.

The scanner will use this only for binaries.

Parameters

obj (CFFObject) – The object.

setWaitObject(wo: Pro.Core.NTIWait) → None¶

Sets a wait object used to support cancellation or progress reporting during long scanning operations.

Parameters

wo (NTIWait) – The wait object.

class StringScanEntry¶

Represents a single string found during scanning.

Attributes:

location

The location of the string.

offset

The byte offset where the string begins.

optidx

Index of the StringScanOptions configuration that detected the string.

size

The length of the string in bytes.

text

The decoded string value.

location¶

The location of the string.

offset¶

The byte offset where the string begins.

optidx¶

Index of the StringScanOptions configuration that detected the string.

size¶

The length of the string in bytes.

text¶

The decoded string value.

class StringScanOptions(min_len: int, encoding: str, lang: str = str(), flags: int = 0)¶

Configuration object describing how strings should be detected.

See also MultiStringScanner.addOptions().

Initializes scanning options.

Parameters

min_len (int) – Minimum number of characters required for a string match.

encoding (str) – Character encoding used when decoding strings.

lang (str) – Language identifier used for filtering.

flags (int) – Optional scanning flags (e.g., StringScanner.ZERO_TERMINATED_ONLY).

Attributes:

encoding

The character encoding used to decode strings (e.g., "utf-8", "utf-16").

flags

Optional scanning flags controlling behavior.

lang

Language identifier.

min_len

Minimum string length required for detection.

encoding¶

The character encoding used to decode strings (e.g., "utf-8", "utf-16").

flags¶

Optional scanning flags controlling behavior.

lang¶

Language identifier.

Supported languages are: "arabic", "chinese", "greek", "hindi", "icelandic", "japanese", "korean", "nepali", "russian", "thai", "ukrainian", "vietnamese".

min_len¶

Minimum string length required for detection.
class StringScanner¶
Low-level scanner for detecting strings.

Attributes:

ZERO_TERMINATED_ONLY

Restricts detection to zero-terminated strings only.

Methods:

scan(data, lang, encoding)

Performs string scanning on the specified container.

setCallback(cb, ud)

Sets a callback function invoked when a string is found.

setFlags(flags)

Configures scanner behavior flags.

setMinimumLength(len)

Sets the minimum string length required for detection.

setWaitObject(wo)

Sets a wait object used to support cancellation or progress reporting during long scanning operations.

ZERO_TERMINATED_ONLY: Final[int]¶

Restricts detection to zero-terminated strings only.

scan(data: Pro.Core.NTContainer, lang: str, encoding: str) → int¶

Performs string scanning on the specified container.

Parameters

data (NTContainer) – The data to scan.

lang (str) – Language identifier used during detection.

encoding (str) – Encoding used to interpret characters.

Returns

Returns the number of strings detected.

Return type

int

See also setCallback().
setCallback(cb: object, ud: object) → None¶
Sets a callback function invoked when a string is found.

The callback must return a non-zero value to interrupt the scanning.
def callback(offset, size, ud):
    buf = c.read(offset, size)
    print(buf.decode("utf-8", errors="replace"))
    return 0
Parameters

cb (object) – The callback function.

ud (object) – User-defined data passed to the callback.
setFlags(flags: int) → None¶

Configures scanner behavior flags.

Parameters

flags (int) – Scanner flags such as ZERO_TERMINATED_ONLY.

See also setMinimumLength().

setMinimumLength(len: int) → None¶

Sets the minimum string length required for detection.

Parameters

len (int) – Minimum number of characters.

See also setFlags().

setWaitObject(wo: Pro.Core.NTIWait) → None¶

Sets a wait object used to support cancellation or progress reporting during long scanning operations.

Parameters

wo (NTIWait) – The wait object.

Pro.Strings — API for string detection¶

Overview¶

Low-Level String Scanning¶

Multi-Configuration String Scanning & Filtering¶

Module API¶

`Pro.Strings` — API for string detection¶