Pular para o conteúdo principal

Segurança e fortalecimento

Esta página coleta as decisões de segurança para uma implantação Kanera auto-hospedada. Ele cobre o que a Internet enfrenta, quais segredos são importantes, o que o servidor contata e quais configurações devem ser reforçadas quando a pilha estiver em execução.

Leia depois Primeiros passos. As configurações detalhadas estão em outras páginas de auto-hospedagem, que estão vinculadas a cada seção.

O que enfrenta a internet​

O pacote docker-compose.yml não publica nenhum dos serviços de aplicativo. Você decide o que publicar, geralmente por meio de um compose.override.yml e um proxy reverso. Veja Serviços e roteamento.

ServiçoExposiçãoNotas
webPúblico, por trás do seu proxy HTTPSO único serviço que os navegadores precisam. Seu nginx encaminha a API do aplicativo e o tráfego em tempo real para api internamente.
public-apiOpcional, públicoPublique-o apenas para integrações, referência de API ou agente de IA OAuth.
mcpOpcional, públicoPublique-o apenas se clientes remotos de IA precisarem se conectar.
apiApenas internoNunca dê à API principal seu próprio domínio público.
workerApenas internoExecuta agendadores e entrega externa.
postgresApenas loopback de hostObrigado a 127.0.0.1:5433 por padrão (POSTGRES_BIND_PORT). Use um túnel SSH para acesso remoto.
valkeyApenas internoNenhuma porta publicada. Ele funciona sem senha na rede Compose, portanto nunca o publique.
admin-apiDesativado por padrãoComeça apenas com COMPOSE_PROFILES=admin. Coloque-o em seu próprio domínio se você habilitá-lo.
MonitoramentoDesativado por padrãoCom o monitoring perfil, Prometheus e Grafana se ligam a 127.0.0.1 a menos que você defina MONITORING_BIND_IP, por exemplo, para um endereço VPN. Nunca os vincule a 0.0.0.0.

Quanto menos serviços você publicar, menos haverá para atacar. Uma implantação que usa apenas o aplicativo Web precisa de um único domínio público.

TLS e o proxy reverso​

Os contêineres do Kanera falam HTTP simples. Encerre o TLS em seu proxy reverso ou balanceador de carga (Caddy, Traefik, nginx ou um balanceador de carga em nuvem) e atenda todos os domínios públicos por HTTPS.

  • Definir COOKIE_SECURE=truee faça WEB_ORIGIN e COOKIE_DOMAIN corresponda ao endereço HTTPS público.
  • O contêiner da web envia Strict-Transport-Security com includeSubDomains e uma vida útil de um ano. Os navegadores também insistirão em HTTPS para subdomínios do domínio do aplicativo, portanto, mantenha os subdomínios API, MCP e admin em HTTPS.
  • Também envia uma Política de Segurança de Conteúdo, X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, e uma restrição Permissions-Policy. Não os retire no proxy.

Os limites de taxa e as restrições de entrada usam o IP do cliente. Esse IP só é confiável quando um proxy substitui os cabeçalhos de encaminhamento:

ConfiguraçãoCompor padrãoDefinir como true quando
API_TRUST_PROXYfalseO aplicativo fica atrás de um proxy que define o IP real do cliente.
PUBLIC_API_TRUST_PROXYfalseO mesmo, para a API pública.
MCP_TRUST_PROXYtrueDeixe true somente enquanto o MCP for acessível somente por meio de tal proxy.
ADMIN_TRUST_PROXYtrueDeixe true somente enquanto a API admin estiver acessível somente por meio desse proxy.

Se um serviço confiar em cabeçalhos de proxy, mas os clientes puderem acessá-lo diretamente, eles poderão falsificar seu IP e contornar os limites por IP.

Segredos​

