159 lines
6.5 KiB
Markdown
159 lines
6.5 KiB
Markdown
# Ligbox Infrastructure Constitution
|
||
|
||
Constituição de governança para toda a infraestrutura Ligbox / Ibytera no cluster Proxmox `big1`.
|
||
Aplica-se a VMs, CTs, rede, segurança, deploys e integrações (mail, ops, portal).
|
||
|
||
---
|
||
|
||
## Core Principles
|
||
|
||
### I. Network Segmentation — vmbr1 como LAN L2 pura
|
||
|
||
A rede interna das VMs (`10.10.10.0/24`) deve ser servida por **vmbr1**, bridge **sem IPv4 no host Proxmox**:
|
||
|
||
- `bridge-ports none` — isolada do hardware
|
||
- Host **não** actua como gateway na vmbr1
|
||
- Gateway das VMs: **pfSense LAN** (`10.10.10.1`)
|
||
- Documentação de referência: `docs/network/INTERFACES_PROXMOX.md`
|
||
|
||
**Drift conhecido (2026-06-08):** VMs operam em `vmbr4000` (Hetzner vSwitch, host `10.10.10.254`). Migração para vmbr1 requer plano aprovado — não improvisar.
|
||
|
||
### II. Proxmox Interfaces — alteração tripla obrigatória
|
||
|
||
O ficheiro `/etc/network/interfaces` do host Proxmox é **crítico e imutável sem aprovação**:
|
||
|
||
1. Descrever intenção real e diff completo antes de qualquer alteração
|
||
2. Obter confirmação explícita do Roger **três vezes**
|
||
3. Verificar iptables antes e depois; limpar duplicatas; nunca `ifreload` múltiplo sem limpeza
|
||
|
||
Ordem das regras importa (FIFO). Destino WAN pfSense = `10.0.0.2`, **nunca** LAN `10.10.10.1` em DNAT.
|
||
|
||
### III. Anti-Scan Hetzner — regras obrigatórias (NON-NEGOTIABLE)
|
||
|
||
Quatro linhas de proteção FORWARD devem estar activas na secção vmbr1:
|
||
|
||
```
|
||
post-up iptables -I FORWARD -s 10.10.10.0/24 ! -d 10.10.10.0/24 -j DROP
|
||
post-up iptables -I FORWARD -s 10.10.10.0/24 ! -d 10.10.10.0/24 -p udp --dport 53 -j ACCEPT
|
||
```
|
||
|
||
**Proibido:** `POSTROUTING MASQUERADE` genérico para `10.10.10.0/24` (causa abuse reports).
|
||
|
||
Verificação obrigatória: após qualquer alteração de rede e **diariamente**.
|
||
|
||
### IV. Separation of Concerns — Mail vs Ops
|
||
|
||
| VM | Papel | Restrição |
|
||
|----|-------|-----------|
|
||
| **112** | Carbonio mail + portal onboard | Não misturar workloads de ops/monitoring |
|
||
| **113** | PMG mail gateway | Filtro SMTP apenas |
|
||
| **122** | Ligbox Ops Platform | API, desk, workers — **sem mail stack** |
|
||
|
||
Comunicação entre 112 e 122 via API/webhook na LAN (`10.10.10.x`), nunca exposição directa à internet.
|
||
|
||
### V. Security Baseline — toda VM exposta
|
||
|
||
Toda VM/CT com SSH (LAN ou WAN) deve ter:
|
||
|
||
- **fail2ban** activo com jail `sshd` (bantime ≥ 3600s, maxretry ≤ 5)
|
||
- `PasswordAuthentication` verificado com `sshd -T` (não confiar só no ficheiro principal)
|
||
- Ficheiros `sshd_config.d/*.conf` verificados (sobrescrevem config principal)
|
||
- Portas de serviço bindadas à LAN quando possível (`10.10.10.x`, não `0.0.0.0`)
|
||
|
||
### VI. pfSense API — acesso validado
|
||
|
||
- URL produção: `https://firewall.itecnologys.com/api/v2/` (via Traefik)
|
||
- Fallback directo: `https://10.10.10.1:10443/api/v2/`
|
||
- Autenticação: **Basic Auth** (`-u user:password`), nunca headers customizados
|
||
- Após alterações NAT/firewall: `POST /api/v2/firewall/apply`
|
||
- DNAT externo → pfSense WAN (`10.0.0.2`), portas SSH VMs via pfSense (2501–2522)
|
||
|
||
### VII. Spec-Driven Development — Spec Kit obrigatório
|
||
|
||
Todo trabalho de feature segue o fluxo Spec Kit **antes** de implementação:
|
||
|
||
```
|
||
/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.checklist
|
||
→ /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement
|
||
```
|
||
|
||
- Constitution (este ficheiro) precede qualquer feature
|
||
- Specs em `specs/` com branch `NNN-nome-feature`
|
||
- Não implementar sem `plan.md` + `tasks.md` validados
|
||
- Backlog livre migra para specs numeradas
|
||
|
||
### VIII. Documentation First — Obsidian + repo
|
||
|
||
- Inventário VMs: `obsidian-infra/docs/TABELA_VMS_*.md` — actualizar após cada VM nova
|
||
- Decisões arquitecturais: `docs/decisions/DECISAO_*.md`
|
||
- Chat bruto / sessões: `obsidian-infra/` (vault principal)
|
||
- Código deployável: `/opt/<projeto>/` na VM + sync para `workspace/projects/`
|
||
|
||
### IX. Simplicity — YAGNI no MVP
|
||
|
||
- Preferir SQLite a Postgres para ops MVP (VM122)
|
||
- Docker compose mínimo (api + worker + redis + frontend)
|
||
- Adiar: SOC, Wazuh centralizado, 7 agents, Postgres cluster
|
||
- Cada feature justifica complexidade adicional
|
||
|
||
---
|
||
|
||
## Security Requirements
|
||
|
||
| Requisito | Implementação |
|
||
|-----------|---------------|
|
||
| SSH externo | pfSense NAT `95.216.14.146:PORTA` → VM:22 |
|
||
| SSH interno | `root@10.10.10.x` a partir do host ou LAN |
|
||
| Webhook secrets | Rotação obrigatória em produção (não usar defaults dev) |
|
||
| Credenciais | Nunca commitar em git; usar `.env` local |
|
||
| Cloudflare API | Tokens com scope mínimo (zone DNS, não account-wide) |
|
||
| Tailscale/scanning | Monitorar regras FORWARD; bloquear vazamento LAN→WAN |
|
||
|
||
---
|
||
|
||
## Infrastructure Inventory (referência rápida)
|
||
|
||
| Componente | IP / Porta | Notas |
|
||
|------------|-----------|-------|
|
||
| Proxmox host | 95.216.14.162 | vmbr0 |
|
||
| pfSense LAN | 10.10.10.1 | VM100, gateway VMs |
|
||
| pfSense WAN | 10.0.0.2 | Destino DNAT |
|
||
| VM112 mail | 10.10.10.112:2512 | Carbonio + portal |
|
||
| VM113 PMG | 10.10.10.113:2513 | Mail gateway |
|
||
| VM122 ops | 10.10.10.122:2522 | Ligbox Ops MVP |
|
||
| CT119 qtm | 10.10.10.119 | Não migrar — reservado |
|
||
| Traefik | CT114 / VM105 | `firewall.itecnologys.com` |
|
||
|
||
---
|
||
|
||
## Development Workflow
|
||
|
||
1. **Constitution** — verificar compliance antes de iniciar feature
|
||
2. **Specify** — requisitos (o quê / porquê, sem tech stack)
|
||
3. **Clarify + Checklist** — obrigatório para produção
|
||
4. **Plan + Tasks** — arquitectura e passos executáveis
|
||
5. **Analyze** — consistência cross-artifact antes de implementar
|
||
6. **Implement** — código + deploy + verificação
|
||
7. **Validate** — testes, fail2ban, iptables, health endpoints
|
||
8. **Document** — actualizar inventário VMs e decisões
|
||
|
||
### Quality gates (bloqueantes)
|
||
|
||
- [ ] Constitution compliance verificada
|
||
- [ ] fail2ban activo na VM alvo
|
||
- [ ] Sem alteração não aprovada em `/etc/network/interfaces`
|
||
- [ ] Regras anti-scan Hetzner verificadas
|
||
- [ ] Health check da feature OK
|
||
- [ ] Inventário VMs actualizado
|
||
|
||
---
|
||
|
||
## Governance
|
||
|
||
- Esta constitution **supera** backlog informal, prompts ad-hoc e decisões não documentadas
|
||
- Emendas requerem: proposta escrita, aprovação Roger, bump de versão, data de ratificação
|
||
- Toda PR / sessão de implementação deve verificar compliance com esta constitution
|
||
- Drift de infra (ex.: vmbr1 com IP, VMs em vmbr4000) deve ser documentado em `docs/network/` até resolução
|
||
- Complexidade adicional (novo serviço, nova VM, nova bridge) requer spec dedicada — não improvisar
|
||
|
||
**Version**: 1.0.0 | **Ratified**: 2026-06-08 | **Last Amended**: 2026-06-08
|