ophion/docs/SECURITY.md

# 🔐 OPHION Security Guide

## Visão Geral

OPHION foi projetado com segurança em camadas (defense in depth):

1. **Autenticação** - JWT + API Keys
2. **Autorização** - RBAC + Scopes
3. **Rate Limiting** - Proteção contra DDoS/Brute Force
4. **Criptografia** - TLS + Bcrypt + SHA256
5. **Auditoria** - Logs de todas as ações
6. **Isolamento** - Multi-tenant por organização

---

## 🔑 Autenticação

### JWT Tokens

- **Access Token**: Curta duração (15-60 min)
- **Refresh Token**: Longa duração (7-30 dias)
- **Algoritmo**: HS256 (HMAC-SHA256)
- **Revogação**: Via Redis blacklist

```bash
# Header de autenticação
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### API Keys

- **Formato**: `ophion_` + 64 caracteres hex
- **Storage**: Hash SHA256 (nunca plaintext)
- **Scopes**: Permissões granulares
- **Rotação**: Recomendado a cada 90 dias

```bash
# Exemplo de API Key
ophion_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

# Header de autenticação
Authorization: Bearer ophion_xxx...
```

### Scopes de API Key

| Scope | Descrição |
|-------|-----------|
| `metrics:read` | Ler métricas |
| `metrics:write` | Enviar métricas |
| `logs:read` | Ler logs |
| `logs:write` | Enviar logs |
| `traces:read` | Ler traces |
| `traces:write` | Enviar traces |
| `alerts:read` | Ler alertas |
| `alerts:write` | Criar/editar alertas |
| `admin` | Acesso administrativo |
| `*` | Acesso total |

---

## 🛡️ Proteções

### Rate Limiting

| Endpoint | Limite | Janela |
|----------|--------|--------|
| `/api/v1/auth/*` | 5 req | 1 min |
| `/api/v1/*` (API) | 100 req | 1 min |
| `/api/v1/ingest/*` | 1000 req | 1 min |
| `/api/v1/export/*` | 10 req | 1 hora |

### Brute Force Protection

- **Máximo de tentativas**: 5 falhas
- **Bloqueio**: 15 minutos
- **Tracking**: Por IP + Email

### Security Headers

```http
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), microphone=(), camera=()
```

---

## 🔒 Senhas

### Política de Senha

- Mínimo 12 caracteres
- Letra maiúscula obrigatória
- Letra minúscula obrigatória
- Número obrigatório
- Caractere especial obrigatório
- Bloqueio de senhas comuns

### Armazenamento

- **Algoritmo**: Bcrypt
- **Cost Factor**: 12
- **Salt**: Único por senha (auto-gerado)

---

## 🔐 Criptografia

### Em Trânsito

- TLS 1.2+ obrigatório em produção
- Certificados Let's Encrypt (automático)
- HSTS habilitado

### Em Repouso

- Senhas: Bcrypt hash
- API Keys: SHA256 hash
- Tokens: Opcionalmente criptografados
- Dados sensíveis: AES-256-GCM (configurável)

---

## 📝 Auditoria

### Eventos Registrados

- `auth.login` - Login bem-sucedido
- `auth.login_failed` - Falha de login
- `auth.logout` - Logout
- `apikey.created` - API key criada
- `apikey.revoked` - API key revogada
- `user.created` - Usuário criado
- `user.deleted` - Usuário deletado
- `config.changed` - Configuração alterada
- `alert.created` - Alerta criado
- `data.export` - Exportação de dados

### Campos de Auditoria

```json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "event_type": "auth.login",
  "user_id": "uuid",
  "org_id": "uuid",
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "resource": "/api/v1/auth/login",
  "action": "POST",
  "status": "success",
  "details": {}
}
```

---

## 🏢 Multi-Tenancy

### Isolamento de Dados

- Cada organização tem `org_id` único
- Queries sempre filtradas por `org_id`
- API Keys vinculadas à organização
- Usuários pertencem a uma organização

### RBAC (Role-Based Access Control)

| Role | Permissões |
|------|------------|
| `viewer` | Somente leitura |
| `operator` | Leitura + Ack de alertas |
| `editor` | Leitura + Escrita |
| `admin` | Acesso total à organização |
| `super_admin` | Acesso total ao sistema |

---

## ⚙️ Configurações de Segurança

### Variáveis de Ambiente

```bash
# Obrigatórias
JWT_SECRET=<random-64-chars>           # openssl rand -hex 32
ADMIN_PASSWORD=<strong-password>

# Recomendadas
HTTPS_ONLY=true                        # Forçar HTTPS
SESSION_TIMEOUT=3600                   # 1 hora
REFRESH_TOKEN_DAYS=7                   # 7 dias
PASSWORD_MIN_LENGTH=12                 # Mínimo 12 chars
RATE_LIMIT_ENABLED=true
AUDIT_LOG_ENABLED=true

# IP Whitelist (opcional)
ADMIN_IP_WHITELIST=10.0.0.0/8,192.168.0.0/16
API_IP_WHITELIST=                      # Vazio = todos permitidos
```

### Checklist de Produção

- [ ] JWT_SECRET único e forte (64+ chars)
- [ ] HTTPS habilitado
- [ ] Senhas fortes para todos os usuários
- [ ] Rate limiting habilitado
- [ ] Logs de auditoria habilitados
- [ ] Backup configurado
- [ ] Firewall configurado
- [ ] Atualizações automáticas
- [ ] Monitoramento de segurança

---

## 🚨 Resposta a Incidentes

### Se suspeitar de comprometimento:

1. **Revogar todas as API Keys**
   ```bash
   ophion security revoke-all-keys
   ```

2. **Invalidar todas as sessões**
   ```bash
   ophion security invalidate-sessions
   ```

3. **Rotacionar JWT Secret**
   ```bash
   # Atualizar .env com novo JWT_SECRET
   ophion restart
   ```

4. **Revisar logs de auditoria**
   ```bash
   ophion logs --type audit --since 24h
   ```

5. **Resetar senhas comprometidas**

---

## 📞 Reportar Vulnerabilidades

Se você encontrar uma vulnerabilidade de segurança:

1. **NÃO** abra uma issue pública
2. Envie email para: security@ophion.io
3. Inclua detalhes e passos para reproduzir
4. Aguarde confirmação antes de divulgar

**Programa de Bug Bounty**: Em breve!

---

## 🔄 Atualizações de Segurança

Assine nossa lista de segurança:
- Email: security-announce@ophion.io
- GitHub Security Advisories

Versões com suporte de segurança:
- Última versão: Suporte completo
- Versão anterior: Patches críticos por 6 meses