public interface

INativeCodeAnalyzer

com.pnfsoftware.jeb.core.units.code.asm.analyzer.INativeCodeAnalyzer<InsnType extends com.pnfsoftware.jeb.core.units.code.IInstruction>

Class Overview

Definition of a code analyzer. Typically, a code analyzer is instantiated by a code unit. Clients should not attempt to create such objects. There exists one implementation of this object, provided to clients by the INativeCodeUnit. This reference implementation supports partial concurrency: the analyze() method may be called by concurrent threads.

An analysis pass consists of several passes:
- standard analysis (always)
- advanced analysis (optional - in settings -, relies on decompilation)
- global analysis (optional, plugin-specific, may rely on decompilation)

Summary

Constants
int FLAG_CALLEE_DIRTY_ANALYSIS The analyzer should analyze callee routines with PERMISSION_DIRTY, whatever the caller's permission is.
int FLAG_CALLEE_FORCEFUL_ANALYSIS The analyzer should analyze callee routines with PERMISSION_FORCEFUL, whatever the caller's permission is.
int FLAG_CALLEE_GENTLE_ANALYSIS The analyzer should analyze callee routines with PERMISSION_GENTLE, whatever the caller's permission is.
int FLAG_CODE_CONTIGUOUS The analyzer should parse the routine instructions sequentially.
int FLAG_NO_CACHES_CHECK The analyzer should not check for previously cached results (internal use only).
int FLAG_NO_MERGE The analyzer will not merge the newly created routine into another routine.
int FLAG_NO_ROUTINE The analyzer will not create a routine
int FLAG_TRANSIENT The analyzer should consider data/routine as meaningless (no cache, faster).
int PERMISSION_DIRTY The analyzer may undefine items as well as pre-existing routines

Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.
int PERMISSION_FORCEFUL The analyzer may undefine existing overlapping instruction or data items if necessary

Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.
int PERMISSION_GENTLE The analyzer does not undefine existing items.
int PERMISSION_GOD_MODE The analyzer may undefine items as well as pre-existing routines.
Public Methods
abstract void analyze()
Start an analysis pass.
abstract void analyze(boolean preventAdvancedAnalysis, boolean preventSiglibMatch)
Start an analysis pass.
abstract boolean clearAnalysisQueue()
abstract INativeDataItem defineData(long address, INativeType type)
abstract INativeDataItem defineData(long address, INativeType type, int appliedSize)
abstract boolean enqueuePointerForAnalysis(PointerDescription pointer, int permission, int flags)
Register a pointer (code or data) for analysis.
abstract boolean enqueuePointerForAnalysis(PointerDescription pointer, int permission)
Register a pointer (code or data) for analysis.
abstract boolean enqueuePointerForAnalysis(PointerDescription pointer)
Register a pointer (code or data) for a gentle analysis.
abstract boolean enqueueRoutineForReanalysis(INativeMethodItem routine)
Enqueue an existing routine for reanalysis.
abstract INativeCodeAdvancedAnalyzer<InsnType> getAdvancedAnalyzer()
Retrieve a reference to the optional advanced analyzer object.
abstract int getAnalysisCount()
Get the number of times a code analysis was performed.
abstract MemoryRanges getAnalysisRanges()
Retrieve a reference to the memory ranges that the analyzer works on.
abstract INativeCodeAnalyzerExtension<InsnType> getAnalyzerExtensionsManager()
Retrieve a reference to the analyzer extensions manager.
abstract ICodeObjectUnit getContainer()
Retrieve a reference to the optional code object container that holds the code to be analyzed.
abstract DebugInformationPolicy getDebugInformationPolicy()
Retrieve the debug information policy that this code analyzer is using.
abstract ICompiler getDetectedCompiler()
Get the compiler detected when analyzing the input file.
abstract IVirtualMemory getMemory()
Retrieve a reference to the virtual memory.
abstract INativeCodeModel<InsnType> getModel()
Get the memory model managed by this analyzer.
abstract IProcessor<InsnType> getProcessor()
Retrieve a reference to the machine code processor.
abstract ITypeManager getTypeManager()
Get a reference to the type manager.
abstract UnmanglerService getUnmanglerService()
Retrieve the unmangler service (managing name-unmanging engines) used by this analyzer.
abstract boolean isAnalyzing()
Determine if an analysis is already taking place, possibly in another thread.
abstract boolean needsAnalysis()
Determine if an analysis pass is required.
abstract boolean recordAnalysisComment(long address, String comment)
Record a meta-comment generated during the analysis.
abstract boolean recordDynamicBranchTarget(long instructionAddress, boolean resolved, IBranchTarget target, boolean prepareAnalysis)
Record branch resolutions for dynamic callsites.
abstract boolean recordDynamicRegisterValue(long instructionAddress, boolean postExec, long register, long value)
abstract void requestAnalysisInterruption()
Request the interruption of the current analysis pass.
abstract boolean unrecordDynamicBranchTarget(long instructionAddress, boolean resolved, IBranchTarget target)
Unrecord a branch resolution.

