PersonalSOC 사용 설명서
이 단말의 로그와 방어 상태를 버튼 하나로 읽기 전용으로 모아 한눈에 알 수 있는 보고서로 만들어 주는 앱의 사용법입니다. 화면 조작을 순서대로 설명하고, 명령줄은 뒤쪽 장에 모아 두었습니다.
1. PersonalSOC란
PersonalSOC는 이 단말의 로그와 방어 상태를 모아 검출 사항과 보고서로 정리하는 앱입니다. 전담 담당자가 없는 개인이 자신의 단말에서 무슨 일이 일어나고 있는지를 근거와 함께 알고 다음에 할 일을 정할 수 있도록 만들어졌습니다.
읽기 전용이므로 설정을 바꾸거나 파일을 지우거나 통신을 차단하지 않습니다. 로그 분석은 LLM도 네트워크도 사용하지 않는 정해진 절차의 분석기가 수행합니다. LLM 연동은 선택 사항이며 처음에는 꺼져 있습니다.
할 수 없는 것
- 실행 중인 단말 1대를 위한 도구입니다. 여러 단말을 한꺼번에 보는 기능은 없습니다.
- 권한을 높이지 않습니다. root가 아니면 읽을 수 없는 로그는 “읽을 수 없음”으로 표시하며 sudo는 사용하지 않습니다.
- “검출 없음”은 안전의 증명이 아닙니다. 종합 위험도 0에서 100까지의 기준값일 뿐 확률이 아닙니다.
- 읽는 대상은 정해진 수집원뿐입니다. 화면에서 읽을 파일이나 명령을 지정할 수는 없습니다.
2. 설치와 실행 방법
PersonalSOC는 RoamSwitch와는 별개의 앱으로, RoamSwitch 배포물에 포함되어 있습니다. 아이콘도 별도이며 RoamSwitch 메뉴에는 진입점이 없고, 앱으로서 단독으로 열립니다.
| 환경 | 설치와 여는 방법 |
|---|---|
| Mac | RoamSwitch의 DMG에 PersonalSOC.app이 들어 있습니다. '응용 프로그램' 폴더로 옮긴 뒤 'PersonalSOC'를 엽니다. macOS 12 이상을 지원합니다. |
| Linux (클라이언트 에디션) | RoamSwitch의 deb, rpm, tarball, Arch 패키지에 동봉되어 있습니다. 앱 목록에서 “PersonalSOC”를 열거나 터미널에서 personalsoc-app을 실행합니다. 화면에는 WebKitGTK 4.1이 필요하며 deb와 rpm에서는 자동으로 설치됩니다. Arch에서는 webkit2gtk-4.1을 선택적 의존성으로 설치하세요. |
| Linux Server Edition | 명령만 포함되어 있습니다. 터미널에서 personalsoc를 실행합니다(화면 앱 personalsoc-app은 포함되지 않습니다). 서버 에디션 운영은 운영 매뉴얼 (Linux Server)을 참조하세요. |
3. 첫 상황 확인
'상태 확인'을 눌렀을 때만 고정된 수집원을 읽습니다. 읽게 하고 싶지 않은 수집원은 설정에서 끌 수 있습니다.
순서
- 앱을 열고 오른쪽 위의 “설정”을 누릅니다.
- 그 아래에 이 OS에서 읽는 수집원이 나열됩니다. 읽게 하고 싶지 않은 것이 있으면 체크를 해제합니다.
- “저장”을 누른 뒤 “← 뒤로”로 홈 화면에 돌아갑니다.
- “상황 확인”을 누릅니다. 진행 상황 막대가 나타나고, 끝나면 결과 탭이 나열됩니다.
끝나면 “확인이 끝났습니다. 탐지 3건 / IOC 2건”처럼 건수가 표시됩니다. 탭 보는 법은 다음 장에서 설명합니다.
| 환경 | 읽는 대상 |
|---|---|
| Mac | macOS 통합 로그(최근 24시간의 sudo와 sshd)와 MCP 설정(Claude Code, Claude Desktop, opencode, Cursor, Windsurf, Gemini CLI, VS Code, Cline, Roo Code)과 Claude Code 설정(~/.claude/settings.json 등). 웹 서버 액세스 로그(macOS 기본 Apache, Homebrew의 nginx와 httpd)도 읽습니다. Gatekeeper가 거부한 기록은 읽는 데 약 10초가 걸리므로 처음에는 꺼져 있습니다. |
| Linux | 인증 로그(sshd), auditd, 웹 액세스 로그(nginx / apache. 가상 호스트별 로그 포함), DNS 쿼리 로그(dnsmasq / named), MCP 설정(Claude Code, Claude Desktop, opencode, Cursor, Windsurf, Gemini CLI, VS Code, Cline, Roo Code), Claude Code 설정(~/.claude/settings.json 등). |
| 공통 | RoamSwitch가 설치되어 있으면 그 MCP(읽기만 하는 도구만 사용). “RoamSwitch의 MCP(읽기 전용)에서 탐지 이력과 설정 진단을 가져옵니다” 체크로 끌 수 있습니다. |
| 동봉 도구 | AccessScope와 PathScope(설치되어 있는 경우)의 진단 요약, 그리고 이 단말에서 동작 중인 RoamSwitch Sensor가 발견한 LAN 계층의 위협. 정해진 명령을 정해진 인수로 실행하고 요약만 읽습니다. 인수는 바꿀 수 없습니다. 모두 위의 수집원 목록에서 끌 수 있습니다. 없을 때는 그 사실이 수집원의 비고에 표시됩니다. |
4. 결과 보는 법
| 탭 | 보이는 내용 |
|---|---|
| 대시보드 | 종합 위험(기준값) 게이지, 심각도별 건수, 분류별 발생 건수, 발생 추이, MITRE ATT&CK 건수를 그래프로 볼 수 있습니다. 자료가 있을 때는 RoamSwitch 방어의 커버리지(지금 작동 중인 비율과 사각지대), 동봉 도구의 진단 요약, 지난번 확인과의 차이도 개요 칸에 표시됩니다. |
| 보고서 | 수집원, 분류별 검출 사항, IOC를 정리한 Markdown 보고서입니다. 'Markdown 복사'로 통째로 복사할 수 있고, 'Markdown 소스 표시'로 원본 문자열로 전환할 수 있습니다. |
| 발견 사항 | 검출을 한 건씩 볼 수 있습니다. 심각도, 확도, ATT&CK 번호, 건수, 근거가 된 로그의 행 번호가 붙습니다. |
| 수집원 | 무엇을 확인했는지의 목록입니다. 상태는 “읽음”, “해당 없음”, “읽을 수 없음(권한)”, “실패”, “비활성” 중 하나이며, “읽을 수 없음”과 “실패”인 수집원은 확인하지 못한 것입니다. |
| IOC | 로그에서 발견된 IP, 도메인, URL, 해시의 목록입니다. 실수로 열지 않도록 198[.]51[.]100[.]7처럼 무해화한 표기로 나옵니다. |
| LLM용 요약 입력 | LLM 연동이 꺼져 있을 때만 나타나는 탭입니다. 직접 LLM에 전달하기 위한 요약이며 로그의 원문 행은 들어 있지 않습니다. “복사”로 사용합니다. |
5. 설정과 정기 실행
홈 화면 오른쪽 위의 “설정”을 열면 기능별 탭으로 나뉘어 있습니다. 바꾼 뒤에는 “저장”을 누르고 “← 뒤로”로 홈에 돌아갑니다.
표시 언어 “자동(OS 설정에 따름)” 외에 日本語, English, Deutsch, Español, Français, Italiano, 한국어, Português (Portugal), 简体中文, 繁體中文 중에서 고를 수 있습니다.
정기 실행(선택)
“정기적으로 자동 확인”에 체크하고 저장하면 Mac에서는 launchd 사용자 에이전트, Linux에서는 systemd 사용자 타이머에 등록됩니다. 간격은 15분에서 24시간까지 7단계 중에서 고르며, 처음에는 1시간입니다.
실행되는 것은 personalsoc scan --notify뿐이며 root는 사용하지 않습니다. 지난번에 없던 탐지가 있을 때만 알리고, 본문은 건수뿐입니다(Linux에서는 notify-send가 필요합니다). “지난번에 없던 탐지가 있을 때만 알림”으로 알림을 끌 수도 있습니다.
정기 실행은 일반 사용자 권한으로 동작하므로 root가 아니면 읽을 수 없는 로그(인증·웹 서버·auditd)는 읽을 수 없습니다. 읽지 못한 로그가 있으면, 처음 한 번과 읽지 못한 로그의 조합이 바뀌었을 때 「N개의 로그를 읽지 못했습니다: 이름」이라고 알립니다. 모두 읽었을 때는 아무것도 알리지 않습니다. 그 로그들을 확인하려면 sudo personalsoc scan을 실행합니다.
personalsoc schedule status로 정기 실행이 등록되어 있는지, 마지막으로 동작한 시각, 읽지 못한 로그를 확인할 수 있습니다. 설정 화면에도 같은 내용이 표시됩니다.
Linux에서 notify-send(Debian·Ubuntu에서는 패키지 libnotify-bin)가 없으면 알림이 나오지 않습니다.
systemd 사용자 타이머는 로그아웃 중에는 동작하지 않습니다. 서버에서는 loginctl enable-linger를 한 번 실행하세요.
체크를 해제하고 저장하면 등록이 해제됩니다.
6. LLM 연동(선택)
LLM 연동은 선택 사항이며 처음에는 꺼져 있습니다. 활성화하면 상황 확인 후에 선택한 LLM의 명령이 추가 조사를 하고 감사관으로서 보고서를 작성합니다. 사용할 수 있는 것은 opencode, claude, codex, agy 명령입니다.
순서
- “LLM 연동 사용”에 체크합니다.
- “사용할 LLM”을 선택합니다. “(미설치)”로 표시되는 것은 이 단말에 명령이 없는 것입니다.
- 필요하면 모델과 타임아웃(초)을 바꿉니다. 모델을 비워 두면 그 LLM의 기본값이 사용됩니다.
- “저장”을 누르고 홈으로 돌아가 “상황 확인”을 누릅니다. 확인 후 이어서 LLM 조사가 실행됩니다.
LLM에 전달되는 것
- 전달하는 것은 검출 내용, 근거가 되는 로그 줄, MCP 반환값, 수집원의 비고입니다. LLM이 요청하면 프로세스 실행 기록과 설정 파일의 일치한 줄 부근(200자까지)도 전달됩니다. PathScope의 차단 지점(최대 3곳, 80자까지), AccessScope의 탐지 종류와 건수, Sensor의 위협 요약(200자까지)도 가져옵니다. 모두 비밀은 마스킹하고 글자 수를 제한합니다. 파일 자체, 셸, AccessScope의 근거 줄과 설명, Sensor의 detail은 전달하지 않습니다.
- 전달하기 전에 키, 토큰, 비밀번호 같은 비밀을 마스킹하고 보이지 않는 문자를 제거합니다.
- PersonalSOC는 LLM에 셸도 파일도 주지 않습니다. LLM은 “조사하고 싶은 것”을 요청할 뿐이며, PersonalSOC가 허용한 읽기 전용 도구를 실행해 결과를 돌려줍니다. 조사 횟수는 최대 6회입니다.
- LLM의 출력은 신뢰하지 않으며 보고서에서는 인용으로 취급합니다. LLM은 탐지를 과도하게 심각하게 해석하기도 하므로 결론은 반드시 “검출 사항”에서 확인하세요.
- LLM이 쓴 IP 주소, 도메인, CVE 번호, 해시, PID, 프로세스 이름은 LLM에 전달한 자료(로그 본문, 분석 요약, 도구 결과)와 대조합니다. 자료 어디에도 없는 값은 보고서의 '수집한 자료에 나타나지 않는 값'에 지어낸 값일 수 있다고 표시합니다. 문자열만 비교하며 LLM에는 묻지 않습니다. 보고서 끝에는 LLM에 전달한 조사 결과를 전달한 그대로 부록으로 싣습니다.
도구 제한에 대하여
- 설정 표의 “상태” 열에서
opencode와claude는 “도구를 제한하고 실행”으로 표시됩니다. claude는 내장 도구, MCP 서버, 스킬을 끄고 사용자 설정도 읽어 들이지 않은 채 실행합니다. opencode는 모든 권한을 거부로 한 채 실행합니다. codex와agy는 이 방법으로는 멈출 수 없으므로 “도구를 제한할 수 없음”으로 표시됩니다.
7. 명령줄에서 사용하기
명령은 personalsoc입니다. Linux에서는 /usr/bin/personalsoc에, Mac에서는 PersonalSOC.app/Contents/MacOS/ 안에 있습니다.
Mac에서는 앱을 '응용 프로그램' 폴더에 넣었다면 명령은 /Applications/PersonalSOC.app/Contents/MacOS/personalsoc에 있습니다. 짧은 이름으로 부르려면 터미널에서 다음을 실행합니다. 이후에는 personalsoc만으로 실행할 수 있습니다.
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/PersonalSOC.app/Contents/MacOS/personalsoc /usr/local/bin/personalsoc
| 명령 | 할 수 있는 일 |
|---|---|
personalsoc scan | 이 기기의 로그와 RoamSwitch(MCP)를 자동으로 확인하고 탐지 결과를 목록으로 표시합니다. root만 읽을 수 있는 로그(인증, 웹 서버, auditd)는 sudo를 붙여 실행합니다. |
personalsoc scan --report | Markdown 보고서를 표시합니다(LLM 없음). |
personalsoc scan --llm <name> | LLM이 읽기 전용 도구로 조사하여 감사관으로서 작성한 보고서를 표시합니다. name은 opencode, claude, codex, agy 등입니다. |
personalsoc scan --notify | 지난번에 없던 탐지가 있을 때만 알립니다. 정기 실행이 호출하는 형태입니다. |
personalsoc scan --format <text|markdown|json|sarif> | 기계가 읽는 형식으로 출력합니다. json과 sarif(SARIF 2.1.0)는 표준 출력에 결과만 냅니다. markdown은 Markdown 보고서입니다. json과 sarif는 --report나 --llm과 함께 쓸 수 없습니다. |
personalsoc scan --fail-on <high|medium|low> | 그 심각도 이상의 검출이 있으면 종료 코드 3으로 끝납니다. --fail-on-partial을 붙이면 읽지 못한 수집원이 있을 때 종료 코드 4로 끝납니다(검출 없음은 안전의 증명이 아닙니다). |
personalsoc scan --since-last | 지난번 확인과의 차이를 보여 주고 이번 확인의 스냅샷을 이력에 남깁니다. 이력은 PersonalSOC 자체의 저장 위치에만 기록합니다(8장). |
personalsoc scan --diff <file>personalsoc scan --save-snapshot <file> | --diff는 --format json의 출력 또는 --save-snapshot으로 내보낸 파일과 비교합니다(아무것도 쓰지 않으며 --since-last와 함께 쓸 수 없습니다). --save-snapshot은 이번 결과를 JSON 파일로 내보냅니다(본인만 읽고 쓸 수 있는 권한). |
personalsoc <type> <file> | 지정한 파일을 분석합니다. type은 sshd, auditd, web, dns, unified, mcp, agent, inject, ioc 중 하나입니다. file에 -를 지정하면 표준 입력을 읽으며, --report, --brief, --llm도 붙일 수 있습니다. |
--lang <lang> | 어떤 명령에도 붙일 수 있으며, 표시 언어를 설정보다 우선하여 지정합니다. 코드는 ja, en, de, es, fr, it, ko, pt-PT, zh-Hans, zh-Hant입니다. |
--llm을 붙여 실행하는 것이 LLM에 데이터를 전달하는 명시적 조작이 되므로, 설정의 'LLM 연동 활성화'가 꺼져 있어도 동작합니다. 도구를 제한할 수 없는 LLM에 대한 확인도 요구되지 않으므로, codex나 agy를 사용할 때는 조사 중에 파일이 읽혀 전송될 가능성이 있음을 이해한 뒤 사용하세요.8. 저장 위치와 업데이트
저장되는 것
| 항목 | 위치 |
|---|---|
| 설정 | ~/.config/personalsoc/settings.json(본인만 읽고 쓸 수 있는 권한으로 저장됩니다) |
| 지난번 검출의 기록(알림 판정용) | ~/.local/state/personalsoc/last.json(검출의 지문에 해당하는 해시뿐이며 로그 문자열은 남기지 않습니다) |
| 정기 실행의 등록 | Mac은 ~/Library/LaunchAgents/dev.personalsoc.scan.plist(출력은 ~/Library/Logs/personalsoc-scan.log). Linux는 ~/.config/systemd/user/의 personalsoc-scan.timer와 personalsoc-scan.service입니다. |
| 이전 확인의 스냅샷(이력) | ~/.local/state/personalsoc/history/snapshots.json(본인만 읽고 쓸 수 있는 권한. 검출의 종류·제목·대상·심각도·건수, 가드의 켜짐/꺼짐, MCP 서버의 이름, 수집원의 상태, 종합 위험만 담고 로그의 행, 근거, 설정의 내용, 비밀은 넣지 않습니다. 60회분, 1회당 400건, 2 MiB까지. 넘으면 오래된 것부터 지워지며 폴더를 지우면 이력이 없어집니다. 외부로는 보내지 않습니다) |
PersonalSOC는 보고서와 수집한 로그를 파일로 저장하지 않습니다. 남기고 싶을 때는 화면의 'Markdown 복사'나 명령줄 출력을 사용하세요. LLM을 늘리고 싶을 때는 설정 파일의 profiles를 직접 편집합니다. 화면에서는 바꿀 수 없습니다. 이전 결과와의 비교에 쓰는 확인 기록(이력)만은 다음 표와 같이 남깁니다.
업데이트
Mac은 설정의 “업데이트”에서 갱신합니다. “업데이트 확인”을 눌렀을 때만 lafine.net에 접속하여 최신 버전 정보(공개 JSON)를 받습니다. 이 단말이나 로그의 정보는 보내지 않습니다. 새 버전이 있으면 “다운로드하고 설치”를 누릅니다. 내려받은 파일은 앱에 내장된 공개 키로 서명을 검증하며, 실패하면 아무것도 설치하지 않습니다. 끝나면 앱이 다시 시작됩니다.
Mac에서는 RoamSwitch 본체의 업데이트로는 PersonalSOC가 갱신되지 않습니다. Linux에는 업데이트 기능이 없으며 RoamSwitch 패키지의 업데이트에 포함됩니다.
9. 문제가 생겼을 때
| 증상 | 원인과 대처 |
|---|---|
| 수집원이 “읽을 수 없음(권한)”으로 표시된다 | 인증, 웹 서버, auditd 로그는 관리자 권한이 없으면 읽을 수 없습니다. PersonalSOC는 스스로 권한을 높이지 않으므로 sudo를 붙여 실행하세요. '탐지 없음'과는 다른 상태이며, 그 로그는 확인되지 않았습니다. |
| 정기 실행을 저장할 수 없다 | Mac에서 “격리된 임시 위치에서 실행 중”이라고 표시되면 PersonalSOC.app을 응용 프로그램 폴더로 옮겨 다시 열고 한 번 더 저장합니다. “personalsoc 명령을 찾을 수 없음”이 표시되면 앱 본체와 같은 위치에 personalsoc이 있어야 합니다. |
| claude의 조사가 “Not logged in”으로 실패한다 | PersonalSOC는 claude를 사용자 설정(~/.claude/settings.json의 env나 apiKeyHelper 등)을 읽어 들이지 않은 채 실행합니다. 프록시, Bedrock, Vertex처럼 그 설정으로 인증하는 구성에서는 실패합니다. 설정 파일에 "llm_user_settings": ["claude"]를 직접 추가하면 사용자 설정을 읽어 들여 실행합니다. 도구와 MCP는 계속 꺼진 상태입니다. |