ROAMSWITCH SENSOR ・ 최종 업데이트: 2026-10-27

RoamSwitch Sensor 운영 매뉴얼

LAN에 설치하기만 하면 같은 세그먼트 안의 새 기기 출현과 스푸핑을 탐지하는 네트워크 센서의 도입·운영 가이드입니다. RoamSwitch가 도입된 단말(Mac / Linux Client / Server Edition)에 대해서는 능동적인 취약점 감사도 수행합니다. apt / dnf 패키지로 배포 중입니다.

1. 개요 & 포지셔닝

RoamSwitch(Mac / Linux Client / Server Edition)는 모두 호스트에 상주하는 에이전트 형태입니다. 여기에는 구조적인 사각지대가 두 가지 있습니다.

RoamSwitch Sensor는 LAN에 두는 전용 노드로, 이 두 가지 빈틈을 메웁니다. 구현된 것은 도입된 단말에 대한 능동적 취약점 감사, ARP를 이용한 기기 대장화와 스푸핑 탐지, 옵트인 수동 캡처에 의한 의심스러운 동작의 참고 정보입니다(§6). 탐지와 보고만 하며, 통신은 차단하지 않습니다.

외부 전송 방침(기본값에서는 기기 정보·감사 결과를 전송하지 않음)
Sensor는 「Zero Telemetry」가 아닙니다. (1) 탐지용 데이터 가져오기: CVE 맵 등을 매일 가져옵니다(updates.fetch_cve_map, 기본값 true. false면 오프라인). 기기·감사 데이터는 포함하지 않습니다. (2) 운영자가 설정한 대상으로의 알림·집계: 설정했을 때만 보냅니다.

자기 방어 기능은 구현하지 않습니다(의도적인 설계 결정). Sensor 자체에 대한 공격 대책이 필요한 경우, 동일 머신에 RoamSwitch for Linux의 Server Edition을 별도로 설치할 것을 권장합니다. 두 프로세스는 완전히 독립적으로 공존할 수 있습니다.

2. 현재 동작 확인 환경

3. 설치 & 시작

공식 서명된 패키지 저장소에서 roamswitch-sensor 패키지를 설치합니다. 설치 후 roamswitch-sensor.service(systemd)가 자동으로 활성화·시작됩니다.

3.1 APT(Ubuntu / Debian)

# 1. 저장소 서명 키 등록
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. 저장소 추가
echo "deb [signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/roamswitch.list

# 3. 설치
sudo apt update && sudo apt install roamswitch-sensor

3.2 DNF / RPM(Fedora / RHEL)

# 1. GPG 키 가져오기
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. 저장소 설정 파일 추가
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. 설치
sudo dnf install roamswitch-sensor

3.3 시작 확인

systemctl status roamswitch-sensor.service
sudo roamswitch-sensor status

3.4 CLI / TUI 실행

CLI(roamswitch-sensor)와 대화형 TUI(roamswitch-sensor-tui)는 설치 후 바로 실행할 수 있습니다.

sudo roamswitch-sensor status
sudo roamswitch-sensor-tui
옵트인: 수동적 LAN 가시화 확장
스위치의 미러 포트(SPAN) 수신이나 인라인 투명 브리지 환경에서 사용할 경우, ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE 환경 변수(systemctl edit roamswitch-sensor.service로 설정)에 대상 인터페이스 이름을 지정하면, 해당 인터페이스상의 Ethernet/IPv4/IPv6 헤더를 관측하여 신규 기기 출현이나 알려진 악성 IP와의 통신을 탐지합니다(§6.1 참조). 기본값은 비활성화입니다.

4. 페어링(페어링 코드 방식)

Sensor는 초기 상태에서 아무것도 신뢰하지 않습니다. 페어링은 Sensor 운영자가 발급하는 1회용 페어링 코드를 사용해 이루어집니다. 「Sensor가 이 단말에 대해 능동적인 취약점 감사를 실행해도 된다」는 신뢰 관계는, 단 한 번의 페어링 조작으로 양방향에 동시에 성립합니다(한쪽 방향만의 신뢰라는 상태는 존재하지 않습니다).

전제 조건: Sensor는 고정 IP 주소(정적 할당 또는 DHCP 서버 측 주소 예약)로 운용해 주십시오. 단말은 페어링 시점에 확인한 Sensor의 IP 주소로 이후에도 직접 접속하므로(mDNS 등을 통한 자동 탐색은 수행하지 않습니다), Sensor 측 IP가 바뀌면 재페어링이 필요합니다. 엔드포인트 측은 동적 IP를 유지해도 무방합니다.

4.1 페어링 코드 발급(Sensor 측)

# Sensor 측에서 실행(TUI에서는 c 키)
sudo roamswitch-sensor issue-code

8자리 1회용 코드가 표시됩니다(0/O/1/I/L은 제외). 발급 후 10분이 지나면 만료됩니다. 단말에서 핀으로 고정할 TLS 인증서 핑거프린트(SHA-256)와 함께, 단말 측 운영자에게 바로 전달하십시오.

4.2 코드를 사용한 페어링(엔드포인트 측)

# 엔드포인트 측 (roamswitch-linux)
sudo roamswitch sensor pair --addr <SENSOR_IP> --code <CODE> --fingerprint <SHA256_FINGERPRINT>

Mac판에서는 메뉴 바의 「🔍 RoamSwitch Sensor 페어링…」에서 Sensor의 IP 주소·페어링 코드·인증서 핑거프린트를 입력해 GUI로 동일한 작업을 수행할 수 있습니다.

페어링이 성립하면 이후의 능동적 취약점 감사와 감사 결과 취득은 모두 Ed25519 서명으로 인증됩니다. Linux판 단말은 입력한 핑거프린트와 일치하는 인증서를 가진 Sensor와만 TLS 1.3으로 통신하며, 평문으로 자동 폴백하지 않습니다(§4.4). Sensor가 발급한 코드를 알고 있는 단말 측과 그 코드를 받은 Sensor 측 양쪽이 이 시점에서 서로를 신뢰 완료 상태로 취급합니다.