Constants

public static final int FLAG_CALLEE_DIRTY_ANALYSIS

The analyzer should analyze callee routines with PERMISSION_DIRTY, whatever the caller's permission is.

Constant Value: 16 (0x00000010)

public static final int FLAG_CALLEE_FORCEFUL_ANALYSIS

The analyzer should analyze callee routines with PERMISSION_FORCEFUL, whatever the caller's permission is.

Constant Value: 8 (0x00000008)

public static final int FLAG_CALLEE_GENTLE_ANALYSIS

The analyzer should analyze callee routines with PERMISSION_GENTLE, whatever the caller's permission is.

Constant Value: 4 (0x00000004)

public static final int FLAG_CODE_CONTIGUOUS

The analyzer should parse the routine instructions sequentially. The routine is contiguous in memory, there is no instruction gap, and its size is known and stored in the high 24-bits of the flags.

Constant Value: 2 (0x00000002)

public static final int FLAG_NO_CACHES_CHECK

The analyzer should not check for previously cached results (internal use only).

Constant Value: 32 (0x00000020)

public static final int FLAG_NO_MERGE

The analyzer will not merge the newly created routine into another routine.

Constant Value: 64 (0x00000040)

public static final int FLAG_NO_ROUTINE

The analyzer will not create a routine

Constant Value: 1 (0x00000001)

public static final int FLAG_TRANSIENT

The analyzer should consider data/routine as meaningless (no cache, faster). This can be used for mass data.

Constant Value: 4096 (0x00001000)

public static final int PERMISSION_DIRTY

The analyzer may undefine items as well as pre-existing routines

Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.

Constant Value: 2 (0x00000002)

public static final int PERMISSION_FORCEFUL

The analyzer may undefine existing overlapping instruction or data items if necessary

Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.

Constant Value: 1 (0x00000001)

public static final int PERMISSION_GENTLE

The analyzer does not undefine existing items.

Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.

Constant Value: 0 (0x00000000)

public static final int PERMISSION_GOD_MODE

The analyzer may undefine items as well as pre-existing routines. This permission bypasses all analysis safeguards, and should be used with caution: keep this for user-defined entry-points.

Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.

Constant Value: 3 (0x00000003)

Public Methods

public abstract void analyze ()

Start an analysis pass. Analyze the entry points that were previously registered, create new routines and data items, etc.

public abstract void analyze (boolean preventAdvancedAnalysis, boolean preventSiglibMatch)

Start an analysis pass. Analyze the entry points that were previously registered, create new routines and data items, etc.

Parameters
preventAdvancedAnalysis if true, AA will be prevented no matter what
preventSiglibMatch if true, siglibs application will not be prevented, no matter what

public abstract boolean clearAnalysisQueue ()

public abstract INativeDataItem defineData (long address, INativeType type)

public abstract INativeDataItem defineData (long address, INativeType type, int appliedSize)

public abstract boolean enqueuePointerForAnalysis (PointerDescription pointer, int permission, int flags)

Register a pointer (code or data) for analysis.

Parameters
pointer code or data pointer; code pointers must be of type IEntryPointDescription
permission analysis permission type, one of PERMISSION_GENTLE (0), PERMISSION_FORCEFUL, or PERMISSION_DIRTY
flags analysis flags, a combination any FLAG_xxx entry (currently: FLAG_NO_ROUTINE)
Returns
  • success indicator (pointer was/not enqueued)

public abstract boolean enqueuePointerForAnalysis (PointerDescription pointer, int permission)

Register a pointer (code or data) for analysis. If the pointer is a code pointer, a routine may be created.

