PERSONALSOC · Última atualização: 2026-10-28

Manual de utilização do PersonalSOC

Este manual explica como usar a aplicação que reúne, só de leitura e com um botão, os registos e o estado das defesas deste dispositivo num relatório que se percebe de relance. Primeiro explicam-se as operações no ecrã, e a linha de comandos fica reunida num capítulo mais à frente.

1. O que é o PersonalSOC

O PersonalSOC é uma aplicação que reúne os registos e o estado das defesas deste dispositivo e os resume em constatações e num relatório. Foi pensada para que uma pessoa sem pessoal de segurança dedicado veja, com provas, o que se passa no seu dispositivo e decida o que fazer a seguir.

É só de leitura, por isso não altera definições, não apaga ficheiros nem bloqueia comunicações. A análise dos registos é feita por analisadores de procedimento fixo que não usam nem um LLM nem a rede. A integração com LLM é opcional e está desativada no início.

O que não faz

2. Instalação e arranque

O PersonalSOC é uma aplicação separada do RoamSwitch, incluída na distribuição do RoamSwitch. Tem um ícone próprio, não tem entrada no menu do RoamSwitch e abre-se isoladamente como aplicação.

AmbienteInstalação e abertura
MacO DMG do RoamSwitch contém o PersonalSOC.app. Mova-o para a pasta «Aplicações» e abra «PersonalSOC». É suportado o macOS 12 ou posterior.
Linux (edição cliente)Está incluída nos pacotes deb, rpm, tarball e Arch do RoamSwitch. Abra «PersonalSOC» a partir da lista de aplicações, ou execute personalsoc-app num terminal. A janela precisa do WebKitGTK 4.1, que o deb e o rpm instalam automaticamente. No Arch (Arch), instale webkit2gtk-4.1 como dependência opcional.
Linux Server EditionInclui apenas o comando. Execute personalsoc num terminal (a aplicação com janela personalsoc-app não está incluída). Para a operação da edição de servidor, consulte o Manual de operação (Linux Server).
Também funciona sem o RoamSwitch
O PersonalSOC também pode ser usado isoladamente. Num dispositivo com o RoamSwitch instalado, importa ainda do MCP do RoamSwitch (só são usadas ferramentas de leitura) as deteções por resolver e os resultados do diagnóstico de configuração, e reúne-os com as constatações dos registos num único relatório. Se o RoamSwitch não estiver instalado, essa origem de recolha não é usada.

3. A primeira verificação do estado

Só lê as fontes fixas quando carrega em «Verificar estado». As fontes que não quer que leia podem ser desativadas nas definições.

Passos

  1. Abra a aplicação e prima «Definições» no canto superior direito.
  2. Por baixo aparecem as fontes lidas neste sistema operativo. Desmarque as que não quer que sejam lidas.
  3. Prima «Guardar» e depois «← Voltar» para regressar ao ecrã inicial.
  4. Prima «Verificar estado». Aparece uma barra de progresso e, no fim, os separadores de resultados.

No fim aparecem as contagens, por exemplo «Verificação concluída. 3 deteção(ões) / 2 IOC». O capítulo seguinte explica os separadores.

AmbienteO que é lido
MacO registo unificado do macOS (sudo e sshd das últimas 24 horas) e as definições de MCP (Claude Code, Claude Desktop, opencode, Cursor, Windsurf, Gemini CLI, VS Code, Cline, Roo Code), assim como as definições do Claude Code (~/.claude/settings.json e outras). Lê também os registos de acesso de servidores web (o Apache incluído no macOS e o nginx e o httpd do Homebrew). Ler o registo do que o Gatekeeper recusou demora cerca de 10 segundos, por isso está desativado no início.
LinuxO registo de autenticação (sshd), o auditd, os registos de acesso web (nginx / apache, incluindo os registos separados por anfitrião virtual), os registos de consultas DNS (dnsmasq / named), as definições de MCP (Claude Code, Claude Desktop, opencode, Cursor, Windsurf, Gemini CLI, VS Code, Cline, Roo Code) e as definições do Claude Code (~/.claude/settings.json e outras).
AmbosSe o RoamSwitch estiver instalado, também o seu MCP (só com ferramentas que apenas leem). Pode desativá-lo com a caixa «Obter o histórico de deteções e o diagnóstico de configuração do MCP do RoamSwitch (só de leitura)».
Ferramentas incluídasO resumo dos diagnósticos do AccessScope e do PathScope (se estiverem instalados) e as ameaças da camada LAN encontradas pelo RoamSwitch Sensor, que corre neste dispositivo. O PersonalSOC executa comandos fixos com argumentos fixos e lê apenas o resumo. Os argumentos não podem ser alterados. Cada uma destas fontes pode ser desativada na lista de fontes acima. Quando uma falta, a nota dessa fonte indica-o.

