Guia de Implementação

Passo a passo para colocar o GuardaIA em funcionamento na empresa do seu cliente — da instalação ao redirecionamento do chat corporativo.

O que o GuardaIA faz

O GuardaIA é um gateway de governança de IA que fica entre os funcionários da empresa e os serviços de IA (ChatGPT, Claude, Gemini etc.). Ele:

• Intercepta os prompts antes de saírem da empresa
• Detecta e mascara dados sensíveis (CPF, CNPJ, cartão, chaves de API...)
• Bloqueia o envio se houver dados críticos (modo block)
• Controla o custo mensal por departamento e projeto
• Mantém trilha de auditoria imutável com hash encadeado
• Isola os dados de cada empresa (multi-tenant)

Fluxo de uma requisição:

Funcionário  →  GuardaIA  →  OpenAI / Claude / Gemini
               ↑ autentica       ↑ DLP mascara
               ↑ verifica cota   ↑ registra custo
               ↑ audita          ↑ devolve resposta

Planos comerciais e limites tecnicos

Os planos comerciais passam a ser parte da operacao tecnica. O GuardaIA registra o plano da organizacao e usa essa informacao para bloquear excessos e liberar recursos compativeis.

Pré-requisitos

Instalação

1. Baixar e extrair

Baixe o arquivo tokenguard-mvp.zip e extraia na pasta do projeto:

cd C:\projetos\tokenguard   # Windows
# ou
cd ~/projetos/tokenguard     # Linux / Mac

2. Instalar dependências

pip install -r requirements.txt

3. Configurar o banco (opcional — sem configuração usa SQLite)

Para PostgreSQL, crie o banco e defina a variável de ambiente:

# Windows (cmd)
set DATABASE_URL=postgresql+psycopg://postgres:SENHA@localhost:5432/tokenguard

# Linux / Mac
export DATABASE_URL=postgresql+psycopg://postgres:SENHA@localhost:5432/tokenguard

4. Criar os dados iniciais

python seed.py

O seed imprime no terminal as credenciais de acesso de cada tenant e do super-admin. Salve-as — as chaves tg-... aparecem apenas neste momento.

5. Iniciar o servidor

python run.py

Em Docker local, acesse preferencialmente http://localhost:8080. Se estiver rodando sem Nginx, o app responde em http://localhost:8000.

Configurando o primeiro tenant (empresa cliente)

Configurando provedores de IA

O GuardaIA roteia automaticamente pelo prefixo do modelo:

Azure OpenAI

No cofre, informe o provedor azure e preencha a Base URL no formato:

https://SEU-RECURSO.openai.azure.com/openai/deployments/SEU-DEPLOY

Provedores personalizados (Groq, Mistral, Ollama...)

Menu Chaves de IA (Cofre) → Catálogo de provedores → Cadastrar provedor. Informe o nome, a base URL compatível com a API OpenAI e os prefixos de modelo para roteamento automático.

# Exemplo: Groq
Nome: groq
Base URL: https://api.groq.com/openai/v1
Prefixos: llama-,mixtral-,gemma-

Configurando a proteção de dados (DLP)

Estratégia de implantação em 3 semanas

Para trocar o modo: menu Regras DLP → Modo de operação.

Regras personalizadas

Além dos detectores nativos (CPF, CNPJ, cartão, e-mail, chaves de API...), você pode cadastrar padrões próprios da empresa: matrícula de funcionário, número de prontuário, código de contrato etc.

Menu Regras DLP → Regras personalizadas → informe o padrão (expressão regular) e use o Testador para verificar antes de salvar.

# Exemplos de padrões úteis
Matrícula:     \bMAT-\d{6}\b
Prontuário:    \bPRT-\d{8}\b
NF-e:          \b\d{44}\b
Processo:      \d{7}-\d{2}\.\d{4}\.\d\.\d{2}\.\d{4}

Cotas e projetos

Cotas por departamento

Menu Políticas de Cota → defina o limite mensal em US$ por departamento. Quando atingir:

• 75% — alerta gerado (visível no dashboard e no chat)
• 80% — novo alerta de atenção
• 95% — alerta crítico
• 100% — bloqueio das requisições (HTTP 429) ou só alerta, conforme a política