페어링 코드가 실효된 경우
페어링 코드는 발급 후 10분이 지나면 자동으로 실효되며, 재사용도 불가능한 1회 한정 코드입니다. 실효 후 페어링을 시도하면 거부됩니다. 이 경우 Sensor 측 운영자에게 issue-code로 새 코드를 발급받으십시오.

4.3 수동 페어링(공개 키를 직접 파악하고 있는 경우)

Sensor 운영자가 단말의 공개 키와 주소를 이미 파악하고 있는 경우, 페어링 코드 교환 없이 Sensor 측에서 직접 등록할 수도 있습니다(일반적으로는 4.2의 코드 방식을 사용해 단말 측에서 페어링하도록 하는 편이 간편합니다). 자신의 공개 키와 주소는 다음 명령으로 확인할 수 있습니다.

# 엔드포인트 측에서 자신의 공개 키/주소 확인
sudo roamswitch sensor key

# Sensor 측에서 자신의 공개 키/주소/MAC 주소 확인
sudo roamswitch-sensor status
# Sensor 측
sudo roamswitch-sensor pair <전체 공개 키> --addr <IP 주소> --confirm

4.4 제어 API(TCP 50543)의 보안(TLS·핑거프린트·잠금)

페어링·감사 요청·결과 취득은 Sensor의 제어 API(TCP 50543)에서 이루어집니다. 다음과 같은 방어 기능이 내장되어 있습니다.

sudo roamswitch-sensor pairing show                       # mode, fingerprint, warnings
sudo roamswitch-sensor tls rotate                         # regenerate the certificate
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>   # on each endpoint
control.tls를 required로 설정하는 절차
(1) 모든 단말을 TLS 지원 버전으로 업데이트하고 각 단말에서 TLS 페어링(또는 재핀 고정)을 마칩니다 → (2) roamswitch-sensor status에 평문 연결 경고가 더 이상 나타나지 않는 것을 확인합니다 → (3) sudo roamswitch-sensor config set control.tls required → 데몬을 재시작합니다. off는 TLS가 필수인 Linux판 단말이 연결할 수 없게 되므로 보통은 사용하지 않습니다.

5. 능동적 취약점 감사

페어링된 엔드포인트에 대해, Sensor가 비파괴적인 실증형 취약점 진단을 실행합니다. 파괴적인 작업(데이터 쓰기·삭제, 서비스 중지)은 일절 수행하지 않습니다.

sudo roamswitch-sensor scan <공개 키 또는 그 앞부분>

감사는 4단계로 구성되어 있습니다.

  1. 전체 포트 스캔: 대상 호스트에서 열려 있는 TCP 포트를 남김없이 탐지합니다.
  2. 기존 시그니처 진단: Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC의 인증 없는 노출 확인, SMTP 오픈 릴레이 진단(MAIL FROM/RCPT TO만 전송하고 DATA는 전송하지 않는 안전한 방식), 개발 서버의 CORS 설정 오류·경로 순회·오픈 리다이렉트 진단 등, 알려진 취약점 패턴에 대한 비파괴적인 실증 확인을 수행합니다.
  3. 범용 배너 취득: 위 시그니처로 커버되지 않는 열린 포트에 대해, 연결만으로 배너 문자열을 취득합니다(데이터는 보내지 않습니다). 아무것도 표시하지 않는 열린 포트에는 서비스를 구별하기 위해 GET / HTTP/1.0을 한 번만 보냅니다(한 번의 감사에서 최대 32포트).
  4. nmap NSE 보완 진단: nmap --script safe를 통한 광범위한 프로토콜 대응 보완 진단입니다. 호스트에 nmap이 설치되어 있으면 자동으로 실행됩니다(설치되어 있지 않으면 아무 동작도 하지 않습니다).

표준 외 포트의 서비스도 조사합니다. 6380번의 Redis나 2222번의 SSH 등에도 같은 읽기 전용 확인을 적용합니다. 구분하는 것은 처음 표시와 GET / HTTP/1.0 1회에 대한 응답입니다. 단말의 자기 신고(1회에 64건까지)는 서명 대상이 아니므로 범위를 넓히지 않고, 확인 항목을 고르는 용도로만 씁니다.

감사 결과는 매번 /var/lib/roamswitch-sensor/scan_history.json에 기록되며(탐지 여부와 관계없이, 그 시점에 문제가 없었다는 것도 기록의 가치가 있기 때문입니다), CLI 또는 TUI에서 열람할 수 있습니다.

roamswitch-sensor history
sudo roamswitch-sensor report <공개 키 또는 그 앞부분> --out /tmp/report.md

“열린 포트: 없음”이면서 ARP 응답도 없을 때는 “기기에 닿지 않았을 가능성이 있습니다”라고 표시됩니다. 이는 “문제 없음”이라는 뜻이 아닙니다. “nmap NSE: 실행하지 않음(nmap 미설치)”과 “해당 없음”은 서로 다른 의미입니다.

5.1 클라이언트 측에서의 감사 요청(pull 방식)

페어링된 단말 쪽에서 Sensor에 능동적 취약점 감사를 요청할 수도 있습니다. Mac 버전은 메뉴 막대의 「Sensor에 감사 요청」, Linux 버전은 다음 명령입니다.

sudo roamswitch sensor request-audit

Sensor가 감사를 실행한 후, 단말 측은 요청 5분 후부터 5분 간격으로 최대 5회까지 결과를 가지러 갑니다(최종 확인은 최대 25분 후). 취득한 결과는 단말 측에도 로컬로 저장됩니다.

roamswitch sensor results

Mac판에서는 설정 화면의 「감사 결과」 목록, 또는 MCP 도구 get_sensor_audit_results를 통해 AI 에이전트가 대응 계획을 세울 때의 입력으로도 사용할 수 있습니다. Sensor 측에서 페어링이 해제된 경우 등, 결과 제공이 명시적으로 거부되는 경우도 있습니다(§10 Q6 참조).

