Initial documentation for guided analysis feature. (skip-ci)

Author: bpotchik

docs/dev/guided_analysis.md

@@ -0,0 +1,73 @@
+# Guided Analysis
+
+## Overview
+
+Guided Analysis provides granular control over which basic blocks are included or excluded from analysis. It is especially useful for analyzing obfuscated code, troubleshooting analysis issues, or focusing on specific execution paths while excluding irrelevant code.
+
+## Modes of Operation
+
+Guided Analysis operates in two primary modes:
+
+**Automatic Mode**: Binary Ninja automatically enters guided analysis when encountering problems like invalid instructions. When this happens, direct branch targets are not followed and IL is generated only for the current set of blocks. If new information becomes available that resolves the original trigger condition, the function will reanalyze and may exit guided mode automatically.
+
+**Manual Mode**: Manually enable guided analysis to precisely control analyzed blocks. Analysis begins with only the entry block, requiring explicit manual addition of further blocks.
+
+## Enabling Guided Analysis
+
+### Settings
+![Guided Analysis Settings](../img/guided-analysis-settings.png)
+
+- **`analysis.guided.enable`**: Manually start function analysis in guided mode (default: false)
+- **`analysis.guided.triggers.invalidInstruction`**: Automatically enter guided mode when invalid instructions are encountered (default: true)
+
+### Manual Activation
+
+Set the `analysis.guided.enable` setting to `true` for a function. This will cause only the initial entry basic block to appear, requiring you to manually add additional blocks. It's also possible to enter guided mode by right-clicking on any existing block and using the Halt Disassembly action, discussed later.
+
+## Working with Guided Analysis
+
+### UI Indicators
+
+When guided analysis is active, the UI will show a special indicator at the top of the function. This helps you identify when you are in guided mode and which blocks are available for analysis. The indicator includes a clickable link to exit guided mode, which disables the `analysis.guided.enable` setting and any trigger settings to prevent automatic re-entry into guided mode.
+
+![Guided Analysis Status](../img/guided-analysis-status.png)
+
+### Menu Actions
+
+The guided analysis menu actions are only available in the **Disassembly** view. These actions control direct outgoing edges from basic blocks - indirect branches that use solvers and data flow analysis cannot be controlled through guided analysis.
+
+- **Continue Disassembly**: Right-click on halted blocks to resume analysis of their branch targets
+- **Halt Disassembly**: Right-click on any existing block to stop analysis of its branch targets. This allows you to focus on specific blocks without automatic expansion.
+
+![Guided Analysis Halt](../img/guided-analysis-halt.png)
+
+### Typical Workflow
+
+1. Enable guided analysis (automatically triggered or manually enabled)
+2. Use "Continue Disassembly" to add blocks whose branch targets should be analyzed
+3. Use "Halt Disassembly" to remove blocks from having their branch targets analyzed
+4. Iteratively refine which blocks have their branch targets analyzed based on your needs
+
+## Key Use Cases
+
+Guided Analysis is particularly valuable for:
+
+### Obfuscated Code Analysis
+- **Control flow obfuscation**: Navigate through flattened control flow by manually selecting legitimate paths
+- **Junk code insertion**: Ignore irrelevant code branches that confuse automatic analysis
+- **Anti-analysis techniques**: Bypass detection mechanisms by avoiding trigger blocks
+
+### Malware Analysis
+- **Anti-debugging evasion**: Avoid analysis-detection code paths
+- **Payload extraction**: Focus on malicious functionality while ignoring wrapper code
+- **Command & control**: Trace communication logic through specific execution paths
+
+### Performance & Debugging
+- **Large binary analysis**: Reduce analysis time by focusing on critical sections
+- **Analysis issues**: Isolate problematic regions when Binary Ninja's automatic analysis fails
+- **Incremental analysis**: Gradually expand analysis scope as understanding improves
+
+
+## API Reference
+
+Guided analysis can be controlled programmatically through a dedicated Python API, supporting custom analysis scripts and plugins. Refer to the Python API documentation for detailed usage instructions.