Projetos com cota própria

Para projetos com orçamento separado (chatbot de atendimento, copilot de contratos...), crie um projeto e gere uma chave tg- vinculada a ele. A cota do projeto é independente da cota do departamento.

Menu Projetos → Criar projeto → defina o limite mensal.

Guarda de auditoria monitorada

A retenção dos registros armazenados deixou de ser apenas configuração técnica e passou a ser uma política contratual. O sistema compara o plano da organização com o prazo de retenção configurado e impede prazos acima do permitido.

• Starter: guarda máxima de 30 dias
• Pro: guarda máxima de 6 meses
• Enterprise: guarda máxima de 1 ano

Na tela Retenção de Prompts, o painel informa o plano atual, a política máxima permitida e se existe alguma divergência entre a idade do conteúdo retido e o prazo contratado.

Estimador de projetos

Antes de fechar o orçamento com o cliente, use o Estimador de Projetos (menu lateral): cole a especificação, informe o volume de usuários e veja a projeção de custo em todos os modelos disponíveis, com cenários baixo / esperado / alto.

Portal de chat corporativo

O portal de chat (/chat ou /t/{slug}/chat) é a interface que os funcionários usam para interagir com a IA. É protegido pelo GuardaIA: o funcionário entra com a chave tg- do departamento, escolhe o provedor e o modelo, e conversa normalmente.

O que o funcionário vê

• Seletor de provedor (ChatGPT, Claude, Gemini...) e modelo
• Cada resposta exibe tokens consumidos, custo e — se o DLP agiu — quantos dados foram mascarados
• Se a mensagem for bloqueada (DLP ou cota), aparece orientação clara do que fazer

Distribuindo as chaves

Gere uma chave tg- por departamento no painel. Envie a chave para o funcionário por e-mail ou sistema interno. O funcionário cola a chave no portal de chat uma única vez (fica salva na sessão do navegador).

Redirecionamento de IA pública para o portal

O ponto mais poderoso da solução: quando o funcionário tentar acessar chat.openai.com, claude.ai ou gemini.google.com, ele é redirecionado para o portal corporativo — sem bloquear o trabalho.

Opção 1 — DNS interno (recomendado para empresas com servidor DNS próprio)

# Arquivo de zona do DNS interno
claude.ai          A    IP_DO_TOKENGUARD
chat.openai.com    A    IP_DO_TOKENGUARD
chatgpt.com        A    IP_DO_TOKENGUARD
gemini.google.com  A    IP_DO_TOKENGUARD

Opção 2 — Arquivo hosts local (útil para pilotos e testes)

Quando ainda nao ha DNS interno ou proxy corporativo configurado, e possivel apontar os dominios de IA publica para o GuardaIA diretamente no arquivo hosts da maquina. Essa opcao e boa para validacao controlada, laboratorio ou poucos computadores.

Windows

Arquivo:

C:\Windows\System32\drivers\etc\hosts

Abra o Bloco de Notas como administrador e adicione:

# Redirecionamento IA pública para GuardaIA
IP_DO_GUARDAIA  claude.ai
IP_DO_GUARDAIA  chat.openai.com
IP_DO_GUARDAIA  chatgpt.com
IP_DO_GUARDAIA  gemini.google.com

Depois limpe o cache DNS:

ipconfig /flushdns

Linux

Arquivo:

/etc/hosts

Edite com sudo:

sudo nano /etc/hosts

Adicione:

# Redirecionamento IA pública para GuardaIA
IP_DO_GUARDAIA  claude.ai
IP_DO_GUARDAIA  chat.openai.com
IP_DO_GUARDAIA  chatgpt.com
IP_DO_GUARDAIA  gemini.google.com

Se necessário, limpe o cache DNS conforme a distribuição:

sudo systemd-resolve --flush-caches
# ou
sudo resolvectl flush-caches

macOS

Arquivo:

/etc/hosts

Edite com sudo:

sudo nano /etc/hosts

Adicione:

# Redirecionamento IA pública para GuardaIA
IP_DO_GUARDAIA  claude.ai
IP_DO_GUARDAIA  chat.openai.com
IP_DO_GUARDAIA  chatgpt.com
IP_DO_GUARDAIA  gemini.google.com

