BinaryDebugger.h

#ifndef ROSE_BinaryAnalysis_Debugger_H
#define ROSE_BinaryAnalysis_Debugger_H

#include <featureTests.h>
#ifdef ROSE_ENABLE_BINARY_ANALYSIS

#include <BitFlags.h>
#include <boost/filesystem.hpp>
#include <boost/noncopyable.hpp>
#include <boost/regex.hpp>
#include <Disassembler.h>
#include <Sawyer/BitVector.h>
#include <Sawyer/Message.h>
#include <Sawyer/Optional.h>
#include <Sawyer/Trace.h>

namespace Rose {
namespace BinaryAnalysis {

typedef Sawyer::SharedPointer<class Debugger> DebuggerPtr;

class Debugger: private boost::noncopyable, public Sawyer::SharedObject {
public:
    typedef Sawyer::SharedPointer<Debugger> Ptr;

    enum DetachMode {
        KILL,                                           
        DETACH,                                         
        CONTINUE,                                       
        NOTHING                                         
    };

    enum Flag {
        ATTACH          = 0x00000001,                   
        REDIRECT_INPUT  = 0x00000002,                   
        REDIRECT_OUTPUT = 0x00000004,                   
        REDIRECT_ERROR  = 0x00000008,                   
        CLOSE_FILES     = 0x00000010,                   
        DEFAULT_FLAGS   = 0x00000013                    
    };

    class Specimen {
        BitFlags<Flag> flags_;                          // operational flags
        unsigned long persona_;                         // personality(2) flags

        // Members for running a program
        boost::filesystem::path program_;               // full path of executable program
        std::vector<std::string> arguments_;            // command-line arguments of executable program
        boost::filesystem::path workingDirectory_;      // name or working directory, or use CWD if empty
        std::vector<boost::regex> clearEnvVars_;        // clear environment variables matching these patterns
        std::map<std::string, std::string> setEnvVars_; // environment variables to be set

        // Members for attaching to a process
        int pid_;                                       // process ID (int instead of pid_t for portability)

    public:
        Specimen()
            : persona_(getPersonality()), pid_(-1) {}

        Specimen(int pid) /*implicit*/
            : flags_(DEFAULT_FLAGS), persona_(getPersonality()), pid_(pid) {}

        Specimen(const boost::filesystem::path &name) /*implicit*/
            : flags_(DEFAULT_FLAGS), persona_(getPersonality()), program_(name), pid_(-1) {}

        Specimen(const boost::filesystem::path &name, const std::vector<std::string> &args)
            : flags_(DEFAULT_FLAGS), persona_(getPersonality()), program_(name), arguments_(args), pid_(-1) {}

        Specimen(const std::vector<std::string> &nameAndArgs) /*implicit*/
            : flags_(DEFAULT_FLAGS), persona_(getPersonality()), program_(nameAndArgs.front()),
              arguments_(nameAndArgs.begin()+1, nameAndArgs.end()), pid_(-1) {
        }

    public:
        boost::filesystem::path program() const {
            return program_;
        }
        void program(const boost::filesystem::path &name) {
            program_ = name;
            pid_ = -1;
        }
        const std::vector<std::string>& arguments() const {
            return arguments_;
        }
        void arguments(const std::vector<std::string> &args) {
            arguments_ = args;
        }
        void eraseEnvironmentVariable(const std::string&);

        void eraseMatchingEnvironmentVariables(const boost::regex&);

        void eraseAllEnvironmentVariables();

        void insertEnvironmentVariable(const std::string &name, const std::string &value);

        boost::filesystem::path workingDirectory() const {
            return workingDirectory_;
        }
        void workingDirectory(const boost::filesystem::path &name) {
            workingDirectory_ = name;
        }
        const BitFlags<Flag>& flags() const {
            return flags_;
        }
        BitFlags<Flag>& flags() {
            return flags_;
        }
        unsigned long persona() const {
            return persona_;
        }
        void persona(unsigned long bits) {
            persona_ = bits;
        }
        bool randomizedAddresses() const;
        void randomizedAddresses(bool);
        int process() const {
            return pid_;
        }
        void process(int pid) {
            pid_ = pid;
            program_.clear();
        }
        void print(std::ostream &out) const;

        // Used internally.
        char** prepareEnvAdjustments() const;
    };

public:
    static Sawyer::Message::Facility mlog;              
private:
    typedef Sawyer::Container::Map<RegisterDescriptor, size_t> UserRegDefs;
    enum RegPageStatus { REGPAGE_NONE, REGPAGE_REGS, REGPAGE_FPREGS };

    Specimen specimen_;                                 // description of specimen being debugged
    int child_;                                         // process being debugged (int, not pid_t, for Windows portability)
    DetachMode autoDetach_;                             // how to detach from the subordinate when deleting this debugger
    int wstat_;                                         // last status from waitpid
    AddressIntervalSet breakpoints_;                    // list of breakpoint addresses
    int sendSignal_;                                    // pending signal
    UserRegDefs userRegDefs_;                           // how registers map to user_regs_struct in <sys/user.h>
    UserRegDefs userFpRegDefs_;                         // how registers map to user_fpregs_struct in <sys/user.h>
    size_t kernelWordSize_;                             // cached width in bits of kernel's words
    uint8_t regsPage_[512];                             // latest register information read from subordinate
    RegPageStatus regsPageStatus_;                      // what are the contents of regPage_?
    Disassembler *disassembler_;                        // how to disassemble instructions
    Sawyer::Optional<rose_addr_t> syscallVa_;           // address of some executable system call instruction.

