OpenPanopticon은 Shodan, OpenSky, OpenStreetMap 등 공개 데이터 소스를 지도에 겹쳐 보여주는 로컬 실행형 지리정보 뷰어다. 3D 지구본에서 항공기와 위성, 네트워크 장비, 공개 카메라, 기상·재난 정보 등을 살펴볼 수 있으며, 센서 화면을 흉내 내는 시각 효과도 제공한다. 설치 없이 이용하는 라이브 데모와 소스 코드는 GitHub 저장소에서 확인할 수 있다.

실행과 설정

직접 실행하려면 Node 22 이상이 필요하다. 실행에 필요한 런타임 의존성은 따로 설치하지 않아도 된다. 저장소를 내려받은 뒤 .env.example을 .env로 복사하고, Shodan의 SHODAN_API_KEY를 설정한다. 이 키가 주요 Shodan 레이어에 필요하며, 나머지 키는 선택 사항이다. ZIP으로 받으면 폴더 이름은 OpenPanopticon-main이다.

  • Linux·macOS에서는 ./start.sh를 실행한다. ZIP에서 실행 권한이 빠졌다면 bash start.sh를 사용한다.
  • Windows에서는 START.bat을 실행한다.
  • 직접 시작하려면 npm start 또는 node server.js를 실행한다.

시작 스크립트는 Node 버전을 확인하고 서버가 응답하면 브라우저를 연다. 직접 접속할 주소는 http://127.0.0.1:8420/이다. 처음 실행할 때 .env가 없으면 시작 스크립트가 생성한다.

기본적으로 지구본은 실행 기기의 공개 IP를 바탕으로 찾은 위치를 중심으로 연다. 위치는 도시 수준에서만 대략 맞을 수 있고, 모바일이나 VPN에서는 틀릴 수 있다. 사이드바의 저장 위치 설정에서 현재 화면, 좌표 또는 기기의 위치를 홈으로 지정할 수 있다. 고정한 홈은 해당 브라우저의 로컬 저장소에 보관되며 서버로 전송되지 않는다. 홈을 지정하지 않으면 시작 때 위치를 확인하고 실패하면 Austin을 사용한다.

데이터와 화면 조작

지구본에는 Shodan이 색인한 현재 화면 범위의 호스트, OpenSky 항공기, CelesTrak 위성, OpenStreetMap 시설물, 공개 카메라, AIS 선박, 재난·위험 정보, 위성 영상과 센서 데이터 등을 레이어로 표시할 수 있다. 일부 레이어는 API 키가 있어야 켜진다. SHODAN_API_KEY 외에 OpenSky, GreyNoise, Cesium Ion 키는 기존 레이어를 보완하고, AIS, OpenCelliD, WiGLE, Windy, OpenWebcamDB, FIRMS, 511, EIA, Cloudflare Radar, CARTO 라벨은 각각의 레이어를 활성화한다. 허가된 RSOE EDIS 피드에는 EDIS_API_URL과 EDIS_API_KEY가 필요하다. Google 서비스 계정은 선택형 Earth Engine 바탕 지도에 사용한다.

