Segurança
O Agente roda na máquina do cliente com acesso ao certificado da empresa. Esta página descreve o que ele protege, como, e o que fica sob responsabilidade de quem opera.
O que nunca sai da máquina
| Item | Onde fica | Quem acessa |
|---|---|---|
| Chave privada do certificado | No arquivo .pfx informado, no token A3 ou no repositório do Windows. | Só o processo do Agente, na hora de assinar ou de abrir o TLS com a SEFAZ. Nunca é copiada, exportada ou transmitida. |
| Senha do PFX / PIN do token | Cofre de senhas do sistema operacional. Sem cofre (Linux headless): arquivo com permissão restrita ao usuário. | Só o Agente. Nunca em log, nunca na configuração, nunca no painel. |
| Notas off-line e numeração | nfce/nfce.db, nfce/notas/*.json.gz, backups. | O Agente; o servidor recebe cada nota na sincronização. |
O que trafega para o Brasil NFe: metadados públicos do certificado (titular, emissor, validade, thumbprint, certificado público em Base64), assinaturas prontas, respostas da SEFAZ, a telemetria de status (versão, plataforma, nome da máquina, série, contadores da fila) e as notas off-line (JSON + XML assinado). Nada disso permite assinar em nome da empresa fora do Agente.
O que o pacote fiscal off-line contém: as regras fiscais da NFC-e (montagem/assinatura do XML, QR Code, DANFE), schemas e tabelas. Não contém senhas, tokens, integrações nem o painel. A configuração fiscal da empresa que ele recebe tem os campos secretos removidos (senha do certificado, código de pareamento, token da API, segredos de integração); o CSC fica porque o QR Code exige.
O código de pareamento como credencial
- É uma credencial de portador: quem o apresenta ao Brasil NFe fala como aquela empresa. Guarde como senha; nunca o coloque no PDV nem em páginas web (o PDV não precisa dele: ele fala com a API local, e a API local é quem apresenta o código ao servidor).
- Revogável no painel a qualquer momento, com efeito imediato (o Agente é derrubado). Gerar um novo código também invalida o anterior.
- Uma conexão por empresa: uma segunda instância com o mesmo código derruba a primeira ("substituído"). Se você vir esse estado sem ter instalado outro Agente, revogue o código e investigue.
- O
UserTokenda API nunca passa pelo Agente nem pelo navegador: ao encaminhar uma NFC-e online, o Agente chama um endpoint autenticado pelo código de pareamento e é o servidor que usa o token da empresa por dentro.
Assinatura: limites e auditoria
- O Agente assina no padrão exigido pela SEFAZ apenas o que o servidor (ou o pacote fiscal off-line) monta; ele não monta documentos por conta própria.
- Há limites de tamanho e quantidade por lote de assinatura, para que um código vazado não transforme o Agente num "oráculo" de assinatura ilimitado.
- Auditoria local em
audit.db: data/hora, empresa, certificado, hash do dado assinado, tamanho e latência, por item. Só metadados. Use para investigar qualquer suspeita de uso indevido. - O pacote off-line pede assinaturas ao Agente com autorização de uso único, válida só para a empresa e a nota em curso.
Conexões de rede
| Conexão | Proteção |
|---|---|
| Agente ⇄ Brasil NFe | Sempre TLS (wss:///https://), autenticado pelo código de pareamento. |
| Agente → SEFAZ (mTLS) | Só endereços oficiais das SEFAZ; certificado do servidor validado contra as raízes do sistema + ICP-Brasil embutidas. Proxy só por túnel, com TLS ponta a ponta. |
| PDV → Agente (API local) | HTTP em 127.0.0.1:9155 por padrão. Navegadores só das origens autorizadas (CORS + checagem de Origin, 403 fora da lista). Sem origem configurada, nenhuma página web chama. |
| Operações internas (assinatura para o pacote fiscal, correção de nota) | Só dentro da própria máquina, com autorização de uso único; recusam chamadas de navegador. |
Ao expor a API local na rede (--bind 0.0.0.0, servidor de loja), restrinja a porta no firewall à rede interna dos caixas. A API local não tem autenticação própria: ela confia na rede em que está exposta e nas origens autorizadas para navegadores.
Pacote fiscal e atualizações assinados
- O pacote fiscal e cada release do Agente são assinados digitalmente pelo Brasil NFe; a chave de verificação está embutida no Agente.
- O Agente recusa pacote sem assinatura válida, com arquivo faltando ou com hash divergente, faz um autoteste antes de ativar e instala na pasta de dados do usuário. A versão anterior fica para rollback.
- Atualização do Agente: hash do instalador + assinatura verificados antes de aplicar. Instalações
.deb/.rpmnão se autoatualizam (o gerenciador de pacotes é a cadeia de confiança). - A assinatura de código Authenticode do instalador Windows (SmartScreen) está em implantação; até lá, confira o SHA-256 exibido na página de download.
Console remoto
O painel executa no Agente uma lista fechada de comandos (status, notas, nota, config, update), sempre no escopo da empresa da conexão. Não há execução de shell nem de código arbitrário. Parear e remover pareamentos só é possível na máquina.
Dados no disco
- Pasta de dados por usuário (
%APPDATA%\br.com.brasilnfe.agent\ou~/.local/share/br.com.brasilnfe.agent/). No Linux headless, o segredo do certificado fica em arquivo com permissão restrita ao usuário. - O DANFE não é guardado (é regenerado do XML).
- Backups do banco em
Documentos\BrasilNFe Agente\backup-nfce(Windows) ounfce/backup. Se a pasta Documentos sincroniza com OneDrive/Drive, os backups também sincronizam: leve isso em conta na política de dados da empresa (contêm as notas emitidas off-line, sem nenhum segredo). - Nada é apagado do banco; arquivos por nota de notas transmitidas há mais de 90 dias são removidos.
Recomendações operacionais
- Uma conta de usuário dedicada para o serviço em servidores (systemd
User=), e opairfeito com essa conta. - Relógio certo na máquina (NTP): TLS com a SEFAZ e a data de emissão das notas dependem disso.
- Firewall: saída 443 para
api.brasilnfe.com.bre SEFAZ; entrada na porta da API local só da rede dos caixas, se exposta. - Perdeu a máquina ou suspeita de vazamento: revogue o código no painel imediatamente e gere outro; troque a senha do certificado se ele estava em arquivo.
- Certificado vencendo: a validade aparece na lista de empresas; renove antes.
- Mantenha a atualização automática ligada (padrão). Ela é assinada e corrige problemas sem visita à loja.
- Monitore a fila off-line: o alerta de 12 h (tela, log, painel) indica nota que não conseguiu subir; o prazo legal da contingência off-line é de 24 h na maioria das UFs.
- Não compartilhe o código de pareamento com o fornecedor do PDV: ele não é necessário para a integração.