ida-cli

# ida-cli

CLI headless para IDA e toolkit baseado em skills para análise de binários em macOS e Linux. O `ida-cli` seleciona automaticamente um backend de runtime, inicia um servidor local quando necessário, e expõe a mesma superfície como uma CLI plana, um transporte MCP via stdio e um transporte MCP HTTP Streamable.

[中文说明](https://github.com/cpkt9762/ida-cli/blob/master/README.zh-CN.md)

## Dois Pontos de Entrada para o Utilizador

- o binário local `ida-cli` (cliente + serviço num único executável)
- a skill instalável `ida-cli` (`skill/SKILL.md`) para ambientes de agentes

A camada de serviço subjacente (worker / router) é iniciada e encerrada automaticamente pela CLI. Só precisa de executar `serve` / `serve-http` explicitamente quando quiser um serviço de longa duração e endereçável externamente.

## Matriz de Suporte

### Plataformas Anfitriãs

- Suportadas: macOS, Linux
- Não suportadas: Windows

### Política de Runtime do IDA

| Versão do IDA | Backend | Notas |
|---|---|---|
| `< 9.0` | unsupported | — |
| `9.0 – 9.2` | `idat-compat` | invoca `idat` + IDAPython |
| `9.3+` | `native-linked` | faz ligação com `idalib` fornecido (vendored) |

A seleção do backend é feita em tempo de execução por `probe-runtime`. A compilação ainda requer um IDA SDK porque a camada nativa fornecida (vendored) é ligada a ele; em tempo de execução, a CLI abre o próprio IDA a partir de `IDADIR` ou de um caminho de instalação comum normalizado.

## Capacidades Atuais

Em runtimes IDA 9.x suportados, o `ida-cli` pode:

- abrir binários PE / ELF / Mach-O crus e reutilizar bases de dados `.i64` em cache
- listar e resolver funções, desmontar por endereço ou nome, descompilar via Hex-Rays
- consultar segmentos, strings, importações, exportações, pontos de entrada, símbolos globais
- resolver contexto de endereço ↔ segmento / função / símbolo
- ler bytes / strings / inteiros, aplicar helpers `read_*` e `convert_number`
- consultar xrefs para / de um endereço (incluindo xrefs para strings e campos de struct)
- construir grafos de chamadas, blocos básicos e caminhos de fluxo de controlo
- procurar texto, imediatos, bytes, instruções, operandos, pseudocódigo
- declarar / aplicar tipos, renomear símbolos e locais, definir comentários
- executar snippets IDAPython via `run_script`

Itens em aberto: algumas operações de escrita intensiva e edição avançada de tipos ainda estão parciais no `idat-compat`. Consulte [docs/TOOLS.md](https://github.com/cpkt9762/ida-cli/blob/master/docs/TOOLS.md) para a lista de ferramentas gerada.

## Início Rápido

### Recomendado: Instalar a Skill

O ponto de entrada predefinido é a skill `ida-cli`, não uma instalação manual da CLI.

```bash
# list the skill exposed by this repository
npx -y skills add https://github.com/cpkt9762/ida-cli --list

# install the ida-cli skill for Codex
npx -y skills add https://github.com/cpkt9762/ida-cli --skill ida-cli --agent codex --yes --global
```

Após a instalação, a skill inclui o seu próprio wrapper de bootstrap:

```bash
~/.agents/skills/ida-cli/scripts/ida-cli.sh --help
~/.agents/skills/ida-cli/scripts/ida-cli.sh probe-runtime
~/.agents/skills/ida-cli/scripts/ida-cli.sh --path /path/to/binary list-functions --limit 20
```

Se `ida-cli` não estiver presente, o wrapper instala-o através do instalador do repositório antes de encaminhar o comando.

### Instalação Direta da CLI (Opcional)

Utilize isto apenas se quiser a CLI autónoma sem passar pela skill.

```bash
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --add-path
```

Variantes úteis:

```bash
# install a specific release
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --tag v0.9.3 --add-path

# build directly from a branch or ref
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --ref master --build-from-source --add-path
```

Notas:

- O instalador coloca o lançador em `~/.local/bin/ida-cli` por predefinição.
- `--add-path` adiciona esse diretório bin ao seu ficheiro rc de shell.
- Se nem `IDASDKDIR` nem `IDALIB_SDK` estiverem definidos e for necessária uma compilação local, o instalador clona automaticamente o `HexRaysSA/ida-sdk` de código aberto.
- Quando existem múltiplas instalações do IDA, exporte `IDADIR` explicitamente antes de instalar ou executar `ida-cli`.

### Compilar a Partir do Código Fonte

```bash
git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli

export IDADIR="/Applications/IDA Professional 9.4.app/Contents/MacOS"   # or a Linux install
export IDASDKDIR="/path/to/ida-sdk"                                     # root or ida-sdk/src

cargo build --bin ida-cli
./target/debug/ida-cli --help
```

### Utilizar a CLI

A `ida-cli` é orientada ao cliente (client-first). Qualquer subcomando de cliente inicia automaticamente um servidor Streamable-HTTP local vinculado a uma porta aleatória e escreve `/tmp/ida-cli.socket` para descoberta:

```bash
./target/debug/ida-cli --path /path/to/sample.bin list-functions --limit 20
./target/debug/ida-cli --path /path/to/sample.bin decompile --addr 0x140001000
./target/debug/ida-cli --path /path/to/sample.bin raw '{"method":"get_xrefs_to","params":{"address":"0x140001000"}}'
```

Os comandos cujo primeiro argumento é um subcomando de serviço (`serve`, `serve-http`, `serve-worker`, `probe-runtime`) entram em modo de serviço:

```bash
./target/debug/ida-cli serve                          # stdio MCP transport
./target/debug/ida-cli serve-http --bind 127.0.0.1:8765
./target/debug/ida-cli probe-runtime
```

Exemplo de saída do backend-probe:

```json
{"runtime":{"major":9,"minor":1,"build":250226},"backend":"idat-compat","supported":true,"reason":null}
```

```json
{"runtime":{"major":9,"minor":4,"build":260610},"backend":"native-linked","supported":true,"reason":null}
```

Para a superfície completa da CLI, consulte [skill/references/cli-tool-reference.md](https://github.com/cpkt9762/ida-cli/blob/master/skill/references/cli-tool-reference.md).

## Requisitos de Compilação

- Rust 1.87+
- LLVM / Clang
- Sistema anfitrião macOS ou Linux
- Uma instalação do IDA via `IDADIR` (o suporte de runtime começa no IDA 9.0)
- Um IDA SDK via `IDASDKDIR` ou `IDALIB_SDK`

O caminho do SDK pode apontar para qualquer uma das estruturas:

- `/path/to/ida-sdk`
- `/path/to/ida-sdk/src`

## Notas de Runtime

### `idat-compat`

Backend de compatibilidade para IDA 9.0–9.2. Ele invoca `idat`, executa pequenos scripts IDAPython e devolve JSON estruturado ao runtime da CLI.

### `native-linked`

Backend para IDA 9.3+. Faz ligação com a linha `idalib` fornecida (vendored) e abre bases de dados no processo.

### Cache e Caminhos Locais de Runtime

- Cache de bases de dados: `~/.ida/idb/`
- Registos (logs): `~/.ida/logs/server.log`
- Socket Unix do servidor: `~/.ida/server.sock`
- Ficheiro PID do servidor: `~/.ida/server.pid`
- Ficheiro de descoberta da CLI (mapeia a CLI plana para o socket ativo): `/tmp/ida-cli.socket`
- Cache de grandes respostas JSON: `/tmp/ida-cli-out/`

## CI e Lançamentos (Releases)

O GitHub Actions compila e testa a árvore em runners hospedados contra o `HexRaysSA/ida-sdk` de código aberto, pelo que o CI não depende de nenhuma estrutura privada de máquina.

Comportamento atual do workflow:

- pushes e pull requests contra `master` executam validação
- pushes com tag como `v0.9.3` geram arquivos de lançamento para Linux e macOS
- os lançamentos incluem `install.sh` e arquivos por plataforma

Os binários de lançamento são compilados contra stubs do SDK. No momento da instalação, o lançador gerado por `install.sh` resolve o seu runtime local do IDA através de `IDADIR` ou de um conjunto normalizado de caminhos de instalação comuns antes de invocar `ida-cli`.

## Documentação

- [docs/BUILDING.md](https://github.com/cpkt9762/ida-cli/blob/master/docs/BUILDING.md) — compilar a partir do código fonte
- [docs/ARCHITECTURE.md](https://github.com/cpkt9762/ida-cli/blob/master/docs/ARCHITECTURE.md) — router, backends, federação
- [docs/TRANSPORTS.md](https://github.com/cpkt9762/ida-cli/blob/master/docs/TRANSPORTS.md) — stdio, HTTP streamable, multi-IDB
- [docs/TOOLS.md](https://github.com/cpkt9762/ida-cli/blob/master/docs/TOOLS.md) — catálogo de ferramentas gerado
- [docs/TESTING.md](https://github.com/cpkt9762/ida-cli/blob/master/docs/TESTING.md) — testes de integração e unitários
- [skill/SKILL.md](https://github.com/cpkt9762/ida-cli/blob/master/skill/SKILL.md) — bootstrap da skill e política de utilização
- [skill/references/cli-tool-reference.md](https://github.com/cpkt9762/ida-cli/blob/master/skill/references/cli-tool-reference.md) — superfície completa da CLI

## Licença

MIT