공개 데이터 출처와 레이어의 주요 내용은 다음과 같다.

  • Shodan: 화면 범위에서 색인된 모든 호스트를 표시한다. 서비스 종류나 알려진 CVE에 따라 색을 구분할 수 있다.
  • OpenSky·adsbdb: 항공기 위치, 호출부호, 고도, 방향, 수직 속도와 이동 경로를 표시한다. 경로는 최근 2분을 유지한다. 항공기를 누르면 출발·도착 공항, 항공사와 기체 정보를 조회한다. 비상 코드 7500·7600·7700도 표시한다.
  • RainViewer·NASA GIBS: 강수 레이더와 구름 영상 레이어를 제공하며, 약 2시간 전부터 현재와 단기 예측까지 시간대를 움직여 볼 수 있다. GOES-East GeoColor 구름 영상은 미주와 대서양을 대상으로 한다.
  • CelesTrak: 24개 위성 목록 그룹을 제공한다. 브라우저에서 satellite.js로 SGP4 전파를 계산하며, 위성을 선택하면 한 바퀴 도는 동안의 지상 궤적을 그린다.
  • Overpass·OpenStreetMap: 감시 카메라, 군사 시설, 통신탑, 발전소·변전소, 비행장, 항구, 정부·외교 시설, 응급 서비스, 데이터센터, 연료 저장 시설 등 10개 항목을 켜고 끌 수 있다. DeFlock 자료로 표시하는 번호판 인식 카메라는 업체별 필터와 방향이 알려진 카메라만 보는 필터를 제공한다.
  • GDACS, NASA EONET, USGS, NWS, NASA FIRMS: 현재 화면의 재난·위험 정보를 한 형식으로 표시하고 심각도에 따라 색을 구분한다. 적색 단계 이벤트는 지구본에서 점멸하며, 영향 범위가 있는 사건은 다각형으로 표시한다. FIRMS에는 무료 키가 필요하다.
  • NYC DOT, ALERTCalifornia, Windy, OpenWebcamDB: 공개 카메라를 제공한다. 운영자가 플레이어를 제공하면 상세 패널에 삽입하고, 그렇지 않으면 일정 간격으로 정지 화면을 갱신한다. ALERTCalifornia는 키 없이 약 1,290대의 산불 감시용 PTZ 카메라를 제공한다.
  • AISStream: 선박의 실시간 위치, 방향, 속도, 항해 상태, 목적지와 크기를 제공한다. AIS WebSocket 연결과 키는 서버가 관리한다.
  • RIPE Atlas, OpenCelliD, WiGLE, Onionoo: 측정 장비, 추정 범위가 표시된 기지국, Wi-Fi·Bluetooth 조사 지점, 국가별 Tor 중계 용량을 보여준다. Sensor.Community는 시민이 운영하는 대기질·소음 센서의 실시간 값을 표시한다.
  • 주 교통부의 511 피드는 카메라, 사고와 차선 폐쇄를 제공한다. FIVE_ELEVEN_KEYS에 주별 키를 추가할 수 있으며 24개 주 호스트가 미리 설정돼 있다. NASA GIBS 위성 영상은 일별 전 지구 컬러 영상, 야간 조명, 지표면 온도와 열 이상을 날짜별로 살펴볼 수 있다.
  • IODA, EIA, Cloudflare Radar, Raspberry Shake의 지역 신호는 인터넷 장애, 미국 전력 수요, Cloudflare 장애 주석, 주변 시민 지진계 정보를 사이드바에 표시한다.

GDACS는 지진·사이클론·홍수·화산·가뭄·산불의 전 세계 다중 재난 경보를 녹색·주황색·적색으로 제공하며 30일 범위를 다룬다. NASA EONET v3는 폭풍, 산불, 화산, 바다·호수 얼음 등의 자연 현상을 점·다각형으로 제공한다. USGS는 최근 24시간 지진과 깊이, 체감 보고, 쓰나미 표시를 제공하며 규모 6 이상은 적색, 4.5 이상은 주황색으로 표시한다. NWS는 다각형이 포함된 미국 경보만 지도에 그린다. FIRMS는 최근 48시간 VIIRS 산불 탐지 자료를 신뢰도와 복사열 출력에 따라 표시한다. RSOE EDIS는 라이선스가 있는 피드만 지원한다.

표시 옵션에는 OpenStreetMap 자료를 사용하는 CARTO 라벨이 있다. 2026년 9월 25일부터 CARTO 무료 키가 필요하며, 키를 CARTO_API_KEY로 설정하면 라벨이 기본 활성화된다. 키가 없으면 버튼은 비활성 상태로 남는다. 라벨 설정에서 글자색, 대비, 굵기를 바꿀 수 있고, 확대 수준에 따라 주요 도로부터 주거지 도로까지 표시한다. 지상 시설물은 타원체의 고정 높이가 아니라 지형에 맞춰 표시한다. CYCLE은 일정 간격으로 현재 화면의 항목 하나를 임의로 선택해 상세 패널에 연다.