Gere cada segredo separadamente, por exemplo com openssl rand -hex 32, e mantê-los em um armazenamento secreto fora do servidor, bem como em .env. Na produção, a API se recusa a iniciar enquanto espaços reservados de desenvolvimento conhecidos ainda estão em uso. Também se recusa a iniciar quando SECRETS_ENCRYPTION_KEY está faltando ou é igual a JWT_SECRET, ou quando MCP_INTERNAL_SECRET ou ADMIN_JWT_SECRET é igual JWT_SECRET.

SegredoProtegeSe você mudar isso
POSTGRES_PASSWORDO login do banco de dadosAtualize também o usuário do banco de dados em execução.
JWT_SECRETSessões de aplicativosTodos estão desconectados. Esta é a maneira mais rápida de encerrar cada sessão após uma suspeita de vazamento.
MFA_ENCRYPTION_KEYSegredos do autenticador e códigos de recuperaçãoTodo autenticador registrado para de funcionar.
MEDIA_SIGNING_SECRETURLs de mídia assinadosOs links de mídia existentes param de ser resolvidos.
SECRETS_ENCRYPTION_KEYCredenciais armazenadas de SMTP, armazenamento, webhook, destino de bate-papo e aplicativo GitHubAs credenciais armazenadas não podem mais ser descriptografadas e devem ser inseridas novamente.
MCP_INTERNAL_SECRETA troca privada entre mcp e public-apiDefina o mesmo novo valor em ambos os serviços. As solicitações de MCP em andamento podem falhar.
ADMIN_JWT_SECRETSessões do portal de gerenciamentoOs administradores do portal estão desconectados.
METRICS_TOKEN/metrics raspagemAtualize o Prometheus para corresponder.
DB_BACKUP_ENCRYPTION_PASSPHRASEBackups criptografadosOs backups feitos com a senha antiga ainda precisam da senha antiga.

Kanera não possui uma maneira integrada de criptografar novamente os dados armazenados com uma nova chave. Tratar MFA_ENCRYPTION_KEY e SECRETS_ENCRYPTION_KEY tão duradouro e planeje uma rotação antes de precisar dela. Veja Segredos que vale a pena guardar.

As métricas estão ativadas por padrão, mas /metrics retorna 404 até METRICS_TOKEN está definido. O perfil de monitoramento se recusa a iniciar sem METRICS_TOKEN e GRAFANA_ADMIN_PASSWORD.

Tráfego de saída​

Kanera não tem verificação de atualização. A análise do produto está desativada por padrão e destina-se apenas ao Kanera Cloud. O servidor contata apenas destinos que você, seus administradores ou usuários configuram:

  • Seu servidor SMTP, armazenamento compatível com S3 e bucket de backup.
  • Serviços push do navegador, uma vez que um administrador da organização habilita o push.
  • Webhooks do espaço de trabalho e destinos de bate-papo (Slack, Discord, Telegram, Zulip) configurados pelos administradores do espaço de trabalho.
  • Canais pessoais ntfy, Gotify ou webhook configurados pelos usuários.
  • ALERT_WEBHOOK_URL para alertas operacionais, se definido.
  • Trello, durante uma importação que copia anexos com TRELLO_API_KEYe GitHub, quando um aplicativo GitHub está configurado para visualizações de links.
  • Catraca Cloudflare, somente quando suas chaves estão definidas. Deixe-os desabilitados para auto-hospedagem normal.

Um destino não está configurado pelo operador. Quando um cliente de IA liga para o MCP search.docs ferramenta, o serviço MCP baixa o índice de documentação pública de https://www.kanera.app/docs-search.json e pesquisa localmente. A consulta de pesquisa não é enviada.

Redes privadas​

Os webhooks do espaço de trabalho e os destinos de chat devem usar endereços HTTPS públicos. Kanera recusa metadados de loopback, privados, CGNAT, link-local e nuvem e outros endereços reservados. Ele verifica novamente o endereço na hora da entrega e não segue redirecionamentos. Isso impede que um webhook ou destino de bate-papo seja apontado para serviços dentro da sua rede.

Os canais de notificação pessoal seguem a mesma regra, a menos que você aceite:

KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS=true

