Package com.pnfsoftware.jeb.core.units.code.asm.analyzer

Interface INativeCodeAnalyzer<InsnType extends IInstruction>

@Ser public 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 Details

    • PERMISSION_GENTLE

      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.

      See Also:

    • PERMISSION_FORCEFUL

      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.

      See Also:

    • PERMISSION_DIRTY

      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.

      See Also:

    • PERMISSION_GOD_MODE

      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.

      See Also:

    • FLAG_NO_ROUTINE

      static final int FLAG_NO_ROUTINE
      The analyzer will not create a routine
      See Also:

    • FLAG_CODE_CONTIGUOUS

      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.
      See Also:

    • FLAG_CALLEE_GENTLE_ANALYSIS

      static final int FLAG_CALLEE_GENTLE_ANALYSIS
      The analyzer should analyze callee routines with PERMISSION_GENTLE, whatever the caller's permission is.
      See Also:

    • FLAG_CALLEE_FORCEFUL_ANALYSIS

      static final int FLAG_CALLEE_FORCEFUL_ANALYSIS
      The analyzer should analyze callee routines with PERMISSION_FORCEFUL, whatever the caller's permission is.
      See Also:

    • FLAG_CALLEE_DIRTY_ANALYSIS

      static final int FLAG_CALLEE_DIRTY_ANALYSIS
      The analyzer should analyze callee routines with PERMISSION_DIRTY, whatever the caller's permission is.
      See Also:

    • FLAG_NO_CACHES_CHECK

      static final int FLAG_NO_CACHES_CHECK
      The analyzer should not check for previously cached results (internal use only).
      See Also:

    • FLAG_NO_MERGE

      static final int FLAG_NO_MERGE
      The analyzer will not merge the newly created routine into another routine.
      See Also:

    • FLAG_TRANSIENT

      static final int FLAG_TRANSIENT
      The analyzer should consider data/routine as meaningless (no cache, faster). This can be used for mass data.
      See Also:

    • FLAG_DATA_UNSAFE

      static final int FLAG_DATA_UNSAFE
      The analyzer should consider potential data found heuristically which is not safe (in particular: address can be never reached, size may be unaccurate)
      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

      boolean enqueuePointerForAnalysis(Pointer pointer)
      Register a pointer (code or data) for a gentle analysis.
      Parameters:
      pointer - code or data pointer; code pointers must be of type ICodePointer
      Returns:
      success indicator (pointer was/not enqueued)

    • enqueuePointerForAnalysis

      boolean enqueuePointerForAnalysis(Pointer 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 ICodePointer
      permission - analysis permission type, one of PERMISSION_GENTLE (0), PERMISSION_FORCEFUL, or PERMISSION_DIRTY
      Returns:
      success indicator (pointer was/not enqueued)

    • enqueuePointerForAnalysis

      boolean enqueuePointerForAnalysis(Pointer 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 ICodePointer
      permission - analysis permission type, one of PERMISSION_GENTLE (0), PERMISSION_FORCEFUL, or PERMISSION_DIRTY
      flags - analysis flags, a combination any FLAG_xxx entry (for example: FLAG_NO_ROUTINE)
      Returns:
      success indicator (pointer was/not enqueued)

    • enqueueRoutineForReanalysis

      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)

    • 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 what
      preventSiglibMatch - 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 use isAnalyzing() to determine whether the analysis has stopped.

    • defineData

      INativeDataItem defineData(long address, INativeType type)
      Parameters:
      address -
      type -
      Returns:

    • defineData

      INativeDataItem defineData(long address, INativeType type, int appliedSize)
      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 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

    • unrecordDynamicBranchTarget

      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.
      Parameters:
      instructionAddress -
      resolved -
      target -
      Returns:

    • recordDynamicRegisterValue

      boolean recordDynamicRegisterValue(long instructionAddress, boolean postExec, long register, long value)
      Parameters:
      instructionAddress -
      postExec -
      register -
      value -
      Returns:

    • recordAnalysisComment

      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