Manual de Integração
AGX Shield

O que o AGX Shield é (e o que NÃO é)

O AGX Shield é uma plataforma de vigilância de endpoints: um servidor central (painel web) e agentes leves instalados nas máquinas. O princípio é simples e está em tudo que ele faz:

Isso é uma escolha de projeto deliberada. Um produto que bloqueia sozinho pode parar a operação por engano. O AGX expõe o comportamento suspeito com contexto (qual processo, qual caminho, qual assinatura, qual pai) e deixa a decisão com quem entende o ambiente.

O que ele NÃO faz

• Não bloqueia nem encerra processos automaticamente.
• Não apaga arquivos do usuário.
• Não substitui o antivírus — complementa (recomendamos manter o Defender ativo).
• Não envia dados para fora da sua rede (o servidor é seu).

Requisitos de Ambiente

Instalação

3.1 — Subir o servidor

No host Linux, dentro da pasta do projeto:

cd ~/agxshield
docker compose up -d

No primeiro acesso ao painel, um assistente de configuração (Setup Wizard) pede: nome da empresa, usuário/senha de admin, URL do painel e configura o 2FA (escaneie o QR Code no Google Authenticator). Ao final, ele gera a API Key usada pelos agentes.

3.2 — Instalar o agente (Windows)

Na máquina cliente, em PowerShell como administrador:

powershell -ExecutionPolicy Bypass -File "C:\AGXShield\Instaladores\instalar_agx.ps1" -ServidorUrl "http://SEU_SERVIDOR:8080"

O instalador registra o agente, salva a configuração em config.json e inicia a vigilância. Se ele não encontrar o servidor, avisa e pergunta se você quer prosseguir em modo limitado — nunca instala "quebrado em silêncio".

3.3 — Desinstalar o agente

powershell -ExecutionPolicy Bypass -File "C:\AGXShield\Instaladores\desinstalar_agx.ps1"

A desinstalação pede o código 2FA como proteção contra remoção acidental ou maliciosa. Se a instalação ficou sem o segredo 2FA (raro), entra em modo de emergência: digite REMOVER para confirmar.

Arquitetura

Três camadas conversam entre si. Entender isso ajuda a TI a saber onde cada dado vive — e por que a limpeza funciona do jeito que funciona.

Onde cada dado é guardado

Os dados ficam em armazéns diferentes — saber disso é o que evita a confusão de "limpei mas continua aparecendo":

• RAM do servidor — alertas recentes em memória (rápido, volátil).
• Arquivos JSON diários — log permanente por data (threats_AAAA-MM-DD.json).
• SQLite vigilancia.db — histórico de URLs, conexões, processos e alertas de vigilância. É a fonte da verdade, sobrevive a reinício.

Pilares de Detecção

Cada pilar observa um vetor de ataque diferente. A lógica comum: julgar pelo comportamento e contexto, não pelo nome do arquivo — porque malware se disfarça com nomes legítimos.

Correlação de sinais — onde mora a inteligência

Nenhum sinal isolado acusa um vazamento. O valor está no cruzamento. A regra central combina três perguntas: saiu dado? (volume), de qual processo e de onde ele roda? (caminho do executável) e havia humano? (Pilar 8).

• Volume + presença humana — o mesmo upload de centenas de MB é classificado como provável ação legítima (havia humano operando) ou como suspeito/crítico (máquina ociosa). O AGX mede volume, nunca conteúdo.
• Confiança pelo local, não pelo nome — um processo é avaliado por onde seu executável foi carregado (Program Files/System32 = de casa; Temp/Downloads = suspeito). Nome é fácil de falsificar; o caminho real de carga, não.
• Identidade por MAC — a máquina é reconhecida pela assinatura da placa de rede (MAC) e pelo IP real da conexão, não pelo IP que ela declara. Mesmo que o endpoint troque de rede (DHCP, VPN), o AGX sabe que é a mesma máquina.
• Scanner multi-rede — a descoberta de dispositivos usa a visão de todos os agentes, cada um na sua zona, enxergando redes que o servidor sozinho não alcançaria, e marcando máquinas sem agente (os pontos cegos).

