# 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

```json
{
  "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:

```bash
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

```go
// 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