Hanium IoT Vulnerability Monitor (SBOMGuard)

클라우드에서 여러 대의 IoT 기기를 한 번에 관리하는 오픈소스 패키지 취약점 진단 솔루션입니다. Raspberry Pi에 올라간 경량 Collector가 기기의 소프트웨어 구성 명세(SBOM)와 네트워크 노출 정보를 수집해 클라우드로 보내면, 백엔드가 CVE 스캔·네트워크 스캔·AI 우선순위 분석을 수행하고 관리자용 React 대시보드로 결과를 보여줍니다.

한이음 드림업 2026 · 수행 기간 2026-04-01 ~ 2026-10-30

용도	URL
대시보드	https://sbomguard.site
API (프로덕션)	https://api.sbomguard.site

Raspberry Pi의 VPN join·SBOM 업로드는 EC2 직접 주소(http://18.183.189.134:8000)를 권장합니다 — docs/troubleshooting.md

주요 기능

기능	설명
SBOM 수집	Collector가 Syft로 펌웨어·컨테이너의 오픈소스 구성요소를 추출해 HTTPS로 업로드
CVE 스캔	업로드된 SBOM을 Trivy 서버로 스캔해 알려진 취약점(NVD / GitHub Advisory)을 매칭
네트워크 스캔	RustScan → Nmap → Nuclei 체인으로 열린 포트·서비스·템플릿 취약점 탐지
AI 우선순위 분석	CVSS·EPSS·노출도 기반 2-Stage 앙상블 모델 + Groq LLM 설명 생성
통합 대시보드	기기·CVE·스캔 상태·추이를 한 화면에서 보는 React 보안 관제 UI
경량 Collector	Raspberry Pi 4용 에이전트 — MQTT mTLS 등록, WireGuard VPN, SBOM 업로드

Architecture

한 대의 EC2 위에서 Docker Compose 3개 서비스(FastAPI · Mosquitto · Trivy)와 호스트 PostgreSQL이 돌고, Raspberry Pi(Collector) 가 MQTT·WireGuard·HTTPS로 연결됩니다. 프론트엔드는 S3 + CloudFront, API는 EC2 :8000 직접 호출입니다.

컴포넌트	역할
CloudFront + S3 (프론트)	React 빌드 정적 호스팅. 수동 빌드 업로드
iot_backend (FastAPI)	REST API, JWT 인증, MQTT 구독, WireGuard 허브, 네트워크 스캔 실행, Trivy 클라이언트
iot_mosquitto	MQTT 브로커 — Pi가 `devices/register`로 Publish, backend가 Subscribe (TLS 1.3 mTLS)
iot_trivy	Trivy CVE 스캔 서버. backend만 내부 네트워크로 접근
PostgreSQL 16	관계형 DB `project5`. EC2 호스트에 직접 설치 (RDS·컨테이너 아님)
WireGuard (`wg0`)	Pi ↔ backend VPN 터널. 사설망(NAT) 뒤 기기를 스캔하기 위한 경로
S3 (SBOM)	Collector가 Presigned URL로 SBOM JSON 업로드 (`S3_DATA_BUCKET`)
Raspberry Pi Collector	Syft SBOM 생성, MQTT 등록, VPN join, HTTPS 업로드. 도어락·fleet 워크로드 호스팅

전체 구조도·확장 목표(ECS·RDS) 대비 현재 PoC 차이·시퀀스 다이어그램: docs/architecture.md

시스템 동작 흐름

#	흐름	프로토콜	경로
1	기기 등록·heartbeat	MQTT mTLS	Pi → Mosquitto `:8883` → backend `devices/register` 구독 → `devices` upsert
2	VPN 합류	HTTP + WireGuard	Pi → `POST /devices/{id}/vpn/join` → backend `wg0` peer 추가 → `wg_ip_address` 할당
3	SBOM 업로드	HTTPS + S3	Syft → init API → S3 Presigned PUT → complete → `sbom` 저장
4	CVE 스캔	내부 HTTP	`POST /devices/{id}/scans` → backend → `iot_trivy:4954` → `cves` / `devices_cves`
5	네트워크 스캔	VPN + subprocess	`POST /devices/{id}/network-scans` → backend → `wg_ip_address` 대상 RustScan→Nmap→Nuclei
6	대시보드 조회	HTTPS	Browser → CloudFront(S3) + Browser → EC2 `:8000` API (JWT)
7	AI 위험도 분석	내부 (on-demand)	CVE 상세/리포트 조회 시 NVD·EPSS enrichment → 앙상블 모델 → Groq LLM (캐시)

파이프라인별 시퀀스 다이어그램: docs/architecture.md · Trivy 상세: docs/trivy-scan.md · AI 상세: docs/ml-handoff.md

기술 스택

영역	스택
Backend	FastAPI, PostgreSQL, aiomqtt, WireGuard, JWT
Frontend	React (Create React App)
Infra	Docker Compose on EC2, Mosquitto, Trivy server, AWS S3 · CloudFront
IoT (Collector)	Python, Docker, Syft
스캔 · AI	Trivy, RustScan · Nmap · Nuclei, LightGBM/XGBoost 앙상블, Groq LLM (`gpt-oss-20b`)

디렉터리 구조

collector/   # Raspberry Pi 에이전트 · 스마트 도어락 시연 · fleet SBOM 스텁
backend/     # FastAPI · DB · MQTT 구독 · CVE/네트워크 스캔 파이프라인 · AI 추론
frontend/    # React 보안 관제 대시보드
infra/       # Docker Compose · Mosquitto · MQTT 인증서 스크립트 · 배포
scanners/    # CVE 시연용 공격 도구 (교육용)
AI/          # 위험도 예측 ML 모델 아티팩트 · 학습 노트북
docs/        # 아키텍처 · API · DB · 배포 · 트러블슈팅 등 공통 문서
shared/      # 공통 스키마 (OpenAPI 이전 예정)

실행 방법

프로젝트에서 실제로 쓰는 명령입니다. 운영 배포 전체 절차는 docs/deployment.md를 참고하세요.

# Backend (로컬)
cd backend && pip install -r requirements.txt
cd app && python -m uvicorn main:app --reload      # http://127.0.0.1:8000/docs

# Frontend (로컬)
cd frontend && npm ci && npm start                 # http://localhost:3000

# EC2 운영 스택 (backend + mosquitto + trivy)
cd infra && cp .env.example .env
docker compose up -d --build

Raspberry Pi Collector 실행: collector/README.md · 상세 시연: docs/collector.md

환경 변수 / 설정

대상	파일	핵심 값
Backend	`backend/.env` (`.env.example` 복사)	`DB_`, `SECRET_KEY`, `MQTT_`, `CORS_ORIGINS`
Infra (EC2)	`infra/.env` (`.env.example` 복사)	`DB_`, `API_PORT`, `MQTT_PORT`, `WG_`, `S3_DATA_BUCKET`
Frontend	빌드 시 환경변수	`REACT_APP_API_URL` (프로덕션 기본값은 `.env.production`)
Collector	`collector/.env`	`DEVICE_ID`, `API_BASE_URL`, `MQTT_BROKER`, `WG_ENABLED`

전체 변수 목록과 운영 값: docs/deployment.md · infra/.env.example

문서

문서	역할
`docs/architecture.md`	시스템 구성·데이터 흐름·시퀀스 다이어그램의 기준 문서
`docs/api.md`	REST API · MQTT · JWT 인증 계약
`docs/database.md`	PostgreSQL 테이블·스키마·ERD
`docs/deployment.md`	EC2 · Docker Compose · MQTT 인증서 · WireGuard 배포 절차
`docs/troubleshooting.md`	운영 중 확인된 이슈와 해결
`docs/backend.md` · `docs/frontend.md` · `docs/collector.md`	컴포넌트별 상세 (폴더 구조·연동·시연)
`docs/trivy-scan.md`	Trivy CVE 스캔 파이프라인 상세
`docs/ml-handoff.md`	AI 모델 → 백엔드 연동 스펙
`docs/decisions.md`	주요 기술·설계 결정 기록
`CONTRIBUTING.md`	브랜치·PR·역할 분담 규칙

문서 전체 목록·읽는 순서: docs/README.md

개발 / 브랜치 전략

기본 흐름: develop에서 feature/<영역>/<작업명> 분기 → PR → develop 머지
시연·제출: main (항상 시연 가능한 상태 유지)
API·MQTT·DB 스키마 변경 시 docs/api.md · docs/database.md를 같은 PR에서 갱신
상세 규칙(영역 접두사·PR 라벨·역할 경계): CONTRIBUTING.md

팀 · 역할

역할	담당
IoT	윤아령
Frontend · AI	박대호
Infra	강유진
Backend	박소정
Security	최지현

Navigation Menu

Repository files navigation

Hanium IoT Vulnerability Monitor (SBOMGuard)

주요 기능

Architecture

시스템 동작 흐름

기술 스택

디렉터리 구조

실행 방법

환경 변수 / 설정

문서

개발 / 브랜치 전략

팀 · 역할

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
AI		AI
backend		backend
collector		collector
docs		docs
frontend		frontend
infra		infra
scanners		scanners
shared		shared
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Hanium IoT Vulnerability Monitor (SBOMGuard)

주요 기능

Architecture

시스템 동작 흐름

기술 스택

디렉터리 구조

실행 방법

환경 변수 / 설정

문서

개발 / 브랜치 전략

팀 · 역할

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages