# Taint Engine

**Repository Path**: shinian9712/taint_engine

## Basic Information

- **Project Name**: Taint Engine
- **Description**: Taint Engine is a TCG backend that supports taint tracking, providing  simple and easy to use API.
- **Primary Language**: C
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-08-26
- **Last Updated**: 2024-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Taint Engine

1) Introduction
Taint Engine is a TCG backend that supports taint tracking, providing simple and easy to use
API. Different from other taint tracking tools using instrumentation to achieve taint tracking,
Taint Engine integrates taint tracking as a basic function in TCG backend, which provides a 
flexible and highly aggregated way to implement taint tracking, while leave TCG frontend 
unchanged. Currently, Taint Engine supports all the QEMU targets and 64bit host. 

2) How To Use
To use the taint tracking API provided by Taint Engine, Taint Engine should be enabled before 
compiling QEMU, which can be enabled by:
    configure --enable-taint-engine

Before using taint tracking API, headers of Taint Engine should be included:
    #include "tcg/tcg-taint.h"

3) Taint Tracking API
Taint Engine provides a series of simple but powerful taint tracking APIs, which can be easily
used in TCG helpers and virtual devices. The APIs are as follows:

    a) void taint_engine_set_mem_untaint (unsigned mmuidx, size_t gpa);
        Clear taint info of guest's memory(1 byte) indicated by @mmuidx and @gpa. 
        @mmuidx: MMU index.
        @gpa: guest physical address. 

    b) void taint_engine_set_mem_taint (unsigned mmuidx, size_t gpa, uint8_t taint);
        Set taint info of guest's memory(1 byte) indicated by @mmuidx and @gpa as @taint. 
        @mmuidx: MMU index.
        @gpa: guest physical address. 

    c) void taint_engine_set_env_untaint (size_t hva);
        Clear taint info of host's memory(1 byte) indicated by @hva. 
        @hva: host virtual address.

    d) void taint_engine_set_env_taint (size_t hva, uint8_t taint);
        Set taint info of host's  memory(1 byte) indicated by @hva as @taint. 
        @hva: host virtual address.

    e) uint8_t taint_engine_get_mem_taint (unsigned mmuidx, size_t gpa);
        Get taint info of guest's memory(1 byte) indicated by @mmuidx and @gpa.
        @mmuidx: MMU index.
        @gpa: guest physical address. 

    f) uint8_t taint_engine_get_env_taint (size_t hva);
        Get taint info of guest's memory(1 byte) indicated by @hva.
        @hva: host virtual address.
        
    g) void taint_engine_init (void);
        Initialize Taint Engine.
    
    h) void taint_engine_run (void);
        Start Taint Engine.
    
    i) void taint_engine_stop (void);
        Stop Taint Engine temporary.

A brief example to illustrate how use taint tracking api:
    
    vl.c:
    ...
    #incldue "tcg/tcg-taint.h"
    ...

    int main (...) {
        ...
        /* Before using taint tracking API, we need to
          * 1) Initialize Taint Engine.
          * 2) Start Taint Engine. */
        taint_engine_init (); // Initialize Taint Engine.
        taint_engine_start (); // Start Taint Engine.
        ...
    }

    helper.c:
    ...
    #incldue "tcg/tcg-taint.h"
    ...

    void example_helper0 () {
        /* when invoking this helper, the taint info of
          * guest's memory indicated by mmuidx=0 and 
          * address=0x4000 will be set to 1. */
        taint_engine_set_mem_taint (0,  0x4000, 1);
    }

     void example_helper1 () {
        /* when invoking this helper, we can easily get 
          * the taint info of guest's memory indicated by
          * mmuidx=0 and address=0x8000. */
        uint8_t taint_info = taint_engine_get_mem_taint (0, 0x8000);
    }

4) Performance
Generally, the performance of Taint Engine is about five times slower than other TCG backend. 
Because we are using interpreter to achieve taint tracking.