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.
- ida_domain-0.0.3.dev0/LICENSE.TXT → ida_domain-0.0.3.dev1/LICENSE +1 -1
- ida_domain-0.0.3.dev1/PKG-INFO +208 -0
- ida_domain-0.0.3.dev1/README.md +176 -0
- ida_domain-0.0.3.dev1/ida_domain/__init__.py +45 -0
- ida_domain-0.0.3.dev1/ida_domain/base.py +134 -0
- ida_domain-0.0.3.dev1/ida_domain/basic_blocks.py +116 -0
- ida_domain-0.0.3.dev1/ida_domain/bytes.py +2070 -0
- ida_domain-0.0.3.dev1/ida_domain/comments.py +185 -0
- ida_domain-0.0.3.dev1/ida_domain/database.py +770 -0
- ida_domain-0.0.3.dev1/ida_domain/entries.py +252 -0
- ida_domain-0.0.3.dev1/ida_domain/functions.py +392 -0
- ida_domain-0.0.3.dev1/ida_domain/heads.py +116 -0
- ida_domain-0.0.3.dev1/ida_domain/hooks.py +4640 -0
- ida_domain-0.0.3.dev1/ida_domain/instructions.py +265 -0
- ida_domain-0.0.3.dev1/ida_domain/names.py +354 -0
- ida_domain-0.0.3.dev1/ida_domain/operands.py +396 -0
- ida_domain-0.0.3.dev1/ida_domain/segments.py +95 -0
- ida_domain-0.0.3.dev1/ida_domain/signature_files.py +176 -0
- ida_domain-0.0.3.dev1/ida_domain/strings.py +262 -0
- ida_domain-0.0.3.dev1/ida_domain/types.py +360 -0
- ida_domain-0.0.3.dev1/ida_domain/xrefs.py +387 -0
- ida_domain-0.0.3.dev1/ida_domain.egg-info/PKG-INFO +208 -0
- ida_domain-0.0.3.dev1/ida_domain.egg-info/SOURCES.txt +26 -0
- ida_domain-0.0.3.dev1/ida_domain.egg-info/requires.txt +18 -0
- ida_domain-0.0.3.dev1/pyproject.toml +73 -0
- ida_domain-0.0.3.dev0/.github/workflows/create-release.yml +0 -416
- ida_domain-0.0.3.dev0/.github/workflows/publish-docs.yml +0 -81
- ida_domain-0.0.3.dev0/.gitignore +0 -140
- ida_domain-0.0.3.dev0/PKG-INFO +0 -158
- ida_domain-0.0.3.dev0/README.md +0 -134
- ida_domain-0.0.3.dev0/docs/Makefile +0 -20
- ida_domain-0.0.3.dev0/docs/README.md +0 -201
- ida_domain-0.0.3.dev0/docs/_static/custom.css +0 -67
- ida_domain-0.0.3.dev0/docs/_templates/autosummary/class.rst +0 -30
- ida_domain-0.0.3.dev0/docs/_templates/autosummary/module.rst +0 -60
- ida_domain-0.0.3.dev0/docs/api.rst +0 -122
- ida_domain-0.0.3.dev0/docs/conf.py +0 -146
- ida_domain-0.0.3.dev0/docs/examples.rst +0 -280
- ida_domain-0.0.3.dev0/docs/index.rst +0 -94
- ida_domain-0.0.3.dev0/docs/installation.rst +0 -279
- ida_domain-0.0.3.dev0/docs/themes/hex-rays-theme/css/style.css +0 -70
- ida_domain-0.0.3.dev0/docs/themes/hex-rays-theme/images/ida_domain.png +0 -0
- ida_domain-0.0.3.dev0/docs/themes/hex-rays-theme/images/ida_domain.svg +0 -3
- ida_domain-0.0.3.dev0/examples/traverse.py +0 -52
- ida_domain-0.0.3.dev0/ida_domain/__init__.py +0 -25
- ida_domain-0.0.3.dev0/ida_domain/basic_blocks.py +0 -156
- ida_domain-0.0.3.dev0/ida_domain/bytes.py +0 -252
- ida_domain-0.0.3.dev0/ida_domain/comments.py +0 -160
- ida_domain-0.0.3.dev0/ida_domain/database.py +0 -275
- ida_domain-0.0.3.dev0/ida_domain/functions.py +0 -354
- ida_domain-0.0.3.dev0/ida_domain/ida_command_builder.py +0 -239
- ida_domain-0.0.3.dev0/ida_domain/instructions.py +0 -169
- ida_domain-0.0.3.dev0/ida_domain/names.py +0 -125
- ida_domain-0.0.3.dev0/ida_domain/segments.py +0 -127
- ida_domain-0.0.3.dev0/ida_domain/signature_files.py +0 -49
- ida_domain-0.0.3.dev0/ida_domain/strings.py +0 -124
- ida_domain-0.0.3.dev0/ida_domain/types.py +0 -107
- ida_domain-0.0.3.dev0/ida_domain/version.py +0 -35
- ida_domain-0.0.3.dev0/ida_domain/xrefs.py +0 -132
- ida_domain-0.0.3.dev0/ida_domain.egg-info/PKG-INFO +0 -158
- ida_domain-0.0.3.dev0/ida_domain.egg-info/SOURCES.txt +0 -47
- ida_domain-0.0.3.dev0/ida_domain.egg-info/requires.txt +0 -9
- ida_domain-0.0.3.dev0/pyproject.toml +0 -43
- ida_domain-0.0.3.dev0/tests/ida_domain_test.py +0 -631
- ida_domain-0.0.3.dev0/tests/pytest.ini +0 -3
- ida_domain-0.0.3.dev0/tests/resources/example.til +0 -0
- ida_domain-0.0.3.dev0/tests/tools/README.md +0 -33
- ida_domain-0.0.3.dev0/tests/tools/dumpbin.py +0 -30
- ida_domain-0.0.3.dev0/tests/tools/tiny.asm +0 -132
- ida_domain-0.0.3.dev0/uv.lock +0 -448
- {ida_domain-0.0.3.dev0 → ida_domain-0.0.3.dev1}/ida_domain.egg-info/dependency_links.txt +0 -0
- {ida_domain-0.0.3.dev0 → ida_domain-0.0.3.dev1}/ida_domain.egg-info/top_level.txt +0 -0
- {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
|
+
[](https://badge.fury.io/py/ida-domain)
|
|
36
|
+
[](https://pypi.org/project/ida-domain/)
|
|
37
|
+
[](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
|
+
[](https://badge.fury.io/py/ida-domain)
|
|
4
|
+
[](https://pypi.org/project/ida-domain/)
|
|
5
|
+
[](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)
|