4. Como ler os resultados

SeparadorO que se vê
PainelGráficos mostram o indicador do risco global (estimativa), as contagens por gravidade, as ocorrências por categoria, a evolução ao longo do tempo e as contagens MITRE ATT&CK. Quando há material para isso, as caixas de resumo mostram também a cobertura das defesas do RoamSwitch (a parte que funciona agora e os pontos cegos), os resumos dos diagnósticos das ferramentas incluídas e as alterações desde a última verificação.
RelatórioUm relatório em Markdown que reúne as origens de recolha, as constatações por categoria e os IOC. «Copiar Markdown» copia-o por inteiro e «Mostrar a fonte do Markdown» passa para o texto original.
AchadosPode percorrer as deteções uma a uma, cada uma com gravidade, confiança, número ATT&CK, contagem e os números de linha dos registos que a sustentam.
FontesA lista do que foi verificado. O estado é «Lido», «Não presente», «Ilegível (permissão)», «Falhou» ou «Desativado», e as fontes ilegíveis ou com falha não foram verificadas.
IOCA lista dos IP, domínios, URL e hashes encontrados nos registos. Aparecem em forma neutralizada, como 198[.]51[.]100[.]7, para que nada seja aberto por engano.
Resumo de entrada para um LLMEste separador só aparece quando a integração com LLM está desativada. É um resumo para entregar a um LLM manualmente e não contém linhas de registo em bruto. Use «Copiar».
Sobre o número do risco global
O risco global é uma estimativa de 0 a 100 que soma cada tipo de deteção ponderado por gravidade e confiança. Não é uma probabilidade e não aumenta por mais vezes que a mesma deteção apareça. A confiança tem três níveis: «Confirmado», «Provável» e «Hipótese».

5. Definições e execução periódica

«Definições», no canto superior direito do ecrã inicial, está dividido em separadores por função. Depois de alterar algo, prima «Guardar» e depois «← Voltar» para regressar ao início.

Idioma de apresentação Além de «Automático (seguir o sistema)», pode escolher japonês, inglês, alemão, espanhol, francês, italiano, coreano, português (Portugal), chinês simplificado ou chinês tradicional, cada um mostrado com o seu próprio nome.

Execução periódica (opcional)

Marque «Verificar automaticamente a intervalos regulares» e guarde: no Mac é registado como agente de utilizador do launchd e no Linux como temporizador de utilizador do systemd. O intervalo escolhe-se entre 7 níveis de 15 minutos a 24 horas e no início é de 1 hora.

Só é executado o personalsoc scan --notify, sem usar root. Notifica apenas quando existe uma deteção que não existia da última vez, e a mensagem contém só contagens (no Linux é preciso o notify-send). Também pode desativar a notificação com «Notificar apenas quando existir uma deteção que não existia da última vez».

A execução periódica corre com permissões de utilizador comum, por isso não consegue ler os registos que exigem root (autenticação, servidor web, auditd). Se algum registo não puder ser lido, na primeira vez e quando muda a combinação de registos ilegíveis, notifica «N registos não puderam ser lidos: nome». Quando tudo pôde ser lido, não notifica nada. Para verificar esses registos, execute sudo personalsoc scan.

Com personalsoc schedule status, pode confirmar se a execução periódica está registada, a hora da última execução e os registos que não puderam ser lidos. O ecrã de definições mostra o mesmo conteúdo.

No Linux, sem o notify-send (nos Debian e Ubuntu, o pacote libnotify-bin), as notificações não aparecem.

Os temporizadores de utilizador do systemd não funcionam com a sessão terminada. Num servidor, execute loginctl enable-linger uma vez.