5.2 사양서와의 차이, 경계값 확인, AI의 추측(선택)

사양서와의 차이 및 경계값 확인(design_flaw.enabled. 기본 꺼짐, 옵트인) 페어링된 동의 단말만 대상입니다. OpenAPI / Swagger 문서를 찾아 선언과 실제 응답의 차이를 보고합니다. 쿼리 인수에는 정해진 안전한 값을 넣고 5xx 등의 이상을 보고합니다. 보내는 것은 GET뿐이며 기기 1대당 최대 20회 요청입니다. 순서는 고정이며 AI가 고르지 않습니다(요약은 비밀을 가리며, 1건당 240자까지).
AI에게 추측 작성시키기(선택) roamswitch-sensor design-hypotheses는 기록의 요약만을 선택한 AI 도구에 넘겨 미확인 추측을 작성하게 합니다. 실행한 사용자의 권한으로 동작하며, 제공업체에 요약이 전송될 수 있습니다. 기기에는 아무것도 보내지 않습니다.

6. 수동적 ARP 모니터링 & LAN 가시화

Sensor는 두 가지 방법으로 LAN의 기기를 파악합니다. (1) ARP 테이블 감시: 약 10초마다 읽어 새로운 IP/MAC과, 알려진 IP의 MAC 변화(스푸핑의 징후)를 탐지합니다. (2) 능동 ARP 스윕: nmap -sn -PR로 직접 연결된 서브넷(최대 /22)을 1시간마다 조사해 대장에 저장합니다. nmap이 없으면 (1)만 동작합니다.

roamswitch-sensor arp-events

탐지한 이벤트는 roamswitch-sensor arp-events나 TUI의 「ARP 이벤트」 탭(Enter로 상세)에서 확인할 수 있습니다. 각 이벤트에는 발생 시각·심각도(치명적~정보. 게이트웨이 IP의 MAC 변경은 「치명적」)·판단 근거·관련 기기의 정체·구체적인 다음 절차가 함께 표시됩니다.

6.1 수동적 LAN 가시화 확장(옵트인)

위의 ARP 모니터링은 「Sensor 자신이 과거에 통신한 기기」만을 대상으로 하지만, ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE 환경 변수로 대상 인터페이스를 지정하면, 해당 인터페이스상의 Ethernet/IPv4/IPv6 헤더와 기기가 스스로 알리는 내용만 관측하여(DNS·DHCP·mDNS·SSDP·WS-Discovery·LLDP 외의 데이터 내용은 보지 않음) 다음을 수행합니다.

sudo systemctl edit roamswitch-sensor.service
# [Service]
# Environment=ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE=eth0

sudo systemctl restart roamswitch-sensor.service
roamswitch-sensor passive-events

환경 변수를 추가했으면 sudo systemctl restart roamswitch-sensor로 재시작합니다. systemctl edit만으로는 실행 중인 데몬에 반영되지 않습니다. 반영되었는지는 roamswitch-sensor status의 「수동 캡처: eth0에서 수신 중」으로 확인합니다. 「수동 캡처는 비활성입니다」 그대로라면 재시작하지 않은 것입니다.

수신 버퍼는 capture.rcvbuf_mb(MiB. 기본 4, 0이면 시스템 기본값)로 바꿉니다. 권한이 CAP_NET_RAW뿐이므로, net.core.rmem_max를 넘는 부분은 잘립니다. kernel_drops가 나오면 rmem_max를 올리고(예: sudo sysctl -w net.core.rmem_max=8388608, 영구 적용은 /etc/sysctl.d/), capture.rcvbuf_mb도 올립니다.

일반 NIC와 미러 포트의 차이
일반적인 단일 NIC로도 ARP·브로드캐스트·멀티캐스트 범위 내에서는 신규 기기 탐지가 동작합니다(실제 물리 LAN에서 검증됨). 다만 LAN상의 다른 2대 간 일반 유니캐스트 통신까지 관측하려면 스위치의 미러 포트(SPAN) 수신, 또는 Sensor를 인라인 투명 브리지로 설치하는 구성이 필요합니다.

6.2 기기 대장과 기기 메모

대장은 roamswitch-sensor device-inventory로 볼 수 있습니다. device-note로 메모를 등록한 기기는 '파악됨', 미등록은 '확인 필요'입니다. 보인 VLAN ID는 내보내기의 vlans 열 등에도 나옵니다.

sudo roamswitch-sensor refresh
roamswitch-sensor device-inventory
sudo roamswitch-sensor device-note aa:bb:cc:dd:ee:ff "3F copier"

6.3 의심스러운 동작의 참고 정보(모두 탐지 전용)

수동 캡처(§6.1, 옵트인)를 활성화하면 다음 참고 정보를 제시합니다. 모두 탐지와 표시만 하며, Sensor가 통신을 차단하는 일은 없습니다.

6.4 보이지 않는 범위(커버리지) 표시

수동 감시는 아무것도 들리지 않는 상태와 조용한 네트워크를 그대로는 구별하지 못합니다. Sensor는 스스로 관측할 수 있었던 것만 세어, 보이지 않는 범위를 '이벤트 없음'으로 착각하지 않도록 합니다. 새로운 통신도 새로운 소켓도 만들지 않습니다. 기본으로 켜져 있습니다.

세는 원인의 예는 수동 캡처를 열 수 없음, 30초 이상 멈춤, 수신이 5회 연속 실패, 5분간 프레임이 없고 링크도 끊김, 커널의 폐기(최근 10분), 2048바이트를 넘는 프레임, 헤더를 읽을 수 없는 프레임 등입니다. ARP 테이블을 읽을 수 없는 회차는 기준을 지우지 않고 셉니다.

할 수 없는 것 셀 수 있는 것은 Sensor가 스스로 관측할 수 있는 것뿐입니다. 미러 포트 설정 실수처럼 수신은 정상이지만 도착하는 프레임이 치우쳐 있을 뿐인 경우는 구별하지 못합니다. 5분간 프레임이 없고 링크는 살아 있는 경우(capture_silent, info)에는 '조용함'과 '들리지 않음'을 구별할 수 없다고 그대로 표시합니다.