Isso permite que os usuários enviem notificações ntfy, Gotify e webhook pessoais para http:// e receptores de rede privada. Endereços de link local e metadados, multicast e outros intervalos reservados permanecem bloqueados. Isso não relaxa a regra para webhooks de espaço de trabalho ou destinos de bate-papo. Ative-o somente se você aceitar que qualquer usuário possa fazer com que o servidor envie solicitações para hosts em sua rede interna. Veja E-mail e notificações.

Cópias de segurança​

O opcional db-backup O serviço criptografa cada dump do PostgreSQL com AES-256 simétrico GPG antes de carregá-lo para um armazenamento compatível com S3. Um manual pg_dump não está criptografado, então criptografe-o você mesmo antes de sair do servidor. Arquivos carregados no kanera_uploads volume não são cobertos por db-backup e precisam de seu próprio backup. Mantenha os backups e a senha de backup fora do disco principal do servidor. Veja Armazenamento e backups.

Atualizações​

Correções de segurança são fornecidas para a última versão marcada. Execute uma versão marcada em vez do main branch, atualize quando um novo for lançado, leia as notas de lançamento e faça backup antes de atualizar. As imagens de terceiros no arquivo de composição são fixadas em versões exatas, portanto, uma reimplantação de rotina não altera o PostgreSQL ou o Valkey sem uma alteração revisada. Veja Atualizações e dimensionamento.

Contas e login​

  • Feche a inscrição pública. Depois de criar sua organização, defina SIGNUPS_ENABLED=false. Os links de convite continuam funcionando.
  • Verifique endereços de e-mail. Assim que o correio de saída funcionar, defina EMAIL_VERIFICATION_ENABLED=true.
  • Mantenha a otimização de autenticação ativada. AUTH_RATE_LIMIT_ENABLED o padrão é true, permitindo 10 tentativas por minuto por IP.
  • Exigir MFA. Os administradores da organização podem exigir um autenticador para todos sob Configurações -> Organização -> Segurança. Veja Perfil e segurança.
  • Tempos de vida da sessão. Os tokens de acesso ao aplicativo duram 5 minutos e as sessões de atualização duram 10 dias (JWT_ACCESS_TTL, JWT_REFRESH_TTL_DAYS).
  • Portal de gerenciamento. Está desativado por padrão e usa suas próprias contas e segredos. Se você ativá-lo, suas sessões de suporte atuarão como proprietárias da organização alvo. Cada um deles é registrado em um log de auditoria e expira sozinho, após 60 minutos por padrão (SUPPORT_SESSION_TTL_MINUTES, no máximo 480).

Acesso do agente de IA​

Expor mcp e as rotas OAuth em public-api somente se você quiser clientes de IA remotos. O controle do plano não se aplica a implantações auto-hospedadas, portanto, quando o MCP estiver acessível, qualquer membro poderá conectar um agente que atue com as permissões desse membro.

  • Definir MCP_SERVER_PUBLIC_URL e PUBLIC_API_OAUTH_ISSUER para seus próprios domínios. Os tokens OAuth são vinculados a esse endereço MCP e rejeitados por /api/v1.
  • Qualquer cliente pode registar-se em /oauth/register. O registro não concede nada até que um usuário conectado aprove a conexão na tela de consentimento.
  • As solicitações públicas autenticadas de API e MCP são limitadas a 400 por minuto por credencial por padrão. As tentativas de chave com falha são limitadas a 10 por minuto por IP. Veja Referência Ambiental.
  • O serviço MCP registra o nome, a duração e o resultado de cada chamada de ferramenta, mas não seus argumentos.

Veja Integrações e APIs para configuração e Permissões e segurança do agente pelo que um agente pode fazer.

Relatar uma vulnerabilidade​

Não abra uma edição pública por um problema de segurança. E-mail [email protected] com uma descrição, etapas de reprodução, o componente afetado e se isso afeta a configuração padrão auto-hospedada. Os relatórios são reconhecidos em até cinco dias úteis. Veja SECURITY.md no repositório Kanera para escopo e divulgação.