Skip to content

Commit fa5404b

Browse files
noderavennoderaven
committed
Rewrite README with comprehensive overview, scope, and doc index
1 parent 291476a commit fa5404b

1 file changed

Lines changed: 170 additions & 32 deletions

File tree

‎README.md‎

Lines changed: 170 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -4,61 +4,199 @@ VBA macro chain demonstrating modern EDR-evasion techniques, originally
44
authored during OSCP study and modernized in v2 for the Windows 11 24H2 /
55
Microsoft Defender for Endpoint era.
66

7+
> **Educational artifact, not a weapon.** v2 is a polished sketch of a
8+
> credible OSEP-grade chain. The repo does not ship working shellcode; you
9+
> supply your own. The detection profile is documented honestly in
10+
> [docs/threat-model.md](docs/threat-model.md) -- a tuned MDE will catch
11+
> the chain, and that is expected.
12+
713
## Status
814

9-
- **v2** is the current head of `main`. Modular VBA, Python build tooling,
10-
ISO/LNK delivery wrappers, indirect syscalls, hardware-breakpoint AMSI
11-
bypass, PPID-spoofed EarlyBird APC.
12-
- **v1** is preserved at git tag `v1`. See `docs/history.md` for the v1
13-
narrative and review findings.
15+
- **v2** is the current head of `main`. Modular VBA (9 source files plus a
16+
generated `Payload.bas`), Python build tooling, ISO + LNK delivery
17+
wrappers, CI on every push.
18+
- **v1** is preserved at git tag `v1`. See [docs/history.md](docs/history.md)
19+
for the v1 narrative and review findings (the v1 file had a number of
20+
bugs that prevented it from compiling or running -- the rewrite was a
21+
clean break, not a refactor).
1422

15-
## Quickstart
23+
## What the chain does
24+
25+
When the assembled `.docm` is opened in Word with macros enabled, `AutoOpen`
26+
fires and walks an eight-phase pipeline:
27+
28+
```
29+
Phase 0 AMSI scans macro source pre-runtime; defeated by source obfuscation
30+
Phase 1 AutoOpen + ValidateEnvironment sandbox/uptime/domain keying
31+
Phase 2 Engine bootstrap DispCallFunc resolved; RW page allocated
32+
Phase 3 ResolveSyscalls map \KnownDlls\ntdll.dll; build SSN table
33+
Phase 4 Sensor blinding HWBP AMSI bypass + TEB ETW zero
34+
Phase 5 Payload decryption AES-256-CTR in pure VBA
35+
Phase 6 Injection dllhost-spoofed PPID + EarlyBird APC
36+
Phase 7 Schedule Cleanup Application.OnTime Now + 2s
37+
Phase 8 Cleanup (deferred) best-effort VBProject self-erase
38+
```
39+
40+
Each technique is covered in detail in
41+
[docs/techniques.md](docs/techniques.md). The phase boundaries are
42+
intentional: each phase returns a status, a failure bails the chain cleanly,
43+
and `Debug.bas` provides phase-by-phase telemetry via `OutputDebugStringA`
44+
for lab walkthroughs.
1645