    //----------------------------------------
    // Real constructors
    //----------------------------------------
protected:
    Debugger()
        : child_(0), autoDetach_(KILL), wstat_(-1), sendSignal_(0), kernelWordSize_(0), regsPageStatus_(REGPAGE_NONE),
          disassembler_(NULL) {
        init();
    }

    explicit Debugger(const Specimen &specimen)
        : child_(0), autoDetach_(KILL), wstat_(-1), sendSignal_(0), kernelWordSize_(0), regsPageStatus_(REGPAGE_NONE),
          disassembler_(NULL) {
        init();
        attach(specimen);
    }

public:
    ~Debugger() {
        detach(autoDetach_);
    }

    //----------------------------------------
    // Static allocating constructors
    //----------------------------------------
public:
    static Ptr instance() {
        return Ptr(new Debugger);
    }

    static Ptr instance(const Specimen &specimen) {
        return Ptr(new Debugger(specimen));
    }

    //----------------------------------------
    // Attaching to subordinate
    //----------------------------------------
public:
    void attach(const Specimen&, Sawyer::Optional<DetachMode> onDelete = Sawyer::Nothing());
    int isAttached() { return child_; }

    void detach(Sawyer::Optional<DetachMode> mode = Sawyer::Nothing());

    void terminate();

    //----------------------------------------
    // Operations on a subordinate
    //----------------------------------------
public:
    void executionAddress(rose_addr_t va);

    rose_addr_t executionAddress();

    void setBreakpoint(const AddressInterval&);

    void clearBreakpoint(const AddressInterval&);

    void clearBreakpoints() { breakpoints_.clear(); }

    void singleStep();

    void runToBreakpoint();

    void runToSyscall();

    Sawyer::Container::Trace<rose_addr_t> trace();

    enum FilterActionFlags {
        REJECT = 0x00000001,                          
        STOP   = 0x00000002                           
    };

    typedef BitFlags<FilterActionFlags> FilterAction;

    template<class Filter>
    Sawyer::Container::Trace<rose_addr_t> trace(Filter &filter) {
        Sawyer::Container::Trace<rose_addr_t> retval;
        while (!isTerminated()) {
            rose_addr_t va = executionAddress();
            FilterAction action = filter(va);
            if (action.isClear(REJECT))
                retval.append(va);
            if (action.isSet(STOP))
                return retval;
            singleStep();
        }
        return retval;
    }

    size_t kernelWordSize();

    Sawyer::Container::BitVector readRegister(RegisterDescriptor);

    void writeRegister(RegisterDescriptor, const Sawyer::Container::BitVector&);
    void writeRegister(RegisterDescriptor, uint64_t value);
    Sawyer::Container::BitVector readMemory(rose_addr_t va, size_t nBytes, ByteOrder::Endianness order);

    size_t writeMemory(rose_addr_t va, size_t nBytes, const uint8_t *bytes);

    template<typename T>
    void writeMemory(rose_addr_t va, const T &value) {
        size_t n = writeMemory(va, sizeof(T), (const uint8_t*)&value);
        ASSERT_always_require(n == sizeof(T));
    }

    size_t readMemory(rose_addr_t va, size_t nBytes, uint8_t *buffer);

    std::string readCString(rose_addr_t va, size_t maxBytes = UNLIMITED);

    bool isTerminated();

    std::string howTerminated();

    const RegisterDictionary* registerDictionary() const;

    Disassembler* disassembler() const {
        return disassembler_;
    }

    int waitpidStatus() const { return wstat_; }

    int remoteSystemCall(int syscallNumber, std::vector<uint64_t> args);

    int remoteOpenFile(const boost::filesystem::path &fileName, unsigned flags, mode_t mode);

    int remoteCloseFile(unsigned remoteFd);

    rose_addr_t remoteMmap(rose_addr_t va, size_t nBytes, unsigned prot, unsigned flags, const boost::filesystem::path&,
                           off_t offset);

public:
    static void initDiagnostics();

private:
    // Initialize tables during construction
    void init();

    // Wait for subordinate or throw on error
    void waitForChild();

    // Open /dev/null with the specified flags as the indicated file descriptor, closing what was previously on that
    // descriptor. If an error occurs, the targetFd is closed anyway.
    void devNullTo(int targetFd, int openFlags);

    // Get/set personality in a portable way
    static unsigned long getPersonality();
    static void setPersonality(unsigned long);

    // Address of a system call instruction. The initial search can be expensive, so the result is cached.
    Sawyer::Optional<rose_addr_t> findSystemCall();

};

std::ostream& operator<<(std::ostream&, const Debugger::Specimen&);

} // namespace
} // namespace

#endif
#endif