Depois limpe o cache DNS:

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Opção 3 — Proxy corporativo (Squid, Zscaler, Palo Alto...)

Configure uma regra de reescrita de URL que redirecione os domínios de IA para https://tokenguard.suaempresa.com.br/chat. A maioria dos proxies corporativos suporta isso com uma regra simples.

Opção 4 — Extensão de navegador

Para ambientes sem controle de DNS, uma extensao Chrome/Edge pode interceptar as URLs e redirecionar. Esta opcao esta no roadmap do GuardaIA.

Gestão de acessos (IAM)

Papéis disponíveis

Conceder acesso ao administrador do cliente

1. Menu Acessos (IAM) → Conceder acesso
2. Informe o e-mail Google do administrador, papel admin da organização e a organização
3. Envie para o cliente a URL do tenant: http://seudominio.com/t/slug-da-empresa
4. Na primeira vez que ele abrir a URL e clicar em Entrar com Google, já entrará direto no tenant dele

Mesmo e-mail em várias empresas

O mesmo e-mail pode administrar N organizações (caso de um contador com vários CNPJs). No login, se o e-mail tiver mais de uma empresa vinculada, aparece um seletor de tenant. Cada empresa tem URL própria para evitar a escolha:

http://seudominio.com/t/empresa-a   ← entra direto na Empresa A
http://seudominio.com/t/empresa-b   ← entra direto na Empresa B

Ir para produção

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

set TG_ADMIN_TOKEN=troque-por-um-valor-aleatorio-longo

TG_GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
TG_SUPERADMIN_EMAIL=voce@suaempresa.com

# Nginx (trecho)
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

[Unit]
Description=GuardaIA

[Service]
WorkingDirectory=/opt/tokenguard
ExecStart=/usr/bin/python run.py
EnvironmentFile=/opt/tokenguard/.env
Restart=always

[Install]
WantedBy=multi-user.target

Perguntas frequentes

O funcionário vai perceber que está passando pelo GuardaIA?

Depende da interface. No portal de chat (/chat), a marca e visivel. Se o sistema interno do cliente ja usava a API OpenAI, basta trocar a base_url para o GuardaIA — a resposta e identica ao formato OpenAI, com um campo extra tokenguard nos metadados.

O que acontece se o GuardaIA ficar fora do ar?

Os funcionários perdem o acesso à IA corporativa enquanto o serviço está indisponível. Em modo alta disponibilidade (roadmap), múltiplas instâncias com load balancer eliminam esse risco. Para ambientes críticos, configure monitoramento com alertas.

A chave de API da empresa está segura?

Sim. As chaves dos provedores são criptografadas com AES (Fernet) usando uma master key que nunca vai para o banco. O painel nunca exibe a chave em claro — nem no formulário, nem na listagem. Em produção, substitua o arquivo .master_key por um serviço de KMS (AWS KMS, Azure Key Vault, HashiCorp Vault).

Posso usar com n8n, LangChain ou outros frameworks?

Sim. O GuardaIA e compativel com qualquer cliente que suporte a API OpenAI. Basta configurar:

# n8n — nó "OpenAI"
Base URL: http://localhost:8000/v1
API Key:  tg-SEU-TOKEN-DE-DEPARTAMENTO

# Python / LangChain
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="tg-...")

# JavaScript
const openai = new OpenAI({ baseURL: 'http://localhost:8000/v1', apiKey: 'tg-...' });

Como exportar o relatório de DLP para a diretoria?

No menu Auditoria e Logs, use os filtros para selecionar o período e o status. Os dados podem ser exportados diretamente do browser (botão direito → Salvar) ou via API (GET /admin/dlp-findings-log?org_id=...) para integração com Power BI ou Google Data Studio.

O expurgo de prompts quebra a auditoria?

Não. O hash encadeado da auditoria é calculado sobre os metadados (tokens, custo, modelo, timestamp) — o conteúdo do prompt nunca participa do hash. Expurgar o conteúdo por LGPD preserva o Selo de Integridade da trilha auditável.