46+
## Repo layout
47+
48+
```
49+
macro/
50+
Strings.bas MkStr / MkAStr / HexToBytes (no flat sensitive literals)
51+
Structs.bas PE, NT, CONTEXT64, exception, Toolhelp32 types
52+
Engine.bas DispCallFunc shim, RWX hygiene, Call0..Call12
53+
Aes.bas AES-256-CTR (mirror of payload/aes.py)
54+
Syscalls.bas HellsGate SSN extraction; SysCall0..SysCall12
55+
Evasion.bas HWBP AMSI bypass via VEH; TEB.EtwTraceData zero
56+
Injection.bas PPID-spoofed CreateProcessW; NtAllocate/Write/Protect/Queue/Resume
57+
SolidMacro.bas AutoOpen, RunExploit, ValidateEnvironment, Cleanup
58+
Debug.bas DbgPrint / DbgAssert gated by DEBUG_ENABLED
59+
build/
60+
assemble.py glues .bas files into a .docm-ready VBA project
61+
62+
payload/
63+
aes.py pure-Python AES-256-CTR (no third-party deps)
64+
build.py CLI: shellcode.bin -> macro/Payload.bas
65+
__init__.py
66+
67+
delivery/
68+
lnk/build_lnk.py pure-Python MS-SHLLINK builder
69+
iso/build_iso.py pycdlib-based ISO 9660 + Joliet builder
70+
xll/README.md future-work placeholder for the native twin
71+
72+
tests/ pytest covering all Python tooling (43 tests)
73+
docs/
74+
README files plus techniques / threat-model / delivery / development /
75+
history and the superpowers/ design spec + implementation plan.
76+
77+
.github/workflows/ci.yml pytest + assemble --check on push/PR
1778
```
18-
# Encrypt your shellcode
79+
80+
## Quickstart
81+
82+
```bash
83+
# 1. Generate Payload.bas from your shellcode (encrypted with AES-256-CTR)
1984
python payload/build.py path/to/shellcode.bin --out macro/Payload.bas
2085

21-
# Assemble the macro source
22-
python macro/build/assemble.py
86+
# 2. Static-check the assembled VBA project
87+
python macro/build/assemble.py --check
2388

24-
# Import macro/build/dist/*.bas into Word's VBA editor and save as .docm
89+
# 3. Assemble the module set ready for Word VBA editor import
90+
python macro/build/assemble.py
91+
# Wrote macro/build/dist/Strings.bas
92+
# Wrote macro/build/dist/Structs.bas
93+
# ... (10 files total)
2594

26-
# (Optional) bundle for delivery past Mark-of-the-Web
95+
# 4. (Optional) bundle for delivery past Mark-of-the-Web
2796
python delivery/lnk/build_lnk.py --target "data\\report.docm" --out report.lnk
2897
python delivery/iso/build_iso.py report.lnk data/report.docm --out report.iso
2998
```
3099

31-
See [docs/development.md](docs/development.md) for the full build / test
32-
workflow.
100+
`assemble.py --flatten` produces one combined `Module1.bas` if you prefer a
101+
single-paste workflow over module-by-module import.
33102

34-
## Scope
103+
If `python` isn't on your PATH, use `python3` -- everything in this repo
104+
targets Python 3.10+.
35105

36-
This is an educational artifact. It uses techniques that are publicly
37-
documented and detected to some degree by every modern EDR. The
38-
[threat model](docs/threat-model.md) documents exactly what each technique
39-
beats and what catches it. A tuned MDE will catch the chain; that is
40-
expected and documented.
106+
## Testing
41107

42-
If you are looking for a production-grade red-team tool, this is not it.
43-
If you are studying for OSEP or want to understand how modern Office-macro
44-
evasion is built, this should be useful.
45-
46-
## Repo layout
108+
Python side runs automatically via pytest:
47109

