Deploy do Agente

PatchPilotAgent.exe é um binário Windows autossuficiente (sem necessidade de Python). Implante-o como um Windows Service em cada máquina que deseja gerenciar.

Antes de começar

Registre as exclusões de AV se usar Bitdefender GravityZone ou Windows Defender:

Registrar exclusões de AV (execute como Administrador)

deploy\register_av_exclusion.ps1

Consulte Coexistência com GravityZone para detalhes.

config.ini

Todos os métodos de deploy compartilham o mesmo config.ini. Substitua os valores destacados:

config.ini

[server]
SERVER_URL=https://your-patchone-server
API_KEY=<your-api-key>
TENANT_ID=default
HEARTBEAT_INTERVAL=300

[agent]
LOG_LEVEL=INFO

Configuração	Descrição	Padrão
SERVER_URL	URL base do servidor PatchOne	obrigatório
TENANT_ID	Identificador do tenant (default para on-prem)	default
API_KEY	Segredo compartilhado para autenticação do agente	obrigatório
HEARTBEAT_INTERVAL	Segundos entre check-ins	300
LOG_LEVEL	DEBUG, INFO, WARNING, ERROR	INFO

Fluxo de deploy

---

Método 1 — PowerShell One-Liner (recomendado)

Ideal para instalações individuais, scripts de automação e ferramentas RMM. Execute em um PowerShell como Administrador.

Com a URL do servidor pré-configurada (a máquina já inicia realizando check-ins):

Execute como Administrador

& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/patchone-org/app/main/deploy/windows/install.ps1'))) -ServerUrl https://your-patchone-server

Sem configuração inicial (configure o config.ini depois):

Execute como Administrador

irm https://raw.githubusercontent.com/patchone-org/app/main/deploy/windows/install.ps1 | iex

Verifique o resultado:

Get-Service PatchOneAgent
PatchPilotAgent.exe --version

Privilégios de administrador

O script verifica se está sendo executado como Administrador antes de fazer qualquer alteração. Se executado sem privilégios suficientes, ele exibe uma mensagem de erro e encerra sem realizar modificações.

Upgrade via script

Para atualizar para a versão mais recente, re-execute o mesmo comando. O script detecta a instalação existente, preserva a configuração atual e substitui apenas o binário:

Execute como Administrador

& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/patchone-org/app/main/deploy/windows/install.ps1'))) -ServerUrl https://your-patchone-server

---

Método 2 — Windows Package Manager (winget)

Para ambientes que gerenciam pacotes com o Windows Package Manager:

Instalar

winget install PatchOne.PatchPilotAgent

Após a instalação via winget, o agente inicia em estado não configurado — o serviço sobe, mas aguarda a URL do servidor antes de realizar check-ins.

Opção A — Editar config.ini diretamente:

%PROGRAMFILES%\PatchOne\config.ini

Defina SERVER_URL e API_KEY, depois reinicie o serviço:

Restart-Service PatchOneAgent

Opção B — Executar o binário com a flag de servidor (não reregistra o serviço):

Execute como Administrador

& "C:\Program Files\PatchOne\PatchPilotAgent.exe" --install --server-url https://your-patchone-server

Este comando é idempotente — pode ser repetido para atualizar a URL sem recriar o serviço.

Upgrade via winget

winget upgrade PatchOne.PatchPilotAgent

A configuração existente (SERVER_URL, API_KEY) é preservada durante o upgrade.

---

Método 3 — Script de Inicialização via GPO (recomendado para domínio)

Ideal para ambientes com domínio.

Configuração

1. Copie os arquivos para um compartilhamento de rede:

   \\server\sysvol\PatchOne\
     PatchPilotAgent.exe
     config.ini

2. No Gerenciamento de Política de Grupo, crie um novo GPO.

3. Navegue até: Configuração do Computador → Configurações do Windows → Scripts → Inicialização

4. Adicione um novo script de inicialização:

   • Script: \\server\sysvol\PatchOne\PatchPilotAgent.exe
   • Parâmetros: --install

5. Vincule o GPO à Unidade Organizacional (OU) de destino.

6. Force uma atualização de Política de Grupo ou aguarde a próxima reinicialização.

As máquinas instalam o agente na próxima reinicialização e aparecem no dashboard em seguida.

Verificar

Verificar status do serviço em uma máquina de destino

sc query PatchOneAgent

Saída esperada inclui STATE: 4 RUNNING.

---

Método 4 — WinRM / PowerShell Remoto

Use quando tiver acesso WinRM, mas sem GPO de domínio.

Deploy em massa via WinRM

$hosts = Get-Content hosts.txt
foreach ($h in $hosts) {
    $session = New-PSSession -ComputerName $h
    Copy-Item PatchPilotAgent.exe -Destination "C:\Program Files\PatchOne\" -ToSession $session
    Copy-Item config.ini          -Destination "C:\Program Files\PatchOne\" -ToSession $session
    Invoke-Command -Session $session -ScriptBlock {
        & "C:\Program Files\PatchOne\PatchPilotAgent.exe" --install
        Start-Service PatchOneAgent
    }
    Remove-PSSession $session
}

hosts.txt — um hostname ou IP por linha.

---

Método 5 — Script de deploy em massa (PsExec)

O script deploy_agents.py usa PsExec para deploy em larga escala.

Deploy por lista de hosts

python deploy\deploy_agents.py ^
  --hosts hosts.txt ^
  --server-url https://your-patchone-server ^
  --api-key <key>

Deploy por faixa CIDR

python deploy\deploy_agents.py ^
  --cidr 192.168.1.0/24 ^
  --server-url https://your-patchone-server ^
  --api-key <key>

Falsos positivos de AV com PsExec

O binário do agente pode acionar falsos positivos de AV quando implantado via PsExec. Registre as exclusões de AV primeiro ou prefira o método GPO.

---

Método 6 — Instalação manual

Para uma única máquina ou testes:

Instalação manual (execute como Administrador)

xcopy /Y PatchPilotAgent.exe "C:\Program Files\PatchOne\"
xcopy /Y config.ini          "C:\Program Files\PatchOne\"

"C:\Program Files\PatchOne\PatchPilotAgent.exe" --install
sc start PatchOneAgent

---

Gerenciamento do serviço do agente

Ação	Comando
Iniciar	sc start PatchOneAgent
Parar	sc stop PatchOneAgent
Reiniciar	sc stop PatchOneAgent && sc start PatchOneAgent
Desinstalar	PatchPilotAgent.exe --uninstall
Status	sc query PatchOneAgent
Verificar versão	PatchPilotAgent.exe --version

Arquivo de log do agente

Os logs são gravados em C:\Program Files\PatchOne\agent.log. O nível de log é controlado por LOG_LEVEL no config.ini.

Atualização automática do agente

Quando o servidor publica uma nova versão, o agente se atualiza automaticamente. Consulte Atualização Automática do Agente para detalhes.