7. CLI 명령어 빠른 참조

명령어 기능 개요
roamswitch-sensor status Sensor 자신의 공개 키·IP 주소·MAC 주소, 페어링 수·ARP 이벤트 수·대기 중인 감사 요청 수, 제어 API의 TLS 상태를 표시
roamswitch-sensor issue-code 1회용 페어링 코드를 발급(10분간 유효). Sensor의 인증서 핑거프린트도 표시
roamswitch-sensor list 페어링된 단말의 목록을 표시
roamswitch-sensor pair <public-key> [--addr <IP>] [--name <name>] --confirm 공개 키와 주소를 직접 지정해 단말을 수동으로 페어링(일반적으로는 issue-code를 사용해 단말 측에서 자동으로 페어링하게 하는 편이 간편합니다)
roamswitch-sensor unpair <public-key> 페어링 해제
roamswitch-sensor scan <public-key> 페어링된 단말에 능동적 취약점 감사를 실행
roamswitch-sensor history [public-key] 감사 이력을 표시(공개 키를 생략하면 전체 단말)
roamswitch-sensor report <public-key> [--out <file>] 가장 최근 감사 결과를 Markdown 리포트로 출력
roamswitch-sensor arp-events 탐지된 ARP 이벤트(신규 기기·스푸핑 의심)를 표시
roamswitch-sensor pairing show / tls show 제어 API의 TLS 상태(모드·핑거프린트·평문 연결 경고·수신 대기 IP·구 v1 서명 허용 여부)를 표시(pairing show와 tls show는 동일한 내용)
roamswitch-sensor tls rotate TLS 인증서를 재생성(이전 핑거프린트의 핀은 모두 무효가 되며 단말 측에서 재핀 고정이 필요)
roamswitch-sensor refresh LAN 상의 기기를 지금 즉시 재스캔(ARP 스윕)하여 기기 대장을 갱신
roamswitch-sensor device-inventory 기기 대장(LAN 상에서 관측한 모든 기기·온라인 상태·메모)을 표시
roamswitch-sensor device-note <MAC> [note] 기기에 메모를 등록(메모를 생략하면 삭제)
roamswitch-sensor passive-events / iot-events / network-threats / iot-advisories 수동 캡처에서 유래한 각 이벤트(신규 기기·악성 IP로의 연결 / IoT 기기의 동작 / 의심스러운 통신 / IoT 취약점 정보)를 표시
roamswitch-sensor lan-overview [--json]
roamswitch-sensor network-threats --json [--limit N] [--min-severity …]
LAN 전체의 상태(기기 수·VLAN·위협 건수 등)와 위협 목록을 표시합니다. --json으로 JSON을 출력합니다(--limit은 최대 500). 둘 다 읽기 전용이며 root가 아니어도 실행할 수 있습니다. PersonalSOC와 Linux 버전 MCP가 읽습니다.
roamswitch-sensor config [show | set <키> <값>] 설정의 표시·변경(정기 감사·알림·보존 기간·컬렉터·제어 API·탐지 데이터 취득·언어). control.bind_addr와 control.tls는 데몬 재시작 시 반영되며, 그 외에는 재시작이 필요 없음(§11.8)
roamswitch-sensor diff [공개 키] 이전 감사와의 차이 표시(신규 발견·해소·새로 열린 포트·도달 불가 의심)
roamswitch-sensor export <scans|inventory|audit-log|unmanaged|all> … 감사 증적을 CSV / JSON / 인쇄용 HTML로 내보내기
roamswitch-sensor audit-log [verify] 작업·승인 로그 표시. verify로 해시 체인 변조 감지
roamswitch-sensor notify-test 설정한 알림 대상(Webhook / syslog)에 테스트 알림을 보내 연결 확인
roamswitch-sensor audit-unmanaged <IP|MAC> --confirm
roamswitch-sensor unmanaged-audits
RoamSwitch 미도입 기기의 경량 감사(연결 확인만). audit-unmanaged <IP 또는 MAC> --confirm으로 수동 실행, unmanaged-audits [--detail]로 결과 목록(§13)
roamswitch-sensor design-hypotheses [鍵] --llm 名前 최신 design_flaw 결과로 선택한 AI 도구가 확인되지 않은 추측을 쓰게 합니다(§5.2). --llm·--model·--timeout·--show-prompt
roamswitch-sensor lockdown [status | on | off] 중지 상태 표시(status), 중지(on --reason 사유), 해제(off). 페어링·감사·전송·알림을 모두 멈춥니다(§14)
roamswitch-sensor decommission --confirm 이 Sensor의 키와 저장된 데이터를 삭제하고 중지합니다(되돌릴 수 없음). 감사 로그만 남기고, 페어링했던 단말 목록과 해제 방법을 표시합니다(§14)

CLI는 일본어 / 영어에만 대응합니다(LANG 환경 변수를 따릅니다).

8. TUI 조작 가이드

대화형 TUI(roamswitch-sensor-tui)는 10개 언어를 지원하며 CLI와 설정의 모든 것을 조작할 수 있습니다(m으로 기능 목록). 주요 6개 탭(페어링 완료·네트워크 구성·ARP 이벤트·감사 이력·차이·작업 로그)은 Tab으로 전환합니다. 차이는 신규를 빨강, 해소를 초록, 도달 불능 의심을 노랑으로 표시합니다.