Desmarque a caixa e guarde: o registo é removido.

6. Integração com LLM (opcional)

A integração com LLM é opcional e está desativada no início. Depois de ativada, após a verificação do estado, o comando do LLM escolhido faz uma investigação adicional e redige um relatório como auditor. Os comandos que pode usar são opencode, claude, codex e agy.

Passos

  1. Marque «Ativar a integração com LLM».
  2. Escolha o «LLM a utilizar». Um indicado como «(não instalado)» não tem o comando neste dispositivo.
  3. Se necessário, altere o modelo e o tempo limite (segundos). Se deixar o modelo vazio, é usado o predefinido desse LLM.
  4. Prima «Guardar», volte ao início e prima «Verificar estado». Depois da verificação, a investigação do LLM corre logo a seguir.

O que chega ao LLM

Sobre a restrição de ferramentas

Quando usa um LLM cujas ferramentas não podem ser bloqueadas
Durante a investigação o LLM pode ler ficheiros por iniciativa própria, e o que lê é enviado para o serviço desse LLM. Para o usar, marque a confirmação por baixo de «LLM a utilizar». A confirmação é por LLM e, sem a marca, não se pode guardar nem investigar.
Relação com o Zero Telemetry
O «Zero Telemetry» do RoamSwitch (nenhum conteúdo de comunicações nem registos é enviado para o exterior) descreve o próprio RoamSwitch. As comunicações que ocorrem quando ativa a integração com LLM do PersonalSOC não estão incluídas. O destino e o tratamento seguem os termos do LLM escolhido e do seu fornecedor. Enquanto a integração com LLM ficar desativada, o PersonalSOC não envia o conteúdo dos registos para fora do dispositivo.

7. Usar a linha de comandos

O comando é personalsoc. No Linux fica em /usr/bin/personalsoc e no Mac dentro de PersonalSOC.app/Contents/MacOS/.

No Mac, se a aplicação estiver na pasta Aplicações, o comando está em /Applications/PersonalSOC.app/Contents/MacOS/personalsoc. Para o chamar pelo nome curto, execute o seguinte no Terminal. Depois, basta personalsoc.

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/PersonalSOC.app/Contents/MacOS/personalsoc /usr/local/bin/personalsoc
ComandoO que faz
personalsoc scanVerifica automaticamente os registos deste computador e o RoamSwitch (MCP) e mostra as deteções numa lista. Para os registos que só o root pode ler (autenticação, servidor web, auditd), execute-o com sudo.
personalsoc scan --reportMostra o relatório em Markdown (sem LLM).
personalsoc scan --llm <name>Mostra o relatório que o LLM redigiu como auditor depois de investigar com ferramentas só de leitura. name é opencode, claude, codex, agy, etc.
personalsoc scan --notifyNotifica apenas quando existe uma deteção que não existia da última vez. É a forma chamada pela execução periódica.
personalsoc scan --format <text|markdown|json|sarif>Mostra o resultado em forma legível por máquina. json e sarif (SARIF 2.1.0) escrevem apenas o resultado na saída padrão. markdown mostra um relatório em Markdown. json e sarif não podem ser combinados com --report nem com --llm.
personalsoc scan --fail-on <high|medium|low>Termina com o código 3 se houver uma deteção dessa gravidade ou superior. Com --fail-on-partial, termina com o código 4 quando alguma fonte não pôde ser lida (não haver deteções não é prova de segurança).
personalsoc scan --since-lastMostra a diferença em relação à verificação anterior e guarda esta no histórico. O histórico é escrito apenas na localização própria do PersonalSOC (capítulo 8).
personalsoc scan --diff <file>
personalsoc scan --save-snapshot <file>
--diff compara com a saída de --format json ou com um ficheiro escrito por --save-snapshot (não escreve nada e não pode ser combinado com --since-last). --save-snapshot escreve este resultado num ficheiro JSON (que só o utilizador pode ler e escrever).
personalsoc <type> <file>Analisa um ficheiro indicado. type é sshd, auditd, web, dns, unified, mcp, agent, inject ou ioc. Se indicar - como file, lê a entrada padrão, e também se podem acrescentar --report, --brief e --llm.
--lang <lang>Pode ser acrescentado a qualquer comando e define o idioma de apresentação, com prioridade sobre a definição. Os códigos são ja, en, de, es, fr, it, ko, pt-PT, zh-Hans e zh-Hant.
Os LLM na linha de comandos
Na linha de comandos, executar com --llm é a operação explícita que entrega dados ao LLM, pelo que funciona mesmo com «Ativar a integração com LLM» desligada nas definições. Também não é pedida confirmação para um LLM cujas ferramentas não podem ser restringidas; por isso, ao usar codex ou agy, faça-o só depois de perceber que, durante a investigação, os ficheiros podem ser lidos e enviados.

