Necropolis-C2/docs/implant-design.md

Implant Design

Overview

The necropolis implant is a lightweight Go binary that connects to the libp2p network and communicates with its operator entirely through direct p2p streams, with pubsub as a fallback. It has no hardcoded server IPs or DNS names — only a cryptographic reference to the operator's public key.

Directory Structure

implant/
├── main.go              # Entry point
└── core/                # All implant runtime logic
    ├── agent.go         # Core lifecycle, beacon loop, command dispatch, handlers
    ├── shell.go         # Shell path selection (/bin/bash, cmd.exe, etc.)
    ├── shell_unix.go    # PTY-based interactive shell (Linux/macOS)
    ├── shell_windows.go # ConPTY-based interactive shell (Windows)
    ├── portfwd.go       # TCP port forwarding tunnel
    ├── socks.go         # SOCKS proxy tunnel (identical to portfwd currently)
    ├── ps.go            # Process listing (Linux /proc, Windows tasklist)
    ├── antivm.go        # VM detection framework (cross-platform, build-tag gated)
    ├── antivm_linux.go  # 50+ Linux-specific VM detection techniques
    ├── antivm_darwin.go # macOS-specific VM detection techniques
    ├── antivm_windows.go# Windows-specific VM detection techniques
    ├── antivm_stub.go   # No-op stub when compiled without `-tags=antivm`
    ├── embed_evasion.go        # Embeds valak.dll via //go:embed
    ├── evasion_windows.go      # Evasion loader + sleep obfuscation
    ├── valak.dll              # Zig evasion DLL (FreshyCalls, indirect syscalls, AMSI/ETW bypass, module stomping)
    ├── evasion_stub.go         # No-op stub when compiled without `-tags=evasion`
    ├── agent_relay.go          # Implant-to-implant relay advertisement and routing
    ├── embedded_pubkey.go        # Generated: operator's public key embedded at build time
    ├── embedded_implant_key.go   # Generated: implant's unique keypair embedded at build time
    ├── embedded_authtoken.go   # Generated: operator-specific auth token embedded at build time
    └── embedded_boxpubkey.go   # Generated: NaCl box public key embedded at build time

Build Process

1. Operator runs necropolis generate --os linux --arch amd64 (from CLI or standalone)
2. server/core/generate.go unpacks the embedded source tree from server/core/embedsrc/implant_src.tar.gz
3. Injects the operator's public key and a fresh implant Ed25519 keypair into the source tree
4. Optionally applies build tags (-tags=antivm, -tags=evasion) and quiet-mode stubs
5. Cross-compiles with CGO_ENABLED=0 for the target OS/arch
6. When --evasion is set, embeds valak.dll (1.5 MB Zig kernel evasion DLL) into the binary via //go:embed. The DLL is loaded at runtime from memory and provides FreshyCalls syscall dispatch, AMSI/ETW bypass, module stomping, EDR callback removal.
7. Applies garble obfuscation (--obfuscate), UPX compression (--upx), and strip (--quiet)
8. The resulting binary is self-contained — no source tree, no external dependencies

Each build generates a unique implant keypair. The implant keeps the same PeerID across restarts.

Core Lifecycle

Startup

1. Load operator's public key from embedded embedded_pubkey.go
2. Load implant's private key from embedded embedded_implant_key.go
3. Derive libp2p PeerID from implant public key
4. Initialise libp2p host with:
   • TCP + WebSocket transports (no UDP/QUIC for sandbox compatibility)
   • AutoNAT + relay client for NAT traversal
   • DHT client for peer discovery
   • GossipSub pubsub
5. If --peer flag is provided, connect to operator directly
6. If --wss flag is provided, connect via WebSocket Secure (TLS over TCP/443)
7. Start DHT discovery loop to find operator via rendezvous namespace
8. Start DHT dead-drop poll loop (pollDHTCmdLoop) — polls /necropolis/cmd/<id>/<nonce> every 30s for signed command envelopes
9. Once connected, open persistent beacon stream (/bc/1.0.0) to operator
10. Register via signed Z1 (beacon register with system metadata)
11. Start beacon loop and cover traffic loop

Main Loop

beaconLoop (every 10-15s):
  Send Z1 (beacon register) on persistent /bc/1.0.0 stream
  Sleep(interval + random(jitter))

streamKeepaliveLoop (every 5s):
  Write MsgTypeCover on persistent stream to prevent relay idle timeout

