dynamic-instrumentation

name	dynamic-instrumentation
description	Expertise in LLVM-based dynamic binary instrumentation, runtime tracing, and program monitoring. Use this skill when implementing runtime analysis tools, code coverage systems, profilers, or dynamic security monitors.

Dynamic Instrumentation Skill

This skill covers dynamic binary instrumentation (DBI), runtime tracing, and program monitoring using LLVM infrastructure.

Dynamic Binary Instrumentation Overview

What is DBI?

Dynamic Binary Instrumentation allows modifying program behavior at runtime without source code access:

• Insert analysis code at arbitrary points
• Monitor program execution
• Modify control flow and data

LLVM-Based DBI Tools

• QBDI: QuarkslaB Dynamic Binary Instrumentation
• Instrew: Fast instrumentation through LLVM lifting
• binopt: Runtime optimization of binary code

QBDI (QuarkslaB DBI)

Basic Usage

#include <QBDI.h>

// Callback function for instrumentation
QBDI::VMAction onInstruction(QBDI::VMInstanceRef vm, 
                              QBDI::GPRState *gprState,
                              QBDI::FPRState *fprState, 
                              void *data) {
    // Get current instruction info
    const QBDI::InstAnalysis *inst = vm.getInstAnalysis();
    
    printf("Executing: 0x%lx - %s %s\n", 
           inst->address, 
           inst->mnemonic, 
           inst->operandsStr);
    
    return QBDI::VMAction::CONTINUE;
}

int main() {
    QBDI::VM vm;
    
    // Get current stack
    uint8_t *fakestack;
    QBDI::allocateVirtualStack(vm.getGPRState(), 0x100000, &fakestack);
    
    // Add instrumentation callback
    vm.addCodeCB(QBDI::PREINST, onInstruction, nullptr);
    
    // Run target function
    QBDI::rword retval;
    vm.call(&retval, (QBDI::rword)targetFunction, {arg1, arg2});
    
    return 0;
}

Memory Access Tracking

QBDI::VMAction onMemoryAccess(QBDI::VMInstanceRef vm,
                               QBDI::GPRState *gprState,
                               QBDI::FPRState *fprState,
                               void *data) {
    // Get memory accesses for current instruction
    std::vector<QBDI::MemoryAccess> memAccesses = vm.getMemoryAccess();
    
    for (const auto &access : memAccesses) {
        const char* type = (access.type == QBDI::MEMORY_READ) ? "READ" : "WRITE";
        printf("%s: addr=0x%lx, size=%d, value=0x%lx\n",
               type, access.accessAddress, access.size, access.value);
    }
    
    return QBDI::VMAction::CONTINUE;
}

// Register callback for memory access events
vm.addMemAccessCB(QBDI::MEMORY_READ_WRITE, onMemoryAccess, nullptr);

Instruction Filtering

// Only instrument specific instruction ranges
vm.addCodeRangeCB(startAddr, endAddr, QBDI::PREINST, callback, nullptr);

// Instrument specific modules
vm.addCodeAddrCB(targetAddr, QBDI::PREINST, callback, nullptr);

// Remove instrumentation dynamically
vm.deleteInstrumentation(callbackId);

Instrew - LLVM Lifting DBI

Concept

Instrew lifts binary code to LLVM IR at runtime, enabling:

• High-level optimizations on binary code
• Efficient instrumentation through LLVM passes
• JIT recompilation with modifications

Architecture

Binary → Rellume Lifter → LLVM IR → Custom Passes → JIT → Execute
                              ↓
                     [Instrumentation Passes]

Compile-Time Instrumentation

LLVM IR Instrumentation Pass

struct InstrumentationPass : public llvm::PassInfoMixin<InstrumentationPass> {
    llvm::PreservedAnalyses run(llvm::Module &M,
                                 llvm::ModuleAnalysisManager &MAM) {
        auto &Ctx = M.getContext();
        
        // Declare instrumentation functions
        auto *VoidTy = llvm::Type::getVoidTy(Ctx);
        auto *Int64Ty = llvm::Type::getInt64Ty(Ctx);
        
        auto *LogFuncTy = llvm::FunctionType::get(VoidTy, {Int64Ty}, false);
        auto LogFunc = M.getOrInsertFunction("__log_bb", LogFuncTy);
        
        for (auto &F : M) {
            for (auto &BB : F) {
                // Insert at beginning of each basic block
                llvm::IRBuilder<> Builder(&*BB.getFirstInsertionPt());
                
                auto *BBAddr = llvm::ConstantInt::get(
                    Int64Ty, reinterpret_cast<uint64_t>(&BB));
                Builder.CreateCall(LogFunc, {BBAddr});
            }
        }
        
        return llvm::PreservedAnalyses::none();
    }
};

SanitizerCoverage

Built-in LLVM coverage instrumentation:

# Enable coverage instrumentation
clang -fsanitize-coverage=trace-pc-guard source.c

# Edge coverage
clang -fsanitize-coverage=edge source.c

# Trace comparisons
clang -fsanitize-coverage=trace-cmp source.c

// Implement coverage callbacks
extern "C" void __sanitizer_cov_trace_pc_guard(uint32_t *guard) {
    if (!*guard) return;
    
    void *PC = __builtin_return_address(0);
    printf("Edge: guard=%u, PC=%p\n", *guard, PC);
}