110+
```bash
111+
pip install pytest pycdlib==1.14.0
112+
python -m pytest tests/ -v
48113
```
49-
macro/ <- VBA source modules (.bas) + build glue
50-
payload/ <- shellcode encryption (Python AES-256-CTR)
51-
delivery/ <- ISO and LNK delivery wrappers
52-
tests/ <- pytest covering the Python tooling
53-
docs/ <- techniques, threat model, delivery, development, history
54-
```
114+
115+
Expected: 43 tests pass.
116+
117+
- `test_aes.py` pins the AES-256-CTR implementation to NIST FIPS 197 (single
118+
block KAT) and NIST SP 800-38A Section F.5.5 (4-block CTR KAT). The VBA
119+
twin (`Aes.bas`) is built to mirror this byte-for-byte; if the Word-side
120+
decryption produces wrong output, the bug is in `Aes.bas` because Python
121+
is pinned to the standard.
122+
- `test_assemble.py` covers the static-check rules: balanced `Sub/Function`,
123+
no orphan line continuations, no flat sensitive API name literals.
124+
- `test_build.py` round-trips `payload/build.py` output through the regex
125+
parser and back through AES.
126+
- `test_lnk.py` and `test_iso.py` byte-parse the emitted LNK and ISO files
127+
to confirm the on-disk layout matches what Windows expects.
128+
129+
GitHub Actions runs this matrix across Python 3.10 / 3.11 / 3.12 on every
130+
push and pull request -- see [.github/workflows/ci.yml](.github/workflows/ci.yml).
131+
132+
VBA side requires a lab VM. See
133+
[docs/development.md](docs/development.md) for the manual workflow:
134+
import to Word VBA editor, `Debug > Compile VBAProject`, then walk the
135+
phase telemetry via DebugView with the `winword.exe` filter.
136+
137+
## Scope and limitations
138+
139+
This is an OSEP-grade study artifact. Every technique it uses is publicly
140+
documented -- HellsGate is from late 2020, hardware-breakpoint AMSI bypass
141+
is well-known since 2022, PPID spoofing via `UpdateProcThreadAttribute` has
142+
been public since 2011. Detection rules for the combination exist in
143+
publicly-shipped YARA / Sigma / EDR-vendor signature feeds.
144+
145+
The [threat model](docs/threat-model.md) lays out exactly what each
146+
technique beats and what catches it. A representative summary:
147+
148+
| Stage | Beats | Caught by |
149+
|---|---|---|
150+
| HellsGate indirect syscalls | NTDLL user-mode hooks | MDE "syscall from non-image-backed memory" (~2024) |
151+
| HWBP AMSI bypass | byte-patch scans on amsi.dll | VEH installation + DR0/DR7 mutation from Office |
152+
| PPID spoof | forward process-tree heuristics | kernel callback comparing creator PID to attribute PID |
153+
| EarlyBird APC | user-mode hook racing | cross-process write + QueueUserAPC kernel callback |
154+
| ISO-wrapped LNK delivery | default Mark-of-the-Web | `BlockDownloadsOfAllSamples` GPO, OOXMLFileSandboxAttachments |
155+
156+
If you are looking for a production-grade red-team tool, this is not it. If
157+
you are studying for OSEP or want to understand how a modern Office-macro
158+
evasion chain is actually built, the code is here and the rationale is
159+
documented.
160+
161+
## Build / run requirements
162+
163+
- Python 3.10+
164+
- `pip install pytest pycdlib==1.14.0` for the test suite
165+
- Lab VM with x64 Windows 11 24H2 + x64 Microsoft Office 2016+ for the
166+
manual VBA verification path
167+
168+
There are no third-party Python dependencies in the *core* build path
169+
(`payload/aes.py` is pure standard library). `pycdlib` is only used by the
170+
ISO delivery wrapper; `pytest` is dev-only.
171+
172+
## Documentation
173+
174+
| File | Purpose |
175+
|---|---|
176+
| [README.md](README.md) | this file |
177+
| [CHANGELOG.md](CHANGELOG.md) | v1 -> v2 entry |
178+
| [docs/techniques.md](docs/techniques.md) | per-stage technique deep-dive |
179+
| [docs/threat-model.md](docs/threat-model.md) | honest detection profile |
180+
| [docs/delivery.md](docs/delivery.md) | MotW story, ISO/LNK reasoning |
181+
| [docs/development.md](docs/development.md) | build, test, lab workflow |
182+
| [docs/history.md](docs/history.md) | v1 review findings, v2 narrative |
183+
| [docs/superpowers/specs/2026-06-24-solid-macro-modernization-design.md](docs/superpowers/specs/2026-06-24-solid-macro-modernization-design.md) | v2 design spec |
184+
| [docs/superpowers/plans/2026-06-24-solid-macro-v2.md](docs/superpowers/plans/2026-06-24-solid-macro-v2.md) | v2 implementation plan |
185+
186+
## Authorization and use
187+
188+
Use of these techniques is appropriate only with explicit authorization in
189+
contexts such as authorized penetration testing engagements, CTF
190+
competitions, educational study (e.g. OSEP / PEN-300 coursework), and
191+
defensive security research. Do not deploy this against systems you do not
192+
own or do not have written permission to test.
55193

56194
## License
57195

58-
MIT. See `LICENSE`.
196+
MIT. See [LICENSE](LICENSE).
59197

60198
## Author
61199

62200
[noderaven](https://github.com/noderaven). Contributions accepted via PR --
63201
keep them ASCII-only (no em-dashes / curly quotes / emoji) per repo
64-
convention.
202+
convention; commits should be attributable to a single person.

0 commit comments

Comments
 (0)