coverTrafficLoop (every 4-7s):
  Publish random noise to the beacon pubsub topic

discoverOperatorLoop (every 15s):
  Find operator via DHT rendezvous
  If beacon stream is nil, reconnect

pollDHTCmdLoop (every 30s):
  Poll DHT dead-drop at /necropolis/cmd/<id>/<nonce> for signed command envelopes
  Process through existing command handler

commandStream handler:
  Read length-prefixed envelope from /bc/1.0.0/cmd stream
  Verify Ed25519 signature against embedded operator pubkey
  Dispatch by message type
  Send result on persistent beacon stream

Session Mode (Shell, Portfwd, SOCKS)

on incoming stream:
  Read target/winsize from stream header
  Establish local connection / PTY
  Bidirectional io.Copy between libp2p stream and local resource
  On disconnect or Ctrl+]: cleanup and return

Command Handlers

All command handlers follow the same pattern:

1. Deserialise protobuf request from envelope
2. Execute operation (local filesystem, process execution, etc.)
3. Serialise protobuf result
4. Send result via sendResult() — tries persistent stream first, falls back to pubsub

Handler	Protobuf	Operation
handlePs	Z12 → Z13	List processes via /proc (Linux) or tasklist (Windows)
handleLs	Z16 → Z17	Read directory entries
handleCd	Z19 → Z21	os.Chdir()
handlePwd	Z20 → Z21	os.Getwd()
handleExecute	Z14 → Z15	exec.CommandContext() with optional output capture
handleDownload	Z22 → Z23	os.ReadFile() with 100MB limit
handleUpload	Z24 → Z25	os.WriteFile() with optional overwrite and 100MB limit
handleKill	(none) → (none)	Log stack trace, os.Exit(0)
handleScreenshot	Z2 → Z3	Returns "not implemented" stub

Platform Support

Feature	Windows	Linux	macOS
TCP transport	✓	✓	✓
WebSocket transport	✓	✓	✓
Process list	✓ (tasklist)	✓ (/proc)	✓ (stub)
File ops	✓	✓	✓
Interactive shell	✓ (ConPTY)	✓ (PTY)	✓ (PTY)
Port forwarding	✓	✓	✓
VM detection	50+ checks	50+ checks	8 checks
Kernel evasion	✓ (DLL)	—	—

Evasion System

When compiled with --evasion, the implant includes a Zig DLL (valak.dll) built from evasion/ in the source tree. The DLL is embedded via //go:embed valak.dll at compile time and loaded from memory via reflective PE loader at runtime. After loading, the DLL stomps its .text section into a legitimate signed Microsoft DLL (e.g. CryptoAPI.dll, dwrite.dll), frees the original allocation, and wipes its PE headers. Once stomped, the code executes from inside a Microsoft-signed address range with no orphaned PE signature. It provides kernel-level evasion primitives ported from the Tenshu C2 framework:

Technique	Implementation	Persistence
Module stomping	.text copied into signed MS DLL range; original headers wiped	On load
Image header wiping	MZ/PE\0\0 zeroed at original allocation after stomp	On load
Sleep obfuscation (PAGE_NOACCESS)	DLL .text set PAGE_NOACCESS via VirtualProtect during idle	Per sleep cycle
Indirect syscalls	FreshyCalls + HAL's Gate SSN extraction, random ntdll gadget	Available via DLL call
ETW patch	Three-tier: NtTraceControl → HWBP → RET patch	On init
AMSI bypass	DR0 hardware breakpoint + VEH with SuspendThread/ResumeThread	Installed on init
EDR callback removal	SeDebugPrivilege + NtSetInformationProcess(40)	On init
If the DLL fails to load, evasion is skipped. No fallback to pure Go implementations — the DLL is the only evasion path.

Transport Configuration

The implant explicitly disables libp2p's default transports and enables only:

1. WebSocket — primary transport, works through most proxies
2. WebSocket Secure — WSS is a dial address (/dns4/host/tcp/443/wss/p2p/peerid), not a separate transport layer; it uses the same WebSocket transport over TLS
3. TCP — fallback for direct connections

No UDP, no QUIC, no multicast. This maximises sandbox/container compatibility.

The implant always connects with network.WithAllowLimitedConn to work through relay circuits when direct connections are unavailable.

When started with -wss, the implant connects via /dns4/<host>/tcp/443/wss/p2p/<peer-id> before falling back to DHT discovery and dead-drop polling.