{"id":13639448,"url":"https://github.com/carbonblack/binee","last_synced_at":"2026-01-12T00:44:27.179Z","repository":{"id":43676370,"uuid":"193735522","full_name":"carbonblack/binee","owner":"carbonblack","description":"Binee: binary emulation environment","archived":false,"fork":false,"pushed_at":"2023-02-25T04:34:18.000Z","size":29555,"stargazers_count":494,"open_issues_count":17,"forks_count":74,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-08-03T01:14:47.116Z","etag":null,"topics":["analysis","binary","binary-analysis","emulation","hooks","malware","mock","static-analysis","testing","unicorn-emulator"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carbonblack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-25T15:32:15.000Z","updated_at":"2024-07-16T13:07:32.000Z","dependencies_parsed_at":"2024-06-18T19:48:18.945Z","dependency_job_id":"e8571217-be62-4b33-afbd-5fdc4b07fbc9","html_url":"https://github.com/carbonblack/binee","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carbonblack%2Fbinee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carbonblack%2Fbinee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carbonblack%2Fbinee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carbonblack%2Fbinee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carbonblack","download_url":"https://codeload.github.com/carbonblack/binee/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810410,"owners_count":17206758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","binary","binary-analysis","emulation","hooks","malware","mock","static-analysis","testing","unicorn-emulator"],"created_at":"2024-08-02T01:01:00.700Z","updated_at":"2024-11-09T09:30:59.563Z","avatar_url":"https://github.com/carbonblack.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# binee (Binary Emulation Environment)\n\nBinee is a complete binary emulation environment that focuses on introspection\nof all IO operations. Primary goals for this project are to provide a flexible\nenvironment for determining a binaries side effects on the system.\n\nThe goals Binee tries to solve are the following:\n\n1. Realistic loading of a PE file and its required dependencies. The userland\n   memory should look as close to a real execution as possible.\n2. Easy to use hooking framework. We want to create a flexible hooking\n   framework that allows the analyst to rapidly implement new hooks and capture\n   data.\n3. Mock out as much of the OS internals as reasonably possible. Currently,\n   there are small mocks of the file system, registry, threading and TIB/PEB\n   structures for Windows.\n4. The OS environment, as much as possible, should be defined in a\n   configuration file. This enables rapid movement from environment to\n   environment.\n\n**If you choose to use Binee to emulate portions of Microsoft Windows, you are\nsolely responsible for obtaining any necessary rights and licenses from\nMicrosoft.**\n\n## Development and Support\n\nPlease feel free to submit github issues or if you want to talk with us directly, come join is in slack\n\n[slack workspace](https://join.slack.com/t/cb-binee/shared_invite/zt-e13fhpox-yq6ncXpX6hXR8vJ0p8PEvw)\n\n## DEF CON 27 Materials\n\n[slides](https://github.com/carbonblack/binee/blob/defcon27/Kyle%20Gwinnup%20-%20Next%20Generation%20Process%20Emulation%20with%20Binee.pdf)\n\n[demo video](https://github.com/carbonblack/binee/blob/defcon27/Kyle%20Gwinnup%20-%20Next%20Generation%20Process%20Emulation%20with%20Binee%20Demo.mp4)\n\n[presentation](https://www.youtube.com/watch?v=z4OvVFw5pYI)\n\n# Setup and developing in Docker container\n\nIf you are running Binee on Microsoft Windows, you can skip the mock file system step. \n\nMost malware will require at least some standard DLLs and these DLLs will need\nto be accessible from the mock file system. The default \"root\" mock file system\nis located in `os/win10_32/`. In order to allow for the malware to load up DLLs\nyou will need to copy them into the appropriate location within the mock file\nsystem. Typically, these should be copied into,\n`os/win10_32/windows/system32/`. Currently, only 32-bit DLL's pulled from a 32-bit \nWindows installation are supported. Once you have the required files in that\ndirectory, you can move onto the compiling and running step.\n\n## Compiling and running\n\nBuild with the following docker command `docker build -t binee .`\n\n```\ndocker run -it -v $PWD:/bineedev/go/src/github.com/carbonblack/binee binee bash\n```\n\nDownload Golang dependencies and build Binee \n\n```\nroot@2b0fee41629f:~/go/src/github.com/carbonblack/binee# go build\n```\n_Note: presence of go.mod file will direct the build utility to collect dependencies upon build, and also allow for the repository to be cloned and developed at any path (regardless of `$GOPATH`) directory_\n\n\nAt this point you should be able to execute binee within the Docker container\nand see the usage menu.\n\n```\nroot@6a6fe8c2b2a7:~/go/src/github.com/carbonblack/binee# ./binee -h\nUsage of ./binee:\n  -A    list all apisets and their mappings\n  -a string\n        get the real dll name from an apiset name\n  -c string\n        path to configuration file\n  -d    show the dll prfix on all function calls\n  -e    dump pe file's exports table\n  -i    dump a pe file's imports table\n  -j    output data as json\n  -l    call DLLMain while loading DLLs\n  -r string\n        root path of mock file system, defaults to ./os/win10_32 (default \"os/win10_32/\")\n  -v    verbose level 1\n  -vv\n        verbose level 2\n```\n\nIf you are running on Microsoft Windows and/or you have your mock file system\nconfigured properly, you should be able to execute all the PE files within the\n`tests/` directory.\n\n```\nroot@6a6fe8c2b2a7:~/go/src/github.com/carbonblack/binee# go build \u0026\u0026 ./binee tests/ConsoleApplication1_x86.exe \n[1] 0x2190c0b0: F GetSystemTimeAsFileTime(lpSystemTimeAsFileTime = 0xb7feffe0) = 0xb7feffe0\n[1] 0x21905b40: P GetCurrentThreadId() = 0x0\n[1] 0x219138d0: P GetCurrentProcessId() = 0x2001\n[1] 0x2011ef30: P GetCurrentProcessId() = 0x2001\n[1] 0x21905b50: F QueryPerformanceCounter(lpPerformanceCount = 0xb7feffd8) = 0x1\n[1] 0x2190c500: F IsProcessorFeaturePresent(ProcessorFeature = 0xa) = 0x1\n[1] 0x213af570: F _initterm_e(PVFV = 0x4020d8, PVFV = 0x4020e4) = 0x0\n[1] 0x213af970: F _initterm(PVPV = 0x4020cc, PVPV = 0x4020d4) = 0x0\n[1] 0x213be980: F __p___argv() = 0x7ffe0004\n[1] 0x213b96f0: F __p___argc() = 0x7ffe0000\n[1] 0x213bec50: F _get_initial_narrow_environment() = 0x7ffe0000\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x5dda9c68\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'GENERIC_READ = 0x%llx\\n', p0 = 0x80000000) = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x403380\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'GENERIC_WRITE = 0x%llx\\n', p0 = 0x40000000) = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x403380\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'INVALID_HANDLE = 0x%llx\\n', p0 = 0xffffffff) = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x0\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'CREATE_ALWAYS = 0x%x\\n', p0 = 0x2) = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x403380\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'FILE_ATTRIBUTE_NORMAL = 0x%x\\n', p0 = 0x80) = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x403380\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'ERROR_SUCCESS = 0x%x\\n', p0 = 0x0) = 0x403380\n[1] 0x21913b80: F CreateFileA(lpFileName = 'malfile.exe', dwDesiredAccess = 0xc0000000, dwShareMode = 0x0, lpSecurityAttributes = 0x0, dwCreationDisposition = 0x2, dwFlagsAndAttributes = 0x80, hTemplateFile = 0x0) = 0xa00007b6\n[1] 0x2196bfbe: F VerSetConditionMask() = 0xa00007b6\n[1] 0x213ac0a0: P __acrt_iob_func() = 0xa00007b6\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'out = 0x%x\\n', p0 = 0xa00007b6) = 0x403380\n[1] 0x2196bfbe: F VerSetConditionMask() = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x403380\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'out = 0x%x\\n', p0 = 0x403380) = 0x403380\n[1] 0x2196bfbe: F VerSetConditionMask() = 0x403380\n[1] 0x213ac0a0: P __acrt_iob_func() = 0x403380\n[1] 0x213bb710: F __stdio_common_vfprintf(stream = 0x0, format = 'out = 0x%x\\n', p0 = 0x403380) = 0x403380\n[1] 0x21bc0780: P memset(dest = 0xb7feff1c, char = 0x0, count = 0x58) = 0xb7feff1c\n[1] 0x21914000: F WriteFile(hFile = 0xa00007b6, lpBuffer = 0xb7feff10, nNumberOfBytesToWrite = 0xb, lpNumberOfBytesWritten = 0xb7feff0c, lpOverlapped = 0x0) = 0xb\n[1] 0x2190c500: F IsProcessorFeaturePresent(ProcessorFeature = 0x17) = 0x1\n[1] 0x2190fef0: F SetUnhandledExceptionFilter(lpTopLevelExceptionFilter = 0x0) = 0x4\n[1] 0x21927950: F UnhandledExceptionFilter(ExceptionInfo = 0x402100) = 0x1\n[1] 0x219138c0: P GetCurrentProcess() = 0x1\n[1] 0x20122cb0: P GetCurrentProcess() = 0x1\n[1] 0x21910690: F TerminateProcess(hProcess = 0xffffffff, uExitCode = 0xc0000409) = 0xffffffff\n```\n\n\n## Compiling on windows:\n\n1-Install MSYS64/32  : https://osdn.net/projects/mingw/releases/  \n2-update the system packages :   \n`  $ pacman --needed -Sy bash pacman pacman-mirrors msys2-runtime`  \n -restart MSYS then update everything else :   \n`  $ pacman -Su`  \n\n  To compile for Windows 32-bit, run:\n```\n  $ pacman -S python2\n  $ pacman -S make\n  $ pacman -S mingw-w64-i686-toolchain\n  ```\n  To compile for Windows 64-bit, run:\n```\n  $ pacman -S python2\n  $ pacman -S make\n  $ pacman -S mingw-w64-x86_64-toolchain\n  ```\n  -install Go :  \n`pacman -S mingw-w64-x86_64-go`\n\n3-restart MSYS again ; then clone into unicorn and install it:  \n `git clone https://github.com/unicorn-engine/unicorn `  \n `cd unicorn`  \n `./make.sh `  \n `./make.sh install`  \n\n4-Clone Binee and Build \n`cd binee`   \n`go build`  \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarbonblack%2Fbinee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarbonblack%2Fbinee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarbonblack%2Fbinee/lists"}