키 동작
Tab탭 전환
↑↓ / j k항목 선택
c페어링 코드를 발급(10분간 유효). 화면에는 단말 측에서 실행할 명령 sudo roamswitch sensor pair --addr <이 Sensor의 IP> --code <코드> --fingerprint <핑거프린트>가 실제 값이 채워진 상태로 표시됩니다
u페어링 해제
s선택 중인 단말에 능동적 취약점 감사를 실행
a(네트워크 구성 탭) 선택한 기기를 경량 감사(확인 화면 있음, §13). 결과는 메뉴의 '미도입 기기 감사' 탭
K이 Sensor의 중지/해제(확인 화면 있음, 중지 중에는 화면 하단에 빨간 표시). 폐기는 메뉴에서(§14)
n(네트워크 구성 탭) 선택한 기기에 이름·용도·위치 등의 메모를 등록(메모가 있는 기기는 '파악됨'으로 취급)
r지금 LAN 기기를 다시 스캔(ARP 스윕, 기본적으로 1시간마다 자동 실행)
e감사 증적을 내보내기(감사 결과·기기 대장·작업 로그의 CSV, HTML 보고서, JSON). 양식에서 내용·형식·단말·시작일·저장 위치를 지정할 수 있으며 표시 언어(10개 언어)로 생성됩니다. 기본 저장 위치는 ~/.local/state/roamswitch-sensor/이고, 소유자만 읽을 수 있는 새 파일(기존 파일은 덮어쓰지 않습니다)로 생성되며, 내보냈다는 사실 자체도 작업 로그에 기록됩니다
p수동 페어링(공개 키와 주소를 입력 → 확인 화면 → 실행). 양식에 단말 측에서 핀 고정할 Sensor의 TLS 핑거프린트가 표시됩니다
TTLS·페어링 상태(모드·핑거프린트·평문 연결 경고·수신 대기 IP·구 v1 서명 허용 여부). R로 인증서를 재생성(영향을 설명하는 확인 화면 포함)
C설정 편집기(모든 설정 키를 표시·변경. 웹훅 URL은 항상 가려서 표시. 재시작이 필요한 키는 명시)
N알림 테스트(전송 대상별 성공 여부를 표시. URL은 가려서 표시)
m기능 목록 메뉴(수동 모니터링·IoT 동작·의심스러운 통신·IoT 취약점 정보·상태 i·컬렉터 관리 등)
O컬렉터 관리(컬렉터의 데이터 디렉터리가 있는 호스트에서만). Sensor의 등록·폐기·목록·읽기 토큰·감사 로그 이상의 해제. 컬렉터 자체의 알림 전송처 설정은 n
f / l / v(감사 이력 탭) 단말별 필터링. (작업 로그 탭) l로 표시 건수를 변경, v로 해시 체인을 재검증
Enter선택한 행의 상세 표시(감사 이력·변경·ARP 이벤트·기기·작업 로그)
w(상세 표시 중) 보고서를 저장 위치를 지정하여 파일로 내보내기(표시 언어로 생성)
L표시 언어를 선택(language 설정에 저장되며, 데몬이 출력하는 알림·로그의 언어에도 반영됩니다)
q종료

9. 신뢰 모델 & 보안 설계

10. 문제 해결 & FAQ

Q1. 페어링 코드를 입력해도 거부됩니다.

원인은 네 가지를 생각할 수 있습니다. (1) 발급 후 10분이 지났다(issue-code로 재발급). (2) 입력 오류. (3) --addr의 IP가 Sensor의 고정 IP와 다르다. (4) --fingerprint가 인증서와 다르다(roamswitch-sensor pairing show로 확인). 오류가 계속되면 rate_limited로 잠깁니다.

Q2. NSE 보완 진단 결과가 비어 있습니다.

원인은 다음 둘 중 하나입니다. (1) 컨테이너에 nmap이 설치되어 있지 않다. (2) 실행은 되었지만 대상 포트에 해당하는 안전한 스크립트의 출력이 실제로 없었다. nmap NSE 보완 진단은 호스트에 nmap이 설치되어 있으면 자동으로 실행됩니다.

Q3. 감사가 완료될 때까지 얼마나 걸립니까?

전체 포트 스캔만이라면 수십 초 정도입니다. 호스트에 nmap이 설치되어 있으면 NSE 보완 진단이 자동으로 더해져, 대상의 열린 포트 수에 따라 최대 2분 정도 걸릴 수 있습니다. TUI에는 실행 중 경과 초가 계속 표시되므로 진행 상황을 확인할 수 있습니다.

Q4. 페어링했는데도 감사를 실행할 수 없습니다.

원인은 다음 네 가지를 생각할 수 있습니다. (1) 단말 쪽에서 sensor_pairing_enabled: true로 하지 않았다(기본 OFF). (2) Sensor의 고정 IP가 바뀌었다(재페어링 필요). (3) Sensor 쪽에서 unpair되었다. (4) 인증서를 다시 만들어 단말의 핀이 오래되었다(roamswitch sensor repin). 양쪽 목록에서 서로의 등록을 확인하십시오.

Q5. Sensor 자체는 RoamSwitch 본체(Client/Server Edition)와 함께 사용할 수 있습니까?

네. Sensor는 자기 방어 기능이 없는 설계이므로, 동일 머신에 RoamSwitch for Linux Server Edition을 함께 설치할 것을 권장합니다. 두 프로세스는 완전히 독립된 프로세스·데이터 저장소로 동작하며 충돌하지 않습니다.

Q6. roamswitch sensor results가 「페어링이 해제되었습니다」라고 표시됩니다.

Sensor 측에서 이 단말의 페어링이 unpair로 해제되었습니다. Sensor 운영자에게 새 페어링 코드를 발급받아, roamswitch sensor pair --addr <IP> --code <코드> --fingerprint <SHA-256>로 다시 페어링해 주십시오.

11. 조직 규모 감사 운영 기능 (옵트인)

대규모 조직의 보안 담당자가 감사 증적과 변화 파악을 위해 사용하는 기능 모음입니다. 모두 초기 상태에서는 꺼져 있으며, Lafine이나 제3자에게는 아무것도 전송되지 않습니다. 알림·집계 대상은 모두 운영자가 설정한 자사 조직의 것입니다. 설정은 sudo roamswitch-sensor config set <키> <값>으로 하며(데몬 재시작 불필요, 변경 내용은 작업 로그에 기록됨) config show로 현재 값을 확인할 수 있습니다.