Princípio unificador: em cada camada, o AGX confia no atributo que o atacante não consegue forjar — o local de carga (não o nome), o MAC (não o IP), a origem real da conexão (não o que o agente declara), o gesto humano (não a assinatura do binário).

Postura: testemunha, não justiceiro

O AGX observa e reporta — não contra-ataca nem bloqueia automaticamente. É uma decisão de segurança, não de cautela: um agente que reage sozinho vira uma arma que pode ser virada contra ele (um invasor descobre o gatilho e o usa para desligar a proteção). Permanecendo passivo, o AGX tem superfície de ataque mínima. A evidência é registrada no servidor em tempo real, de modo que sobrevive mesmo que o programa malicioso tente se autodestruir na máquina de origem. Quem investiga e age, com contexto e responsabilidade, é a equipe de TI. A tecnologia organiza; o profissional interpreta.

Pilares de apoio

• Heartbeat (MONITOR_HEARTBEAT) — alerta quando um agente para de reportar (possível desligamento ou comprometimento).
• Webcam, Upload suspeito, Software perigoso, Cryptojacking — camadas adicionais de vigilância.
• Scanner de rede — descobre dispositivos na LAN sem instalar nada (equivalente offline ao Advanced IP Scanner).

Roteiro de Testes

Aqui está o diferencial: você não precisa acreditar que funciona — você verifica. Faça cada teste e confira se o alerta esperado aparece no painel, na aba Alertas.

copy C:\Windows\System32\cmd.exe "$env:USERPROFILE\Downloads\conhost.exe"
& "$env:USERPROFILE\Downloads\conhost.exe"

New-Item -Path "C:\Windows\System32\drivers\teste_agx.sys" -ItemType File

\\IP_DA_MAQUINA_VIGIADA\C$

Manutenção & Logs

Exportar antes de limpar

Em qualquer tela (Alertas, Vigilância, Relatório) use Exportar para baixar o JSON. Esse é o registro que a TI deve guardar. Os exports também podem ser reabertos offline na tela Importar Log.

Backup do banco

docker cp agxshield-server:/agxshield/vigilancia.db ./backup_vigilancia_$(date +%Y%m%d_%H%M).db

Zerar a vigilância (começar do zero)

docker exec agxshield-server python3 -c "import sys; sys.path.insert(0,'/agxshield'); from modules.vigilancia_db import limpar_tudo, definir_corte; limpar_tudo(); definir_corte('*')"
docker restart agxshield-server

Verificar que a limpeza funcionou

docker exec agxshield-server python3 -c "
import sqlite3
c = sqlite3.connect('/agxshield/vigilancia.db')
for t in ['urls','conexoes','alertas','processos']:
    print(t, c.execute(f'SELECT COUNT(*) FROM {t}').fetchone()[0])
"

Troubleshooting

Privacidade & Conformidade

O AGX Shield é uma ferramenta corporativa de segurança. Transparência aqui é parte do produto — tanto com a empresa quanto com o funcionário.

O que é monitorado

• Processos em execução, conexões de rede, dispositivos USB, sessões SMB.
• URLs acessadas nos navegadores (histórico das últimas 24h).
• Integridade de arquivos em áreas sensíveis do sistema.

Princípios de privacidade

• Dados ficam na sua rede. O servidor é da empresa; nada é enviado para terceiros.
• PC da empresa é da empresa. O monitoramento se aplica a equipamentos corporativos, com política clara comunicada à equipe.
• Sem ação destrutiva. O AGX observa e reporta; não altera nem remove dados do funcionário.
• A marca de corte permite recomeçar a vigilância sem tocar no navegador da pessoa — respeito mútuo.