update readme

2026-07-07 04:37:29 +01:00
commit 50cbc601d5
69 changed files with 15056 additions and 0 deletions
@@ -0,0 +1,131 @@
+# necropolis Protocol Specification
+
+## 1. Peer Identity
+
+### 1.1 Key Derivation
+
+```
+Operator Key: Ed25519 private key (operator.priv)
+Operator PeerID: libp2p PeerID derived from operator.priv public key
+
+Implant Key: Ephemeral Ed25519 (generated on first run)
+Implant PeerID: libp2p PeerID from implant public key
+```
+
+### 1.2 Implant Certificate
+On first execution, the implant generates:
+- `implant.ed25519` - ephemeral keypair
+- Registration envelope signed by operator key (embedded at build time)
+
+## 2. Topic Structure (PubSub Fallback)
+
+Topics are used as a fallback when direct streams are unavailable. Topic IDs use short opaque prefixes to reduce wire fingerprinting.
+
+```
+/b/<operator-peerid>/bx         # Beacons — implants -> operator (pubsub fallback)
+/c/<operator-peerid>/cx         # Commands — operator -> implant (pubsub fallback)
+/t/<operator-peerid>/tx/<id>    # Per-implant task topics (pubsub fallback)
+/necropolis/cmd/<id>/<nonce>    # DHT dead-drop — operator -> implant command envelopes
+```
+
+Primary communication uses direct libp2p streams (see section 4). DHT dead-drop is the 4th transport rung — implants poll `/necropolis/cmd/<id>/<nonce>` in sequence every 30s for signed command envelopes published by the operator.
+
+### Topic Authorisation
+- `beacons` topic: messages validated against implant's public key
+- Operator drops messages not signed by known implants on `beacons`
+
+## 3. Envelope Format
+
+All messages use Protocol Buffers. Message types use opaque Z-series identifiers.
+
+```protobuf
+package apb;
+
+message Envelope {
+  int64 ID = 1;
+  uint32 Type = 2;
+  bytes Data = 3;
+  bytes Signature = 4;   // Signed by sender's key
+  bytes SenderKey = 5;   // Public key of sender
+  bytes Token = 6;       // Auth token (32 bytes, operator-specific)
+}
+
+The Token field carries a 32-byte random value generated per operator at first run. Implants embed it at build time and reject any Envelope with a mismatched token. This prevents unauthorized peers from sending commands even if the operator's Ed25519 public key is known.
+
+// Z1 — Beacon register (async beacon mode)
+message Z1 {
+  string ID = 1;
+  int64 Interval = 2;
+  int64 Jitter = 3;
+  Register Register = 4;  // commonpb.Register
+  int64 NextCheckin = 5;
+}
+```
+
+## 4. Protocol IDs
+
+Direct libp2p streams use short protocol IDs:
+
+| Protocol | ID | Purpose |
+|---|---|---|
+| Beacon | `/bc/1.0.0` | Persistent beacon stream (implant -> operator) |
+| Command | `/bc/1.0.0/cmd` | Command delivery (operator -> implant) |
+| Shell | `/x/sh/1.0.0` | Interactive shell (Ctrl+] to exit) |
+| Port forward | `/x/pf/1.0.0` | TCP port forwarding |
+| SOCKS | `/x/sk/1.0.0` | SOCKS proxy tunnel |
+
+WSS connections use standard `/dns4/<host>/tcp/443/wss/p2p/<peer-id>` multiaddrs — no custom protocol ID.
+
+## 5. Transport Chain
+
+Implants attempt connections in order:
+1. Direct libp2p peer (`-peer`)
+2. WSS transport (`-wss`)
+3. DHT rendezvous discovery (goroutine, 15s)
+4. DHT dead-drop polling (goroutine, 30s) — signed command envelopes at `/necropolis/cmd/<id>/<nonce>`
+
+## 6. Session Types
+
+### 6.1 Beacon Mode (Persistent Stream)
+1. Implant opens persistent `/bc/1.0.0` stream to operator (relay-aware, `AllowLimitedConn`)
+2. Implant sends signed `Z1` (beacon register) on the stream every 10-15s
+3. A separate goroutine writes `MsgTypeCover` envelopes every 5s to prevent relay idle timeout
+4. Operator reads messages in a loop, updates `LastCheckin`, dispatches by type
+5. Results (`MsgTypeLs`, `MsgTypePs`, etc.) are sent on the same persistent stream
+6. If the stream dies, implant reconnects via DHT discovery + `openBeaconStream`
+
+### 6.2 Command Delivery (Direct Stream)
+1. Operator opens a `/bc/1.0.0/cmd` stream to implant (relay-aware, `AllowLimitedConn`)
+2. Operator signs the envelope and writes it length-prefixed
+3. Implant reads, verifies signature against embedded operator pubkey, dispatches
+4. Implant processes the command and sends the result on the persistent beacon stream
+
+### 6.3 Interactive Session Mode (Stream)
+1. Operator initiates direct libp2p stream to implant
+2. Bidirectional encrypted stream for shell/portfwd/socks
+3. Uses libp2p stream multiplexing
+4. In shell, type `exit` or press **Ctrl+]** to return to the operator prompt
+
+## 7. Message Types
+
+| Type | ID | Direction | Description |
+|---|---|---|---|
+| COVER | 127 | Implant -> Op | Cover traffic (silently dropped by operator) |
+| REGISTER | 0 | Implant -> Op | Initial beacon/registration |
+| TASK | 2 | Op -> Implant | Execute command |
+| TASK_RESULT | 3 | Implant -> Op | Command output |
+| SHELL | 4 | Bidirectional | Interactive shell |
+| DOWNLOAD | 5 | Implant -> Op | File exfiltration |
+| UPLOAD | 6 | Op -> Implant | File deployment |
+| SOCKS | 7 | Bidirectional | SOCKS proxy tunnel |
+| PORTFWD | 8 | Bidirectional | Port forwarding |
+| SCREENSHOT | 9 | Implant -> Op | Screen capture |
+| LS | 10 | Op -> Implant | List directory |
+| CD | 11 | Op -> Implant | Change directory |
+| PWD | 12 | Op -> Implant | Print working directory |
+| EXECUTE | 13 | Op -> Implant | Run command |
+| KILL | 14 | Op -> Implant | Self-terminate |
+| PS | 15 | Implant -> Op | Process list result |
+| DEADMAN | 16 | Op -> Implant | Dead man switch |
+| DISCONNECT | 255 | Bidirectional | Clean close |
+