8. Onde ficam os dados e atualizações

O que é guardado

ItemLocalização
Definições~/.config/personalsoc/settings.json (guardado com permissões que só você pode ler e escrever)
Registo das deteções anteriores (para decidir as notificações)~/.local/state/personalsoc/last.json (apenas hashes que fazem de impressão digital das deteções; não se guarda texto dos registos)
Registo da execução periódicaNo Mac, ~/Library/LaunchAgents/dev.personalsoc.scan.plist (a saída vai para ~/Library/Logs/personalsoc-scan.log). No Linux, personalsoc-scan.timer e personalsoc-scan.service em ~/.config/systemd/user/.
Instantâneos de verificações anteriores (histórico)~/.local/state/personalsoc/history/snapshots.json (só o utilizador a pode ler e escrever. Contém apenas o tipo, o título, o alvo, a gravidade e o número de cada deteção, se cada guarda está ligada ou desligada, os nomes dos servidores MCP, o estado das fontes e o risco global. Sem linhas de registo, provas, conteúdo das definições nem segredos. Até 60 verificações e 400 deteções por verificação, 2 MiB; as mais antigas saem primeiro, e apagar a pasta apaga o histórico. Não é enviado para o exterior)

O PersonalSOC não guarda em ficheiros os relatórios nem os registos recolhidos. Se quiser conservá-los, use «Copiar Markdown» no ecrã ou a saída da linha de comandos. Para acrescentar mais LLM, edite à mão profiles no ficheiro de configuração; não pode ser alterado a partir do ecrã. Só são conservados os registos de verificação (histórico) usados na comparação com a execução anterior, como indicado na tabela seguinte.

Atualizações

No Mac, atualiza-se a partir de «Atualizações» nas Definições. A aplicação só se liga a lafine.net quando prime «Procurar atualizações» e recebe a informação da versão mais recente (um JSON público). Não é enviado nada sobre este dispositivo nem sobre os seus registos. Se existir uma versão mais recente, prima «Transferir e instalar». A assinatura do ficheiro transferido é verificada com a chave pública incorporada na aplicação e, se falhar, não é instalado nada. No fim, a aplicação reinicia.

No Mac, atualizar o próprio RoamSwitch não atualiza o PersonalSOC. No Linux não há função de atualização e o PersonalSOC está incluído nas atualizações dos pacotes do RoamSwitch.

9. Quando algo corre mal

SintomaCausa e solução
Uma fonte mostra «Ilegível (permissão)»Os registos de autenticação, do servidor web e do auditd não podem ser lidos sem direitos de administrador. O PersonalSOC não eleva os seus privilégios; execute-o por isso com sudo. É diferente de «sem deteções»: esse registo não foi verificado.
Não é possível guardar a execução periódicaSe o Mac indicar que a aplicação está a ser executada a partir de uma localização temporária em quarentena, mova o PersonalSOC.app para a pasta Aplicações, abra-o de novo e guarde outra vez. Se indicar que o comando personalsoc não foi encontrado, o personalsoc tem de estar no mesmo local que a própria aplicação.
A investigação com o claude falha com «Not logged in»O PersonalSOC inicia o claude sem carregar as suas próprias definições (como env e apiKeyHelper em ~/.claude/settings.json). As configurações que se autenticam através dessas definições, como um proxy, Bedrock ou Vertex, falham. Se acrescentar à mão "llm_user_settings": ["claude"] ao ficheiro de definições, o claude é iniciado com as suas definições carregadas. As ferramentas e o MCP continuam desativados.
← Página do produto PersonalSOC Ir para o manual para Mac →