Parameters
pointer code or data pointer; code pointers must be of type IEntryPointDescription
permission analysis permission type, one of PERMISSION_GENTLE (0), PERMISSION_FORCEFUL, or PERMISSION_DIRTY
Returns
  • success indicator (pointer was/not enqueued)

public abstract boolean enqueuePointerForAnalysis (PointerDescription pointer)

Register a pointer (code or data) for a gentle analysis.

Parameters
pointer code or data pointer; code pointers must be of type IEntryPointDescription
Returns
  • success indicator (pointer was/not enqueued)

public abstract boolean enqueueRoutineForReanalysis (INativeMethodItem routine)

Enqueue an existing routine for reanalysis.

Parameters
routine method to be reanalyzed (in DIRTY mode)
Returns
  • success indicator (pointer was/not enqueued)

public abstract INativeCodeAdvancedAnalyzer<InsnType> getAdvancedAnalyzer ()

Retrieve a reference to the optional advanced analyzer object.

Returns
  • may be null

public abstract int getAnalysisCount ()

Get the number of times a code analysis was performed.

Returns
  • the number of times analyze() was called and has terminated

public abstract MemoryRanges getAnalysisRanges ()

Retrieve a reference to the memory ranges that the analyzer works on.

public abstract INativeCodeAnalyzerExtension<InsnType> getAnalyzerExtensionsManager ()

Retrieve a reference to the analyzer extensions manager. It manages extensions with architecture-specific or compiler-specific analysis routines.

public abstract ICodeObjectUnit getContainer ()

Retrieve a reference to the optional code object container that holds the code to be analyzed.

public abstract DebugInformationPolicy getDebugInformationPolicy ()

Retrieve the debug information policy that this code analyzer is using. The analyzer and its extensions, when using debug metadata, should respect this policy.

Returns
  • a policy object

public abstract ICompiler getDetectedCompiler ()

Get the compiler detected when analyzing the input file.

Returns
  • may be null

public abstract IVirtualMemory getMemory ()

Retrieve a reference to the virtual memory.

public abstract INativeCodeModel<InsnType> getModel ()

Get the memory model managed by this analyzer.

Returns
  • the memory model

public abstract IProcessor<InsnType> getProcessor ()

Retrieve a reference to the machine code processor.

public abstract ITypeManager getTypeManager ()

Get a reference to the type manager.

public abstract UnmanglerService getUnmanglerService ()

Retrieve the unmangler service (managing name-unmanging engines) used by this analyzer.

public abstract boolean isAnalyzing ()

Determine if an analysis is already taking place, possibly in another thread. This method is purely indicative, and can be used by clients to minimize unnecessary blocking. The result offers no guarantee: by the time client code examines the boolean return value, another thread may have finished an existing or started a new analysis.

public abstract boolean needsAnalysis ()

Determine if an analysis pass is required.

public abstract boolean recordAnalysisComment (long address, String comment)

Record a meta-comment generated during the analysis. The meta-comment is flagless. This method does not notify.

Parameters
address memory address
comment comment string
Returns
  • success indicator

public abstract boolean recordDynamicBranchTarget (long instructionAddress, boolean resolved, IBranchTarget target, boolean prepareAnalysis)

Record branch resolutions for dynamic callsites.

Parameters
instructionAddress the address of a branching instruction making use of a dynamic callsite
resolved true if the target if a true resolution, false if the target is one candidate among possibly many candidate targets
target the target, not null
prepareAnalysis if true, the method may decide to enqueue the target for routine analysis; the decision process depends on whether the instruction is a flow break, call-to-sub, or none, as well as other parameters like whether the added callsite was already known
Returns
  • true if the target was truly added (no duplicate, no error), false otherwise

public abstract boolean recordDynamicRegisterValue (long instructionAddress, boolean postExec, long register, long value)

public abstract void requestAnalysisInterruption ()

Request the interruption of the current analysis pass. The interruption may not happen immediately. Client code may use isAnalyzing() to determine whether the analysis has stopped.

public abstract boolean unrecordDynamicBranchTarget (long instructionAddress, boolean resolved, IBranchTarget target)

Unrecord a branch resolution. Unlike recordDynamicBranchTarget(long, boolean, IBranchTarget, boolean), this call does not trigger a new analysis pass.