extern "C" void __sanitizer_cov_trace_pc_guard_init(
    uint32_t *start, uint32_t *stop) {
    
    static uint32_t N = 0;
    for (uint32_t *x = start; x < stop; x++) {
        *x = ++N;
    }
    printf("Total edges: %u\n", N);
}

Runtime Tracing

Function Tracing

// Compile with: clang -finstrument-functions source.c

extern "C" {
    void __cyg_profile_func_enter(void *func, void *caller) {
        Dl_info info;
        if (dladdr(func, &info)) {
            printf("ENTER: %s\n", info.dli_sname);
        }
    }
    
    void __cyg_profile_func_exit(void *func, void *caller) {
        Dl_info info;
        if (dladdr(func, &info)) {
            printf("EXIT: %s\n", info.dli_sname);
        }
    }
}

XRay Instrumentation

LLVM's built-in instrumentation framework:

# Enable XRay
clang -fxray-instrument -fxray-instruction-threshold=1 source.c

// Custom XRay handler
[[clang::xray_always_instrument]]
void my_function() {
    // Function will always be instrumented
}

// Runtime control
__xray_patch();    // Enable instrumentation
__xray_unpatch();  // Disable instrumentation

Performance Profiling

Block Frequency

struct BlockProfiler : public llvm::PassInfoMixin<BlockProfiler> {
    llvm::PreservedAnalyses run(llvm::Function &F,
                                 llvm::FunctionAnalysisManager &FAM) {
        auto &BFI = FAM.getResult<llvm::BlockFrequencyAnalysis>(F);
        
        for (auto &BB : F) {
            auto Freq = BFI.getBlockFreq(&BB);
            llvm::errs() << BB.getName() << ": " << Freq.getFrequency() << "\n";
        }
        
        return llvm::PreservedAnalyses::all();
    }
};

Sampling Profiler Integration

// Use with perf or similar
// Map addresses back to source using debug info

void interpretProfile(const std::string &profilePath) {
    // Parse profile data
    // Map samples to LLVM IR/source locations
    // Generate optimization hints
}

System Call Monitoring

SysCallStubber

Intercept and monitor system calls:

// Intercept system calls at LLVM IR level
struct SyscallMonitor : public llvm::PassInfoMixin<SyscallMonitor> {
    llvm::PreservedAnalyses run(llvm::Module &M,
                                 llvm::ModuleAnalysisManager &MAM) {
        for (auto &F : M) {
            for (auto &BB : F) {
                for (auto &I : BB) {
                    if (auto *Call = llvm::dyn_cast<llvm::CallInst>(&I)) {
                        if (isSyscallWrapper(Call)) {
                            instrumentSyscall(Call);
                        }
                    }
                }
            }
        }
        return llvm::PreservedAnalyses::none();
    }
};

eBPF Integration

bpfcov - Code Coverage with eBPF

// eBPF program for coverage collection
SEC("uprobe/target_function")
int trace_function(struct pt_regs *ctx) {
    u64 addr = PT_REGS_IP(ctx);
    
    // Record coverage
    u32 *count = bpf_map_lookup_elem(&coverage_map, &addr);
    if (count) {
        __sync_fetch_and_add(count, 1);
    }
    
    return 0;
}

Taint Tracking

Dynamic Taint Analysis

// Shadow memory for taint tracking
class TaintTracker {
    std::unordered_map<void*, TaintInfo> shadowMemory;
    
public:
    void markTainted(void *addr, size_t size, TaintSource source) {
        for (size_t i = 0; i < size; i++) {
            shadowMemory[(char*)addr + i] = {source, true};
        }
    }
    
    bool isTainted(void *addr) {
        return shadowMemory.count(addr) && shadowMemory[addr].tainted;
    }
    
    void propagateTaint(void *dst, void *src, size_t size) {
        for (size_t i = 0; i < size; i++) {
            if (isTainted((char*)src + i)) {
                markTainted((char*)dst + i, 1, shadowMemory[(char*)src + i].source);
            }
        }
    }
};

Best Practices

1. Minimize Overhead: Only instrument necessary code paths
2. Buffer Events: Batch event logging to reduce I/O
3. Use Sampling: Full tracing is expensive, sample for production
4. Thread Safety: Ensure instrumentation is thread-safe
5. Symbol Resolution: Use debug info for meaningful output

Integration Patterns

Fuzzer Integration

// Coverage-guided fuzzing with instrumentation
void fuzzerCallback(uint8_t *data, size_t size) {
    // Reset coverage
    __sanitizer_cov_reset_coverage();
    
    // Run target
    targetFunction(data, size);
    
    // Collect coverage
    uint8_t *coverage = __sanitizer_cov_get_coverage();
    feedbackToFuzzer(coverage);
}

Debugging Integration

// Breakpoint-like instrumentation
void onBreakpoint(void *addr, void *context) {
    // Dump registers
    // Inspect memory
    // Allow continue/step
}

Resources

See Dynamic Binary Instrumentation, Monitor, and eBPF sections in README.md for related tools and projects.

Getting Detailed Information

When you need detailed and up-to-date resource links, tool lists, or project references, fetch the latest data from:

https://raw.githubusercontent.com/gmh5225/awesome-llvm-security/refs/heads/main/README.md

This README contains comprehensive curated lists of:

• Dynamic Binary Instrumentation tools (DBI section)
• Runtime monitoring and tracing tools (Monitor section)
• eBPF-related projects and resources