Pacote de aprovação de TI do agente

Fluxo só de saída

O agente é um serviço do Windows instalado no servidor da empresa, e é ele quem abre toda conexão. Nada na nuvem se conecta ao servidor, e não há porta de entrada para liberar no firewall.

As consultas ficam compiladas no binário. A nuvem escolhe só o domínio de dados e a janela a ler; nunca envia SQL, script ou comando ao servidor.

O agente lê um conjunto fixo de tabelas e colunas, declarado no manifesto do ERP. Não guarda cópia de dado de negócio em disco, e os seus logs não registram valores de negócio.

Rede: nomes e portas

O agente não precisa de nenhuma regra de entrada. Toda conexão dele com o AutoController sai do servidor em TCP 443, cifrada com TLS, e os dados trafegam sob TLS mútuo: o agente confere o gateway e o gateway confere o agente.

A conexão com o SQL Server depende de onde o agente roda. No próprio servidor do banco (o padrão), ela é local. Em outro servidor (veja a seção sobre gMSA), libere entre os dois servidores a porta TCP da instância e, quando a instância é nomeada e configurada sem porta, também a porta UDP 1434 do SQL Server Browser. Esse tráfego fica dentro da rede da empresa e nunca vai para a nuvem.

Libere a saída pelos nomes, nunca por endereço IP, para estes dois destinos, ambos em TCP 443:

• cadastro.ingestao.autocontroller.ai — cadastro do agente (TLS 1.3, sem certificado de cliente).
• agente.ingestao.autocontroller.ai — envio dos dados, heartbeat e renovação do certificado, sob TLS mútuo.

Proxy e inspeção TLS

Isente os dois nomes da inspeção TLS. O agente confia apenas na âncora de confiança compilada nele, nunca no repositório de certificados do Windows: um proxy ou firewall que intercepta o TLS apresenta o próprio certificado, e o agente o recusa. O diagnóstico, com o comando abaixo, reporta esse caso como inspecao_tls.

Se a saída passa por um proxy, ele é configurado explicitamente no agente, no formato http://host:porta, sem usuário nem senha. O agente nunca lê o proxy das configurações do sistema: nem de variáveis de ambiente, nem de WinINet, WinHTTP, PAC ou WPAD.

Só proxy HTTP é suportado (HTTPS e SOCKS não são), e ele precisa admitir um CONNECT sem autenticação deste servidor para os dois nomes, na porta 443. Se o proxy da empresa exige autenticação (resposta 407, NTLM ou Kerberos), crie uma regra que dispense este servidor da autenticação para esses dois destinos.

agente diagnostico

roda as verificações da instalação, entre elas a da saída para o AutoController.

Permissões no banco: o script de GRANT do manifesto

O login do agente recebe SELECT somente nas tabelas e colunas que as consultas do catálogo leem — nunca db_datareader, nunca escrita.

Essas tabelas e colunas estão publicadas no manifesto de cada ERP, que o seu DBA aplica e audita. O kit de instalação que o AutoController entrega traz o script de GRANT gerado para a sua versão e para a conta do serviço; esta página não o reproduz.

No servidor, os comandos abaixo mostram de onde vem esse script, e o diagnóstico confere que o login tem SELECT em cada coluna do manifesto e que não tem nenhum papel amplo no banco (como db_datareader ou db_owner) nem permissão de leitura, escrita ou alteração sobre o banco inteiro. Ele não inventaria concessões em outras tabelas ou colunas: auditar uma concessão a mais continua com o seu DBA.

agente manifesto

lista cada consulta, tabela e coluna que o agente lê.

agente manifesto --sql <login>

imprime, para o login informado, o mesmo script de GRANT que o kit traz.

agente diagnostico

confere, entre outras verificações, que o login tem SELECT em cada coluna do manifesto e nenhum papel amplo no banco nem permissão de leitura, escrita ou alteração sobre o banco inteiro; concessões em outras tabelas ou colunas ficam com a auditoria do seu DBA.

Conta do serviço e gMSA

Quando o agente roda no próprio servidor do banco (o padrão), o serviço usa a conta virtual NT SERVICE\AutoControllerAgente, criada e gerenciada pelo Windows, e nenhuma gMSA é necessária. O kit de instalação que o AutoController entrega traz, gerados para a sua versão e para essa conta, as permissões da pasta de instalação, a instalação do serviço e o script de GRANT; esta página não os reproduz.

Quando roda em outro servidor, o serviço usa uma conta de serviço gerenciada de grupo (gMSA). Este guia cobre só o lado do Active Directory, e em nenhuma etapa uma senha é criada ou manuseada:

• o administrador do domínio cria a gMSA com PrincipalsAllowedToRetrieveManagedPassword apontando para o servidor do agente, ou para um grupo que o contenha;
• no servidor do agente, a TI instala a conta e confirma que o teste retorna True, com os cmdlets abaixo;
• a equipe do AutoController escolhe a opção de conta gMSA ao gerar o kit, que passa a trazer a instalação do serviço e o login SQL FROM WINDOWS para essa conta.

Install-ADServiceAccount

instala a gMSA no servidor do agente.

Test-ADServiceAccount

precisa retornar True antes de seguir.

Integridade: hash, assinatura e Raiz G1

v0 (hoje): o binário não tem assinatura de código. A equipe do AutoController entrega à TI o arquivo junto com a versão e o SHA-256 dele. Antes de executá-lo, a TI calcula o SHA-256 do arquivo com o primeiro cmdlet abaixo e compara com o SHA-256 entregue pela equipe do AutoController. Quando o kit de instalação estiver disponível, é ele que imprimirá esse SHA-256 para a sua versão. A comparação não diferencia maiúsculas de minúsculas: o cmdlet imprime o hash em maiúsculas, e o valor de referência pode vir em minúsculas. Se os valores divergirem, não execute nada e avise o AutoController.

A partir da primeira versão distribuída pelo canal, o .exe levará assinatura Authenticode de uma autoridade certificadora própria do AutoController, em três níveis: a Raiz G1 assina a Emissora G1, e a Emissora G1 emite o certificado do signatário. As chaves das duas ficarão no AWS KMS, numa conta da AWS dedicada a elas, e só assinarão com o fator MFA do operador do AutoController; a chave do signatário será RSA não-exportável no AWS KMS, sempre com o mesmo nome de signatário entre renovações, para que uma regra de publicador do App Control do Windows sobreviva à reemissão anual do certificado. O supervisor do agente verificará os metadados do canal, o hash e a assinatura antes de cada atualização.

Para que essa assinatura seja aceita, a TI instalará uma única vez a Raiz G1, e só ela, no repositório de raízes confiáveis da máquina, LocalMachine\Root, e só no servidor do agente: nunca em outro servidor, nunca por GPO de domínio, e nada em LocalMachine\CA nem em TrustedPublisher — a Emissora G1 viaja dentro da assinatura. A ordem será: primeiro a Raiz G1 em LocalMachine\Root, com o segundo comando abaixo; depois o terceiro comando abaixo confere a instalação, antes de o serviço ser instalado; só então o quarto comando abaixo reportará Valid. A instalação no repositório do usuário (CurrentUser\Root) não conta: o administrador veria Valid na própria sessão, mas o serviço roda como NT SERVICE\AutoControllerAgente, que não enxerga esse repositório, e o agente não partiria. A impressão digital da Raiz G1, para a TI conferir o arquivo que receber, será publicada com a primeira versão distribuída pelo canal.

• O que essa confiança permitirá: neste servidor, o Windows aceitará todo certificado de assinatura de código que a Emissora G1 emitir, e não só o do agente. As regras de publicador do AppLocker casam pelo nome do signatário, então um certificado da Emissora G1 com o nome de outro publicador passaria nas regras desse publicador neste servidor; é a custódia da chave da Emissora G1, descrita acima, que limita esse alcance.
• O que ela não permitirá: a Raiz G1 e a Emissora G1 trazem dentro de si o uso restrito à assinatura de código (EKU codeSigning), que o CryptoAPI do Windows aplica a toda a cadeia abaixo delas; um certificado emitido sob a Raiz G1 será recusado para TLS, para autenticação de cliente e para qualquer outro propósito. A exceção é um software com tratamento próprio de confiança que leia o repositório do Windows, como o Java configurado com Windows-ROOT, que ignora essa restrição — por isso a Raiz G1 vai só no servidor do agente.
• Como retirá-la: apagar a Raiz G1 de LocalMachine\Root desfará a instalação, e o agente deixará de partir. Para recusar a confiança mesmo que a raiz continue no repositório ou volte a ele, a TI colocará o certificado em LocalMachine\Disallowed com o último comando abaixo. Isso valerá para a Raiz G1, para a Emissora G1 ou para o certificado do signatário, funcionará sem rede e será a resposta a um comprometimento: nenhum dos três níveis tem lista de revogação nem OCSP, e a substituição virá numa nova emissão de certificados do AutoController.

Get-FileHash -Algorithm SHA256

calcula o SHA-256 do arquivo (v0, hoje).

Import-Certificate -CertStoreLocation Cert:\LocalMachine\Root

instalará a Raiz G1 no repositório da máquina, no console elevado do servidor do agente, com -FilePath apontando para o arquivo da Raiz G1 (a partir da primeira versão distribuída pelo canal).

agente instalar requisitos

conferirá, antes de o serviço ser instalado, que a Raiz G1 está em LocalMachine\Root, que nenhum certificado da cadeia está em Disallowed e que a raiz vale para assinatura de código; se algo faltar, recusará nomeando o motivo e a correção (a partir da primeira versão distribuída pelo canal).

Get-AuthenticodeSignature

reportará Valid depois que a Raiz G1 estiver em LocalMachine\Root; antes disso, reportará UnknownError, porque a cadeia termina numa raiz em que o Windows ainda não confia (a partir da primeira versão distribuída pelo canal).

Import-Certificate -CertStoreLocation Cert:\LocalMachine\Disallowed

colocará um certificado da cadeia em Disallowed, no console elevado, com -FilePath apontando para ele: o Windows passará a recusá-lo na hora, sem rede, mesmo com a Raiz G1 ainda em LocalMachine\Root (a partir da primeira versão distribuída pelo canal).

Política de atualização

v0 (hoje): a v0 não se atualiza sozinha; ela é atualizada à mão. A troca da v0 pela primeira versão distribuída pelo canal é a única reinstalação admitida.

A partir da primeira versão distribuída pelo canal, as atualizações seguirão estas regras:

• Anéis: cada versão nova passará primeiro por um tenant interno de teste, depois pelos conectores em homologação (a onda 0), por um cliente canário, pelos clientes que optarem por receber antes e, por fim, por todos. A promoção de um anel ao seguinte exigirá um período sem sinal ruim.
• Janela de manutenção: cada cliente declarará dia, hora e fuso da sua janela, e uma atualização interrompida retomará na janela seguinte. Uma correção de segurança poderá furar a janela.
• Classes de mudança: a classe de cada release será deduzida dela, nunca declarada à mão. Manifestos idênticos serão mudança padrão, pré-autorizada e distribuída automaticamente na janela, depois da onda 0; uma mudança de manifesto será mudança normal, que passa por CAB e DBA e nunca é distribuída automaticamente; uma correção de segurança será mudança emergencial.
• Reversão automática: o supervisor do agente trocará a versão depois do lote em andamento e só a confirmará se, dentro da janela de carência, o processo seguir vivo, o heartbeat for aceito e as verificações do diagnóstico passarem; senão, voltará sozinho à versão anterior.

Política de suporte

As regras abaixo valem a partir da primeira versão distribuída pelo canal: as janelas de suporte contam dessa versão, e a v0 piloto é substituída uma única vez por ela.

As releases minor são aproximadamente mensais. Têm suporte as duas minors anteriores ou seis meses, o que for menor; o caminho de atualização é garantido a partir da major anterior.

Deprecação e sunset têm data publicada; o pin de um tenant vale no máximo até o fim da janela de suporte da versão fixada. O pin é a versão que o cliente pede para manter fixa no seu ambiente.

Sistemas operacionais suportados: Windows Server 2016 a 2025 (2016, 2019, 2022 e 2025).

Residência dos dados

O gateway que recebe as conexões do agente roda na AWS, na região sa-east-1 (São Paulo), e o banco central do AutoController fica na mesma região, assim como os seus backups. O que o agente envia é armazenado no Brasil.

Remoção

O que fica no servidor: a remoção do serviço mantém as chaves do agente no perfil do serviço e o direito de logon como serviço concedido na instalação, e apagar as pastas não remove nenhum dos dois. O que encerra a identidade do agente é a revogação no console: com o certificado revogado, a chave que ficou no servidor não serve para nada.

Se a TI aplicou a etapa opcional certificado-sql, fica também o que ela gravou, e só isso: um certificado autoassinado em LocalMachine\My; o contêiner da chave dele no Microsoft RSA SChannel Cryptographic Provider, com uma única entrada de leitura para o SID de serviço da instância; e o valor SuperSocketNetLib\Certificate da instância, apontando para esse certificado. É a única escrita do agente na configuração do SQL Server, feita pela TI no console elevado, nunca pelo serviço do agente nem a pedido da nuvem. Esse certificado é da instância, não do agente: nem a remoção do serviço nem a revogação no console o tocam, e a etapa não o renova.

Para remover o agente:

• no servidor, a TI para e desregistra o serviço com o primeiro comando abaixo;
• se a TI aplicou a etapa certificado-sql, ela usa o segundo comando abaixo para reverter a etapa antes de apagar %ProgramFiles%\AutoController, porque é o agente.exe dessa pasta que a desfaz. Enquanto o SQL Server usa o certificado da etapa, a reversão não termina numa execução só: ela diz para executá-la de novo depois do próximo reinício da instância, na janela do DBA, ou com a instância parada; a pasta fica até uma execução terminar ok e sem nenhuma linha sobras;
• opcionalmente, se não for reinstalar, apague as pastas %ProgramData%\AutoController e %ProgramFiles%\AutoController;
• no SQL Server, o DBA remove o usuário do banco e o login (DROP USER e DROP LOGIN), o que remove junto as permissões concedidas;
• peça ao AutoController para revogar o agente no console.

agente servico remover

para o serviço, desregistra-o e remove a origem dele no log de eventos do Windows.

agente instalar certificado-sql --reverter

reverte a etapa certificado-sql, no console elevado, desfazendo só o que ela criou: limpa o valor Certificate quando ele aponta para o certificado da etapa, retira a leitura da chave e apaga o certificado e o contêiner da chave — estes dois só quando a instância não usa mais o certificado da etapa, ou está parada. Nunca para, parte nem reinicia o SQL Server. Num servidor com mais de uma instância, ele recusa sem mudar nada e lista as instâncias: execute-o informando cada instância em que a etapa foi aplicada; numa instância em que ela não foi aplicada, ele termina sem mudar nada.

Divulgação de vulnerabilidades

Reporte vulnerabilidades de forma privada para security@autocontroller.ai, nunca em issue pública, com a descrição, o impacto, os passos para reproduzir e a versão afetada.

Resposta inicial em até 48 horas úteis. Plano de correção em até 5 dias úteis após a confirmação.

Depois da correção, a divulgação é coordenada, por um aviso de segurança e por comunicado direto aos clientes afetados quando houver impacto. Pesquisadores que reportarem de boa-fé são creditados, se desejarem.