{"id":13845567,"url":"https://github.com/REW-sploit/REW-sploit","last_synced_at":"2025-07-12T02:32:08.328Z","repository":{"id":38203679,"uuid":"377511440","full_name":"REW-sploit/REW-sploit","owner":"REW-sploit","description":"Emulate and Dissect MSF and *other* attacks","archived":false,"fork":false,"pushed_at":"2024-02-28T08:33:22.000Z","size":2375,"stargazers_count":136,"open_issues_count":1,"forks_count":23,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-08-05T17:44:45.001Z","etag":null,"topics":["blueteam","cobaltstrike","defense","emulation","malware-analysis","metasploit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/REW-sploit.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}},"created_at":"2021-06-16T13:47:41.000Z","updated_at":"2024-07-22T02:06:18.000Z","dependencies_parsed_at":"2024-02-28T09:35:03.893Z","dependency_job_id":"5291d54f-6c1f-4651-95b7-5bdce9d1adf4","html_url":"https://github.com/REW-sploit/REW-sploit","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/REW-sploit%2FREW-sploit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/REW-sploit%2FREW-sploit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/REW-sploit%2FREW-sploit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/REW-sploit%2FREW-sploit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/REW-sploit","download_url":"https://codeload.github.com/REW-sploit/REW-sploit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225784806,"owners_count":17523708,"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":["blueteam","cobaltstrike","defense","emulation","malware-analysis","metasploit"],"created_at":"2024-08-04T17:03:28.651Z","updated_at":"2024-11-21T18:32:21.721Z","avatar_url":"https://github.com/REW-sploit.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\n\n\u003cimg src=\"https://github.com/REW-sploit/Rs-files/blob/main/img/REW-sploit-Logo.png?raw=true|\" width=\"300\" alt=\"Logo\" style=\"zoom:30%;\" /\u003e\n\n# REW-sploit\n\nNeed help in analyzing  Windows shellcode or attack coming from **Metasploit Framework** or **Cobalt Strike** (or may be also other malicious or obfuscated code)? Do you need to automate tasks with simple scripting? Do you want help to decrypt **MSF** generated traffic by extracting keys from payloads?\n\n**REW-sploit** is here to help Blue Teams!\n\nHere a quick demo:\n\n[\u003cimg src=\"https://asciinema.org/a/ln8tkJH7bOhACFRMdnPmk2i1o.svg\" alt=\"asciicast\" width=\"700\" style=\"zoom:33%;\" /\u003e](https://asciinema.org/a/ln8tkJH7bOhACFRMdnPmk2i1o)\n\nAn introduction to the tool has been registered at **Insomni'hack 2022**:\n\nhttps://www.youtube.com/watch?v=-sjM0k0hvMU\n\n## Install\n\nInstallation is very easy. I strongly suggest to create  a specific Python Env for it:\n\n```\n# python -m venv \u003cyour-env-path\u003e/rew-sploit\n# source \u003cyour-env-path\u003e/rew-sploit/bin/activate\n# git clone https://github.com/REW-sploit/REW-sploit.git\n# cd REW-sploit\n# pip install -U setuptools\n# pip install -r requirements.txt\n# ./apply_patch.py -f\n# ./rew-sploit\n```\n\nIf you prefer, you can use the Dockerfile. To create the image:\n\n```\ndocker build -t rew-sploit/rew-sploit .\n```\n\nand then start it (sharing the `/tmp/` folder):\n\n```\ndocker run --rm -it --name rew-sploit -v /tmp:/tmp rew-sploit/rew-sploit\n```\n\nYou see an `apply_patch.py` script in the installation sequence. This is required to apply a small patch to the `speakeasy-emulator` (https://github.com/fireeye/speakeasy/) to make it compatible with `REW-sploit`. You can easily revert the patch with `./apply_patch.py -r` if required.\n\nOptionally, you can also install Cobalt-Strike Parser:\n\n```\n# cd REW-sploit/extras\n# git clone https://github.com/Sentinel-One/CobaltStrikeParser.git\n```\n\n**NOTE**: from version `0.4.2` I switched to use the latest commit of `Speakeasy-Emulator` instead of the stable release. If you want to use the stable release, use\n\n```\npip install -r requirements_stable.txt\n```\n\n\n\n## Standing on the shoulder of giants\n\n`REW-sploit` is based on a couple of great frameworks, `Unicorn` and `speakeasy-emulator` (but also other libraries). Thanks to everyone and thanks to the OSS movement!\n\n\n\n## How it works\n\nIn general we can say that whilst Red Teams have a lot of tools helping them in \"automating\" attacks, Blue Teams are a bit \"tool-less\". So, what I thought is to build something to help Blue Team Analysis.\n\n`REW-sploit` can get a shellcode/DLL/EXE, emulate the execution, and give you a set of information to help you in understanding what is going on. Example of extracted information are:\n\n- API calls\n- Encryption keys used by **MSF** payloads\n- decrypted 2nd stage coming from **MSF**\n- Cobalt-Strike configurations (if [CobaltStrike parser is installed](https://github.com/Sentinel-One/CobaltStrikeParser))\n\nYou can find several examples on the current capabilities here below:\n\n- [RC4 Keys Extraction](https://asciinema.org/a/ln8tkJH7bOhACFRMdnPmk2i1o?speed=2)\n- [RC4 Keys Extraction + PCAP 2nd stage decryption](https://asciinema.org/a/TfrcYnCaCuCPGVhaeq0wkEyag?speed=2)\n- [ChaCha Keys Extraction](https://asciinema.org/a/01oMaPMG0BmLkPhXkIMNvSO4c?speed=2)\n- [Meterpreter session Decryption (no RSA)](https://asciinema.org/a/Q8zZ8Ri7ZPzpBOZRTh9eZpzWi?speed=2)\n- [Cobalt-Strike beacon Emulation](https://asciinema.org/a/ps4VdIqY71W786j9lOAz9taOp?speed=10)\n- [Cobalt-Strike config Extraction](https://asciinema.org/a/1hGjmn9hgx5i2CAZFePpbaI70?speed=5)\n- [Debugging options](https://asciinema.org/a/kIhOo2jKjOBTcxh8VrU0UzkXi)\n- [Dumping Threads](https://asciinema.org/a/5SeKKodDXl79vceM7eXjsQJil?speed=2)\n- [Dumping Memory Allocations](https://asciinema.org/a/MCWCt3phS9L9YABCeDnUd3poF)\n\n\n## Donut support\n\nYou know for sure the [Donut](https://github.com/TheWover/donut) package, able to create PIC from EXE, DLL, VBScript and JScript.\n\n`Donut`, in order to evade detection, uses a API exports enumeration based on hashes computed on every API name, as many PIC do. This is very CPU intensive (especially in an emulated environment like `REW-sploit`). \nSo, I implemented a sort of shortcut (changed from 0.3.3 release) to unhook some of the slowest parts of emulation when a `Donut` stub is detected.\n\nAlso, in order to be able to correctly complete the emulation, you need to give to `Speakeasy` the DLL to get the complete exports. To do it copy the following DLLs\n\n```\nkernel32.dll\nmscoree.dll\nole32.dll\noleaut32.dll\nwininet.dll\n```\n\nin the `Speakeasy` folder `winenv/decoys/amd64` and/or `winenv/decoys/x86` (see [Speakeasy](https://github.com/fireeye/speakeasy#readme) README for details). If you don't need them, don't leave the DLLs there, in other case they can slow down emulation.\n\nFor `Donut` 1.0 you may want to add even the following DLLs\n\n```\ncombase.dll\nshell32.dll\nntdll.dll\n```\n\n##  EgeBalci/sgn\n\nThis [Shikata Ga Nai](https://github.com/EgeBalci/sgn.git) implementation works just fine most of the times. In some cases it fails with an `invalid read`, so I implemented `Fixup #4` for it. \n\n\n## Anti-debug\n\nA new command `emulate_antidebug` has been added from version `0.4`: this should help in identifying antidebug tricks used in teh analyzed code, so that you can patch it when executing in a real debug environment. This is an example of what has been implemented:\n```\n[#] Call to QueryPerformanceCounter() at 0x414049\n[#] IsDebuggerPresent() at 0x4157e7\n[#] CheckRemoteDebuggerPresent() at 0x415828\n[#] Suspect NtQueryInformationProcess() at 0x4158b3\n[#] Suspect NtQuerySystemInformation() at 0x415a22\n[#] Direct access to PEB!BeingDebugged at 0x415a6a\n[#] Direct access to PEB!NtGlobalFlag at 0x415a9e\n[#] Suspect access to HeapBase (may be used to access Flags and ForceFlags) at 0x415b17\n[#] GetProcAddress() of CRSS.EXE at 0x415b75\n[#] Exclusive CreateFileA() on current process at 0x415bc4\n[#] Call to GetLocalTime() at 0x415bfd\n[#] Call to GetSystemTime() at 0x415c20\n[#] Call to GetTickCount() at 0x415c52\n[#] Call to QueryPerformanceCounter() at 0x415ca6\n[#] Call to timeGetTime() at 0x415cd7\n[#] Call to VirtualProtect() on \"Return Address\" at 0x4120b9\n```\n\n\n## Dumping functions\n\nThe `emulate_payload` command has 3 options to dump content of several artifacts:\n\n```\n  -T, --thread          Dump CreateThread API content from lpStartAddress\n  -W, --writefile       Dump WriteFile API content\n  -M, --writemem        Dump VirtualAlloc API allocated content\n```\n\nWith these options you can dump the content of memory areas or files during emulation. For example the `--writemem` option allows to dump all the allocated memory when accessed in read or execution (for example with a JMP in the area); a common behavior of malicious code is to allocate memory, decrypt it and then execute or use it to do additional things. This option allows to get this content after decryption.\n\n\n\n## A couple of words about performance\n\nObviously emulation slows down everything. Moreover, hooking every instruction in order to interact with the execution, make things even slower. In general this works fine with small shellcode, but have some issues with complex code. That's why I added an option to **turn off** hooking to speed up execution:\n\n```\nemulate_payload -P \u003cpath_to_filename\u003e -U 0\n```\n\nIn this way you can get a picture of what the emulated code is doing (with API tracking), but nothing else will be done (no fixups, no key extractions, etc). If you specify something different than `0` the hooking will be re-enabled when the `IP` (instruction pointer) will reach the specified address (fixups will be applied from the same address).\n\n\n## Fixups\n\nIn some cases emulation was simply breaking, for different reasons. In some cases obfuscation was using some techniques that was confusing the emulation engine. So I implemented some ad-hoc fixups (you can enable them by using `-F` option of the `emulate_payload` command). Fixups are implemented in `modules/emulate_fixups.py`. Currently we have\n\nUnicorn issue #1092:\n\n```\n    #\n    # Fixup #1\n    # Unicorn issue #1092 (XOR instruction executed twice)\n    # https://github.com/unicorn-engine/unicorn/issues/1092\n    #               #820 (Incorrect memory view after running self-modifying code)\n    # https://github.com/unicorn-engine/unicorn/issues/820\n    # Issue: self modfying code in the same Translated Block (16 bytes?)\n    # Yes, I know...this is a huge kludge... :-/\n    #\n```\n\nFPU emulation issue:\n\n```\n    #\n    # Fixup #2\n    # The \"fpu\" related instructions (FPU/FNSTENV), used to recover EIP, sometimes\n    # returns the wrong addresses.\n    # In this case, I need to track the first FPU instruction and then place\n    # its address in STACK when FNSTENV is called\n    #\n```\n\nTrap Flag evasion:\n\n```\n    #\n    # Fixup #3\n    # Trap Flag evasion technique\n    # https://unit42.paloaltonetworks.com/single-bit-trap-flag-intel-cpu/\n    #\n    # The call of the RDTSC with the trap flag enabled, cause an unhandled\n    # interrupt. Example code:\n    #        pushf\n    #        or dword [esp], 0x100\n    #        popf\n    #        rdtsc\n    #\n    # Any call to RDTSC with Trap Flag set will be intercepted and TF will\n    # be cleared\n    #\n```\n\nToo few values on stack:\n\n```\n    #\n    # Fixup #4\n    # Stack too small (not enough values stored)\n    # \n    # Some obfuscator/evasion technique try to access some values on the stack\n    # (like for example SGN https://github.com/EgeBalci/sgn.git):\n    #\n    #     cmovne ax, word ptr [esp + 0xfa]\n    #\n    # In this case the emulation fails with an \"invalid_read\" since ESP is too\n    # close to the top of the stack. This creates some 'fake' values.\n    #\n```\n\n\n\n## Customize YARA rules\n\nFile `modules/emulate_rules.py` contains the **YARA** rules used to intercept the interesting part of the code, in order to implement instrumentation. I tried to comment as much as possible these sections in order to let you create your own rule (please share them with a pull request if you think they can help others). For example:\n\n```\n#\n# Payload Name: [MSF] windows/meterpreter/reverse_tcp_rc4\n# Search for  : mov esi,dword ptr [esi]\n#               xor esi,0x\u003cconst\u003e\n# Used for    : this xor instruction contains the constant used to\n#               encrypt the lenght of the payload that will be sent as 2nd\n#               stage\n# Architecture: x32\n#\nyara_reverse_tcp_rc4_xor_32 = 'rule reverse_tcp_rc4_xor {                \\\n                               strings:                                  \\\n                                   $opcodes_1 = { 8b 36                  \\\n                                                  81 f6 ?? ?? ?? ?? }    \\\n                               condition:                                \\\n                                   $opcodes_1 }'\n```\n\n\n\n## Issues\n\nPlease, open Issues if you find something that not work or that can be improved. Thanks!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FREW-sploit%2FREW-sploit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FREW-sploit%2FREW-sploit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FREW-sploit%2FREW-sploit/lists"}