Interface INativeCodeAnalyzer<InsnType extends IInstruction>
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 sub-passes:
- standard analysis (always)
- advanced analysis (optional - in settings -, relies on decompilation)
- global analysis (optional, plugin-specific, may rely on decompilation)
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
The analyzer should analyze callee routines withPERMISSION_DIRTY
, whatever the caller's permission is.static final int
The analyzer should analyze callee routines withPERMISSION_FORCEFUL
, whatever the caller's permission is.static final int
The analyzer should analyze callee routines withPERMISSION_GENTLE
, whatever the caller's permission is.static final int
The analyzer should parse the routine instructions sequentially.static final int
The analyzer should not check for previously cached results (internal use only).static final int
The analyzer will not merge the newly created routine into another routine.static final int
The analyzer will not create a routinestatic final int
The analyzer should consider data/routine as meaningless (no cache, faster).static final int
The analyzer may undefine items as well as pre-existing routinesstatic final int
The analyzer may undefine existing overlapping instruction or data items if necessarystatic final int
The analyzer does not undefine existing items.static final int
The analyzer may undefine items as well as pre-existing routines. -
Method Summary
Modifier and TypeMethodDescriptionvoid
analyze()
Start an analysis pass.void
analyze
(boolean preventAdvancedAnalysis, boolean preventSiglibMatch) Start an analysis pass.boolean
defineData
(long address, INativeType type) defineData
(long address, INativeType type, int appliedSize) boolean
enqueuePointerForAnalysis
(Pointer pointer) Register a pointer (code or data) for agentle analysis
.boolean
enqueuePointerForAnalysis
(Pointer pointer, int permission) Register a pointer (code or data) for analysis.boolean
enqueuePointerForAnalysis
(Pointer pointer, int permission, int flags) Register a pointer (code or data) for analysis.boolean
Enqueue an existing routine for reanalysis.Retrieve a reference to the optional advanced analyzer object.int
Get the number of times a code analysis was performed.Retrieve a reference to the memory ranges that the analyzer works on.Retrieve a reference to the analyzer extensions manager.Retrieve a reference to the optional code object container that holds the code to be analyzed.Retrieve the debug information policy that this code analyzer is using.Get the compiler detected when analyzing the input file.Retrieve a reference to the virtual memory.getModel()
Get the memory model managed by this analyzer.Retrieve a reference to the machine code processor.Get a reference to the type manager.Retrieve the unmangler service (managing name-unmanging engines) used by this analyzer.boolean
Determine if an analysis is already taking place, possibly in another thread.boolean
Determine if an analysis pass is required.boolean
recordAnalysisComment
(long address, String comment) Record a meta-comment generated during the analysis.boolean
recordDynamicBranchTarget
(long instructionAddress, boolean resolved, IBranchTarget target, boolean prepareAnalysis) Record branch resolutions for dynamic callsites.boolean
recordDynamicRegisterValue
(long instructionAddress, boolean postExec, long register, long value) void
Request the interruption of the current analysis pass.boolean
unrecordDynamicBranchTarget
(long instructionAddress, boolean resolved, IBranchTarget target) Unrecord a branch resolution.
-
Field Details
-
PERMISSION_GENTLE
static final int PERMISSION_GENTLEThe analyzer does not undefine existing items.Note: PERMISSION_* values are integers ordered from the least permissive to the most permissive.
- See Also:
-
PERMISSION_FORCEFUL
static final int PERMISSION_FORCEFULThe analyzer may undefine existing overlapping instruction or data items if necessaryNote: PERMISSION_* values are integers ordered from the least permissive to the most permissive.
- See Also:
-
PERMISSION_DIRTY
static final int PERMISSION_DIRTYThe analyzer may undefine items as well as pre-existing routinesNote: PERMISSION_* values are integers ordered from the least permissive to the most permissive.
- See Also:
-
PERMISSION_GOD_MODE
static final int PERMISSION_GOD_MODEThe 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.
- See Also:
-
FLAG_NO_ROUTINE
static final int FLAG_NO_ROUTINEThe analyzer will not create a routine- See Also:
-
FLAG_CODE_CONTIGUOUS
static final int FLAG_CODE_CONTIGUOUSThe 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.- See Also:
-
FLAG_CALLEE_GENTLE_ANALYSIS
static final int FLAG_CALLEE_GENTLE_ANALYSISThe analyzer should analyze callee routines withPERMISSION_GENTLE
, whatever the caller's permission is.- See Also:
-
FLAG_CALLEE_FORCEFUL_ANALYSIS
static final int FLAG_CALLEE_FORCEFUL_ANALYSISThe analyzer should analyze callee routines withPERMISSION_FORCEFUL
, whatever the caller's permission is.- See Also:
-
FLAG_CALLEE_DIRTY_ANALYSIS
static final int FLAG_CALLEE_DIRTY_ANALYSISThe analyzer should analyze callee routines withPERMISSION_DIRTY
, whatever the caller's permission is.- See Also:
-
FLAG_NO_CACHES_CHECK
static final int FLAG_NO_CACHES_CHECKThe analyzer should not check for previously cached results (internal use only).- See Also:
-
FLAG_NO_MERGE
static final int FLAG_NO_MERGEThe analyzer will not merge the newly created routine into another routine.- See Also:
-
FLAG_TRANSIENT
static final int FLAG_TRANSIENTThe analyzer should consider data/routine as meaningless (no cache, faster). This can be used for mass data.- See Also:
-
-
Method Details
-
getProcessor
IProcessor<InsnType> getProcessor()Retrieve a reference to the machine code processor.- Returns:
-
getMemory
IVirtualMemory getMemory()Retrieve a reference to the virtual memory.- Returns:
-
getContainer
ICodeObjectUnit getContainer()Retrieve a reference to the optional code object container that holds the code to be analyzed.- Returns:
-
getAnalysisRanges
MemoryRanges getAnalysisRanges()Retrieve a reference to the memory ranges that the analyzer works on.- Returns:
-
getTypeManager
ITypeManager getTypeManager()Get a reference to the type manager.- Returns:
-
getModel
INativeCodeModel<InsnType> getModel()Get the memory model managed by this analyzer.- Returns:
- the memory model
-
getAdvancedAnalyzer
INativeCodeAdvancedAnalyzer<InsnType> getAdvancedAnalyzer()Retrieve a reference to the optional advanced analyzer object.- Returns:
- may be null
-
getAnalyzerExtensionsManager
INativeCodeAnalyzerExtension<InsnType> getAnalyzerExtensionsManager()Retrieve a reference to the analyzer extensions manager. It manages extensions with architecture-specific or compiler-specific analysis routines.- Returns:
-
getUnmanglerService
UnmanglerService getUnmanglerService()Retrieve the unmangler service (managing name-unmanging engines) used by this analyzer.- Returns:
-
getDetectedCompiler
ICompiler getDetectedCompiler()Get the compiler detected when analyzing the input file.- Returns:
- may be null
-
getDebugInformationPolicy
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
-
enqueuePointerForAnalysis
Register a pointer (code or data) for agentle analysis
.- Parameters:
pointer
- code or data pointer; code pointers must be of typeICodePointer
- Returns:
- success indicator (pointer was/not enqueued)
-
enqueuePointerForAnalysis
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 typeICodePointer
permission
- analysis permission type, one ofPERMISSION_GENTLE
(0),PERMISSION_FORCEFUL
, orPERMISSION_DIRTY
- Returns:
- success indicator (pointer was/not enqueued)
-
enqueuePointerForAnalysis
Register a pointer (code or data) for analysis.- Parameters:
pointer
- code or data pointer; code pointers must be of typeICodePointer
permission
- analysis permission type, one ofPERMISSION_GENTLE
(0),PERMISSION_FORCEFUL
, orPERMISSION_DIRTY
flags
- analysis flags, a combination anyFLAG_xxx
entry (currently:FLAG_NO_ROUTINE
)- Returns:
- success indicator (pointer was/not enqueued)
-
enqueueRoutineForReanalysis
Enqueue an existing routine for reanalysis.- Parameters:
routine
- method to be reanalyzed (in DIRTY mode)- Returns:
- success indicator (pointer was/not enqueued)
-
clearAnalysisQueue
boolean clearAnalysisQueue()- Returns:
-
needsAnalysis
boolean needsAnalysis()Determine if an analysis pass is required.- Returns:
-
isAnalyzing
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.- Returns:
-
getAnalysisCount
int getAnalysisCount()Get the number of times a code analysis was performed.- Returns:
- the number of times
analyze()
was called and has terminated
-
analyze
void analyze()Start an analysis pass. Analyze the entry points that were previously registered, create new routines and data items, etc. -
analyze
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 whatpreventSiglibMatch
- if true, siglibs application will not be prevented, no matter what
-
requestAnalysisInterruption
void requestAnalysisInterruption()Request the interruption of the current analysis pass. The interruption may not happen immediately. Client code may useisAnalyzing()
to determine whether the analysis has stopped. -
defineData
- Parameters:
address
-type
-- Returns:
-
defineData
- Parameters:
address
-type
-appliedSize
-- Returns:
-
recordDynamicBranchTarget
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 callsiteresolved
- true if the target if a true resolution, false if the target is one candidate among possibly many candidate targetstarget
- the target, not nullprepareAnalysis
- 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
-
unrecordDynamicBranchTarget
boolean unrecordDynamicBranchTarget(long instructionAddress, boolean resolved, IBranchTarget target) Unrecord a branch resolution. UnlikerecordDynamicBranchTarget(long, boolean, IBranchTarget, boolean)
, this call does not trigger a new analysis pass.- Parameters:
instructionAddress
-resolved
-target
-- Returns:
-
recordDynamicRegisterValue
boolean recordDynamicRegisterValue(long instructionAddress, boolean postExec, long register, long value) - Parameters:
instructionAddress
-postExec
-register
-value
-- Returns:
-
recordAnalysisComment
Record a meta-comment generated during the analysis. The meta-comment is flagless. This method does not notify.- Parameters:
address
- memory addresscomment
- comment string- Returns:
- success indicator
-