레이어 선택·필터, 광학 모드, 오버레이, 라벨 스타일과 사이드바 상태는 localStorage에 저장돼 새로고침과 서버 재시작 뒤에도 복원된다. 이는 UI 설정만 저장하며 자격 증명, 조회 결과, 위치는 저장하지 않는다. 비공개 창 등에서 저장소를 사용할 수 없으면 기본값을 쓴다. 저장된 설정은 사이드바 아래쪽에서 초기화할 수 있다.

광학 모드는 실제 GLSL 후처리로 장면을 처리하며 1부터 5까지의 키로 선택한다. EO는 필터가 없는 화면이고, FLIR는 열화상 색상·자동 대비·센서 노이즈를, SAR는 후방 산란과 얼룩 잡음·거리선을, CRT는 곡면 왜곡과 주사 효과를 표현한다. CEL은 포스터화와 윤곽선을 적용한다. R은 모든 레이어를 다시 동기화하고, H는 화면 장식을 숨긴다. [는 사이드바를 접고 Esc는 상세 패널을 닫는다.

조회 한도와 캐시

화면 범위에 따라 조회하는 레이어는 기본적으로 고도 45km 위에서 새 데이터를 가져오지 않는다. 이 제한은 설정할 수 있으며, HUD의 FETCH를 눌러 45·100·250·500km로 바꾼다. 높이를 올리면 API 크레딧을 더 쓸 수 있다. 45km에서는 화면 범위가 약 40km에 불과하므로 도시 전체를 보는 일반적인 고도에서는 새 조회가 일어나지 않을 수 있다. 제한이 작동하면 FETCH에 HOLD ▲45km가 표시되고 각 레이어에는 현재 고도와 아래쪽 화살표가 나타난다. 이미 받은 데이터와 커버리지는 유지하며 카메라가 제한 고도 아래에 머물면 레이어가 다시 조회한다. 위성은 화면 범위를 조회하는 대신 궤도 요소로 위치를 계산하므로 예외다.

서버 캐시는 메모리와 providers/cache/에 저장돼 재시작 뒤에도 남는다. 위치 변환 결과는 메모리에만 보관한다. 파일 캐시는 시작 때와 6시간마다 정리하며 최장 보관 기간은 72시간이다. 화면 범위 조회는 고정 격자에 맞춰 요청 범위와 캐시 키를 함께 만든다. 브라우저는 화면 범위를 먼저 여유 있게 넓히고, 서버는 데이터 출처별 최대 범위에 맞춰 격자 칸을 덮는다. 출처별 한도는 VIEW_MAX_DEG로 정하며 휴대전화 기지국·Wi-Fi는 0.5도, OpenSky는 5도까지다. 너무 넓은 Overpass 조회는 시간 초과로 실패할 수 있어, 큰 범위에서는 중심 영역만 답하고 결과에 trimmed를 표시한다.

캐시 보관 기간은 자료 성격에 따라 다르다. 고정 시설물·Shodan 호스트·기지국 등 static 자료는 72시간, 궤도 요소는 orbit으로 24시간, 경보·위험·교통 사고·센서 값은 hazard로 1시간, 항공편 일정은 schedule로 30분, 레이더 프레임 목록은 live로 4분, 계정 잔액은 account로 1분 보관한다. 항공기와 선박의 실시간 위치는 서버에 캐시하지 않는다. 브라우저에서는 항공기 경로를 최근 2분간 유지한다.

항공편 일정은 호출부호와 UTC 날짜를 키로 삼고, 항공기를 눌렀을 때 실시간 조회한다. 일정은 30분 보관하며 조회 결과는 캐시도 갱신한다. 기체 정보는 변하지 않는 항공기 식별자로 캐시한다. 항공기 위치와 일정이 맞지 않으면 상세 패널에 불일치를 표시한다. 궤도 요소는 계속 변하고 CelesTrak이 2시간마다 갱신하므로, 오래된 요소로 계산하면 저궤도 물체 위치가 실제와 수십 km 어긋날 수 있다.

브라우저도 레이어별 기능 캐시를 두며, 항목은 최대 4,000개, 수명은 1시간이다. 이동 중에도 기존 점을 유지하고, 최근 조회 범위 안에서는 네트워크 요청 없이 다시 그린다. 기본적으로 화면에 30% 여유를 두고 조회하며 레이어에 따라 15~60%를 적용한다. 조회 조건을 바꾸면 캐시를 비우지만 색상이나 표시 방식만 바꾸면 캐시에서 즉시 다시 그린다. SYNC는 메모리·디스크 캐시를 건너뛰어 갱신하고, FLUSH는 브라우저 기능 캐시와 서버 응답 캐시까지 비운 뒤 다시 조회한다.

조회 실패 시 각 레이어는 30초, 60초, 90초, 120초, 300초, 이후 반복되는 1시간 간격으로 재시도한다. 제공처가 더 긴 대기 시간을 지정하면 그 시간을 따른다. 예를 들어 OpenSky는 표준 Retry-After가 아니라 X-Rate-Limit-Retry-After-Seconds를 사용하며 서버와 브라우저가 이를 존중한다. 대기 중에는 자동 조회를 막고, 건너뛴 시도는 단계에 포함하지 않는다. SYNC, 레이어를 껐다 켜기, 조회 조건 변경은 대기 단계를 초기화하고 즉시 새 요청을 보낸다. 재시도는 예약 당시 화면을 그대로 쓰지 않고 현재 카메라와 고도 제한을 다시 확인한다. 성공하면 대기 단계는 초기화된다.

OpenSky는 호출 빈도 제한이 아니라 하루 단위 크레딧을 사용한다. 익명 사용량은 IP당 400, 인증 사용량은 OPENSKY_CLIENT_ID와 OPENSKY_CLIENT_SECRET 설정 시 4,000, 활성 피더는 8,000이며 매일 00:00 UTC에 충전된다. 25제곱도 이내의 /states/all 요청은 크레딧 1개를 쓴다. 6초마다 조회하면 시간당 600회여서 4,000 크레딧은 7시간이 되기 전에 소진될 수 있다.

따라서 조회 간격은 남은 크레딧과 다음 충전까지의 시간에 따라 계산한다. 응답의 X-Rate-Limit-Remaining을 이용하며, 피드 갱신 주기보다 빠르게 요청하지 않고 최대 간격은 5분이다. 새 인증 크레딧을 가진 UTC 하루 시작 시점에는 약 20초 간격이 된다. 화면 이동으로 인한 중복 조회는 1도 격자로 줄이며, 브라우저 탭이 숨겨져 있을 때는 조회를 멈췄다가 돌아오면 한 번 갱신한다. OPENSKY_CREDIT_FLOOR는 기본값 60인 자동 조회 예약분으로, 사용자가 직접 조회할 크레딧을 남긴다. SYNC는 잔액과 무관하게 조회한다.

제공처·개인정보·사용상 주의

화면이 안정된 뒤 700ms가 지나면 브라우저가 현재 화면 범위의 레이어를 갱신한다. 화면 범위는 4도로 제한되고 각 데이터 출처도 별도 한도를 적용한다. Shodan은 검색마다 쿼리 크레딧을 사용하지만 이미 조회한 격자 안에서 움직이는 동안에는 결과를 재사용한다. 자동 조회를 멈추려면 상단의 AUTO를 HOLD로 바꾸고, 화면을 정한 뒤 SYNC를 누른다.

OpenWebcamDB는 비상업적 용도로만 무료이며 공간 필터가 없는 목록 경로를 사용한다. 약 1,500대 목록 전체를 한 번 페이지별로 가져와 72시간 캐시한 뒤 화면에 맞게 거른다. Overpass는 공유 서비스로 IP당 실행 슬롯이 약 2개다. 선택한 시설 유형은 하나의 통합 조회로 요청하고, 인프라와 ALPR 레이어는 요청 사이에 간격을 둔 직렬 큐를 공유한다. 429 응답이 오면 세 미러를 바꿔 시도한 뒤 대기하고, 사이드바에 재시도까지 남은 시간을 표시한다. Nominatim은 초당 1회 제한을 두며 검색을 지연 처리하고 메모리에 72시간 캐시한다. NWS 경보의 약 85%는 다각형 대신 예보 구역을 참조한다. 구역을 각각 조회하면 수백 건의 요청이 더 필요하므로 지도에는 그리지 않고 레이어 설명에 수를 표시한다.

이 프로그램은 데이터를 로컬에서 다루지만 익명 서비스는 아니다. 서버는 실행 기기의 IP로 각 제공처에 요청하며, 제공처는 IP와 조회 영역을 볼 수 있다. 지도 타일, Sentinel-2·NASA GIBS·RainViewer 영상, 웹캠, 항공기 사진, 설정된 Cesium Ion 영상과 지형은 브라우저가 직접 가져온다. /api/geoip는 기기의 공개 IP를 ipwho.is에 보내 위치를 확인하며 결과를 메모리에 30분 저장한다. 위치 지정 버튼은 캐시를 건너뛴다. Shodan·WiGLE 등 키가 필요한 서비스는 계정과 검색 내역을 연결할 수 있다. 디스크 캐시에는 조회 영역의 응답이 최대 72시간 남으며 FLUSH로 삭제할 수 있다. 캐시 키는 해시로 저장되지만 결과 데이터는 남는다. 장소명 검색은 디스크에 기록하지 않는다.

저장소는 모든 정보가 공개 API에서 왔다고 해서 어떤 이용이든 합법적이거나 현명한 것은 아니라고 경고한다. Shodan의 호스트 노출 정보는 연결 허가가 아니다. 소유하지 않은 시스템을 검색·접속하거나 기본 비밀번호를 시험하는 행위는 여러 관할권에서 범죄가 될 수 있다. 타인의 네트워크를 대상으로 한 공격 표면 조사에는 사전 서면 허가가 필요하다. WiGLE·OpenCelliD 자료로 특정인의 기기 위치를 알아내는 일도 일반적인 인프라 조사와는 다른 윤리·법적 문제를 낳는다. 카메라 레이어는 운영자가 공개한 카메라만 표시하며, 보안이 취약한 사설 카메라는 의도적으로 노출하지 않는다. Shodan에는 취약한 카메라가 포함될 수 있으므로 열람만 하고 접촉하지 말라고 안내한다.

재난 정보는 상황 파악용이지 생명 안전 판단용이 아니다. GDACS·EONET 자료에는 지연이 있고 앱도 데이터를 캐시하므로 실제 비상 상황에서는 지역 공식 경보를 따라야 한다. OpenStreetMap 자료는 자원봉사자가 제공해 불완전하거나 오래됐을 수 있으며, 표시가 없다고 시설이 없다는 뜻은 아니다. 항공기·위성 위치는 취미 수준의 정확도이므로 항법에 사용하지 말아야 한다.

OpenWebcamDB는 비상업적 이용만 허용한다. OpenSky와 OpenWebcamDB도 비상업적 조건이 있으며, Shodan·WiGLE 등은 재배포와 자동·대량 이용을 제한할 수 있다. 다른 사람을 위해 호스팅하거나 결과를 재배포하면 제공처 약관을 위반할 수 있으므로 각 약관을 확인해야 한다. 코드는 GPL-3.0-or-later이며, 포함된 public/providers/satellite.min.js는 별도의 MIT 라이선스를 따른다. OpenStreetMap 자료를 재게시할 때는 ODbL에 따른 출처 표시가 필요하다.

저장소는 Node 프록시 server.js가 서버 측 자격 증명을 보관하고 30개가 넘는 외부 API 응답을 정규화한다고 설명한다. 브라우저 쪽은 Cesium 지구본, 레이어, 광학 효과와 HUD로 구성되며, 테스트와 GitHub Pages용 정적 데모도 포함한다. Cesium Ion 토큰만은 Cesium이 브라우저에서 지형·영상을 가져오는 구조 때문에 예외적으로 브라우저에 전달된다. 제작자는 이 토큰을 공개 정보로 취급하고, Cesium Ion 계정에서 사용하는 자산에 대한 읽기 전용 권한으로 제한하라고 안내한다. 새 데이터 소스 추가 절차는 providers/README.md에 Sensor.Community를 예로 들어 설명돼 있다.