Skip to content

Latest commit

 

History

History
93 lines (82 loc) · 4.05 KB

README.md

File metadata and controls

93 lines (82 loc) · 4.05 KB
Raw

Self-Propelled Instrumentation

Note

  1. Currently SPI depends on a customized dyninstAPI
  • build dyninst with arch-x86.h exposed to public
  • build dyninst with OpenMP disabled
  1. Dynamically linked functions may appear twice during instrumentation, because these functions exist in .plt sections too.

TODOs

  • Inter-host propel
  • Solve the arch-x86.h dependency problem
    • A possible solution is to expose codegenAPI in dyninst
  • OpenMP hangs during parsing
  • Test suite
  • Update MIST and SecStar

How to Install

  1. Copy example-make.config to be config.mk.
  2. Edit config.mk to define each macro variable.
  • DYNINST_DIR: absolute path of Dyninst's lib directory
  • SP_DIR: absolute path of this package (the output of pwd), because this file is also used by Makefile, I don't put pwd in it.
  • DYNLINK: true for building shared library for agent, otherwise for building static library
  1. Run make spi to build injector and libagent.so.
  2. Run make test_agent to build example user agents
  3. For more make options, see Make Arguments

How to Run

  1. Export Runtime environment variables, see Environment Variable section for detail:
  2. SP_DIR
  3. PLATFORM
  4. SP_AGENT_DIR
  5. Make sure that your system does not block non-child ptrace
  • To temporarily disable this measure (until a reboot), execute the following command:
    echo 0 > /proc/sys/kernel/yama/ptrace_scope
  • To permanently disable this measure, edit the file /etc/sysctl.d/10-ptrace.conf and follow the directions in that file.
  • For more information, see https://wiki.ubuntu.com/SecurityTeam/Roadmap/KernelHardening
  1. There are two ways to kick start the Self-Propel
    1. To use the environment variable LD_PRELOAD when starting the user process.
      Ex: LD_PRELOAD=$SP_DIR/PLATFORM/test_agent/print_test_agent.so [EXECUTABLE]
    2. To use the injector to force a running process to load agent library, note that injector has two modes, pid injection and port injection
      Ex: $SP_DIR/PLATFORM/injector.exe pid [PID] or $SP_DIR/PLATFORM/injector.exe port [PORT NUMBER]

Interprocess Propel

  • Local Machine
    • Interprocess propelling relies on the following environment variables: SP_DIR, PLATFORM, SP_AGENT_DIR
  • Inter-host
    • Export desired environment variables in your .bashrc file. Following environment variables are necessary:
      • SP_DIR
      • PLATFORM
      • SP_AGENT_DIR
      • Add DYNINST_ROOT/lib, SP_DIR/PLATFORM to your LD_LIBRARY_PATH

Environment Variables

  1. FOR DEBUGGING
  2. SP_COREDUMP: enables core dump when segfault happens
  3. SP_DEBUG: enables printing out debugging messages
  4. SP_TEST_RELOCINSN: only uses instruction relocation instrumentation worker
  5. SP_TEST_RELOCBLK: only uses call block relocation instrumentation worker
  6. SP_TEST_SPRING: only uses sprint block instrumentation worker
  7. SP_TEST_TRAP: only uses trap instrumentation worker
  8. SP_NO_TAILCALL: don't instrument tail calls
  9. SP_LIBC_MALLOC: will always use libc malloc
  10. SP_NO_LIBC_MALLOC: will never use libc malloc
  11. FOR RUNTIME
  12. PLATFORM: 'i386-unknown-linux2.4' for x86 or 'x86_64-unknown-linux2.4' for x86-64
  13. SP_DIR: the root directory of self-propelled instrumentation.
  14. SP_AGENT_DIR: the directory path of agent shared library that will be injected.

Shared memory id used

  1. 1986+[user_process_pid]: for communication between injector process and user process

Make Arguments

For testing

  • make unittest: build unittests
  • make mutatee: build simple mutatees
  • make external_mutatee: build real world mutatees
  • make test: unittest + mutatee + external_mutatee

For main self propelled

  • make injector_exe
  • make agent_lib
  • make spi: agent_lib + injector_exe

For everything

  • make / make all: spi + test

For cleaning

  • make clean_test: clean test stuffs
  • make clean: only clean core self-propelled stuffs, excluding dependency
  • make clean_all: clean everything, including dependency
  • make clean_objs: clean core self-propelled objs