11.1 정기 감사와 이전 감사와의 차이

schedule.enabled를 true로 하면 페어링된 모든 단말을 정기적으로 감사합니다(기본 24시간마다). 이전과의 차이는 roamswitch-sensor diff로 확인할 수 있습니다. 열려 있던 포트가 모두 보이지 않게 되면 정지 중인 것과 구별할 수 없으므로 도달 불능 의심으로 처리합니다.

무인 감사에서도 「합의한 단말만 감사한다」는 보증은 깨지 않습니다. 단말이 마지막으로 인증한 시점의 MAC을 저장해 두고, 감사 전후에 같은 MAC이 그 IP에서 응답하는지를 nmap의 ARP로 확인합니다. 다르면 감사하지 않고(또는 결과를 폐기하고) 알립니다.

다른 VLAN의 단말은 기본적으로 대상이 아닙니다. schedule.allow_routed_endpoints(기본 꺼짐)에서는, 서명된 요청이 schedule.routed_proof_minutes(기본 30분, 5~1440) 이내에 같은 주소에서 도착했는지 등으로 확인합니다.

동작하지 않는 이유(nmap 없음, 주소가 없는 단말, 본인 확인 결속이 없는 단말)는 status의 “보이는 범위”에 경고로 표시됩니다. 알림 대상이 있으면 coverage_gap이 한 번 전달되고, 해소되면 coverage_restored가 전달됩니다. 락다운 중과 시간대 밖에서는 경고로 하지 않고 status에 한 줄을 표시합니다.

11.2 알림 (Webhook·syslog)

notify.webhook_urls와 notify.syslog.host(RFC 5424, UDP 또는 TCP)로 리그레션·신규 기기·ARP 스푸핑 등을 보냅니다. notify.min_severity와 재전송 간격으로 좁힐 수 있고, roamswitch-sensor notify-test로 연결을 확인할 수 있습니다.

status에 알림 대상과 마지막 전달 결과가 표시됩니다. 전달에 실패하는 동안은 경고가 표시되므로 roamswitch-sensor notify-test로 확인합니다. 성공하면 경고는 사라집니다.

11.3 감사 증적 내보내기

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out 파일] [--endpoint 공개 키의 앞부분] [--since 날짜]. html은 브라우저에서 PDF로 저장할 수 있습니다. CSV는 수식 주입에 대한 대책이 되어 있습니다. 출력은 0600이며, 내보내기 자체도 작업 로그에 남습니다. TUI에서는 e 키로 같은 지정을 할 수 있습니다.

11.4 작업·승인 로그 (변조 감지)

페어링·감사·설정 변경·거부한 접근을 실행자와 함께 기록합니다. 각 행이 직전 행의 SHA-256을 포함하는 해시 체인이며, 변조는 roamswitch-sensor audit-log verify로 알 수 있습니다(이상이면 종료 코드 2). Webhook URL의 값은 남기지 않습니다. 끝부분 삭제에 대비해 컬렉터(§11.6)에도 선두를 보냅니다.

11.5 보존 기간

retention.scan_history_days·retention.audit_log_days·retention.inventory_stale_days에 일수를 설정하면 오래된 감사 이력·작업 로그·오랫동안 보이지 않는 기기를 자동으로 삭제합니다(0 = 기간으로는 삭제하지 않음, 기본값). 메모를 등록한 기기는 대장에서 삭제되지 않습니다.

11.6 여러 Sensor 집계 (중앙 컬렉터, 선택 사항)

여러 거점에서 여러 Sensor를 운영하는 경우, 별도 호스트에서 roamswitch-sensor-collector(패키지에 포함, 기본 비활성)를 실행해 각 Sensor의 서명된 요약을 수집합니다.

# On the collector host (a separate host from the Sensor is recommended)
sudo systemctl enable --now roamswitch-sensor-collector   # listens on 127.0.0.1:8443 by default
sudo roamswitch-sensor-collector token                     # read token for the dashboard
sudo roamswitch-sensor-collector enroll <Sensor public key> --name Tokyo --site Tokyo

# On each Sensor
sudo roamswitch-sensor config set collector.url https://collector.example.org:8443
sudo roamswitch-sensor config set collector.enabled true
# On the collector host: where the collector's own alerts go
echo 'https://hooks.example.org/…' | sudo roamswitch-sensor-collector notify set --add-webhook - --min-severity high
sudo roamswitch-sensor-collector notify set --syslog-host 192.0.2.10 --syslog-protocol tcp
sudo roamswitch-sensor-collector notify show   # a Webhook URL is shown up to its host only
sudo roamswitch-sensor-collector notify test

컬렉터가 이력(scans.jsonl·events.jsonl)을 읽지 못했을 때는 「데이터 없음」으로 오인하지 않도록, 읽지 못한 분량을 셉니다. 손상된 행은 그 행만 건너뛰고, 날짜를 읽을 수 없는 행은 정리에서 지우지 않습니다. 결과는 /api/overview의 storage_health, 대시보드, 시작 시 로그에 나옵니다. 새로운 통신은 하지 않습니다.

11.7 탐지 데이터 취득(updates.fetch_cve_map)

Sensor는 서명된 CVE 맵(능동 진단에 사용하는 알려진 취약점 데이터)과 nmap NSE 데이터베이스를 업데이트 서비스에서 매일 가져옵니다. 이 통신에는 기기·감사 데이터가 포함되지 않습니다. 완전 오프라인으로 운용하는 경우에는 sudo roamswitch-sensor config set updates.fetch_cve_map false를 실행하십시오(변경은 재시작 없이 다음 주기부터 반영되며, 이후에는 기본 제공 데이터만 사용합니다).

11.8 설정 키 목록

roamswitch-sensor config show로 현재 값을 확인하고, config set <키> <값> [<키> <값> …]로 변경합니다(여러 키는 원자적으로 저장되며, TUI에서는 C의 설정 편집기에서도 변경할 수 있습니다). 「재시작」 열이 「필요」인 키만 데몬 재시작(sudo systemctl restart roamswitch-sensor)으로 반영됩니다.

