https://github.com/jenting/vallum

https://github.com/jenting/vallum

Last synced: about 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/jenting/vallum
• Owner: jenting
• License: apache-2.0
• Created: 2026-06-07T00:42:48.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2026-06-07T09:22:07.000Z (about 2 months ago)
• Last Synced: 2026-06-07T10:13:43.193Z (about 2 months ago)
• Language: Shell
• Size: 96.7 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Vallum — 100.x 東西向防火牆集中管控平台

> *Vallum*：羅馬的防禦長城（如 Hadrian's Wall）。跨異質環境（k8s + Linux + Windows VM）

> 拉一道統一的東西向防火牆 —— 不靠底層（kubevirt/VMware），規則做在 guest OS 與 k8s namespace。

自建（in-house，不買商用），預設 **deny `100.0.0.0/8`** 東西向、嚴格 allowlist。

## 模組（全部完成，皆在 Azure 端到端實測通過）

| # | 模組 | 技術 | 狀態 |

|---|---|---|---|

| 1 | 控制面 zone UI + generator | static HTML（zone×zone 矩陣）+ Python（model→規則） | ✅ |

| 2 | k8s 強制 | Cilium **CNP**（deny-only + except，namespaced） | ✅ |

| 2b | k8s 自動覆蓋 | **Kyverno** generate + Argo CD（含 bypass 還原） | ✅ |

| 3 | Linux VM 強制 | **nftables** + Ansible（push / apply-on-change） | ✅ |

| 4 | Windows VM 強制 | **Windows Defender Firewall**（補集 block，PowerShell） | ✅ |

| 5 | 合規 dashboard | Python 蒐集 + 靜態 HTML（五態，含 bypass/未納管偵測） | ✅ |

**核心閉環**：中央 zone model → generator 編譯 → k8s + Linux + Windows 三種強制 → 合規可視化。

---

# 入口：控制面（Zone UI + Generator）

集中以 **zone（label 群組）+ zone×zone 矩陣**管理東西向政策，編譯成各強制點的設定，走 GitOps 套用。

```bash

./scripts/serve-ui.sh                 # 開 http://localhost:8765/ui/ 編矩陣、匯出 model.json

python3 controlplane/generate.py      # model.json → 各強制目標的設定檔

cd controlplane && python3 -m unittest test_generate -v   # 編譯邏輯單元測試

```

- **Source of truth**：`controlplane/model.json` —— `zones`、`members`（entity↔zone↔CIDR mapping）、`allow`（zone×zone 對稱矩陣）。

- entity 的 allowlist = 其 zone 經矩陣可達的所有 zone 的 CIDR 聯集。

- **generator 一次產出三種強制目標**：

| member kind | 產出 | 套用 |

|---|---|---|

| `k8s-ns` | Cilium CNP → `gitops/generated/k8s//` | Argo / kubectl |

| `linux-vm` | nftables allowlist → `ansible/host_vars/.yml` | `ansible/apply.sh` |

| `windows-vm` | Windows FW 腳本 → `gitops/generated/windows/.ps1` | `RunPowerShellScript` |

設計: `docs/superpowers/specs/2026-06-07-vallum-zone-controlplane-design.md`

![Vallum zone UI](docs/images/zone-ui.png)

> 跨域 allow（例如 Windows ↔ Linux）需**兩端各自套用** —— host-based 各自強制是本質，不是 bug。

---

# 強制目標 ① k8s（Cilium CNP）

每個 in-scope namespace 各部署一份 CNP：`foo=bar` namespace 可雙向通指定 peer，其餘 100.x 全擋。

- deny-only + `except`，並設 `enableDefaultDeny:{ingress,egress}=false` —— 只扣 100.x，不誤傷 DNS / 叢集內流量。

- CNP 是 **namespaced**；`foo=bar` 與否由「部署哪份 CNP」決定。

真值表（PoC 場景，vm-02=`100.64.2.0/24`）:

| 流量 | 結果 |

|---|---|

| `foo=bar` ns ↔ vm-02 | ✅ 雙向 |

| `foo=bar` ns → vm-01 / 其餘 100.x | ⛔ |

| 其他 ns → 任何 100.x | ⛔ |

| 叢集內 node↔node / pod↔apiserver / DNS | ✅ 不受影響 |

### Provisioning（每叢集，在 Azure node 上）

```bash

ROLE=server ./provision/k3s-install.sh                 # k3s（關 flannel）

# 多 node: ROLE=agent K3S_URL=https://:6443 K3S_TOKEN= ./provision/k3s-install.sh

CILIUM_VERSION=1.16.3 ./provision/cilium-install.sh    # 對該叢集 kubeconfig 裝 Cilium

```

### 套用 + 驗收

```bash

CONTEXT= ./scripts/apply.sh                                   # 套 namespace/CNP/netshoot

CONTEXT= VM02=100.64.2.4 VM01=100.64.1.4 ./scripts/verify.sh  # egress 真值表

CONTEXT= ./scripts/verify-reverse.sh                          # 反向（VM→pod，NodePort+eTP=Local）

```

> 反向需 NodePort + `externalTrafficPolicy: Local` 保留來源 IP，Cilium 才能用 CIDR identity 比對 `except`。

