sorcery-go/docs/SECURITY.md

Sorcery-Go Security — The Warding

1. Defence in Depth

Layer	Responsibility	Tooling
1	In-kernel MAC enforcement	eBPF LSM (Tomb Guard)
2	Device + network control	eBPF cgroup filters
3	Network firewall between nodes	OPNsense / IPFire (Coven isolation)
4	Per-process network filtering	OpenSnitch or Portmaster (selectable per node)
5	Content-addressing and verification	Merkle root + per-blob SHA-256 hashing
6	Quarantine and containment	cgroup freezer, multi-runtime (LXC, Podman, Firecracker, baremetal)

2. Firewall-First Security Model

Sorcery-Go delegates all transport security to the network boundary. A dedicated firewall appliance (OPNsense or IPFire) isolates the Coven so that only authorized Sanctum IPs may exchange Essence traffic. This eliminates the need for application-layer certificate management entirely.

Recommended Firewall Rules

Direction	Source	Destination	Port	Action
Intra-Coven	Sanctum subnet	Sanctum subnet	8080 (sorcery)	Allow
Intra-Coven	Sanctum subnet	Sanctum subnet	8181 (Fester)	Allow
Intra-Coven	Sanctum subnet	Sanctum subnet	9090 (Cockpit)	Allow
Outbound	Master Sanctum	Artifact cache	8181	Allow
Default	Any	Any	Any	Deny

There is no built-in TLS, mTLS, or application-layer encryption in the codebase. All crypto/rand, crypto/tls, and crypto/x509 code paths have been removed. Task IDs are generated deterministically using atomic counters and nanosecond timestamps.

3. eBPF Tomb Guard — The Immutable Vault

Every runtime environment — LXC, Podman, Firecracker, or baremetal — is enforced by the same eBPF LSM program (sorcery-tomb-guard). Unlike user-space profiles, eBPF provides in-kernel enforcement that works uniformly across all runtimes without per-runtime profile syntax.

The Tomb Guard BPF program attaches to file_open, path_link, and path_unlink hooks and applies a single policy:

• Read-only access to /var/lib/sorcery-go/essences/ and its contents.
• Deny all writes, hardlinks, symlinks, and deletes under the Tomb.
• Allow read access to /var/lib/sorcery-go/state/state.db.

If a compromised container or process attempts to poison the Tomb, the eBPF LSM blocks the operation in-kernel and the Warding raises an Illegal Write Attempt alarm that is rendered on the Cockpit Threat Map.

4. Network Gatekeepers

The Coven supports either OpenSnitch or Portmaster (selectable per node, never both). The Sorcery-Go engine auto-detects which is active and injects the appropriate rules.

OpenSnitch Rule

{
  "name": "Sorcery-Essence-Sync",
  "enabled": true,
  "action": "allow",
  "duration": "always",
  "operator": {
    "type": "list",
    "data": [
      { "type": "simple",    "operand": "process",    "data": "/usr/local/bin/sorcery-go" },
      { "type": "regexp",    "operand": "dest_host",  "data": "registry\\.local" }
    ]
  }
}

Portmaster Integration

Defines the Sorcery-Go process as a Trusted System Utility with a scoped network boundary — only the stream to the Master Essence Registry is permitted; all other egress from the build sandbox is dropped.

5. Emergency Banishment

If a Worker is physically stolen or compromised:

sorcery-go ward banish <node-id>

This freezes the offending Sanctum via cgroup/runtime freeze and records the banishment in the Warding alarm log. The firewall rule for that node should also be removed or blocked at the network boundary.

6. Quarantine Logic

When the Warding detects a high-severity threat (binary signature mismatch in the Tomb), it can automatically:

1. Freeze the offending process or container via cgroups (cgroup.freeze) — works identically across LXC, Podman, Firecracker, and baremetal.
2. Sever the Essence links to prevent memory-based exploit spread.
3. Broadcast the alarm to every other Sanctum.
4. Highlight the node red on the Cockpit Threat Map.

7. First-Boot Hardening Test

// pkg/warding/audit_test.go
func TestFirstBootHardening(t *testing.T) {
    // eBPF Tomb Guard must block writes to /var/lib/sorcery-go/essences/
    err := os.WriteFile("/var/lib/sorcery-go/essences/malicious_hash",
        []byte("void"), 0644)
    if err == nil {
        t.Error("SECURITY FAILURE: eBPF Tomb Guard allowed write to Tomb!")
    }
}

Run this after every deploy to confirm the Warding is active.

8. Security Pulse Indicator

The Cockpit WebUI shows a single traffic-light indicator:

• Green — eBPF Tomb Guard active; OpenSnitch/Portmaster reporting zero leaks
• Yellow — A toolchain is currently being validated in the Lab
• Red — Hash mismatch or unauthorized write detected — Automatic Quarantine engaged