TinyInst```

Copyright 2020 Google LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

## O que é o TinyInst?

O TinyInst é uma biblioteca de instrumentação dinâmica leve que pode ser usada para instrumentar apenas módulo(s) selecionado(s) no processo, deixando o restante do processo executar nativamente. Ele foi feito para ser fácil de entender, fácil de modificar e fácil de usar para hackear. Não foi projetado para ser compatível com todos os alvos (mais sobre isso adiante).

### Como ele se compara ao [DynamoRIO](https://dynamorio.org/) e ao [PIN](https://software.intel.com/en-us/articles/pintool)?

O TinyInst não foi concebido como um substituto para frameworks complexos de instrumentação como DynamoRIO e PIN, mas sim como uma alternativa para cenários em que uma solução mais leve seria suficiente. O TinyInst assume que o alvo é bem-comportado (no sentido explicado abaixo), o que não é o caso para frameworks mais complexos. Assim, provavelmente você não conseguirá executar o TinyInst com sucesso contra malware como [foi feito com o DynamoRIO anteriormente](https://www.slideshare.net/MaximShudrak/fuzzing-malware-for-fun-profit-applying-coverageguided-fuzzing-to-find-bugs-in-modern-malware). Por outro lado, se um alvo não funciona com outros frameworks devido ao módulo que não precisa ser instrumentado, e o módulo instrumentado é bem-comportado, ele pode funcionar com o TinyInst. Como com o TinyInst a maior parte do processo executa nativamente, ele terá um tempo de inicialização de processo mais curto e pode superar outras soluções em casos em que o processo alvo gasta muito tempo nos módulos onde a instrumentação não é necessária.

### Como ele se compara ao [Mesos](https://github.com/gamozolabs/mesos) e ao [TrapFuzz](https://github.com/googleprojectzero/p0tools/tree/master/TrapFuzz)?

O TinyInst é uma solução completa de reescrita de binários, portanto, comportamentos arbitrários podem ser alterados no módulo alvo. Isso permite, por exemplo, extrair cobertura de arestas em vez de apenas blocos básicos. Além disso, o TinyInst não depende de outros softwares, como o IDA Pro, para identificar blocos básicos.

### Quais sistemas operacionais o TinyInst suporta?

O TinyInst funciona no Windows (x86 e x64), macOS (x64 e ARM64), Linux (x64 e ARM64) e Android (ARM64). Consulte o README no diretório correspondente de cada sistema operacional para notas e limitações adicionais.

### Quais alvos são compatíveis com o TinyInst?

O TinyInst assume que todos os módulos instrumentados são bem-comportados no sentido de que

- Não há código automodificável
- O endereço de retorno na pilha nunca é acessado diretamente pelo programa
OU/E (dependendo das configurações)
- Nenhum dado é armazenado antes do topo da pilha (em endereços abaixo do apontado por ESP/RSP). Essa condição pode ser flexibilizada para "nenhum dado antes de (ESP/RSP - arbitrary_offset)" usando a flag `-stack_offset`.

O TinyInst também exige que DEP/NX esteja habilitado para o processo alvo. Se esse não for o caso, você pode usar a flag `-force_dep` para forçar a ativação. No entanto, no caso improvável de o alvo realmente precisar de DEP desabilitado para funcionar corretamente, forçá-lo pode fazer com que ele se comporte mal.

### Qual é a sobrecarga de desempenho?

De acordo com medições iniciais em decodificação de imagem, em um alvo de 64 bits bem-comportado com as configurações padrão do TinyInst, a sobrecarga de desempenho foi de cerca de 15% sem um cliente e cerca de 20% com o cliente de exemplo que coleta cobertura. Observe que isso não inclui o tempo limite introduzido pela instrumentação inicial dos módulos. Veja as dicas de desempenho abaixo para mais detalhes.

## Compilando o TinyInst

1. Abra um terminal e configure seu ambiente de compilação (por exemplo, no Windows, execute vcvars64.bat / vcvars32.bat)

2. Navegue até o diretório que contém o código-fonte

3. Execute os seguintes comandos (altere o generator de acordo com a versão do IDE e da plataforma para a qual deseja compilar):

#### Windows```
mkdir build
cd build
cmake -G "Visual Studio 16 2019" -A x64 ..
cmake --build . --config Release

macOS```

mkdir build cd build cmake -G Xcode .. cmake --build . --config Release

#### Linux```
mkdir build
cd build
cmake ..
cmake --build . --config Release

Cross-compilação para Android```

mkdir build cd build cmake -DCMAKE_TOOLCHAIN_FILE=</path/to/android/ndk>build/cmake/android.toolchain.cmake -DANDROID_NDK=</path/to/android/ndk> -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM= .. cmake --build . --config Release

Nota #1: o build de 64 bits também será executado em alvos de 32 bits nos sistemas operacionais Windows e Linux

Nota #2: Encontrando problemas ao criar um build de 32 bits em Windows de 64 bits devido ao ambiente não estar configurado corretamente e bibliotecas ausentes? Abra o arquivo .sln gerado no Visual Studio e compile a partir daí em vez de executar cmake --build. Observe também que o build de 64 bits funcionará em alvos de 32 bits, então criar um build de 32 bits pode não ser necessário.

## Usando o TinyInst

O TinyInst é projetado principalmente para ser usado como uma biblioteca dentro de outros programas.

Um cliente TinyInst é escrito como uma subclasse da classe TinyInst. O cliente pode então sobrescrever os métodos da API que precisar. Os métodos da API estão definidos abaixo.

Após a criação do cliente, ele deve ser inicializado com opções de linha de comando chamando

`void init(int argc, char **argv);`

As opções de linha de comando são definidas abaixo e um cliente também pode definir as suas próprias. Depois disso, para executar e controlar um programa instrumentado, as seguintes funções podem ser usadas.

`DebuggerStatus Run(int argc, char **argv, uint32_t timeout);`
`DebuggerStatus Attach(unsigned int pid, uint32_t timeout);`

Essas funções ou executam um programa (usando a linha de comando especificada) ou anexam a um programa já em execução. Se nenhum método alvo for especificado, o alvo continuará em execução até que o programa encerre, o programa sofra um crash ou o tempo limite (dado em milissegundos) expire. Se um método alvo for definido, o TinyInst retornará sempre que o método alvo for inserido e sempre que o método alvo retornar, permitindo que o chamador execute tarefas adicionais.

Quando `Run` e `Attach` retornam enquanto o processo alvo ainda está ativo, as seguintes funções podem ser usadas para encerrar o processo ou continuar a execução.

`DebuggerStatus Kill();`

`DebuggerStatus Continue(uint32_t timeout);`

O TinyInst acompanha um binário de cobertura de exemplo, que pode ser invocado usando

`<options> -- <target command line>`

Exemplo no Windows:

`litecov.exe -instrument_module notepad.exe -coverage_file coverage.txt -- notepad.exe`


## API de Instrumentação

### Callbacks de eventos do depurador 

Esses callbacks são apenas informativos e o cliente não deve emitir nenhum código instrumentado durante eles. Os clientes devem chamar o mesmo handler definido na superclasse antes de tratar esses eventos por conta própria.

`OnProcessCreated`
Chamado quando o processo alvo é criado ou anexado.

`OnProcessExit`
Chamado quando o processo alvo encerra.

`OnProcessEntrypoint`
Chamado quando o entrypoint do processo (binário principal) é alcançado

`OnTargetMethodReached`
Se o método alvo for definido, chamado quando o método alvo é alcançado pela primeira vez.