### 自動覆蓋（Kyverno + Argo CD）— #2b

手動逐 ns 部署有覆蓋率漏洞。Kyverno `generate` 自動補：非系統 ns 一律拿到對的 CNP，新 ns 即時覆蓋，被改/刪的 CNP 由 `synchronize:true` 還原（順便抓 bypass）。

```bash

helm repo add kyverno https://kyverno.github.io/kyverno/ && helm repo update

helm upgrade --install kyverno kyverno/kyverno -n kyverno --create-namespace --version 3.2.6

kubectl --context  apply -f gitops/kyverno/          # RBAC + ClusterPolicy

CONTEXT= ./scripts/verify-gitops.sh                  # 自動覆蓋 / label 切換 / bypass 還原

```

正式以 Argo CD 交付: `gitops/argocd/appset-eastwest.yaml`。

設計: `…/specs/2026-06-07-k8s-cilium-eastwest-adapter-design.md`、`…/2026-06-07-eastwest-cnp-gitops-kyverno-design.md`

---

# 強制目標 ② Linux VM（nftables，host-based）

CNP 只在 k8s 內執行，管不到 VM↔VM。Linux VM 用 nftables 補上：專屬 table 只 drop `100.0.0.0/8`，嚴格 allowlist（host_vars 指定放行的 100.x peer），其餘 100.x（含 k3s node）全擋，對外/管理面不受影響。

```bash

# 在 VM 上（PoC 用 az run-command 推；正式由 CI/AWX 經 SSH）

sudo REPO=https://github.com/jenting/vallum.git bash ansible/apply.sh

ALLOW= DENY_K3S=100.64.11.4 ./scripts/verify-vm.sh   # ALLOW 對端需開 :80 監聽

```

設計取捨: apply-on-change 推一次，**不做 reconcile、無 cron、無自寫 systemd**；規則重開機後需重推。

設計: `…/specs/2026-06-07-linux-nftables-eastwest-ansible-design.md`

---

# 強制目標 ③ Windows VM（Windows Defender Firewall）

Windows FW 沒有 except 且 Block 優先於 Allow，故 generator 預算 `100.0.0.0/8 − allowlist` **補集**，產 PowerShell 建 Inbound/Outbound Block 規則（Group `Vallum`）。

```bash

./provision/win-vm-create.sh          # 建 Windows Server 2022 VM（PoC）

python3 controlplane/generate.py      # model.json → gitops/generated/windows/.ps1

az vm run-command invoke -g JENTING-RESOURCE-GROUP -n jenting-win-01 \

  --command-id RunPowerShellScript --scripts @gitops/generated/windows/jenting-win-01.ps1

VM=jenting-win-01 ALLOW=100.64.2.4 DENY=100.64.1.4 ./scripts/verify-win.sh

```

設計: `…/specs/2026-06-07-windows-defender-fw-eastwest-design.md`

---

# 合規 Dashboard — #5

唯讀稽核全機隊東西向狀態（k8s CNP + VM nft + Windows FW），對比 model.json 的 expected，加上發現未納管 entity，產靜態 HTML。

```bash

python3 controlplane/audit.py         # 蒐集→比對→ controlplane/out/compliance.html

./scripts/serve-report.sh             # 開 http://localhost:8766/compliance.html

cd controlplane && python3 -m unittest test_dashboard -v   # 純函式單元測試

```

五態: 🟢COMPLIANT 🔴MISSING 🟠DRIFT 🟣BYPASS ⚪UNMANAGED（後二者對應「誰繞過 / 誰沒設好」）。

設計: `…/specs/2026-06-07-vallum-compliance-dashboard-design.md`

![Vallum 合規 dashboard](docs/images/compliance-dashboard.png)

---

## 參考：IP 分配（Azure `jenting-vnet` = `100.64.0.0/16`，PoC 環境）

| Entity | subnet / IP | zone | 角色 |

|---|---|---|---|

| jenting-k3s-host-01（k8s-01） | `100.64.11.0/24` / `.11.4` | k8s-web | 叢集 node（不受 CIDR 政策影響） |

| jenting-k3s-host-02（k8s-02） | `100.64.12.0/24` / `.12.4` | — | 叢集 node |

| jenting-vm-01 | `100.64.1.0/24` / `.1.4` | vm-a | Linux VM |

| jenting-vm-02 | `100.64.2.0/24` / `.2.4` | vm-b | Linux VM |

| jenting-win-01 | `100.64.3.0/24` / `.3.4` | win-prod | Windows VM |

## Caveats

- **k8s 覆蓋率**: 沒部署 CNP 的 namespace 不會被擋 → 用 Kyverno 自動覆蓋（#2b）。

- **Cilium**: 若啟用 `policy-cidr-match-mode: nodes`，deny 100.x 會誤擋 node↔node；本 PoC 維持預設（空）。

- **Linux/Windows**: apply-on-change，無持續 reconcile；被竄改的自動還原靠合規面（#5）偵測，或中央排程重推。

- **跨域 allow**: 兩個 host 間互通需兩端各自放行（host-based 本質）。