LINUX용 ROAMSWITCH · 작동 참조
CLI/헤드리스 운영 가이드
GUI를 사용하지 않고 클라우드 VPS, SSH 너머, cron, 모니터링 스크립트, AI 에이전트(MCP)에서 RoamSwitch for Linux를 운영하기 위한 레퍼런스입니다.
- 클라이언트 버전(
roamswitch): 노트북용. 접속 대상의 신뢰도에 따라 nftables 프로파일을 전환합니다. 이 가이드의 주된 대상입니다. - 서버 버전(
roamswitch-server): VPS와 서버용. 기본 전체 거부, FIM, eBPF 연동, 긴급 알림 등을 갖추고 있습니다. 자세한 내용은 RoamSwitch Server Edition 운영 매뉴얼을 참조하십시오.
1. 구성품
| 구성 요소 | 다음으로 실행 | 역할 |
|---|---|---|
roamswitch-daemon (클라이언트) |
루트(시스템 Type=notify + WatchdogSec=30) |
클라이언트의 모든 특권 처리. nftables 제어, 네트워크 판정, 랜섬웨어/멀웨어 감시, fanotify, ARP/NDP 고정, DNS 적용 등. TCP/UDP 소켓은 열지 않음 |
roamswitch-server-daemon (서버) |
루트(시스템 Type=notify + WatchdogSec=30) |
서버의 모든 특권 처리. 인바운드 기본 전체 폐기, SSH/관리 출처 IP 예외 보호, FIM(중요 파일과 디렉터리 집합의 변조 탐지), Falco eBPF UNIX 소켓 수신, 프로세스 동결(SIGSTOP), 실행(exec) 레코더, 이벤트 전송(옵트인), 알림 발송 |
roamswitch(CLI) |
로그인 사용자(일부 작업에는 sudo가 필요함) | 씬 클라이언트가 데몬 상태를 읽고 있습니다. Client Edition에서 /run/roamswitch/roamswitch.sock IPC를 사용하거나 Server Edition에서 --server, server, fim 및 emergency-restore 하위 명령을 제공합니다. |
roamswitch-mcp |
AI 클라이언트에 의해 생성됨 | AI 에이전트의 프로그래밍 방식 상태 검색을 위한 MCP 서버(stdio/JSON-RPC)입니다. 설정을 바꾸는 도구는 없습니다. MCP 설정을 참조하세요. |
roamswitch-ransomware-rollback |
root(watch는 systemd의 roamswitch-ransomware-rollback-watch.service) |
랜섬웨어 복구 도구. btrfs 서브볼륨과 LVM 논리 볼륨의 스냅샷을 만들고 필요한 파일만 꺼냅니다. 클라이언트 패키지에 포함되며 GUI의 '침해 대응' 탭에서도 사용할 수 있습니다 |
roamswitch-app |
로그인 사용자 | GTK GUI(클라이언트 에디션에만 해당). 헤드리스 환경에서는 필요하지 않습니다. |
A 헤드리스 배포는 데몬 + roamswitch CLI(원하는 경우 roamswitch-mcp 추가)에서 실행됩니다. 모든 자율 방어 메커니즘은 GUI 없이 작동합니다.
roamswitch)과 Server Edition(roamswitch-server)은 상호 배타적인 패키지(Conflicts)입니다. 서버 환경에 roamswitch-server을 배포합니다.2. 데몬(시스템 서비스)
클라이언트 에디션
sudo systemctl status roamswitch.service # 가동 상태
sudo systemctl enable roamswitch.service # 부팅 시 자동 시작(설치 시 활성화)
sudo systemctl restart roamswitch.service # 재시작
journalctl -u roamswitch.service -f # 로그 추적
journalctl -u roamswitch.service --since "1h ago"
데몬은 시작할 때와 매 사이클(3초 간격)마다 다음 처리를 자율적으로 수행합니다.
- 연결된 게이트웨이 MAC을 식별하고
trusted_networks에 대해 nftables 프로필(open/balanced/lockdown)을 적용합니다. - 행동 기반 랜섬웨어 탐지(fanotify + Shannon 엔트로피 + 카나리아)
- 온액세스 악성 코드 검사(fanotify, 선택적으로 ClamAV)
- ARP 스푸핑 모니터링 및 신뢰할 수 없는 네트워크에 대한 예방 게이트웨이 ARP/NDP 고정
- 프로필당 커널 강화(sysctl / Yama / 코어 덤프 /
/tmpnoexec) - 위협 방지 DNS 적용(
dns_enabled+dns_scope) - 피싱 차단을 위한 링크 가드(NFQUEUE)
/run/roamswitch/state.json에 대한 런타임 상태 출력
서버 에디션
sudo systemctl status roamswitch-server.service # 가동 상태
sudo systemctl restart roamswitch-server.service # 재시작
journalctl -u roamswitch-server.service -f # 로그 추적
3. CLI 명령 참조
기본 구문: roamswitch <command> [options]. 인수 없이 실행하면 기본값은 status입니다. 출력 언어는 자동으로 OS 로케일(LC_ALL / LC_MESSAGES / LANG)을 따릅니다.
| 명령 | 권한 | 설명 |
|---|---|---|
status [--server](별칭 report / server-status) |
사용자 | 보안 건전성 진단(보통 31개 항목, --server 지정 시 서버판 42개 항목), 점수(0–100), 등급, 개선 조언. --json으로 동일한 내용을 기계 판독 가능한 JSON으로 표준 출력에 출력 |
server [status|config|setup|tui|test-notify|restart|ack|ebpf|bans|unban|allowlist] |
사용자/루트 | Server Edition 관리. config는 설정, setup은 마법사, tui는 TUI(일반 사용자는 읽기 전용), test-notify는 알림 테스트, restart는 재시작(설정 리로드는 미지원). ack는 긴급 격리 확인 응답, ebpf는 격리 상태와 인시던트 이력. allowlist [list|add <rule> <process> [--exe <절대 경로>] [--days N] <reason...>|renew <rule> <process> [--days N]|remove]는 오탐 허용 목록(기한은 1~365일, 기본 30일). bans [--json]은 SSH 무차별 대입 가드의 상태, unban <IP|IPv6 /64|--all>은 차단 해제(root) |
fim [verify|update] |
사용자/루트 | 중요 경로 파일 무결성 모니터링 확인(verify) 및 기준 해시 데이터베이스 업데이트(update) |
bans [--json] |
사용자/루트 | SSH 무차별 대입 가드의 상태(차단/탐지만/정지 중과 그 이유), 지금 차단 중인 접속 출처와 남은 시간, 최근 기록을 표시합니다. 차단 목록은 root만 읽을 수 있으므로 sudo를 붙입니다. --json 지원. 서버 버전의 server bans와 같습니다 |
unban <IP | IPv6 /64 | --all> |
뿌리 | SSH 무차별 대입 가드와 웹 액세스 가드의 차단을 해제하고 그 접속 출처의 SSH 실패 횟수도 지웁니다. --all 로 모두 해제합니다. 서버판의 server unban 과 같습니다 |
posture [status|ack] |
사용자 | 클라이언트 에디션. "신뢰(개방)"로 등록한 네트워크가 이 기기의 상태에 따라 어떻게 다뤄지고 있는지 표시합니다(status, 생략 가능). ack는 탐지 내용을 확인해 문제없다고 기록하고 신뢰로 되돌립니다(데몬이 실행 중이 아니면 root만). 확인 이후의 탐지는 다시 표준 보호로 낮춥니다. 서버 에디션에서는 사용할 수 없습니다 |
ssh-allow [status|check|add|remove|enable|disable] |
뿌리 | 서버 에디션. ssh_allow_only_sources(IP 주소와 CIDR)에 있는 접속 원본만 새 SSH 연결을 열 수 있게 합니다(ssh_allow_only_enabled, 기본값 꺼짐). 이미 연결된 세션은 끊지 않습니다. 목록이 비어 있거나 지금 SSH로 연결 중인 접속 원본이 목록에 없으면 켜지 않습니다. check는 켰을 때 거부되는지만 알려 주며 아무것도 바꾸지 않습니다. disable은 데몬을 기다리지 않고 규칙을 제거합니다 |
emergency-restore |
뿌리 | 모든 긴급 eBPF/방화벽 격리를 해제하고 네트워크 기준을 복원합니다. |
ports [-a|--all] |
사용자 | 0.0.0.0, 인증되지 않은 DB 및 개발 서버의 수신 포트입니다. -a에는 루프백 전용 포트가 포함됩니다. |
guards |
사용자 | 자동 방어 가드 상태(포트 이상, ARP, USB 저장소, 다운로드, DNS 위협, 카나리아, 개발 서버 격리기, Bluetooth) |
wifi |
사용자 | Wi-Fi 암호화 강도(개방형/WEP/WPA/유선) 및 SSID |
sharing [status|on|off] |
사용자 | 비신뢰 네트워크에서 공유 서비스(SSH / Samba / RDP)의 자동 정지와 복원. on은 비신뢰 연결 시 자동 정지 |
audit-url <URL> |
사용자 | 로컬 피드 + 휴리스틱을 통해 URL 피싱 및 위협 위험 검사(대상을 가져오지 않음); hxxps://example[.]com 같은 무력화 표기 주소는 먼저 원래 주소로 되돌림 |
audit-secrets [--text] <text|path|directory> |
사용자 | 텍스트・파일・디렉터리(재귀적, .git/node_modules 등 제외)에서 API 키, 개인 키 및 토큰을 감지합니다(데이터를 전송하지 않음). audit-secrets <폴더>는 dist와 build를 조사하지 않습니다. 공개되는 쪽은 scan-frontend로 조사합니다. 찾으면 종료 코드 1, 인수가 없거나 경로처럼 보이는 인수가 존재하지 않으면 2입니다. 문자열로 검사하려면 --text를 붙입니다. |
audit-logs [hours] |
사용자 | 지난 N시간 동안의 시스템 저널/인증 로그를 집계하고 분류합니다(기본값 24). API 키나 토큰은 자동으로 마스킹됩니다. 로그 패턴 이상 탐지 결과(신규 패턴 및 통계적 빈도 급증)도 표시합니다. |
canary |
사용자 | 랜섬웨어 카나리아 미끼 파일 상태 및 무결성, 감지된 인시던트 기록(최근 50건까지) |
port-anomaly(별칭 port-guard) |
일반 | 미확인 포트 노출 가드의 기준선 확보 상태, 현재 자동 차단된 포트, 감지된 인시던트 기록(최근 50건까지) |
quarantine [list] |
사용자 | 악성코드 격리 저장소의 내용(샘플, 원본 경로, 위협 이름, 날짜) |
knowledge [query](별칭 faq) |
사용자 | 오프라인 지식 베이스 검색 |
airgap [enable|disable] |
사용자/루트 | Air-Gap 긴급 차단의 발동 / 해제(클라이언트판 전용). enable은 모든 외부 통신을 drop(이미 확립되어 있던 연결도 끊음), disable로 복구. 자동 해제 구조는 아래의 「격리(Air-Gap) 정책」을 참조 |
help (--help / -h) |
사용자 | 도움말 표시(하위 명령 도움말의 경우 roamswitch <command> --help) |
scan-packages [폴더...] |
일반 | 설치된 OS 패키지(dpkg/pacman/dnf/zypper)를 알려진 CVE 맵과 대조합니다. 폴더를 넘기면 락 파일(7개 에코시스템)도 대상으로 합니다. Ubuntu(20.04·22.04·24.04·26.04)에서는 수정 버전이 나온 CVSS 7.0 이상의 CVE만 대조합니다. 네트워크 연결은 일절 하지 않습니다 |
scan-vulns [--confirm] |
일반 | active_vuln_scan_enabled: true(기본 OFF)인 경우에만 127.0.0.1 한정으로 Redis/Memcached/MongoDB/dockerd의 무인증 도달 확인, 감지된 개발 서버에 대한 CORS 설정 오류·경로 탐색·오픈 리다이렉트·SSRF·반사형 XSS(GET만, 스크립트가 없는 무해한 표식) 진단, SMTP 오픈 릴레이 진단, Telnet/FTP/SSH 실증형 노출 진단을 실행합니다. --confirm 없이는 드라이런입니다 확인된 소견(✗)이 1건 이상이면 종료 코드는 1입니다. SSH 배너와 nmap 보고(ℹ)는 정보이며 세지 않습니다. |
vuln-status |
일반 | scan-vulns --confirm이 기록한 각 프로브의 최신 결과(취약점 있음/문제 없음/판정 불가)와 경과 일수를 표시합니다. 미실행이면 실행을 권하고 종료하며, 자동으로 다시 스캔하지 않습니다. GUI(ports 탭)와 MCP의 get_vulnerability_scan_history로도 볼 수 있습니다 |
notifications(별칭 notification-history) |
사용자 | RoamSwitch가 전송한 알림(로그 감사 이상, ClickFix 탐지 등)의 이력(최근 1주일, 최신순). --json으로 JSON 배열, --export <파일>로 JSON Lines를 출력 |
frozen [list|resume <PID>|resume all] |
사용자/root | 각 가드(랜섬웨어 고속 암호화 탐지·카나리아 변조·커널 취약점 공격 탐지·eBPF 가드의 핀포인트 차단)가 SIGSTOP으로 동결 중인 프로세스를 목록으로 표시하고, 오탐이었을 경우 해제(SIGCONT). 동결은 강제 종료가 아니므로 해제하면 멈춘 지점부터 그대로 재개됩니다. resume all로 전체 해제. root 소유 프로세스의 해제에는 sudo가 필요 |
resource-guard (별칭 leak-guard) |
사용자 | 리소스 고갈·프로세스 이상 탐지 가드(Server Edition 전용)의 탐지 인시던트 이력. 네트워크 공개 서비스의 지속적인 RSS 증가(메모리 누수/DoS)나 크래시 루프를 신뢰도 등급과 함께 표시 |
timeline (별칭 incident-timeline) |
사용자 | 링크 가드(ARP 스푸핑), 랜섬웨어 카나리아, eBPF 런타임 가드, 리소스 가드의 탐지를 하나의 시계열로 합치고, 프로세스 계보와 MITRE ATT&CK 태그를 붙입니다(실험적). --json은 JSON 배열을 표준 출력으로, --export <파일>은 JSON Lines를 파일로 출력합니다. 증거 번들을 저장한 탐지 아래에는 저장 행이 └─로 나열됩니다. |
xdp-gate [status|enable|disable] |
사용자/root | XDP 부팅 시 게이트(실험적)의 상태 표시 및 활성화·비활성화. status는 roamswitch-xdp-gate.service의 활성 여부와 현재 프로그램 상태를 표시. 기본값은 비활성 |
sensor [key|list|pair|repin|unpair|request-audit|results] |
일반/root | 네트워크 센서 “RoamSwitch Sensor”(별도 기기에 설치)와 페어링 코드로 상호 신뢰하게 한다. pair --addr <IP> --code <코드> --fingerprint <SHA-256>로 Sensor가 낸 코드와 Sensor 화면에 표시되는 핑거프린트를 입력한다(Sensor는 고정 IP가 전제). TLS 1.3 인증서를 고정(pin)하며, 네트워크에서 가져오지 않고 평문으로도 전환하지 않는다. 그 밖에 request-audit(능동적 취약점 감사 요청. 결과는 results) 등이 있다. sensor_pairing_enabled: true(기본 OFF)가 필요하다. 자세한 내용은 Sensor 운용 매뉴얼 참조 |
port-scan (alias portscan) |
일반 | 착신 포트 스캔 탐지 가드의 탐지 이력(송신 IP, 자동 차단 여부·지속 시간)을 표시합니다. 신규 미지 포트 「노출」을 탐지하는 port-anomaly와는 별개의 기능입니다 |
lockfile-fim [verify|update] [--quiet|-q] |
뿌리 | 의존성 잠금 파일의 변조 감시 검증(verify)과 베이스라인 갱신(update). root 권한이 필요. 감시 대상은 프로젝트 폴더(서버판은 lockfile_watch_dirs) |
scan-scripts <FOLDER...> |
사용자 | node_modules의 package.json에서 preinstall / install / postinstall / prepare 스크립트를 정적으로 나열합니다(인벤토리이며 위협 판정이 아닙니다). pip·uv의 extra-index-url과, .npmrc로 가져오는 곳을 고정하지 않은 @scope도 보여 줍니다. 공개 직후의 버전을 가져오지 않는 설정(pnpm의 minimumReleaseAge 등)이 없으면 심각도 “낮음”으로 표시합니다. 통신하지 않으며, 환경 변수와 다른 곳의 설정도 읽지 않습니다. --accept(사람만 실행할 수 있으며 MCP에서는 불가)로 확인을 마치면, 이후에는 설치 시 실행되는 코드가 늘어난 패키지도 표시합니다. 기준은 ~/.config/roamswitch/package_install_baseline.json에 다이제스트만 저장합니다. |
scan-typosquat <FOLDER...> |
사용자 | package.json의 의존성 이름을 유명 npm 패키지 이름의 동봉 목록과 편집 거리 1~2로 대조하여 타이포스쿼팅 의심 항목을 제시합니다(참고 정보. 네트워크 연결 없음). 이름 끝이 js·.js인 것(nodemonjs, zustand.js 등)은 그 끝을 제거한 이름으로도 대조합니다. |
web-scan [FOLDER...] [--quarantine] [--json] |
사용자/루트 | 웹 셸(PHP·JavaScript·JSP·ASP), 주입 코드, 이미지로 위장한 PHP, .htaccess 악용을 내장 규칙, 서명된 일일 피드, /etc/roamswitch/rules.d의 규칙으로 검사합니다. 생략하면 문서 루트와 PHP 세션(바로 아래의 sess_)을 검사합니다. 기본값은 확인만 하며, --quarantine(root)으로 격리합니다. 종료 코드: 0 = 탐지 없음, 2 = critical / high 있음, 1 = 실행 실패 |
web-rules [status|list|validate <file.json>|locked|unlock-account <user>|example] |
사용자/루트 | 웹 애플리케이션 계층 규칙의 상태(버전, 배포된 버전, 사용자 규칙 위치, 격리 수준, 계정 조치, 탐지 후 훅) 표시(status), 불러온 규칙 목록(list), 사용자 규칙 파일 검증(validate), 계정 조치로 비활성화한 로그인 셸 확인(locked)과 복원(unlock-account, root), 설정과 훅의 예시(example) |
web-gate-config <PATH> [--proxy URL] |
사용자/루트 | 식별자(접수 번호·주문 번호 등)를 조회하는 위치를 지키는 웹 게이트의 nginx 설정을 출력합니다(아무것도 변경하지 않음). 게이트는 Unix 소켓으로만 동작하며 네트워크로 나가지 않습니다. |
web-id-check '<URL with {n}>' --start N [--count 3..10] [--yes] |
사용자/루트 | 자기 사이트의 식별자를 받는 위치에 로그인 없이 연속된 번호(최대 10건)를 GET으로 조회하고, 번호마다 다른 내용이 돌아오는지 확인합니다. 돌아온다면 다른 사람의 정보를 볼 수 있을 가능성이 있습니다(종료 코드 2). 이 단말의 네트워크 밖 호스트에는 --yes가 필요합니다. |
web-guard-check [--hours N] |
사용자/루트 | 액세스 로그와 웹 서버 설정으로, 이 환경이 웹 액세스 가드의 차단에 적합한지 점검합니다(아무것도 변경하지 않음). 요청이 많은 접속 출처, 사설 주소와 공유 주소에서 온 비율, 방문자 주소를 복원하는 설정의 유무를 조사하여 '적합', '일부에만 효과', '부적합', '판단 불가'를 표시합니다. 부적합이면 종료 코드 1입니다. 로그를 읽으려면 root가 필요합니다. |
roamswitch doctor [--json] |
사용자/루트 | RoamSwitch의 방어를 지탱할 수 있는 단말인지 조사합니다(아무것도 변경하지 않으며 통신도 하지 않습니다). 필수 도구(nft·systemctl 등)의 유무, 그것들과 RoamSwitch의 파일을 root 이외가 쓸 수 있는지, dpkg --verify / rpm -V의 결과, 수동으로 설치한 CA 인증서, 데몬과 ufw·fail2ban 등의 가동 여부를 확인합니다. --json으로 JSON을 출력합니다. 실패가 1건이라도 있으면 종료 코드 1(주의만 있으면 0). Server TUI의 “도구”에서도 사용할 수 있습니다. |
roamswitch scan-frontend <FOLDER> |
사용자/루트 | 공개되는 프런트엔드 파일에서 API 키·비밀 키 등(audit-secrets와 같은 탐지), JWT, 소스맵(.map)을 찾습니다. dist·build·public 등을 읽고, 없으면 폴더 자체를 읽습니다(audit-secrets <폴더>는 dist와 build를 보지 않습니다). 값은 앞 4자와 길이만 표시하며, 발견되면 종료 코드 1입니다. 상한은 파일당 5 MB, 전체 200 MB, 20,000개 파일이며, 심볼릭 링크는 따라가지 않습니다. |
kernel-modules [--json] [--apply [MODULE...]] [--remove] |
사용자/루트 | Copy Fail·Dirty Frag·act_pedit에 사용된 커널 모듈(algif_aead·esp4·esp6·rxrpc·act_pedit)을 로드할 수 있는지 읽기만으로 조사한다(통신하지 않음). --apply(root)로 사용하지 않는 것을 modprobe.d로 막고, --remove로 되돌린다. 진단 점수에는 들어가지 않는다 |
audit-agent-setup [FOLDER...] [--json | --format text|json|sarif] |
사용자/루트 | AI 에이전트의 지시 파일·스킬·설정을 읽기 전용으로 점검한다(통신하지 않음). 대상은 ~/.claude·~/.codex·~/.cursor 등, 등록한 프로젝트와 FOLDER의 CLAUDE.md·AGENTS.md 등, openclaw.json, 에이전트 메모리, VS Code 작업, GitHub Actions의 workflows, Claude Code·Gemini CLI·Codex·Cursor·OpenCode의 설정이다. 보이지 않는 Unicode 문자, 지시 덮어쓰기, 비밀의 외부 전송, 열기만 해도 실행되는 훅 등을 지적한다(HTML 주석 안은 더 무겁게 다룬다). 본문과 비밀은 출력하지 않는다. 일치 항목은 사람이 확인할 곳이며, 악의를 단정하는 것은 아니다. --json과 --format sarif(SARIF 2.1.0)로 출력할 수 있고, 각 지적에 OWASP LLM과 ATT&CK 태그가 붙는다. |
detection-coverage [--server | --client] [--json | --format json|navigator] |
사용자 | 공격자가 방어를 약화시키거나, 흔적을 지우거나, 눌러앉을 때 쓰는 MITRE ATT&CK 기법별로, RoamSwitch가 탐지할 수 있는지(탐지 / 일부 / 보지 않음), 보이지 않는 부분, 담당 가드가 지금 동작하는지(동작 중 / 중지 / 일부만 동작 / 알 수 없음)를 목록으로 보여 준다(코드와 로컬 설정을 읽기만 하며, 아무것도 실행하지 않고 통신도 하지 않는다). 기법마다 근거가 되는 코드가 남아 있는지 테스트로 확인하며, 목록에 없는 기법은 평가하지 않았다. Client Edition은 38개 기법(일부 31·보지 않음 7), Server Edition은 38개 기법(일부 25·보지 않음 13)이며, 탐지로 평가한 기법은 없다. --server / --client로 Edition을 고른다(생략하면 설치된 Edition). --json은 MCP 도구 get_detection_coverage와 같은 JSON을 출력한다. --format navigator를 쓰면 같은 표를 MITRE ATT&CK Navigator 레이어(layer 4.5)로 출력합니다(탐지는 녹색, 일부는 노랑, 보지 않음은 빨강, 평가하지 않은 기법은 색 없음). |
vuln-accept <ECOSYSTEM> <PACKAGE> <CVE-ID> --version VERSION --reason TEXT [--days N] | --list | --revoke ... |
사용자 | 패키지 CVE 대조의 탐지에 사람이 기한이 있는 “수용”을 기록한다. roamswitch vuln-accept <에코시스템> <패키지> <CVE-ID> --version VERSION --reason 이유 [--days 일수](이유는 필수. 기본 90일, 최장 365일), --list, --revoke. 수용한 탐지는 결과에 남으며 “조치 필요”와는 별도로 센다. 기한이 지나면 원래대로 돌아가고 알림 이력에 남는다. 지정한 버전에만 효력이 있으며, MCP에서는 수용할 수 없다 |
sigma-check [RULE.yml] [--against-exec-history] [--json] |
사용자/루트 | 직접 /etc/roamswitch/sigma.d에 둔 Sigma 규칙(process_creation의 일부 작성 방식)을 불러올 수 있는지 확인합니다. --against-exec-history는 기록된 실행(exec) 이벤트에 대해 시험적으로 일치를 조사합니다(실행 로그는 root 전용). 불러오지 못한 규칙은 이유와 함께 표시됩니다. root 소유이며 다른 사용자가 쓸 수 없는 파일만 읽습니다. 실행 기록기에서의 일치는 알림·타임라인·전달만 하고 차단하지 않습니다. 네트워크 연결 없음 |
bluetooth-audit [--json] |
사용자 | BlueZ 설정(/etc/bluetooth/input.conf, main.conf)에 페어링 전 기기의 키보드 연결을 허용하는 항목이 없는지 확인하고, 연결된 Bluetooth 키보드·마우스를 나열합니다(읽기 전용) |
audit-npm-signatures <DIR> [--confirm] |
사용자 | npm audit signatures로 설치된 패키지의 서명·provenance를 검증(RoamSwitch에서 npmjs.com과 통신하는 유일한 명령. --confirm 없이는 드라이런. 서버판은 npm_audit_signatures_enabled의 활성화도 필요) |
install [--pm npm|pnpm] [--yes] |
사용자 | npm / pnpm의 install을 감싸서 라이프사이클 스크립트의 실행만 bwrap 샌드박스에 가둔다(패키지 다운로드는 평소처럼 네트워크에 접속해 수행한다). 터미널이 없는 환경(스크립트 등)에서는 --yes를 붙이지 않는 한, 스크립트를 실행하지 않고 종료 코드 2로 멈춘다. |
forward status|test|queue (alias event-forward) |
사용자/루트 | 이벤트 전달(syslog RFC 5424 / CEF, JSON Lines, HMAC 서명 구조화 웹훅)의 상태 확인(status)·연결 테스트(test)·재전송 큐 표시(queue). 옵트인이며 기본값 꺼짐, 설정한 대상에만 전송(서버판 운영 매뉴얼 §16) |
events search|tree|export|verify|status (alias exec-events) |
뿌리 | exec 레코더 로그의 검색(search: --since 2h --pid N --exe S --user U --parent P --text S --json)·트리(tree <pid>)·내보내기(export)·해시 체인 검증(verify. 변조 탐지이며 방지는 아님)·상태(status). 로그는 root 전용이며 보통 sudo가 필요하다(운용 매뉴얼 §15) |
격리(Air-Gap) 정책
고정 타이머만으로 해제하면 기다리기만 하는 공격자에게 돌파당하므로, 격리의 트리거는 신뢰도로 분류됩니다(클라이언트판·서버판 공통).
- 저신뢰도(수동 Air-Gap, 범용 이상, eBPF의 Error / Warning 이하 등): 짧은 타이머 후에 전체 복구합니다(클라이언트:
airgap_low_confidence_secs, 기본값 600초. 서버:guard.yaml의safety_timer_secs, 기본값 300초.0으로 타이머 비활성). - 높은 신뢰도(카나리아 변조, 대량 덮어쓰기, lockdown 중의 ARP 스푸핑, eBPF의 Critical / Emergency / Alert 등): 조용히 복구하지 않고, 원인이 사라진 것을 확인했을 때만 알림과 함께 해제합니다. ack도 없이 상한(
airgap_hard_cap_secs/isolation_hard_cap_secs, 기본 3600초,0= 상한 없음)에 도달하면 축퇴(DEGRADED) 모드로 전환합니다. - 축퇴 모드는 시간이 지나도 절대 자동으로 열리지 않습니다(클라이언트는 루프백, 서버는 관리 경로만 허용). 해제는 원인 소멸의 재확인,
roamswitch server ack, 수동 해제(GUI /roamswitch emergency-restore)로만 가능합니다. 클라이언트는airgap_degraded_lift_rfkill을true로 하지 않는 한 Wi-Fi의 rfkill도 되돌리지 않습니다. - 관리 경로 이외의 확립된 연결은 끊어집니다(C2나 리버스 셸도). 수동 Air-Gap은 낮은 신뢰도이지만, ARP 스푸핑 경고의 “지금 바로 차단”에서 발동하면 높은 신뢰도가 되며, 게이트웨이의 MAC을 전송 없이 재확인합니다(
arp_recheck_consecutive회·arp_recheck_min_secs초 이상). 전환은 타임라인에 기록됩니다.
랜섬웨어 복구(스냅샷 및 파일 단위 복원)
다음 명령은 roamswitch-ransomware-rollback의 것입니다(roamswitch의 하위 명령이 아닙니다). 상태는 /var/lib/roamswitch에 저장됩니다.
| 명령 | 권한 | 설명 |
|---|---|---|
roamswitch-ransomware-rollback snapshot [--path PATH] [--label TEXT] |
root | 대상(기본값 $HOME)의 스냅샷을 지금 만듭니다. 대상은 btrfs 서브볼륨 또는 LVM 논리 볼륨 |
roamswitch-ransomware-rollback watch [--path PATH] [--periodic-interval-secs N] |
root | 상주 감시. 짧은 시간에 파일이 대량으로 덮어써지거나 다른 방어 기능이 기록한 Critical 이벤트가 발생하면 스냅샷을 자동으로 만듭니다. 사전 스냅샷도 정기적으로 만듭니다(기본 6시간마다, btrfs는 4세대, LVM은 2세대 보관. 탐지 시점 스냅샷 이후에는 정기 생성을 기본 7일간 멈춤) |
roamswitch-ransomware-rollback list [--path PATH] [--json] |
root | 이 도구가 만든 스냅샷 목록(종류, 실체 존재 여부, 권장 사전 스냅샷). --json으로 기계 판독용 출력 |
roamswitch-ransomware-rollback restore-files <ID> <PATH> [--dest DIR] |
root | 스냅샷에서 지정한 파일이나 디렉터리만 현재 상태를 덮어쓰지 않고 다른 위치로 꺼냅니다(기본값 <대상>/RoamSwitch-Recovered/<ID>/). 복구의 첫 번째 선택지 |
roamswitch-ransomware-rollback mount-for-browsing <ID> / unmount-browse <MOUNT_POINT> |
root | restore-files에 넘길 경로를 고르기 위해 스냅샷의 내용을 볼 수 있게 합니다(btrfs는 그대로, LVM은 읽기 전용 임시 마운트). 끝나면 unmount-browse로 해제합니다 |
roamswitch-ransomware-rollback config get|set --periodic-interval-secs N |
root | 사전 스냅샷 간격(초. 0이면 끄기, 그 외에는 300 이상). 실행 중인 watch에 재시작 없이 반영됩니다. 탐지 시점 스냅샷을 끄는 설정은 없습니다 |
roamswitch-ransomware-rollback restore <ID> [--yes] [--accept-tampered] |
root | 대상 전체를 스냅샷 상태로 되돌립니다(파괴적). 탐지 시점 스냅샷은 이미 암호화된 파일을 포함하므로 --accept-tampered가 없으면 거부됩니다. 먼저 restore-files를 시도하세요 |
예
sudo roamswitch status # 클라이언트 종합 진단(31개 항목)
sudo roamswitch status --server # 서버판 종합 진단(42개 항목)
sudo roamswitch ports -a # 전체 리스닝 포트
roamswitch guards # 가드 가동 상태
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets . # 현재 디렉터리 재귀 스캔
roamswitch audit-logs 72 # 최근 72시간 로그 분석
sudo roamswitch sharing on # 미신뢰 네트워크에서 SSH/Samba/RDP 자동 중지
sudo roamswitch fim verify # FIM 파일 무결성 검증
sudo roamswitch fim update # FIM 기준선 업데이트
sudo roamswitch emergency-restore # 긴급 차단 전체 해제 및 복구
sudo roamswitch airgap enable # 긴급 차단
sudo roamswitch airgap disable # 해제
sudo roamswitch server ack # 긴급 격리를 확인 응답(FULL 격리 중에는 엄격한 격리를 유지, 축소 모드 중에는 해제)
roamswitch canary # 카나리아 인시던트 기록
roamswitch vuln-status # 최근 스캔 결과와 경과 일수(pass_age)를 표시
roamswitch port-anomaly # 미확인 포트 노출 가드 인시던트 기록
roamswitch server ebpf # eBPF 가드의 격리 상태와 인시던트 기록
roamswitch server bans # SSH 무차별 대입 가드의 상태와 차단 중인 접속 출처 목록
sudo roamswitch server unban 203.0.113.9 # SSH 무차별 대입 가드의 차단 해제(root 필요)
roamswitch notifications # 최근 1주일간의 알림 기록
roamswitch frozen # 동결 중인 프로세스 목록
sudo roamswitch frozen resume 12345 # 오탐 프로세스를 해제
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10 # 페어링 코드로 Sensor와 페어링
sudo roamswitch sensor key # 자신의 공개 키/주소를 표시
roamswitch port-scan # 포트 스캔 탐지 이력
roamswitch timeline --json # all incident-timeline records as JSON
roamswitch notifications --export n.jsonl # JSON Lines
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch forward status
sudo roamswitch server allowlist add "<rule>" mytool --exe /usr/local/bin/mytool --days 30 reviewed false positive
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>
sudo roamswitch server tui
서버 버전은 root로 동작하므로 sudo 없이 status / status --server / ports -a를 실행하면 “미가동”으로 잘못 판정하거나 프로세스 정보가 누락될 수 있습니다. 설정을 변경하는 sharing / fim update / airgap / emergency-restore 등도 sudo가 필요합니다. 그 밖의 읽기 명령은 sudo 없이도 정확하게 동작합니다.
--help는 서브커맨드마다 있습니다(예:roamswitch ports --help).- 기계가 읽을 수 있는 출력은
status --json, MCP(§6),/run/roamswitch/state.json(§5) 등에서 얻을 수 있습니다. - 클라이언트 버전은 데몬이 프로파일을 판정하며, CLI에서는 전환하지 않습니다. 강제하려면
manual_override를 사용합니다(§5). status는 항상 exit code 0입니다. 모니터링에서는 점수 행을 읽습니다(예는 §7).
4. 구성 파일
클라이언트 에디션(~/.config/roamswitch/config.json)
데몬은 루트로 실행되며 찾은 첫 번째 유효한 파일(또는 루트 전용 환경에서는 /root/.config/roamswitch/config.json)을 사용하여 /home/*/.config/roamswitch/config.json을 검색합니다.
| 열쇠 | 유형 / 기본값 | 설명 |
|---|---|---|
language | 문자열 / OS 로케일 | UI 및 CLI 언어(ja / en / ko / zh-Hans / zh-Hant / de / fr / es / it / pt-PT) |
trusted_networks | [{name, mac, level}] | 신뢰할 수 있는 네트워크 mac은 게이트웨이 MAC이고, level은 open / balanced / lockdown입니다. |
away_protection_level | 문자열 / lockdown | 알 수 없는 네트워크의 기본 프로필 |
manual_override | 문자열 / 널 | 강제 open / balanced / lockdown(자동의 경우 null) |
dns_enabled | 부울 / true | 위협 방지 DNS 시행 |
dns_provider | 문자열 / quad9 | quad9 / cloudflare / adguard / cleanBrowsing |
dns_scope | 문자열 / untrusted_only | untrusted_only / always_on |
arp_spoof_guard_enabled | 부울 / true | ARP 스푸핑 모니터링 |
gateway_arp_lock_enabled | 부울 / true | 신뢰할 수 없는 네트워크에 대한 예방적 게이트웨이 ARP/NDP 잠금 |
port_anomaly_guard_enabled | 부울 / true | 새로운 청취 포트 자동 차단 |
system_wide_fanotify_enabled | 부울 / true | 시스템 전반에 걸친 fanotify 악성 코드 가드 |
pre_exec_blocking_enabled | 부울 / true | 사전 실행 차단(FAN_DENY) |
mount_hardening_enabled | 부울 / true | /tmp 및 /dev/shm의 noexec(비공개 프로필에 적용됨) |
yama_memory_protect_enabled | 부울 / true | Yama ptrace 제한 사항 |
usb_storage_guard_enabled / usb_keyboard_guard_enabled | 부울 / false | USB 저장소/BadUSB 키보드 가드(기본적으로 꺼져 있음) |
usb_zero_trust_enabled | 부울 / false | USB 버스 authenticate_default=0 |
bluetooth_guard_enabled | bool / true | 신뢰할 수 없는 네트워크에서 Bluetooth의 「검색 가능」을 끔(기본값 ON. 전원은 끄지 않으며 연결된 기기는 그대로 유지) |
device_posture_trust_enabled | bool / true | "신뢰(개방)"로 등록한 네트워크도 심각한 탐지가 있는 동안은 표준 보호로 동작(클라이언트 에디션) |
device_posture_window_hours | int 1–72 / 6 | 위의 낮추기에서 탐지를 세는 시간(시간 단위, 1~72) |
sharing_service_control_enabled | 부울 / true | SSH / Samba / RDP 자동 중지/복원 |
scan_exclusions | [string] | 검사에서 제외된 절대 경로 |
link_guard | 물체 | {enabled, mode: "off"|"warn"|"block", allowlist, blocklist_extra, use_threat_dns} |
vpn_on_untrusted_enabled | 부울 / false | 신뢰할 수 없는 네트워크에서 VPN 터널 자동 시작 |
vpn_backend | 문자열 / wireguard | wireguard / tailscale |
active_vuln_scan_enabled | bool / false | scan-vulns 실행을 허용합니다(기본 OFF). 127.0.0.1 한정 도달 확인 프로브를 전송하므로 명시적인 옵트인이 필요합니다 |
pkgcve_watched_folders | [string] | GUI판의 종속성 대조가 대상으로 하는 프로젝트 폴더 목록(절대 경로). CLI의 scan-packages는 이 설정을 참조하지 않고 명령줄 인자로 전달된 폴더만 대상으로 합니다 |
sensor_pairing_enabled | bool / false | RoamSwitch Sensor와의 페어링 코드 방식 상호 신뢰를 허가합니다(기본 OFF). sensor 명령 사용에 필수 |
port_scan_detect_enabled | bool / true | 착신 포트 스캔 탐지 가드 |
port_scan_detect_min_distinct_ports | int / 15 | 탐지 윈도우 내에서 이 수 이상의 서로 다른 포트에 접속한 송신자를 스캔으로 판정 |
port_scan_detect_window_secs | int / 300 | 스캔 판정 집계 윈도우(초) |
port_scan_block_enabled | bool / true | 탐지된 스캔 발신 IP의 자동 차단 |
port_scan_block_duration_secs | int / 600 | 자동 차단의 지속 시간(초) |
airgap_low_confidence_secs | int / 600 | 저신뢰도 Air-Gap이 자동으로 전체 복구되기까지의 초 수(0 = 자동 해제하지 않음). 고신뢰도 격리에는 적용되지 않음(§3 「격리(Air-Gap) 정책」) |
airgap_hard_cap_secs | int / 3600 | 고신뢰도 격리가 축소(DEGRADED) 모드로 전환되기까지의 초 수(0 = 상한 없음). 축소 모드는 시간 경과로는 열리지 않음 |
airgap_degraded_lift_rfkill | bool / false | 축소 모드에서 Wi-Fi의 rfkill도 해제할지 여부(기본값에서는 해제하지 않음) |
airgapAutoRfkill | bool / true | Air-Gap 중에 Wi-Fi 무선을 rfkill로 차단할지 여부(해제 시 원래대로 되돌림) |
arp_recheck_consecutive | int / 3 | ARP 스푸핑으로 인한 격리의 원인이 사라졌다고 간주하는 데 필요한 게이트웨이 MAC의 연속 일치 확인 횟수(1 이상) |
arp_recheck_min_secs | int / 60 | 위의 연속 일치가 지속되어야 하는 최소 초 수 |
arp_recheck_active_probe | bool / true | ARP 기반 격리에서 게이트웨이의 이웃 캐시 항목이 없을 때(링크가 살아 있는 경우), ARP 요청을 직접 1회 보내 게이트웨이 MAC을 확인할지 여부. 신뢰 MAC 이외의 MAC이 응답에 하나라도 있으면 불일치. 20초에 최대 1회 |
credential_access_watch_enabled | bool / true | ~/.ssh의 비밀 키, ~/.aws/credentials, ~/.config/gcloud, 브라우저의 자격 증명 저장소 등을 예상 밖의 프로세스가 열면 알립니다(알림만, 기본 ON. 약 30초 이내에 반영). 백업과 인덱서는 이미 제외되어 있고, 그 밖의 것은 credential_access_watch_allow로 제외할 수 있습니다. AI 에이전트의 로그인용 파일(본인의 읽기는 제외), ~/.git-credentials, ~/.netrc, ~/.pgpass 등도 대상이며, 실제 위치에는 미끼를 두지 않습니다. 아주 짧은 읽기는 알리지 않을 수 있습니다. ~/.kube/config·~/.docker/config.json·~/.azure는 대상이 아닙니다 |
reverse_shell_watch_enabled | bool / true | 셸이나 인터프리터의 입력과 출력이 외부 주소로의 연결에 이어져 있으면 알립니다(알림만, 아무것도 멈추지 않음). 2초마다 확인하고, 연속 두 번 발견된 것만 알립니다. openssl, telnet, ssh, nc, socat 등이 가진 연결에 대화형 셸을 파이프 등으로 이은 형태는 약한 경고로 알립니다. 설정은 약 30초 안에 반영됩니다. 앱의 스위치로도 전환할 수 있습니다 |
reverse_shell_watch_include_private | bool / false | 사설 주소(RFC 1918, CGNAT, 링크 로컬, IPv6 ULA)의 상대도 대상으로 삼습니다. ssh의 ProxyCommand, 컨테이너, 로컬 개발에 정상적인 것이 많아 기본값은 대상 제외입니다. 루프백은 이 설정과 관계없이 보지 않습니다 |
reverse_shell_watch_allow | list / [] | 알림 대상에서 제외할 프로그램. 실행 파일 이름, 끝이 *인 접두사 일치, 절대 경로 중 하나를 배열이나 쉼표로 구분한 문자열로 적습니다(최대 256개). 실행 파일을 확인할 수 없을 때는 프로세스 이름으로 대조합니다 |
netconf_watch_enabled | bool / true | 1분마다 DHCP 리스와 PAC·WPAD를 조사하여, 아는 네트워크에서 새 DHCP 서버·게이트웨이·DNS 서버나 PAC·WPAD가 나타나면 알립니다(알림만. 처음에는 기록만 함). 기준은 /var/lib/roamswitch/netconf_baseline.json입니다. nmcli로 조회할 수 없는 인터페이스는 감시하지 않고 nm_unobservable에 올립니다. 약 30초 이내에 반영됩니다 |
netconf_watch_trusted | list / [] | 예상된 주소(DHCP 서버, 게이트웨이, DNS 서버), PAC 호스트 이름, PAC URL. 적은 것은 알림 없이 기록합니다. 배열이나 쉼표로 구분한 문자열로 적습니다(최대 256개) |
ssh_guard_* | — | SSH 무차별 대입 가드의 10개 키는 서버 에디션(server.conf)과 기본값이 같습니다. 주요 키는 ssh_guard_max_failures(6), ssh_guard_window_secs(600), ssh_guard_ban_secs(3600), ssh_guard_ban_max_secs(604800), ssh_guard_trust_key_days(30), ssh_guard_allow(비어 있음. IP / CIDR)입니다. sshd가 실행 중일 때만 동작하며, 범위를 벗어난 값은 기본값으로 돌아갑니다. 약 1분 안에 반영되고 재시작은 필요 없습니다. 목록 확인과 해제는 roamswitch bans / roamswitch unban입니다 |
fim_intrusion_context_enabled | bool / true | 파일 변조(FIM)와 락파일 변조 알림에, 쓴 프로세스의 계정·실행 파일과 그 프로세스가 속한 SSH 로그인(접속 출처·시각·인증 방식)을 덧붙입니다. 인증 정보 파일 알림에는 SSH 로그인에 속할 때만 덧붙입니다. 데몬을 재시작한 뒤 반영됩니다. 외부로는 아무것도 보내지 않습니다 |
forward_* | — | 이벤트 전달(syslog / JSON Lines / 서명된 Webhook) 설정입니다. 옵트인이며 기본값은 꺼짐입니다. 키는 forward_enabled, forward_syslog_url, forward_webhook_url 등입니다(유형과 기본값은 서버 에디션 운영 매뉴얼 §18) |
exec_recorder_* / exec_rule* | — | 로컬 실행(exec) 레코더와 알림 전용 상관 규칙 EXR-001~016의 설정. 기본값은 활성(메모리 1 GiB 미만 호스트에서는 비활성이며, 명시적 설정이 우선). 키는 exec_recorder_enabled, exec_recorder_retention_mb, exec_recorder_retention_days, exec_recorder_hash_chain, exec_recorder_hash_exe, exec_recorder_cpu_budget_pct, exec_rules_enabled, exec_rules_disabled, exec_rule_service_users, exec_rule_window_secs 및 exec_rules_isolation_optin(기본값 false. true로 한 경우에만 심각도가 높은 규칙이 격리의 트리거가 됨)입니다. EXR-011~016는 exec_rules_isolation_optin이 true여도 격리의 트리거가 되지 않습니다. EXR-013~015도 exec_rules_disabled로 개별적으로 끌 수 있습니다. 알림만 보내며 격리의 트리거가 되지 않습니다. |
sharing_service_control_enabled: true이고 비신뢰 네트워크에 접속하면 실행 중인 SSH 세션이 끊어집니다. 원격 운영에서는 OFF를 권장합니다.서버 에디션(/etc/roamswitch/server.conf)
서버 버전의 설정은 INI 형식이며 0600(root 전용)으로 보호됩니다. 모든 키의 타입과 기본값은 운영 매뉴얼 §18에 있습니다. roamswitch server config show|get|set 또는 roamswitch server tui(전체 149개 키)로 변경하고, sudo roamswitch server restart로 반영합니다.
공용 머신용 관리자 전용 모드
공용 머신은 sudo touch /etc/roamswitch/admin-only로 “관리자 전용”으로 설정할 수 있습니다. 방화벽이나 DNS 등 머신 전체의 변경을 root와 sudo / wheel / roamswitch 그룹으로 제한합니다. 자신의 파일이나 프로세스에 대한 조작(격리, kill 등)은 종전과 같습니다. /etc/roamswitch/admin-only는 root 소유이고 다른 사용자가 쓸 수 없을 때만 유효하며, 기본값은 꺼짐입니다.
5. 로그 및 런타임 상태 파일
| 경로 | 대상 | 설명 |
|---|---|---|
journalctl -u roamswitch.service | 클라이언트 | 클라이언트 데몬 로그(프로필 스위치, 감지, 오류) |
journalctl -u roamswitch-server.service | 서버 | 서버 데몬 로그(FIM 이벤트, Falco 감지, 격리) |
/run/roamswitch/roamswitch.sock | 클라이언트 | 클라이언트 데몬 IPC Unix 도메인 소켓 |
/run/roamswitch/events.sock | 서버 | Falco / Tetragon eBPF 연동 소켓(root:root, mode 0600. Falco도 root로 동작하므로 추가 권한 설정은 필요 없음) |
/run/roamswitch/state.json | 클라이언트 | 주기 상태: {active_level, network_trusted, fanotify_ready} |
/run/roamswitch/alerts.json | 클라이언트 | 최근 경고 대기열 |
/run/roamswitch/approvals.json | 클라이언트 | 승인 대기 중인 대기열 |
/run/roamswitch/fanotify.ready | 클라이언트 | fanotify 가드가 실행 중임을 나타내는 플래그 파일 |
/var/lib/roamswitch/fim.db | 서버 | FIM SHA-256 기준 해시 데이터베이스 |
~/.local/share/roamswitch/quarantine/ | 둘 다 | 검역소(0700, 샘플 0400) + .metadata.json |
/var/lib/roamswitch/exec_log/ | 둘 다 | 실행(exec) 레코더의 해시 체인 포함 JSON Lines(root 전용, 0600). roamswitch events로 검색·검증 |
/run/roamswitch/airgap_isolation.json / host_isolation.json | 둘 다 | 격리(Air-Gap) 상태(FULL / 축소)와 트리거의 기록. 데몬을 재시작해도 격리가 계속 유지됨 |
IPC 직접 호출(고급)
데몬은 /run/roamswitch/roamswitch.sock에서 줄 바꿈으로 구분된 JSON을 허용합니다.
# 프로파일 강제 전환(클라이언트판)
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
| sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock
# 게이트웨이 ARP 고정 즉시 재확인
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
| sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock
6. 프로그래밍 상태(MCP)
roamswitch-mcp는 stdio JSON-RPC로 도구를 제공합니다(get_security_report / get_exposed_ports / audit_secrets 등). 설정을 변경하는 도구는 없습니다. 쓰기가 일어나는 것은 run_active_vuln_scan, audit_security_logs, run_npm_audit_signatures가 자신의 기록 파일을 갱신할 때뿐이며, readOnlyHint가 false인 것도 이 3개뿐입니다. 모든 도구에 MCP 주석(readOnlyHint 등)이 붙어 있고, openWorldHint가 true인 것은 기본값이 비활성인 run_npm_audit_signatures뿐입니다.
외부 호스트에는 연결하지 않습니다. 데몬의 Unix 소켓이나 roamswitch-core를 호출하며, get_security_report와 verify_security_findings는 LAN으로도 보내지 않습니다. get_lan_sensor_overview·get_lan_network_threats는 같은 단말의 Sensor로 읽기 요청을 보내고, get_privilege_escalation_paths·get_access_log_report는 동봉된 PathScope·AccessScope를 고정 인자로 실행합니다. 설정은 MCP 연동 설정 가이드
7. 자동화 레시피
일일 크론 상태 확인 → 점수가 임계값 미만으로 떨어지면 이메일을 보냅니다.
#!/usr/bin/env bash
# /etc/cron.daily/roamswitch-health
out=$(runuser -u "$SUDO_USER" -- roamswitch status 2>&1)
score=$(printf '%s\n' "$out" | grep -oE '[0-9]+/100' | head -1 | cut -d/ -f1)
if [ -n "$score" ] && [ "$score" -lt 80 ]; then
printf '%s\n' "$out" | mail -s "RoamSwitch health: ${score}/100" root
fi
경고 대기열 모니터링(poll Alerts.json)
#!/usr/bin/env bash
last=0
while :; do
ts=$(jq -r 'max_by(.timestamp).timestamp // 0' /run/roamswitch/alerts.json 2>/dev/null || echo 0)
if [ "$ts" -gt "$last" ]; then
jq -c ".[] | select(.timestamp > $last)" /run/roamswitch/alerts.json | logger -t roamswitch-alert
last=$ts
fi
sleep 10
done
fanotify 가드 상태 확인(state.json)
jq -e '.fanotify_ready == true' /run/roamswitch/state.json >/dev/null \
|| echo "WARNING: fanotify guard is not running" >&2
8. 문제 해결
| 증상 | 해상도 |
|---|---|
roamswitch은 "roamswitch-mcp가 설치되어 있는지 확인"하고 종료됩니다. |
데몬이 실행되고 있지 않습니다 → sudo systemctl start roamswitch.service(또는 roamswitch-server.service). 소켓이 있는지 확인 |
roamswitch status은(는) fanotify 🔴를 보여줍니다. "가드가 멈췄어요" |
일시적인 fs.fanotify.max_user_groups 피로. sudo systemctl restart roamswitch.service으로 다시 시작하고 저널에서 확인 |
프로필은 balanced에 유지되며 open에 도달하지 않습니다. |
게이트웨이 MAC가 level: open을(를) 사용하여 trusted_networks에 등록되어 있는지 확인하세요. |
| SSH 연결이 예기치 않게 끊어졌습니다. | 클라이언트 버전에는 신뢰할 수 없는 네트워크에 sharing_service_control_enabled: true이 있습니다. roamswitch sharing off을 통해 비활성화 |
| 구성 변경 사항이 적용되지 않습니다. | The client daemon reads the first of /home/*/.config/…; apply with systemctl restart roamswitch.service. For the server edition, edit /etc/roamswitch/server.conf then run sudo roamswitch server restart (no reload). |
| 서버 통신이 실수로 차단됨 | 클라우드 콘솔(VNC/직렬)에 액세스하고 sudo roamswitch emergency-restore을 실행합니다. |