키 형식 / 가능한 값 기본값 재시작
sitestring(empty)불필요
languageja | en | ko | zh-Hans | zh-Hant | de | fr | es | it | pt-PT(empty = system locale)불필요
schedule.enabledboolfalse불필요
schedule.interval_hoursint24불필요
schedule.window_start_hourint 0–23(unset = always)불필요
schedule.window_end_hourint 0–23(unset = always)불필요
schedule.max_parallelint 1–81불필요
schedule.allow_routed_endpointsboolfalse불필요
schedule.routed_proof_minutesint 5–144030불필요
notify.webhook_urlsURL list(empty)불필요
notify.min_severityinfo | medium | high | criticalmedium불필요
notify.cooldown_minutesint30불필요
notify.syslog.hoststring(empty = off)불필요
notify.syslog.portint514불필요
notify.syslog.protocoludp | tcpudp불필요
retention.scan_history_daysint (0 = never prune)0불필요
retention.audit_log_daysint (0 = never prune)0불필요
retention.inventory_stale_daysint (0 = never prune)0불필요
collector.enabledboolfalse불필요
collector.urlURL(empty)불필요
collector.push_interval_minutesint15불필요
collector.send_unmanaged_devicesbooltrue불필요
collector.send_unmanaged_auditsboolfalse불필요
collector.probe_control_portboolfalse불필요
control.bind_addrIP address0.0.0.0필요
control.tlsoff | optional | requiredoptional필요
control.allow_legacy_signaturesbooltrue불필요
updates.fetch_cve_mapbooltrue불필요
control.listen_ipv6boolfalse필요
capture.rcvbuf_mbint 0–256 (MiB, 0 = system default)4필요
dhcp.active_probebooltrue불필요
dhcp.allowed_serversMAC / IP list(empty = learn the first)불필요
ipv6.enabledbooltrue불필요
ipv6.active_probebooltrue불필요
ipv6.allowed_routersMAC / IP list(empty = trust the IPv4 gateway)불필요
unmanaged_audit.enabledbool (needs authorization + allowed_cidrs first)false불필요
unmanaged_audit.authorizationstring(empty)불필요
unmanaged_audit.allowed_cidrsCIDR list (IPv4 ≤ /16 and IPv6 ≤ /48 refused)(empty)불필요
unmanaged_audit.excludeIP / CIDR / MAC list(empty)불필요
unmanaged_audit.interval_hoursint168불필요
unmanaged_audit.max_parallelint 1–42불필요
unmanaged_audit.product_checkbool (needs unmanaged_audit.enabled)false불필요
unmanaged_audit.noauth_checkbool (needs unmanaged_audit.enabled)false불필요
design_flaw.enabledboolfalse불필요
design_flaw.llm.toolclaude | opencode | codex | agy | (empty)(empty)불필요
design_flaw.llm.modelstring(empty)불필요
design_flaw.llm.timeout_secsint (0 or 5–600)0불필요
security.on_revokedlockdown | wipe | nonelockdown불필요
security.lockdown_after_offline_daysint (0 = off)0불필요

12. 불법 DHCP·IPv6 탐지

반입된 라우터 등이 정규 장비인 척하며 단말의 통신 경로를 가로채는 공격을 찾아냅니다. 탐지와 알림만 하며, 통신은 차단하지 않습니다. 기본적으로 활성화되어 있고 수동 캡처는 필요 없습니다. 결과는 roamswitch-sensor network-threats, TUI, 알림, 로그, 내보내기에 나옵니다.

12.1 불법 DHCP 서버(IPv4·DHCPv6)

1시간마다 무작위 MAC으로 DHCP 탐색을 하나만 보내 응답한 모든 서버를 셉니다. REQUEST는 보내지 않으며 주소를 빌리지 않습니다. 처음 응답한 서버를 정규로 학습하고, 나중에 나타난 서버를 알립니다. 다른 게이트웨이나 DNS를 배포하는 것은 critical입니다.

12.2 IPv6(불법 라우터 광고·NDP 스푸핑·IPv6에서만 보이는 기기)

불법 라우터 광고: IPv4 게이트웨이와 다른 기기가 IPv6 라우터로 동작하면 알립니다(정상 구성이면 ipv6.allowed_routers에 등록). 홉 리밋이 255가 아닌 광고는 무시합니다. NDP 스푸핑: IPv6 주소의 MAC이 바뀌면 알립니다(라우터면 high). IPv6에서만 보이는 기기: 이웃 테이블에만 나타난 기기를 보고합니다.

12.3 무엇을 정상으로 볼지와 설정

dhcp.allowed_servers와 ipv6.allowed_routers를 설정하면 그 이외의 응답을 모두 보고합니다(비어 있으면 처음 것을 학습). ipv6.enabled로 IPv6 감시를 끌 수 있습니다. 제어 API(50543)의 IPv6 대기는 control.listen_ipv6(기본값 false)로 추가합니다. 글로벌 IPv6는 인터넷에서 도달할 수 있으므로 기본적으로 비활성화되어 있습니다.

13. RoamSwitch 미도입 기기의 경량 감사(옵트인)

§5의 능동적 취약점 감사는 페어링하여 합의한 단말만 대상입니다. 페어링하지 않은 프린터·카메라·NAS 등에서 「무엇이 외부에 열려 있는가」를 확인하고 싶다면, 훨씬 한정된 별도의 검사를 쓸 수 있습니다. OpenVAS 같은 깊은 진단, 로그인 시도, 취약점 악용, nmap NSE, 전체 포트 스캔은 합의한 단말에만 합니다.

13.1 하는 일

정해진 55개 포트에 대한 TCP 연결 확인, 열린 포트가 스스로 보내는 표시(배너)의 읽기(웹에는 HEAD /를 1회), 공개된 취약점의 주석만 합니다. 결과는 「LAN에서 닿는다」이지 「취약하다」라고는 하지 않습니다. 제품 확인과 인증 확인은 각각 별도의 옵트인입니다(기본 꺼짐).