docs/img/guided-analysis-halt.png

@@ -2294,6 +2294,15 @@ def set_user_indirect_branches(
 	def set_guided_source_blocks(
 	    self, addresses: List[Tuple['architecture.Architecture', int]]
 	) -> None:
+		"""
+		``set_guided_source_blocks`` sets the complete list of guided source blocks for this function.
+		Only blocks in this set will have their direct outgoing branch targets analyzed. This replaces
+		any existing guided source blocks and automatically enables or disables the ``analysis.guided.enable``
+		setting based on whether addresses are provided.
+
+		:param List[Tuple[architecture.Architecture, int]] addresses: List of (architecture, address) tuples
+		:rtype: None
+		"""
 		address_list = (core.BNArchitectureAndAddress * len(addresses))()
 		for i in range(len(addresses)):
 			address_list[i].arch = addresses[i][0].handle
@@ -2303,6 +2312,14 @@ def set_guided_source_blocks(
 	def add_guided_source_blocks(
 	    self, addresses: List[Tuple['architecture.Architecture', int]]
 	) -> None:
+		"""
+		``add_guided_source_blocks`` adds blocks to the guided source block list for this function.
+		The specified blocks will have their direct outgoing branch targets analyzed. This automatically
+		enables the ``analysis.guided.enable`` setting if it is not already enabled.
+
+		:param List[Tuple[architecture.Architecture, int]] addresses: List of (architecture, address) tuples to add
+		:rtype: None
+		"""
 		address_list = (core.BNArchitectureAndAddress * len(addresses))()
 		for i in range(len(addresses)):
 			address_list[i].arch = addresses[i][0].handle
@@ -2312,6 +2329,14 @@ def add_guided_source_blocks(
 	def remove_guided_source_blocks(
 	    self, addresses: List[Tuple['architecture.Architecture', int]]
 	) -> None:
+		"""
+		``remove_guided_source_blocks`` removes blocks from the guided source block list for this function.
+		The specified blocks will no longer have their direct outgoing branch targets analyzed.
+		This automatically enables the ``analysis.guided.enable`` setting if it is not already enabled.
+
+		:param List[Tuple[architecture.Architecture, int]] addresses: List of (architecture, address) tuples to remove
+		:rtype: None
+		"""
 		address_list = (core.BNArchitectureAndAddress * len(addresses))()
 		for i in range(len(addresses)):
 			address_list[i].arch = addresses[i][0].handle
@@ -2327,16 +2352,19 @@ def is_guided_source_block(
 		:param architecture.Architecture arch: Architecture of the address to check
 		:param int addr: Address to check
 		:rtype: bool
-		:Example:
-
-			>>> current_function.is_guided_source_block(arch, 0x400000)
-			True
 		"""
 		return core.BNIsGuidedSourceBlock(self.handle, arch.handle, addr)
 
 	def get_guided_source_blocks(
 	    self
 	) -> List[Tuple['architecture.Architecture', int]]:
+		"""
+		``get_guided_source_blocks`` returns the current list of guided source blocks for this function.
+		These blocks have their direct outgoing branch targets analyzed.
+
+		:rtype: List[Tuple[architecture.Architecture, int]]
+		:return: List of (architecture, address) tuples representing current guided source blocks
+		"""
 		count = ctypes.c_ulonglong()
 		addresses = core.BNGetGuidedSourceBlocks(self.handle, count)
 		try:
@@ -2353,6 +2381,13 @@ def get_guided_source_blocks(
 				core.BNFreeArchitectureAndAddressList(addresses)
 
 	def has_guided_source_blocks(self) -> bool:
+		"""
+		``has_guided_source_blocks`` checks if this function has any guided source blocks configured.
+		This indicates whether guided analysis is active for this function.
+
+		:rtype: bool
+		:return: True if the function has guided source blocks, False otherwise
+		"""
 		return core.BNHasGuidedSourceBlocks(self.handle)
 
 	def get_indirect_branches_at(