182 lines
8.7 KiB
Markdown
182 lines
8.7 KiB
Markdown
# 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.
|