13.2 켜기

활성화하기 전에 unmanaged_audit.authorization(승인자)과 unmanaged_audit.allowed_cidrs(범위. IPv4는 /16, IPv6는 /48보다 넓으면 거부)를 설정합니다. 정기 실행은 기본 168시간마다이며, 수동 실행에는 --confirm이 필요합니다.

sudo roamswitch-sensor config set unmanaged_audit.authorization "IT policy 2026-07, approved by A. Suzuki"
sudo roamswitch-sensor config set unmanaged_audit.allowed_cidrs 192.168.10.0/24
sudo roamswitch-sensor config set unmanaged_audit.exclude 192.168.10.1
sudo roamswitch-sensor config set unmanaged_audit.enabled true
sudo roamswitch-sensor audit-unmanaged 192.168.10.40 --confirm
roamswitch-sensor unmanaged-audits --detail

13.3 지켜지는 것

allowed_cidrs 밖의 기기, unmanaged_audit.exclude에 있는 기기, 페어링된 단말, Sensor 자신은 어떤 경우에도 조사하지 않습니다. 전후에 MAC을 확인하여 다른 기기라면 중단하거나 결과를 폐기합니다. authorization의 문면은 실행할 때마다 로그에 남습니다.

13.4 제품 확인(CISA KEV에 오른 취약점이 있는 제품인가. 옵트인)

unmanaged_audit.product_check(기본 꺼짐)는 기기의 웹 화면에서 제품명을 읽고 CISA KEV 취약점이 있는지 알려 줍니다. 보내는 것은 웹용 포트(80·8080·8181·443·8443·10443)로의 GET /과 리다이렉트(최대 2회)뿐입니다. 로그인, 비밀번호 시도, 추측한 경로, 취약점을 노리는 입력은 보내지 않습니다. 기기 1대당 최대 12회 요청, 150밀리초 간격입니다.

제품의 표지가 같은 응답에서 모두 확인될 때만 제품명을 지목합니다. 기기가 알린 버전에 NVD 영향 범위의 CVE가 있으면 '해당'(high), 버전을 읽을 수 없으면 '미확인' 주의(medium)로 표시하며, 취약하다고는 말하지 않습니다. 버전을 읽을 수 있는 것은 MikroTik RouterOS뿐입니다. 대응 제품은 Fortinet FortiGate, Ivanti Connect Secure, Citrix NetScaler 등입니다. 표지는 공개된 탐지 시그니처에 기반하며 실제 기기에서는 확인하지 않았습니다.

KEV 사본은 동봉되어 있으며, product_check와 updates.fetch_cve_map가 둘 다 활성화된 경우에만 24시간마다 CISA의 공개 피드 1개 파일을 가져옵니다(LAN 정보는 일절 보내지 않습니다).

인증 없이 응답하는지 확인(unmanaged_audit.noauth_check. 기본 꺼짐, 옵트인) 열려 있던 다음 포트에만 읽기 전용 요청을 하나씩 보냅니다. Redis(6379, PING), Memcached(11211), Docker API(2375), Elasticsearch(9200), etcd(2379), CouchDB(5984), kubelet(10250), ZooKeeper(2181), Ollama(11434)입니다. 쓰기, 설정 변경, AUTH, 비밀번호 전송이나 추측, 로그인은 하지 않습니다.

MongoDB·MySQL 등은 시도가 로그인이 될 수 있으므로 조사하지 않습니다. 결과는 '인증 없이 응답함', '인증 필요', '거부됨', '판단 불가' 중 하나입니다. 경량 감사와 같은 동의 아래에서만 동작합니다. 직접 관리하는 기기에만 사용하십시오.

14. 분실·도난·폐기 시

Sensor에는 단말별 취약점 목록, 페어링된 단말의 주소, 서명 키가 들어 있습니다. 또한 페어링한 단말은 이 Sensor를 '포트 스캔을 허용한 상대'로 취급하므로, 도난당한 Sensor가 같은 LAN에 연결되면 그 상대로 행세할 수 있습니다. 다음 장치로 막습니다.

14.1 컬렉터에서의 폐기와 락다운

roamswitch-sensor-collector revoke <공개 키> --reason 이유로 폐기하면 해당 Sensor의 전송은 403 sensor_revoked로 거부됩니다. 폐기를 알게 된 Sensor는 스스로 정지(락다운)하여 감사·전송·알림·탐색을 모두 멈춥니다. 정지는 재시작 후에도 이어지며 데이터는 남습니다. 소유자의 손에 있다고 확실할 때만 roamswitch-sensor lockdown off로 해제할 수 있습니다.

14.2 삭제·폐기·오프라인 감지

security.on_revoked를 wipe로 하면, 폐기 시 키·TLS 키·설정(Webhook URL 포함)·단말 목록·감사 결과·기기 대장을 0으로 덮어쓰고 삭제합니다. 조작·승인 로그만은 증거로 남깁니다. 기본값인 lockdown은 정지만 합니다. security.lockdown_after_offline_days(기본 0=비활성)로, 오래 전송하지 못하는 Sensor도 스스로 정지합니다.

14.3 이 장치로 할 수 없는 것

단말은 각자가 해제할 때까지 이 Sensor를 계속 신뢰하며, Sensor 쪽에서는 알릴 수 없습니다. 표시된 각 단말에서 Linux는 roamswitch sensor unpair <이 Sensor의 공개 키>, Mac은 설정 > Sensor > 페어링 해제를 실행하십시오. 전원이 꺼진 채 반출된 Sensor에는 정지 지시가 닿지 않으므로, 디스크 암호화(LUKS 등)가 실질적인 방어입니다. 덮어쓰기 삭제는 플래시나 CoW에서는 완전한 삭제를 보장하지 않습니다.

← Server Edition 운영 매뉴얼 Linux판 도입 페이지로 →