Metadata-Version: 2.4
Name: ida_runner
Version: 0.0.2
Summary: A wrapper around IDAPro's `idat` binary
Project-URL: Homepage, https://github.com/nixerr/ida_runner
Author-email: Valentin Shilnenkov <vshilnenkov@protonmail.com>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# ida_runner

A small Python wrapper around IDA Pro's `idat` console binary. It builds and runs
the `idat` command line for you — auto-analyzing a target, optionally running a
headless script, and writing the resulting IDB to a chosen directory.

It is geared toward batch / headless workflows, with built-in file-type hints for
Apple XNU kernelcaches, kernels, and kexts.

## Installation

```sh
pip install ida_runner
```

Or from source:

```sh
git clone https://github.com/nixerr/ida_runner
cd ida_runner
pip install .
```

Requires Python 3.9+ and a working IDA Pro installation that includes the `idat`
binary.

## Usage

```python
from ida_runner import IDARunner, IDABinaryType

# Point the runner at your IDA Pro application directory (the one containing `idat`)
IDARunner.set_idapro_path("/Applications/IDA Professional 9.0.app/Contents/MacOS")

# Auto-analyze a kernelcache and run a headless script against it
IDARunner.execute(
    type=IDABinaryType.KERNELCACHE,
    binary="/path/to/kernelcache",
    idbdir="/path/to/output",          # where to write the .i64 / .idb
    script="/path/to/script.py",       # IDAPython script to run headless
    args=["arg1", "arg2"],             # arguments passed to the script
    logfile="/path/to/ida.log",
    verbose=True,                      # print the constructed command
)
```

### Binary types

`IDABinaryType` maps a high-level binary kind to the IDA loader type passed via
`idat -T`:

| Member        | IDA file type                       |
| ------------- | ----------------------------------- |
| `KERNELCACHE` | `Apple XNU kernelcache for ARM64e`  |
| `KERNEL`      | `Mach-O`                            |
| `KEXT_FAT`    | `Fat Mach-O File, 2`                |
| `KEXT`        | `Mach-O`                            |

## API

### `IDARunner.set_idapro_path(path)`

Class method. Sets the directory containing the `idat` binary. Must be called
before `execute`.

### `IDARunner.execute(type, binary=None, idbdir=None, script=None, args=None, logfile=None, verbose=False)`

Builds and runs the `idat` command. The resulting command is roughly:

```
idat -A -T<file type> [-S<script> <args>] [-L<logfile>] [-o<idbdir>] <binary>
```

- `type` — an `IDABinaryType` selecting the IDA loader file type.
- `binary` — path to the input binary.
- `idbdir` — output directory / path for the database (`-o`).
- `script` — IDAPython script to run headless (`-S`).
- `args` — list of arguments appended to the script invocation.
- `logfile` — log output path (`-L`).
- `verbose` — print the command before running it.

Analysis runs in auto mode (`-A`) with `idat`'s stdout/stderr suppressed.

## License

MIT — see [pyproject.toml](pyproject.toml).
