ida-domain 0.0.3.dev0__tar.gz → 0.0.3.dev1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of ida-domain might be problematic. Click here for more details.

Files changed (73) hide show
  1. ida_domain-0.0.3.dev0/LICENSE.TXT → ida_domain-0.0.3.dev1/LICENSE +1 -1
  2. ida_domain-0.0.3.dev1/PKG-INFO +208 -0
  3. ida_domain-0.0.3.dev1/README.md +176 -0
  4. ida_domain-0.0.3.dev1/ida_domain/__init__.py +45 -0
  5. ida_domain-0.0.3.dev1/ida_domain/base.py +134 -0
  6. ida_domain-0.0.3.dev1/ida_domain/basic_blocks.py +116 -0
  7. ida_domain-0.0.3.dev1/ida_domain/bytes.py +2070 -0
  8. ida_domain-0.0.3.dev1/ida_domain/comments.py +185 -0
  9. ida_domain-0.0.3.dev1/ida_domain/database.py +770 -0
  10. ida_domain-0.0.3.dev1/ida_domain/entries.py +252 -0
  11. ida_domain-0.0.3.dev1/ida_domain/functions.py +392 -0
  12. ida_domain-0.0.3.dev1/ida_domain/heads.py +116 -0
  13. ida_domain-0.0.3.dev1/ida_domain/hooks.py +4640 -0
  14. ida_domain-0.0.3.dev1/ida_domain/instructions.py +265 -0
  15. ida_domain-0.0.3.dev1/ida_domain/names.py +354 -0
  16. ida_domain-0.0.3.dev1/ida_domain/operands.py +396 -0
  17. ida_domain-0.0.3.dev1/ida_domain/segments.py +95 -0
  18. ida_domain-0.0.3.dev1/ida_domain/signature_files.py +176 -0
  19. ida_domain-0.0.3.dev1/ida_domain/strings.py +262 -0
  20. ida_domain-0.0.3.dev1/ida_domain/types.py +360 -0
  21. ida_domain-0.0.3.dev1/ida_domain/xrefs.py +387 -0
  22. ida_domain-0.0.3.dev1/ida_domain.egg-info/PKG-INFO +208 -0
  23. ida_domain-0.0.3.dev1/ida_domain.egg-info/SOURCES.txt +26 -0
  24. ida_domain-0.0.3.dev1/ida_domain.egg-info/requires.txt +18 -0
  25. ida_domain-0.0.3.dev1/pyproject.toml +73 -0
  26. ida_domain-0.0.3.dev0/.github/workflows/create-release.yml +0 -416
  27. ida_domain-0.0.3.dev0/.github/workflows/publish-docs.yml +0 -81
  28. ida_domain-0.0.3.dev0/.gitignore +0 -140
  29. ida_domain-0.0.3.dev0/PKG-INFO +0 -158
  30. ida_domain-0.0.3.dev0/README.md +0 -134
  31. ida_domain-0.0.3.dev0/docs/Makefile +0 -20
  32. ida_domain-0.0.3.dev0/docs/README.md +0 -201
  33. ida_domain-0.0.3.dev0/docs/_static/custom.css +0 -67
  34. ida_domain-0.0.3.dev0/docs/_templates/autosummary/class.rst +0 -30
  35. ida_domain-0.0.3.dev0/docs/_templates/autosummary/module.rst +0 -60
  36. ida_domain-0.0.3.dev0/docs/api.rst +0 -122
  37. ida_domain-0.0.3.dev0/docs/conf.py +0 -146
  38. ida_domain-0.0.3.dev0/docs/examples.rst +0 -280
  39. ida_domain-0.0.3.dev0/docs/index.rst +0 -94
  40. ida_domain-0.0.3.dev0/docs/installation.rst +0 -279
  41. ida_domain-0.0.3.dev0/docs/themes/hex-rays-theme/css/style.css +0 -70
  42. ida_domain-0.0.3.dev0/docs/themes/hex-rays-theme/images/ida_domain.png +0 -0
  43. ida_domain-0.0.3.dev0/docs/themes/hex-rays-theme/images/ida_domain.svg +0 -3
  44. ida_domain-0.0.3.dev0/examples/traverse.py +0 -52
  45. ida_domain-0.0.3.dev0/ida_domain/__init__.py +0 -25
  46. ida_domain-0.0.3.dev0/ida_domain/basic_blocks.py +0 -156
  47. ida_domain-0.0.3.dev0/ida_domain/bytes.py +0 -252
  48. ida_domain-0.0.3.dev0/ida_domain/comments.py +0 -160
  49. ida_domain-0.0.3.dev0/ida_domain/database.py +0 -275
  50. ida_domain-0.0.3.dev0/ida_domain/functions.py +0 -354
  51. ida_domain-0.0.3.dev0/ida_domain/ida_command_builder.py +0 -239
  52. ida_domain-0.0.3.dev0/ida_domain/instructions.py +0 -169
  53. ida_domain-0.0.3.dev0/ida_domain/names.py +0 -125
  54. ida_domain-0.0.3.dev0/ida_domain/segments.py +0 -127
  55. ida_domain-0.0.3.dev0/ida_domain/signature_files.py +0 -49
  56. ida_domain-0.0.3.dev0/ida_domain/strings.py +0 -124
  57. ida_domain-0.0.3.dev0/ida_domain/types.py +0 -107
  58. ida_domain-0.0.3.dev0/ida_domain/version.py +0 -35
  59. ida_domain-0.0.3.dev0/ida_domain/xrefs.py +0 -132
  60. ida_domain-0.0.3.dev0/ida_domain.egg-info/PKG-INFO +0 -158
  61. ida_domain-0.0.3.dev0/ida_domain.egg-info/SOURCES.txt +0 -47
  62. ida_domain-0.0.3.dev0/ida_domain.egg-info/requires.txt +0 -9
  63. ida_domain-0.0.3.dev0/pyproject.toml +0 -43
  64. ida_domain-0.0.3.dev0/tests/ida_domain_test.py +0 -631
  65. ida_domain-0.0.3.dev0/tests/pytest.ini +0 -3
  66. ida_domain-0.0.3.dev0/tests/resources/example.til +0 -0
  67. ida_domain-0.0.3.dev0/tests/tools/README.md +0 -33
  68. ida_domain-0.0.3.dev0/tests/tools/dumpbin.py +0 -30
  69. ida_domain-0.0.3.dev0/tests/tools/tiny.asm +0 -132
  70. ida_domain-0.0.3.dev0/uv.lock +0 -448
  71. {ida_domain-0.0.3.dev0 → ida_domain-0.0.3.dev1}/ida_domain.egg-info/dependency_links.txt +0 -0
  72. {ida_domain-0.0.3.dev0 → ida_domain-0.0.3.dev1}/ida_domain.egg-info/top_level.txt +0 -0
  73. {ida_domain-0.0.3.dev0 → ida_domain-0.0.3.dev1}/setup.cfg +0 -0
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
18
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
21
+ SOFTWARE.
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.4
2
+ Name: ida-domain
3
+ Version: 0.0.3.dev1
4
+ Summary: IDA Domain API - Python interface for IDA Pro reverse engineering platform
5
+ Author-email: Hex-Rays SA <support@hex-rays.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://hex-rays.com/
8
+ Project-URL: Documentation, https://ida-domain.docs.hex-rays.com/
9
+ Project-URL: Repository, https://github.com/hexrayssa/ida-domain
10
+ Project-URL: Issues, https://github.com/hexrayssa/ida-domain/issues
11
+ Keywords: ida,ida-pro,reverse-engineering,disassembler,binary-analysis,malware-analysis,security
12
+ Requires-Python: >=3.9
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: idapro>=0.0.5
16
+ Requires-Dist: typing-extensions>=4.14.0
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
19
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
20
+ Requires-Dist: graphviz>=0.20.0; extra == "dev"
21
+ Requires-Dist: python-semantic-release>=10.3.1; extra == "dev"
22
+ Provides-Extra: docs
23
+ Requires-Dist: mkdocs-material; extra == "docs"
24
+ Requires-Dist: mkdocs-click>=0.9.0; extra == "docs"
25
+ Requires-Dist: mkdocstrings[python]>=0.28.0; extra == "docs"
26
+ Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "docs"
27
+ Requires-Dist: mkdocs-include-markdown-plugin>=7.1.5; extra == "docs"
28
+ Requires-Dist: mkdocs-literate-nav>=0.6.2; extra == "docs"
29
+ Requires-Dist: mkdocs-section-index>=0.3.10; extra == "docs"
30
+ Requires-Dist: mkdocs-llmstxt>=0.2.0; extra == "docs"
31
+ Dynamic: license-file
32
+
33
+ # IDA Domain
34
+
35
+ [![PyPI version](https://badge.fury.io/py/ida-domain.svg)](https://badge.fury.io/py/ida-domain)
36
+ [![Python Support](https://img.shields.io/pypi/pyversions/ida-domain.svg)](https://pypi.org/project/ida-domain/)
37
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
38
+
39
+ The IDA Domain API is a new open-source Python API designed to make scripting in IDA simpler, more consistent, and more natural.
40
+
41
+ This is a first step in a much longer journey. It’s not the finish line, but a foundation for ongoing collaboration between Hex-Rays and the reverse engineering community. Over time, the Domain API will expand to cover more areas of IDA, gradually becoming the main entry point for scripting and plugin development.
42
+
43
+ The **Domain** in Domain API refers to the domain of reverse engineering. Concepts like functions, types, cross-references, and more are first-class citizens in this API, giving you cleaner, domain-focused abstractions for common tasks.
44
+
45
+ The Domain API sits on top of the IDA Python SDK, complementing it rather than replacing it. You can use both side by side—combining the clarity and simplicity of Domain API calls with the full flexibility of the SDK when needed.
46
+
47
+ > **Compatibility:** Requires IDA Pro 9.1.0 or later
48
+
49
+ ## 🚀 Key Features
50
+
51
+ - **Domain-focused design** – Work directly with core reverse engineering concepts like functions, types, and xrefs as first-class citizens.
52
+ - **Open source from day one** – Read the code, suggest improvements, or contribute new ideas.
53
+ - **Pure Python implementation** – No compilation required, works with modern Python versions.
54
+ - **Compatible by design** – Use alongside the IDA Python SDK without conflicts.
55
+ - **Developer-centric** – Reduce boilerplate and streamline frequent tasks.
56
+ - **Independently versioned** – Upgrade at your own pace and pin versions for stability.
57
+ - **Simple installation** – Get started with a single `pip install`.
58
+
59
+ ## 📦 Installation
60
+
61
+ ### Prerequisites
62
+
63
+ **IDA Pro Version:** The IDA Domain library requires IDA Pro 9.1.0 or later.
64
+
65
+ Set the `IDADIR` environment variable to point to your IDA installation directory:
66
+
67
+ ```bash
68
+ export IDADIR="[IDA Installation Directory]"
69
+ ```
70
+
71
+ **Example:**
72
+ ```bash
73
+ export IDADIR="/Applications/IDA Professional 9.1.app/Contents/MacOS/"
74
+ ```
75
+
76
+ > **Note:** If you have already installed and configured the `idapro` Python package, setting `IDADIR` is not required.
77
+
78
+ ### Install from PyPI
79
+
80
+ ```bash
81
+ pip install ida-domain
82
+ ```
83
+
84
+ ## 🎯 Usage Example
85
+
86
+ Here is an example showing how to use IDA Domain to analyze a binary:
87
+
88
+ ```python
89
+ #!/usr/bin/env python3
90
+ """
91
+ Database exploration example for IDA Domain API.
92
+
93
+ This example demonstrates how to open an IDA database and explore its basic properties.
94
+ """
95
+
96
+ import argparse
97
+ from dataclasses import asdict
98
+
99
+ import ida_domain
100
+ from ida_domain import Database
101
+ from ida_domain.database import IdaCommandOptions
102
+
103
+
104
+ def explore_database(db_path):
105
+ """Explore basic database information."""
106
+ ida_options = IdaCommandOptions(auto_analysis=True, new_database=True)
107
+ with Database.open(db_path, ida_options) as db:
108
+ # Get basic information
109
+ print(f'Address range: {hex(db.minimum_ea)} - {hex(db.maximum_ea)}')
110
+
111
+ # Get metadata
112
+ print('Database metadata:')
113
+ metadata_dict = asdict(db.metadata)
114
+ for key, value in metadata_dict.items():
115
+ print(f' {key}: {value}')
116
+
117
+ # Count functions
118
+ function_count = 0
119
+ for _ in db.functions:
120
+ function_count += 1
121
+ print(f'Total functions: {function_count}')
122
+
123
+
124
+ def main():
125
+ """Main entry point with argument parsing."""
126
+ parser = argparse.ArgumentParser(description='Database exploration example')
127
+ parser.add_argument(
128
+ '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
129
+ )
130
+ args = parser.parse_args()
131
+ explore_database(args.input_file)
132
+
133
+
134
+ if __name__ == '__main__':
135
+ main()
136
+
137
+ ```
138
+
139
+ ## 📖 Documentation
140
+
141
+ Complete documentation is available at: [https://ida-domain.docs.hex-rays.com/](https://ida-domain.docs.hex-rays.com/)
142
+
143
+ - **[API Reference](https://ida-domain.docs.hex-rays.com/ref/database/)**: Documentation of available classes and methods
144
+ - **[Getting Started](https://ida-domain.docs.hex-rays.com/getting_started/)**: Complete setup guide including installation and first steps
145
+ - **[Examples](https://ida-domain.docs.hex-rays.com/examples/)**: Usage examples for common tasks
146
+
147
+
148
+ ## 🛠️ Development
149
+
150
+ For development, we use a **[uv](https://docs.astral.sh/uv/)** based workflow:
151
+
152
+ ```bash
153
+ git clone https://github.com/HexRaysSA/ida-domain.git
154
+ cd ida-domain
155
+ uv sync --extra dev
156
+ uv run pre-commit install
157
+ ```
158
+
159
+ ## 🧪 Testing
160
+
161
+ Set the `IDADIR` environment variable to point to your IDA installation directory:
162
+
163
+ Run the test suite using pytest:
164
+
165
+ ```bash
166
+ uv sync --extra dev
167
+ uv run pytest
168
+ ```
169
+
170
+ ## 📚 Build Documentation
171
+
172
+ To build the documentation locally:
173
+
174
+ ```bash
175
+ uv sync --extra docs
176
+ uv run mkdocs serve
177
+ ```
178
+
179
+ Or to just build it,
180
+
181
+ ```bash
182
+ uv run mkdocs build
183
+ ```
184
+
185
+ The documentation is available in site/
186
+
187
+ ### Online Documentation
188
+
189
+ The latest documentation is available at: https://ida-domain.docs.hex-rays.com/
190
+
191
+ ## 📝 Examples
192
+
193
+ Check the [`examples/`](https://github.com/HexRaysSA/ida-domain/tree/main/examples) directory for usage examples:
194
+
195
+ ```bash
196
+ uv run python examples/analyze_database.py
197
+ ```
198
+
199
+ ## Contributing
200
+
201
+ We welcome contributions! Please see our [Contributing Guidelines](https://github.com/HexRaysSA/ida-domain/blob/main/CONTRIBUTING.md) for details on how to:
202
+
203
+ - Report bugs and suggest features
204
+ - Submit pull requests with proper testing
205
+
206
+ ## License
207
+
208
+ This project is licensed under the MIT License - see the [LICENSE](https://github.com/HexRaysSA/ida-domain/blob/main/LICENSE) file for details.
@@ -0,0 +1,176 @@
1
+ # IDA Domain
2
+
3
+ [![PyPI version](https://badge.fury.io/py/ida-domain.svg)](https://badge.fury.io/py/ida-domain)
4
+ [![Python Support](https://img.shields.io/pypi/pyversions/ida-domain.svg)](https://pypi.org/project/ida-domain/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ The IDA Domain API is a new open-source Python API designed to make scripting in IDA simpler, more consistent, and more natural.
8
+
9
+ This is a first step in a much longer journey. It’s not the finish line, but a foundation for ongoing collaboration between Hex-Rays and the reverse engineering community. Over time, the Domain API will expand to cover more areas of IDA, gradually becoming the main entry point for scripting and plugin development.
10
+
11
+ The **Domain** in Domain API refers to the domain of reverse engineering. Concepts like functions, types, cross-references, and more are first-class citizens in this API, giving you cleaner, domain-focused abstractions for common tasks.
12
+
13
+ The Domain API sits on top of the IDA Python SDK, complementing it rather than replacing it. You can use both side by side—combining the clarity and simplicity of Domain API calls with the full flexibility of the SDK when needed.
14
+
15
+ > **Compatibility:** Requires IDA Pro 9.1.0 or later
16
+
17
+ ## 🚀 Key Features
18
+
19
+ - **Domain-focused design** – Work directly with core reverse engineering concepts like functions, types, and xrefs as first-class citizens.
20
+ - **Open source from day one** – Read the code, suggest improvements, or contribute new ideas.
21
+ - **Pure Python implementation** – No compilation required, works with modern Python versions.
22
+ - **Compatible by design** – Use alongside the IDA Python SDK without conflicts.
23
+ - **Developer-centric** – Reduce boilerplate and streamline frequent tasks.
24
+ - **Independently versioned** – Upgrade at your own pace and pin versions for stability.
25
+ - **Simple installation** – Get started with a single `pip install`.
26
+
27
+ ## 📦 Installation
28
+
29
+ ### Prerequisites
30
+
31
+ **IDA Pro Version:** The IDA Domain library requires IDA Pro 9.1.0 or later.
32
+
33
+ Set the `IDADIR` environment variable to point to your IDA installation directory:
34
+
35
+ ```bash
36
+ export IDADIR="[IDA Installation Directory]"
37
+ ```
38
+
39
+ **Example:**
40
+ ```bash
41
+ export IDADIR="/Applications/IDA Professional 9.1.app/Contents/MacOS/"
42
+ ```
43
+
44
+ > **Note:** If you have already installed and configured the `idapro` Python package, setting `IDADIR` is not required.
45
+
46
+ ### Install from PyPI
47
+
48
+ ```bash
49
+ pip install ida-domain
50
+ ```
51
+
52
+ ## 🎯 Usage Example
53
+
54
+ Here is an example showing how to use IDA Domain to analyze a binary:
55
+
56
+ ```python
57
+ #!/usr/bin/env python3
58
+ """
59
+ Database exploration example for IDA Domain API.
60
+
61
+ This example demonstrates how to open an IDA database and explore its basic properties.
62
+ """
63
+
64
+ import argparse
65
+ from dataclasses import asdict
66
+
67
+ import ida_domain
68
+ from ida_domain import Database
69
+ from ida_domain.database import IdaCommandOptions
70
+
71
+
72
+ def explore_database(db_path):
73
+ """Explore basic database information."""
74
+ ida_options = IdaCommandOptions(auto_analysis=True, new_database=True)
75
+ with Database.open(db_path, ida_options) as db:
76
+ # Get basic information
77
+ print(f'Address range: {hex(db.minimum_ea)} - {hex(db.maximum_ea)}')
78
+
79
+ # Get metadata
80
+ print('Database metadata:')
81
+ metadata_dict = asdict(db.metadata)
82
+ for key, value in metadata_dict.items():
83
+ print(f' {key}: {value}')
84
+
85
+ # Count functions
86
+ function_count = 0
87
+ for _ in db.functions:
88
+ function_count += 1
89
+ print(f'Total functions: {function_count}')
90
+
91
+
92
+ def main():
93
+ """Main entry point with argument parsing."""
94
+ parser = argparse.ArgumentParser(description='Database exploration example')
95
+ parser.add_argument(
96
+ '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
97
+ )
98
+ args = parser.parse_args()
99
+ explore_database(args.input_file)
100
+
101
+
102
+ if __name__ == '__main__':
103
+ main()
104
+
105
+ ```
106
+
107
+ ## 📖 Documentation
108
+
109
+ Complete documentation is available at: [https://ida-domain.docs.hex-rays.com/](https://ida-domain.docs.hex-rays.com/)
110
+
111
+ - **[API Reference](https://ida-domain.docs.hex-rays.com/ref/database/)**: Documentation of available classes and methods
112
+ - **[Getting Started](https://ida-domain.docs.hex-rays.com/getting_started/)**: Complete setup guide including installation and first steps
113
+ - **[Examples](https://ida-domain.docs.hex-rays.com/examples/)**: Usage examples for common tasks
114
+
115
+
116
+ ## 🛠️ Development
117
+
118
+ For development, we use a **[uv](https://docs.astral.sh/uv/)** based workflow:
119
+
120
+ ```bash
121
+ git clone https://github.com/HexRaysSA/ida-domain.git
122
+ cd ida-domain
123
+ uv sync --extra dev
124
+ uv run pre-commit install
125
+ ```
126
+
127
+ ## 🧪 Testing
128
+
129
+ Set the `IDADIR` environment variable to point to your IDA installation directory:
130
+
131
+ Run the test suite using pytest:
132
+
133
+ ```bash
134
+ uv sync --extra dev
135
+ uv run pytest
136
+ ```
137
+
138
+ ## 📚 Build Documentation
139
+
140
+ To build the documentation locally:
141
+
142
+ ```bash
143
+ uv sync --extra docs
144
+ uv run mkdocs serve
145
+ ```
146
+
147
+ Or to just build it,
148
+
149
+ ```bash
150
+ uv run mkdocs build
151
+ ```
152
+
153
+ The documentation is available in site/
154
+
155
+ ### Online Documentation
156
+
157
+ The latest documentation is available at: https://ida-domain.docs.hex-rays.com/
158
+
159
+ ## 📝 Examples
160
+
161
+ Check the [`examples/`](https://github.com/HexRaysSA/ida-domain/tree/main/examples) directory for usage examples:
162
+
163
+ ```bash
164
+ uv run python examples/analyze_database.py
165
+ ```
166
+
167
+ ## Contributing
168
+
169
+ We welcome contributions! Please see our [Contributing Guidelines](https://github.com/HexRaysSA/ida-domain/blob/main/CONTRIBUTING.md) for details on how to:
170
+
171
+ - Report bugs and suggest features
172
+ - Submit pull requests with proper testing
173
+
174
+ ## License
175
+
176
+ This project is licensed under the MIT License - see the [LICENSE](https://github.com/HexRaysSA/ida-domain/blob/main/LICENSE) file for details.
@@ -0,0 +1,45 @@
1
+ from __future__ import annotations
2
+
3
+ import logging
4
+ from logging import NullHandler
5
+
6
+
7
+ def _load_dependencies() -> None:
8
+ """
9
+ Load required dependencies
10
+
11
+ This needs to work both inside and outside IDA. This module works on top of IDA Python.
12
+ When running inside IDA, IDA Python is already available. When running outside IDA, we need
13
+ to explicitly import idapro, which loads the IDA kernel libraries and IDA Python for us.
14
+ """
15
+
16
+ # Check if IDA Python is already loaded
17
+ try:
18
+ import ida_kernwin
19
+
20
+ need_idapro = ida_kernwin.is_ida_library(None, 0, None)
21
+ except ImportError:
22
+ need_idapro = True
23
+
24
+ if need_idapro:
25
+ import idapro
26
+
27
+
28
+ __version__ = '0.0.3-dev.1'
29
+
30
+ # Make sure all dependencies are loaded
31
+ _load_dependencies()
32
+
33
+
34
+ # Keep the ida kernel version as int, eg: 920
35
+ import ida_ida
36
+
37
+ __ida_version__ = ida_ida.inf_get_version()
38
+
39
+ if __ida_version__ < 910:
40
+ raise ImportError('IDA Domain requires IDA 9.1.0 or later')
41
+
42
+ # If we reach this point kernel libraries were successfully loaded
43
+ from .database import Database
44
+
45
+ logging.getLogger(__name__).addHandler(NullHandler())
@@ -0,0 +1,134 @@
1
+ from __future__ import annotations
2
+
3
+ import functools
4
+ import logging
5
+ from collections.abc import Callable
6
+
7
+ from ida_idaapi import ea_t
8
+ from typing_extensions import TYPE_CHECKING, Any, Optional, ParamSpec, TypeVar, cast
9
+
10
+ logger = logging.getLogger(__name__)
11
+
12
+ if TYPE_CHECKING:
13
+ from .database import Database
14
+
15
+
16
+ class DatabaseEntity:
17
+ """
18
+ Base class for all Database entities.
19
+ """
20
+
21
+ def __init__(self, database: Optional[Database]):
22
+ """
23
+ Constructs a database entity for the given database.
24
+
25
+ Args:
26
+ database: Reference to the active IDA database.
27
+ """
28
+ self.m_database = database
29
+
30
+ @property
31
+ def database(self) -> Database:
32
+ """
33
+ Get the database reference, guaranteed to be non-None when called from
34
+ methods decorated with @check_db_open.
35
+
36
+ Returns:
37
+ The active database instance.
38
+
39
+ Note:
40
+ This property should only be used in methods decorated with @check_db_open,
41
+ which ensures m_database is not None.
42
+ """
43
+ if TYPE_CHECKING:
44
+ from .database import Database
45
+
46
+ return cast('Database', self.m_database)
47
+
48
+ # Runtime assertion - should never fail if decorator is used correctly
49
+ assert self.m_database is not None, (
50
+ 'Database is None - ensure method is decorated with @check_db_open'
51
+ )
52
+ return self.m_database
53
+
54
+
55
+ F = TypeVar('F', bound=Callable[..., Any])
56
+ C = TypeVar('C', bound=type)
57
+ P = ParamSpec('P')
58
+ R = TypeVar('R')
59
+
60
+
61
+ class InvalidEAError(LookupError):
62
+ """
63
+ Raised when an operation is attempted on an invalid effective address.
64
+ """
65
+
66
+ def __init__(self, ea: ea_t) -> None:
67
+ super().__init__(f'Invalid effective address: 0x{ea:x}')
68
+
69
+
70
+ class InvalidParameterError(ValueError):
71
+ """
72
+ Raised when a function receives invalid arguments.
73
+ """
74
+
75
+ def __init__(self, parameter: str, value: object, message: str) -> None:
76
+ super().__init__(f'Invalid parameter {parameter} value {str(value)}: {message}')
77
+
78
+
79
+ class DatabaseNotLoadedError(RuntimeError):
80
+ """
81
+ Raised when an operation is attempted on a closed database.
82
+ """
83
+
84
+ pass
85
+
86
+
87
+ def decorate_all_methods(decorator: Callable[[F], F]) -> Callable[[C], C]:
88
+ """
89
+ Class decorator factory that applies `decorator` to all methods
90
+ of the class (excluding dunder methods and static methods).
91
+ """
92
+
93
+ def decorate(cls: C) -> C:
94
+ for name, attr in cls.__dict__.items():
95
+ if name.startswith('__'):
96
+ continue
97
+ # Skip static methods and class methods
98
+ if isinstance(attr, (staticmethod, classmethod)):
99
+ continue
100
+ if callable(attr):
101
+ setattr(cls, name, decorator(attr))
102
+ return cls
103
+
104
+ return decorate
105
+
106
+
107
+ def check_db_open(fn: Callable[P, R]) -> Callable[P, R]:
108
+ """
109
+ Decorator that checks that a database is open.
110
+ """
111
+
112
+ @functools.wraps(fn)
113
+ def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
114
+ # Check inside database class
115
+ if args:
116
+ self = args[0]
117
+
118
+ # Check class name as string (avoid circular dependency)
119
+ if self.__class__.__name__ == 'Database':
120
+ if hasattr(self, 'is_open') and not self.is_open():
121
+ raise DatabaseNotLoadedError(
122
+ f'{fn.__qualname__}: Database is not loaded. Please open a database first.'
123
+ )
124
+
125
+ # Check DatabaseEntity instances
126
+ if isinstance(self, DatabaseEntity):
127
+ if not self.m_database or not self.m_database.is_open():
128
+ raise DatabaseNotLoadedError(
129
+ f'{fn.__qualname__}: Database is not loaded. Please open a database first.'
130
+ )
131
+
132
+ return fn(*args, **kwargs)
133
+
134
+ return wrapper
@@ -0,0 +1,116 @@
1
+ from __future__ import annotations
2
+
3
+ import logging
4
+
5
+ import ida_gdl
6
+ from ida_ua import insn_t
7
+ from typing_extensions import TYPE_CHECKING, Iterator, Optional
8
+
9
+ from .base import (
10
+ DatabaseEntity,
11
+ InvalidEAError,
12
+ InvalidParameterError,
13
+ check_db_open,
14
+ decorate_all_methods,
15
+ )
16
+
17
+ if TYPE_CHECKING:
18
+ from ida_funcs import func_t
19
+ from ida_gdl import qbasic_block_t
20
+ from ida_idaapi import ea_t
21
+
22
+ from .database import Database
23
+
24
+
25
+ logger = logging.getLogger(__name__)
26
+
27
+
28
+ class _FlowChart(ida_gdl.FlowChart):
29
+ """
30
+ Flowchart class used to analyze and iterate through basic blocks within
31
+ functions or address ranges.
32
+ """
33
+
34
+ def __init__(
35
+ self, f: func_t = None, bounds: Optional[tuple[ea_t, ea_t]] = None, flags: int = 0
36
+ ):
37
+ super().__init__(f, bounds, flags)
38
+
39
+ def _getitem(self, index: int) -> qbasic_block_t:
40
+ """
41
+ Internal method to access flowchart items by index.
42
+
43
+ Args:
44
+ index: The index of the basic block to retrieve.
45
+
46
+ Returns:
47
+ The basic block at the specified index.
48
+ """
49
+ return self._q[index]
50
+
51
+
52
+ @decorate_all_methods(check_db_open)
53
+ class BasicBlocks(DatabaseEntity):
54
+ """
55
+ Interface for working with basic blocks in functions.
56
+
57
+ Basic blocks are sequences of instructions with a single entry point and single exit point,
58
+ used for control flow analysis and optimization.
59
+
60
+ Args:
61
+ database: Reference to the active IDA database.
62
+ """
63
+
64
+ def __init__(self, database: Database):
65
+ super().__init__(database)
66
+
67
+ def get_instructions(self, block: qbasic_block_t) -> Optional[Iterator[insn_t]]:
68
+ """
69
+ Retrieves the instructions within a given basic block.
70
+
71
+ Args:
72
+ block: The basic block to analyze.
73
+
74
+ Returns:
75
+ An instruction iterator for the block.
76
+ """
77
+ return self.database.instructions.get_between(block.start_ea, block.end_ea)
78
+
79
+ def get_from_function(self, func: func_t, flags: int = 0) -> _FlowChart:
80
+ """
81
+ Retrieves the basic blocks within a given function.
82
+
83
+ Args:
84
+ func: The function to retrieve basic blocks from.
85
+ flags: Optional qflow_chart_t flags for flowchart generation (default: 0).
86
+
87
+ Returns:
88
+ An iterable flowchart containing the basic blocks of the function.
89
+ """
90
+ return _FlowChart(func, None, flags)
91
+
92
+ def get_between(self, start_ea: ea_t, end_ea: ea_t, flags: int = 0) -> _FlowChart:
93
+ """
94
+ Retrieves the basic blocks within a given address range.
95
+
96
+ Args:
97
+ start_ea: The start address of the range.
98
+ end_ea: The end address of the range.
99
+ flags: Optional qflow_chart_t flags for flowchart generation (default: 0).
100
+
101
+ Returns:
102
+ An iterable flowchart containing the basic blocks within the specified range.
103
+
104
+ Raises:
105
+ InvalidEAError: If the effective address is not in the database range.
106
+ InvalidParameterError: If the input range is invalid.
107
+ """
108
+
109
+ if not self.database.is_valid_ea(start_ea, strict_check=False):
110
+ raise InvalidEAError(start_ea)
111
+ if not self.database.is_valid_ea(end_ea, strict_check=False):
112
+ raise InvalidEAError(end_ea)
113
+ if start_ea >= end_ea:
114
+ raise InvalidParameterError('start_ea', start_ea, 'must be less than end_ea')
115
+
116
+ return _FlowChart(None, (start_ea, end_ea), flags)