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
- É uma ferramenta para o único dispositivo em que corre. Não há função para ver vários dispositivos em conjunto.
- Nunca eleva os seus privilégios. Um registo que só o root consegue ler é mostrado como «ilegível» e o sudo não é usado.
- «Sem deteções» não é prova de segurança. O risco global também é apenas uma estimativa de 0 a 100, não uma probabilidade.
- Lê apenas um conjunto fixo de fontes. Não é possível indicar no ecrã ficheiros nem comandos a ler.
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.
| Ambiente | Instalação e abertura |
|---|---|
| Mac | O 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 Edition | Inclui 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). |
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
- Abra a aplicação e prima «Definições» no canto superior direito.
- Por baixo aparecem as fontes lidas neste sistema operativo. Desmarque as que não quer que sejam lidas.
- Prima «Guardar» e depois «← Voltar» para regressar ao ecrã inicial.
- 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.
| Ambiente | O que é lido |
|---|---|
| Mac | O 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. |
| Linux | O 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). |
| Ambos | Se 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ídas | O 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
| Separador | O que se vê |
|---|---|
| Painel | Grá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ório | Um 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. |
| Achados | Pode 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. |
| Fontes | A 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. |
| IOC | A 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 LLM | Este 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». |
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
- Marque «Ativar a integração com LLM».
- Escolha o «LLM a utilizar». Um indicado como «(não instalado)» não tem o comando neste dispositivo.
- Se necessário, altere o modelo e o tempo limite (segundos). Se deixar o modelo vazio, é usado o predefinido desse LLM.
- 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
- O que é entregue é o conteúdo da deteção, as linhas de registo que servem de prova, os valores devolvidos pelo MCP e as notas da origem de recolha. Quando o LLM o pede, são também entregues o registo de execução do processo e a zona em redor da linha correspondente de um ficheiro de configuração (até 200 carateres). Também são incorporados os pontos de bloqueio do PathScope (no máximo 3, até 80 carateres), os tipos e o número de deteções do AccessScope e o resumo de ameaças do Sensor (até 200 carateres). Em todos os casos, os segredos são ocultados e o comprimento é limitado. Não são entregues os próprios ficheiros, a shell, as linhas de prova e as descrições do AccessScope nem o detail do Sensor.
- Antes de os entregar, os segredos como chaves, tokens e palavras-passe são mascarados e os carateres invisíveis são removidos.
- O PersonalSOC não dá ao LLM nem uma shell nem ficheiros. O LLM limita-se a pedir o que quer investigar, e o PersonalSOC executa as ferramentas só de leitura que permite e devolve os resultados. Há no máximo 6 rondas de investigação.
- A saída do LLM não é considerada fiável e no relatório é tratada como uma citação. Um LLM pode ler uma deteção como mais grave do que é, por isso confirme sempre a conclusão nas «Constatações».
- Os endereços IP, domínios, números CVE, hashes, PIDs e nomes de processo que o LLM escreve são comparados com o que ele recebeu (texto dos registos, resumo da análise, resultados das ferramentas). Um valor que não aparece nesse material consta no relatório em «Valores que não constam do material recolhido», como possível invenção. Só se comparam cadeias de texto; o LLM não é consultado. No fim do relatório, os resultados da investigação são anexados tal como foram entregues ao LLM.
Sobre a restrição de ferramentas
- Na coluna «Estado» da tabela nas Definições,
opencodeeclaudemostram «Ferramentas bloqueadas». O claude é iniciado com as ferramentas integradas, os servidores MCP e as skills desativados e sem carregar as suas próprias definições. O opencode é iniciado com todas as permissões negadas. codexeagynão se conseguem desativar deste modo, por isso mostram «Ferramentas não bloqueáveis».
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
| Comando | O que faz |
|---|---|
personalsoc scan | Verifica 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 --report | Mostra 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 --notify | Notifica 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-last | Mostra 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. |
--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
| Item | Localizaçã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ódica | No 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
| Sintoma | Causa 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ódica | Se 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. |