
자체 호스팅 정보보안 관리 시스템 — ISO 27001, NIS2, GDPR/DSGVO, BSI IT-Grundschutz
<!-- © 2026 Claude Hecker — ISMS Builder V 1.76 — AGPL-3.0 -->

# ISMS Builder
**셀프 호스팅 정보 보안 관리 시스템 — 오픈 소스, 클라우드 불필요**
[](https://github.com/coolstartnow/isms-builder/actions/workflows/ci.yml)
[](https://github.com/coolstartnow/isms-builder/actions)
[](LICENSE)
[](https://nodejs.org)
[](CHANGELOG.md)
📖 **[Wiki](https://github.com/coolstartnow/isms-builder/wiki)** — Docker 이미지 사용 &
환경 변수, 아키텍처 & 모듈, FAQ, 기여 (DE/EN)
<!-- GDPR NOTE: The four badges above (CI, Tests, License, Node.js) load resources
from external servers (github.com, shields.io/Cloudflare, img.shields.io).
When this README is rendered in a browser, these requests transmit the viewer's
IP address to third parties (incl. US-based servers — GDPR Art. 44 ff.).
For 100% GDPR-compliant self-hosted documentation, replace these four badge
lines with their local equivalents from docs/badges/ or remove them entirely. -->
---
> ## ⚠️ 보안 경고: 악성코드를 배포하는 가짜 저장소 및 복사본
> ISMS Builder에는 **패키지화된 "릴리스", 설치 프로그램 또는 다운로드 가능한 ZIP 파일이 없습니다** —
> 유일한 정당한 소스는 이 저장소이며, GitHub에서 일반 소스 코드로 직접 복제하거나
> 다운로드해야 합니다. 최소 하나의 **이 프로젝트를 사칭하는 악성 저장소**를 인지하고 있습니다
> (가짜 README, 스크린샷으로 위장한 ZIP으로 연결되는 가짜 "다운로드" 버튼, Windows 악성코드
> 로더 포함 — `.cmd` → `.exe` → Lua-DLL 페이로드 체인). **이 저장소 외의 어디에서도
> "isms_builder" ZIP/설치 프로그램/exe를 다운로드하거나 실행하지 마십시오.**
> 이 프로젝트를 사칭하는 의심스러운 저장소나 사이트를 발견하면
> [이슈](https://github.com/coolstartnow/isms-builder/issues) 또는
> [토론](https://github.com/coolstartnow/isms-builder/discussions)을 열어 신고해 주시면
> 표시할 수 있도록 하겠습니다.
---
> **상태: 활발한 개발 중 — 아직 완성된 제품이 아닙니다.**
> 핵심 모듈은 기능하며 사용 중이지만, 일부 기능은 미완성이고
> 플랫폼은 계속 성장하고 있습니다. 기여, 피드백 및 실제 환경에서의
> 테스트를 매우 환영합니다 — 바로 그것이 이 프로젝트가 오픈 소스로 공개된 이유입니다.
---
> 🛡️ **관련 프로젝트: [NIS2 Quick-Check](https://github.com/coolstartnow/nis2-quickcheck)** —
> 무료 독립형 NIS2 자가 점검(10개 영역 × 5개 질문, EU 27개 회원국 전체, EU 24개
> 공식 언어 전체). 브라우저에서 완전히 실행되며 백엔드도 설치도 필요 없습니다. ISMS Builder의
> 일부가 아니며 사용에 필요하지도 않습니다 — 빠른 첫 방향 설정을 위한 보조 도구일 뿐입니다.
---
## ISMS Builder란 무엇인가요?
ISMS Builder는 정보 보안 관리 시스템(ISMS) 관리를 위한 **셀프 호스팅 웹 플랫폼**입니다.
정책 작성부터 감사 증거에 이르기까지 전체 컴플라이언스 수명 주기를 ISO 27001:2022, NIS2, GDPR/DSGVO, BSI IT-Grundschutz 및 기타 프레임워크에 대해 다룹니다.
**클라우드 없음. SaaS 요금 없음. 데이터는 귀하의 서버에 남습니다.**
> 다섯 자리 수의 벤더 계약 없이 실제 ISMS 도구가 필요한 중소기업, IT 팀 및 컨설턴트를 위해 설계되었습니다.
---
## 의도된 용도 및 범위
이 프로젝트는 한 명의 ISMS 실무자를 위한 실무 도구로 시작하여 그곳에서 성장했습니다. 이 프로젝트가
오픈 소스인 이유는 그 작업이 다른 사람들에게 유용할 수 있기 때문이며, 위장한 상업적 제품이기
때문이 아닙니다. 이를 명확히 밝히는 것이 이 프로젝트가 귀하의 상황에 적합한지 판단하는 데 도움이 됩니다.
**무엇을 위해 만들어졌는가.** 관리 체계의 문서—방침, 위험, 자산, 통제, 증거—를 작성하고 유지하는 소규모 ISMS 팀, 흔히 한 사람, 때로는 소수입니다. *계정이 필요한* 사람의 수는 적게 유지될 것으로 예상됩니다. 대규모 대상에 도달하는 것은 계정 없이도 가능합니다: 방침 확인은 토큰 기반 링크로 전송되므로, 수신자는 로그인하지 않고도 문서를 읽고 확인할 수 있으며 어떤 사용자 목록에도 나타나지 않습니다.
**당신에게 기대하는 것.** ISMS Builder는 자체 호스팅되며, 그로부터 따르는 모든 것—배포, TLS, 강화, 백업, 업데이트, 접근 제어, 그리고 저장하는 모든 것에 대한 데이터 보호 의무—은 당신의 몫입니다. 이 프로젝트는 합리적인 기본 구성을 제공할 뿐, 관리형 서비스가 아닙니다.
**무엇이 아닌가.** 호스팅 SaaS 제공도, 상용 지원 계약도, 서비스 수준 협약도 없습니다. 멀티테넌트 호스팅 제품이 아닙니다. 어떤 표준에 대해서도 당신을 인증하지 않으며, 법률 자문도 아닙니다—작업을 정리하고 증거화하는 데 도움을 줄 뿐, 평가는 여전히 당신과 당신의 심사자의 몫입니다.
**누가 유지하는가.** 한 사람이 본업과 함께 유지합니다. 이슈와 토론은 읽히고 답변되며, 보통 며칠 이내입니다; 보안 보고는 우선순위가 높습니다. 기능 요청은 환영하며 로드맵을 실제로 형성하지만, 제한된 저녁 시간을 두고 경쟁합니다. 조직이 고정된 일정이나 보장된 응답에 의존한다면, 상용 벤더가 정직한 권고입니다—그것은 프로젝트를 피할 이유가 아니라 현실적으로 계획할 이유일 뿐입니다.
---
## 스크린샷
| 로그인 | 대시보드 |
|---|---|
|  |  |
| 적용성 명세서 | 위험 관리 |
|---|---|
|  |  |
| GDPR & 데이터 보호 | 자산 관리 |
|---|---|
|  |  |
| 안내 및 문서 | 보고서 |
|---|---|
|  |  |
| 조치 등록부 | 통제에 대한 조치 |
|---|---|
|  |  |
> `npm start`를 실행하고 `https://localhost:3000`을 열어 전체 데모 데이터셋을 로컬에서 살펴보세요.
---
## 기능 개요
| 모듈 | 설명 | 표준 |
|---|---|---|
| **정책 관리** | 템플릿 CRUD, 버전 관리, 수명 주기(초안 → 검토 → 승인 → 보관), 공간 계층 구조, 첨부 파일 | ISO 27001 §5 |
| **적용성 명세서** | 5개 프레임워크(BSI IT-Grundschutz, EU NIS2, EUCS, EU AI Act, CRA)에 걸친 147개의 내장 통제 항목과 직접 가져오는 ISO 27001 / 9000 / 9001 통제 항목(절대 기본 제공되지 않음), **사용자 정의 통제** 탭 및 기타 모든 프레임워크 탭은 사용하지 않을 경우 관리 → 모듈에서 끌 수 있음(기존 통제 항목은 유지됨), **자체 그룹**(NEN 7510, TISAX 또는 고객 요구사항과 같은 자체 프레임워크로, 자체 탭 보유: 생성하고 미리보기 및 병합 기능을 통해 JSON 파일에서 통제 항목을 가져옴 — 표준 텍스트는 기본 제공되지 않음; [문서](https://github.com/coolstartnow/isms-builder/blob/main/docs/template-type-soa.md)), 인라인 편집, 격차 분석, 교차 매핑 | ISO 27001 A / BSI / NIS2 / EUCS / EUAI / ISO 9001 / CRA |
| **조치 등록부** | 위험 처리, 감사 발견 사항에 대한 조치, 거버넌스 조치 및 TOM을 위한 단일 등록부 — 책임자, 기한, 상태, 증거; SoA 통제 항목, 발견 사항 및 위험에 할당 가능; SoA, 위험, 발견 사항, 거버넌스 및 GDPR에 표시되며 이전 버전에서 자동으로 업그레이드됨 ([문서](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-measures.en.md)) | ISO 27001 §6.1.3 / GDPR Art. 32 |
| **위험 관리** | 위험 등록부, 처리 계획(조치 등록부에 보관), 감사자 역할 | ISO 27001 §6.1 |
| **보안 목표** | 진행률 표시줄이 있는 KPI 추적, 캘린더 연동 | ISO 27001 §6.2 |
| **GDPR 및 개인정보 보호** | VVT, AV 계약, DSFA, TOM, DSAR 대기열, 72시간 타이머, 이메일 알림이 있는 삭제 로그 | DSGVO Art. 13–35 |
| **자산 관리** | 범주, 유형 및 이름별로 정렬되고 정렬 가능한 열이 있는 자산 등록부, 편집 가능한 자산 유형, 종속성 상속이 있는 보호 목표(CIA + 진정성), 분류 등급, EoL 추적 | ISO 27001 A.5.9–5.12 |
| **BCM / BCP** | 비즈니스 영향 분석, 연속성 계획, 훈련, 세 가지 모두를 위한 템플릿, ISO 22301 요구사항 등록부(라이선스 에디션에서 가져오기) | ISO 27001 A.5.29–5.30 / NIS2 |
| **교육 기록** | 교육 카탈로그, 이수 추적, 증거 파일, 참여 확인서(PDF) | ISO 27001 A.6.3 |
| **공급업체 관리** | 공급업체 등록부, 감사 일정 관리, 위험 평가 | ISO 27001 A.5.19–5.22 |
| **법률 및 계약** | 계약, NDA, 개인정보 보호 정책, 만료 캘린더 | |
| **사고 수신함** | CISO 수신함 + **공개 신고 양식**(로그인 불필요) | NIS2 / BSI |
| **거버넌스** | 경영 검토, 회의록, 거버넌스 조치(조치 등록부에 보관) | ISO 27001 §9.3 |
| **보고서** | 준수 매트릭스(통제 항목 × 엔터티), 격차 보고서, 검토 주기, CSV 내보내기 | |
| **감사 발견 사항** | 발견 사항 등록부(IST→SOLL→위험→권고), 조치 계획, 심각도/상태 추적, FIND-YYYY-NNNN 참조 | ISO 27001 §9.2 |
| **감사 관리** | 체크리스트가 있는 감사, 부적합 사항에서 생성된 발견 사항, 연간 감사 프로그램(분기별 계획, 승인), 캘린더 및 대시보드 연동, CSV/PDF 내보내기 | ISO 27001 §9.2, ISO 19011 |
| **정책 확인** | 직원에게 정책을 검증 가능하게 배포하고 이해를 확인하며, 중앙 감사 증거 제공 ([문서](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-policy-acknowledgements.en.md)) | ISO 27001 7.3, A.6.3 |
| **NIS2** | Art. 21 거버넌스 체크리스트(30개 항목) 및 자동 알림이 있는 Art. 23 보고 기한 | NIS2 Art. 21 / 23 |
| **캘린더** | 모듈 전반의 기한을 위한 단일 캘린더: 조치, 위험 처리, 감사, 검토, 계약, 교육, 기한 | |
| **안내** | 검색 기능이 있는 내장 핸드북 및 지식 기반(모듈 가이드, 역할 가이드, 자체 문서), 6개 언어 지원 | |
| **조직 및 회사 로고** | 조직 설정(책임, 언어, 알림, SMTP, WebDAV, 메뉴 순서, 조직 단위) 및 로그인 페이지, 정책 PDF, 인쇄 보기에 표시되는 업로드 가능한 회사 로고; ISMS Builder 로고는 데모 세트와 함께 제공됨 ([문서](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-organisation.en.md)) | |
| **데이터 보호 영향 평가(DPIA)** | 9개의 기성 템플릿(클라우드 내 HR, 영상 감시, 직원 모니터링, AI 서비스, 프로파일링, 건강 데이터, 생체 인식, 내부 고발, 채용), "DPIA가 필요한가?" 사전 점검, 승인 전 DPO 검토 및 인쇄 보기; 회사가 준비하고 DPO가 검토함 ([docs](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-dsfa.en.md)) | GDPR Art. 35 |
| **GDPR 템플릿** | 처리 활동 기록(14), 처리 계약(12), 데이터 침해(10), 정보 주체 답변(10), 기술적·조직적 조치(24)를 위한 기성 템플릿을 6개 언어로 제공; 양식을 미리 채우되 자사에 맞게 신중히 조정해야 하며 법률 자문이 아님 ([docs](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-gdpr.en.md)) | GDPR Art. 30, 28, 33, 12–22, 32 |
| **AI 초안 (정책 어시스턴트)** | 연결된 AI(Ollama)를 사용하거나 원하는 AI와 복사·붙여넣기로 고정 제목 목록에서 문서 초안 작성; 필터가 개인 및 기술 데이터를 차단하고, 자리 표시자는 조직 데이터에서 로컬로 채워짐 ([docs](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-ai-drafts.en.md)) | |
| **모바일 앱 (Android)** | 자체 데이터 세트로 오프라인 작동하며 Wi-Fi 또는 파일 번들을 통해 서버와 동기화하는 별도 Android 앱: 모듈별 권한이 있는 동기화 계정, QR 코드 설정, 템플릿, SoA, 위험, 자산, 발견 사항 및 지침(읽기 전용); `STORAGE_BACKEND=json` 필요 ([docs](https://github.com/coolstartnow/isms-builder/blob/main/docs/module-mobile-sync.en.md)). 아직 공개되지 않음: 미리 사용해 보고 싶다면 [프로젝트 웹사이트](https://www.isms-builder.com/#contact)를 통해 문의 | |
| **추적성** | 모든 레코드가 SoA 통제 항목 + 정책 문서에 연결됨 — 양방향 | |
| **시맨틱 검색** | 키워드 폴백을 갖춘 Ollama(nomic-embed-text) 기반 로컬 AI 검색; AI 주소, 모델 및 **선택적 API 키**(`Authorization: Bearer`로 전송되며, 예를 들어 Ollama 앞단의 게이트웨이로 보내면 해당 로그에서 ISMS Builder의 요청을 식별할 수 있음)는 관리에서 설정; 키는 다시 표시되거나 기록되거나 내보내지지 않음 | |
| **멀티 엔티티** | 기업 구조 트리, 통제 항목 및 정책에 대한 엔티티별 적용 가능성 | |
| **다국어 UI 및 데모 데이터** | 전체 UI, 데모 콘텐츠 및 모듈 문서를 🇩🇪 DE / 🇬🇧 EN / 🇫🇷 FR / 🇳🇱 NL / 🇭🇺 HU / 🇪🇪 ET로 제공; 관리자가 사용 가능한 언어를 제어. FR, NL, HU 및 ET 텍스트는 자체 번역이므로 원어민의 검토를 권장 | |
### ⚠ 중요: ISO 통제 항목은 관리자가 수동으로 설치해야 합니다
> **ISO 27001:2022, ISO 9000:2015, ISO 9001:2015**는 국제표준화기구(ISO, © ISO)가 발행한
> 저작권 보호 표준입니다. 통제 항목 정의(제목, 설명, 요구사항 텍스트)는 이 소프트웨어에
> **포함되어 있지 않으며**, 유효한 ISO 라이선스 없이 **재배포해서는 안 됩니다**.
**실무적 의미:**
ISO 27001, ISO 9000, ISO 9001용 SoA 모듈은 통제 항목 내용 없이 제공됩니다.
관리자는 이 프레임워크를 사용하기 전에 통제 항목을 **수동으로 가져와야 합니다**:
1. [iso.org](https://www.iso.org/) 또는 공인 국가 기관에서 표준의 라이선스 사본을 확보합니다
2. 통제 항목 정의가 담긴 JSON 파일을 준비합니다 (형식은 `scripts/import-iso-controls.sh`에 문서화되어 있음)
3. 가져오기 스크립트를 실행합니다:
```bash
bash scripts/import-iso-controls.sh path/to/iso-controls.json
```
4. ISMS Builder 서버를 재시작합니다
> **기본 제공되는 프레임워크(ISO 라이선스 불필요):**
> BSI IT-Grundschutz, EU NIS2, EUCS, EU AI Act, CRA는 공개적으로 이용 가능한
> EU 법률 및 독일 연방 간행물을 기반으로 하며 완전히 사전 설치되어 있습니다.
>
> **기타 프레임워크(NEN 7510, TISAX, 고객 요구사항 등):** 관리자가 SoA에서 *자체 그룹*을 생성하고
> (**+ 자체 그룹** 버튼) JSON 파일에서 통제 항목을 가져옵니다 — 미리보기가 제공되며, 대체가 아닌 병합 방식으로 처리되고,
> 표준 텍스트는 전혀 포함되지 않습니다. 사용 권한이 있는 콘텐츠만 가져오십시오
> (예시 파일: `docs/examples/soa-custom-framework.example.json`). 위의 ISO 가져오기는 ISO 27001, 9000, 9001로 제한됩니다.
>
> **법적 고지:** ISO 27001/9000/9001, NEN 7510 및 TISAX 평가 카탈로그(VDA ISA)의 표준 텍스트는 해당 발행자의 권리(저작권 및 상표권)의 적용을 받으며 ISMS Builder와 함께 제공되지 않습니다. 데모 데이터의 예시 통제 항목은 표준의 문구와 아무런 관련이 없는 당사가 직접 만든 자리 표시자 텍스트입니다 — 불완전하며 인증이나 TISAX 평가에 사용할 수 없습니다. 사용 권한이 있는 텍스트만 가져오십시오. 이는 법률 자문이 아닙니다.
해당 표준에 대한 유효한 라이선스 없이 ISO 프레임워크 모듈을 운영하는 것은
전적으로 운영자의 책임입니다. ISMS Builder 프로젝트와 그 기여자는 ISO로 보호되는
콘텐츠의 무단 사용에 대해 어떠한 책임도 지지 않습니다.
---
## 빠른 시작
```bash
git clone https://github.com/coolstartnow/isms-builder.git
cd isms-builder
npm install
cp .env.example .env # set JWT_SECRET to a long random string
npm start # http://localhost:3000
```
**`[email protected]` / `adminpass`**로 로그인합니다. 첫 로그인 시 **데모 데이터 언어**(🇩🇪 DE / 🇬🇧 EN / 🇫🇷 FR / 🇳🇱 NL / 🇭🇺 HU / 🇪🇪 ET)를 선택하거나 빈 시스템으로 시작하라는 메시지가 표시됩니다. 로그인 직후 관리자 비밀번호를 변경하세요. 다른 테스트 계정은 [데모 계정](#demo-accounts)을 참조하세요.
HTTPS를 사용하는 프로덕션 환경의 경우:
```bash
# .env
JWT_SECRET=<output of: openssl rand -hex 32> # required; production refuses a missing, short or placeholder secret
STORAGE_BACKEND=json
SSL_CERT_FILE=/etc/ssl/certs/your.crt
SSL_KEY_FILE=/etc/ssl/private/your.key
```
**실제 운영으로 전환하시나요?** 운영 환경은 항상 **새로운 설치**입니다 – 데모와 운영은 절대 섞이지 않습니다.
데모 인스턴스(또는 그 데이터)를 운영 시스템으로 전환하지 마십시오: 새 인스턴스를 설치하고
(`STORAGE_BACKEND=json`이 권장 기본값입니다, `.env.example` 참조), 자체 관리자를 생성한 뒤
자체 시크릿을 설정하십시오. 앱 내의 *Demo Reset*과 *Demo Import*는 데모
인스턴스 전용 기능입니다: 이들은 백업, 복원 또는 마이그레이션 도구가 아니며, *Demo Import*는
`STORAGE_BACKEND=json`에서만 작동합니다.
내장된 SoA 프레임워크(BSI IT-Grundschutz, EU NIS2, EUCS, EU AI Act, CRA)는
모든 스토리지 백엔드에서 자동으로 생성됩니다. ISO 27001 / 9000 / 9001의 통제 항목 텍스트는
ISO의 저작권이 있으며 **절대** 함께 배포되지 않습니다 – `data/iso-controls.json`에 직접 제공하십시오
(`scripts/import-iso-controls.sh` 참조).
---
### 데모 계정
데모 세트에는 다음 계정이 포함되어 있어 모든 역할과 기능을 시험해 볼 수 있습니다. **비밀번호는 공개되어 있으며 데모 용도로만 사용됩니다.**
| 사용자 | 로그인 (이메일) | 비밀번호 | 역할 | 기능 | 테스트 용도 |
|---|---|---|---|---|---|
| admin | `[email protected]` | `adminpass` | 관리자 | CISO + DPO | 관리 기능을 포함한 모든 것 |
| ciso | `[email protected]` | `cisopass` | 콘텐츠 소유자 | **CISO** | 관리자 권한 없이 CISO 기능 (carla와 동일) |
| dsb | `[email protected]` | `dsbpass` | 콘텐츠 소유자 | **DPO** | 관리자 권한 없이 DPO 기능 (dana와 동일) |
| alice | `[email protected]` | `alicepass` | 부서장 | 없음 | 정책, 리스크 및 가이드라인 (읽기 및 쓰기) |
| bob | `[email protected]` | `bobpass` | 읽기 전용 사용자 | 없음 | 읽기 전용 접근 |
| carla | `[email protected]` | `carlapass` | 콘텐츠 소유자 | **CISO** | DPIA 준비 및 승인; DPO 의견은 **입력할 수 없음** |
| dana | `[email protected]` | `danapass` | 콘텐츠 소유자 | **DPO** | DPIA에 대한 DPO 의견 입력 |
carla와 dana는 관리자 권한이 없는 두 명의 별개 인물이므로, DPIA 검토를 의도된 대로 테스트할 수 있습니다: carla가 DPIA를 준비하고, dana가 의견을 입력하며, carla가 승인합니다. ciso와 dsb는 동일한 두 기능을 별도 계정으로 구성한 것입니다.
**어떤 계정이 존재하는지는 시작 방식에 따라 달라집니다:**
- **데이터 디렉터리 없는 Docker 이미지 / 새 설치:** admin, alice, bob, carla, dana.
- **소스 체크아웃 (`git clone`):** 저장소에는 admin, ciso, dsb, alice, bob이 포함된 `data/rbac_users.json`이 함께 제공됩니다. carla와 dana는 데모 가져오기 또는 데모 번들 로드(2FA 비활성화)를 통해 추가됩니다.
- **공개 데모 (`DEMO_HOSTING`):** 위에 나열된 일곱 계정의 비밀번호는 이 공개 값으로 유지됩니다; 해당 데이터 세트에 존재하지 않는 계정은 건너뜁니다.
- 운영으로 전환하면 (Admin → Maintenance → Demo reset) `admin`을 제외한 모든 계정이 삭제됩니다. 전환 직후 admin 비밀번호를 변경하십시오.
## Docker
모든 릴리스는 GitHub Container Registry에 GitHub Package로 게시되며,
`linux/amd64` 및 `linux/arm64`용으로 제공됩니다 — `:latest` 및 `:<version>` 태그가 붙습니다 (예: `:1.37.5.2`):
```bash
docker compose up -d
# App runs at http://localhost:3000
```
또는 Compose 없이 (`data/`는 반드시 바인드 마운트여야 함 — 데이터는 절대 이미지에 포함되지 않음):
```bash
docker run -d --name isms-builder -p 3000:3000 \
-e JWT_SECRET="$(openssl rand -hex 32)" \
-v "$PWD/data:/app/data" \
ghcr.io/coolstartnow/isms-builder:latest
```
이것이 기본값으로, 데이터를 `./data`에 일반 JSON 파일로 저장하며 데이터베이스 컨테이너가 전혀 필요하지 않습니다. 소규모 팀에 권장되는 설정이며, 위의 두 명령이 사용하는 방식입니다.
**JSON 대신 PostgreSQL(또는 MariaDB) 사용하기.** 이미지는 이를 기본적으로 지원하지만, 위의 JSON 설정과 달리 실제 데이터베이스인 두 번째 컨테이너와 앱이 데이터베이스에 접근하는 방법을 알려주는 몇 가지 환경 변수가 필요합니다. 이 저장소를 클론하지 않고 이미지만 가져온 경우(`docker pull ghcr.io/coolstartnow/isms-builder`), 해당 변수 이름은 기본적으로 어디에도 표시되지 않습니다. 변수가 문서화된 `docker-compose.yml`과 `.env.example`은 이미지의 일부가 아니라 이 Git 저장소의 파일이기 때문입니다. 이 섹션은 그 정보가 저장소에만 존재하는 비밀이 되지 않도록 하기 위해 존재합니다.
`isms-builder` 이미지 자체는 데이터베이스 서버를 절대 포함하지 않습니다. `postgres:17`(또는 `mariadb:11`)은 이 프로젝트의 테이블에 대해 전혀 알지 못하는 Docker Hub의 완전히 범용적인 빈 데이터베이스 엔진입니다. 해당 테이블(위험, 자산, SoA 통제 항목 등)은 애플리케이션이 시작되어 빈 데이터베이스를 발견하는 순간 애플리케이션 자체에 의해 자동으로 생성됩니다. 수동 SQL 가져오기도, 별도로 실행해야 하는 마이그레이션 단계도 없습니다. 전체 작동 방식을 알고 싶다면 아래의 "데이터베이스 스키마는 어떻게 생성되나요?"를 참조하세요.
두 개의 컨테이너, 하나의 공유 Docker 네트워크, 그런 다음 앱에 데이터베이스를 찾을 위치를 알려줍니다:
```bash
# 1) An isolated network so the two containers can reach each other by name
docker network create isms-net
# 2) The database — empty until the app first connects and creates its tables
docker run -d --name isms-postgres --network isms-net \
-e POSTGRES_DB=isms_builder \
-e POSTGRES_USER=isms \
-e POSTGRES_PASSWORD="$(openssl rand -hex 16)" \
-v isms-postgres-data:/var/lib/postgresql/data \
postgres:17-alpine
# 3) The app, pointed at that database by container name (isms-postgres) via
# Docker's built-in DNS on the shared network — no host/port juggling needed
docker run -d --name isms-builder --network isms-net -p 3000:3000 \
-e JWT_SECRET="$(openssl rand -hex 32)" \
-e STORAGE_BACKEND=postgres \
-e DB_HOST=isms-postgres \
-e DB_PORT=5432 \
-e DB_USER=isms \
-e DB_PASS="<same password as POSTGRES_PASSWORD above>" \
-e DB_NAME=isms_builder \
ghcr.io/coolstartnow/isms-builder:latest
```
각 변수의 의미는 다음과 같습니다:
| 변수 | 용도 |
|---|---|
| `STORAGE_BACKEND` | PostgreSQL의 경우 `postgres`(또는 `pg`), MariaDB/MySQL의 경우 `mariadb`. 기본 JSON 설정을 사용하려면 설정하지 않은 채로 두십시오(또는 `json`). |
| `DB_HOST` | 데이터베이스 컨테이너의 호스트 이름. 공유 Docker 네트워크에서는 컨테이너의 `--name`만 지정하면 됩니다. Docker가 자동으로 이를 확인합니다. |
| `DB_PORT` | PostgreSQL의 경우 `5432`, MariaDB의 경우 `3306`. |
| `DB_USER` / `DB_PASS` / `DB_NAME` | 데이터베이스 컨테이너에 설정한 값(위의 `POSTGRES_USER`/`POSTGRES_PASSWORD`/`POSTGRES_DB` 또는 MariaDB의 해당 값)과 일치해야 합니다. |
MariaDB의 경우 `postgres:17-alpine`을 `mariadb:11`로 바꾸고, 2단계에서 해당 `MARIADB_DATABASE` /
`MARIADB_USER` / `MARIADB_PASSWORD` 변수를 사용하며, 3단계에서 `STORAGE_BACKEND=mariadb` /
`DB_PORT=3306`을 사용하십시오. 이 프로젝트가 인식하는 모든 환경 변수의 전체 상호 참조 목록은
여기서 다루지 않은 항목(SSL, 리버스 프록시 신뢰, SMTP,
2FA 등)을 포함하여 이 저장소의 [`.env.example`](https://github.com/coolstartnow/isms-builder/blob/main/.env.example)에 있습니다.
Compose 사용자는 이를 무료로 얻을 수 있습니다: `docker-compose.yml`에는 이미 `mariadb`와 `postgres`
서비스 프로필이 포함되어 있습니다(기본적으로 주석 처리되어 있으며, 이에 상응하는 환경 변수 설명도 함께 있음) —
`docker compose --profile postgres up -d`를 실행하면 두 컨테이너가 자동으로 연결되어 시작되며,
수동 네트워킹이나 비밀번호 복사-붙여넣기가 필요하지 않습니다.
**데이터베이스 스키마는 어떻게 생성됩니까?** `postgres:17` 이미지도 `mariadb:11`
이미지도 이 프로젝트에 대해 아무것도 알지 못합니다 — 이들은 Docker Hub에서 가져온 일반적이고 빈 데이터베이스 엔진입니다.
가져올 SQL 덤프 파일도 없고 수동으로 실행할 별도의 마이그레이션 명령도 없습니다.
대신 `isms-builder` 컨테이너가 시작되어 빈 데이터베이스에 연결되는 순간, 자체 애플리케이션 코드(데이터베이스 이미지가 아님)가
필요한 모든 테이블을 즉석에서 생성합니다 — [`server/db/knexDatabase.js`](https://github.com/coolstartnow/isms-builder/blob/main/server/db/knexDatabase.js)를 참조하십시오: 테이블 정의 목록이 있으며,
각각 `hasTable()`로 확인하고 없으면 `createTable()`로 생성하며, 이 모든 과정은 앱이 HTTP 요청을 받아들이기 시작하기 전에 이루어집니다.
따라서 이는 멱등적입니다 — 최초 시작 시 아무것도 없는 상태에서 전체 스키마를 구축하고, 이후 동일한 데이터베이스에 대한 재시작은
테이블이 이미 존재하므로 조용히 아무 작업도 하지 않습니다. 이는 SQLite, MariaDB 11, PostgreSQL 17에 대해 실제 검증된
(참조: [#70](https://github.com/coolstartnow/isms-builder/issues/70)) 수정되지 않은 동일한 메커니즘입니다.
대신 소스에서 빌드하려면 `docker-compose.yml`의 `build:` 블록 주석을 해제하고
`docker compose up -d --build`를 실행하십시오.
이미지에는 서명된 빌드 출처 증명이 포함되어 있습니다:
```bash
gh attestation verify oci://ghcr.io/coolstartnow/isms-builder:latest --owner coolstartnow
```
---
## 요구 사항
- **Node.js 18+** (테스트 완료: 18, 20, 22)
- npm 9+
- (선택 사항) Docker + Docker Compose
- (선택 사항) 로컬 AI 시맨틱 검색을 위한 [Ollama](https://ollama.ai)
---
## 구성 (`.env`)
| 변수 | 기본값 | 설명 |
|---|---|---|
| `JWT_SECRET` | *(필수)* | JWT 서명용 시크릿 — 최소 32자의 무작위 문자 (`openssl rand -hex 32`). `NODE_ENV=production`(Docker 이미지에서는 항상 해당)인 경우, 시크릿이 누락되었거나 너무 짧거나 자리 표시자인 경우 서버가 시작되지 않음 |
| `PORT` | `3000` | HTTP/HTTPS 수신 포트 |
| `STORAGE_BACKEND` | `json` | `json`(기본값이자 현재 권장 사항; 모바일 앱에서 요구됨), `sqlite`, `mariadb` 또는 `postgres` |
| `SSL_CERT_FILE` | — | TLS 인증서 경로 → HTTPS 활성화 |
| `SSL_KEY_FILE` | — | TLS 개인 키 경로 |
| `DATA_DIR` | `./data` | 데이터 디렉터리 재정의 (Docker 볼륨) |
| `SMTP_HOST` | — | 이메일 알림용 SMTP 서버 |
| `SMTP_PORT` | `587` | SMTP 포트 |
| `SMTP_USER` | — | SMTP 사용자 이름 |
| `SMTP_PASS` | — | SMTP 비밀번호 |
| `SMTP_FROM` | — | 알림 발신자 주소 |
---
## 아키텍처
```
server/
index.js — Express app setup, router mounts
auth.js — JWT auth, RBAC ranks, session
routes/ — 17 Express route modules (one per domain)
db/ — Data stores (jsonStore / sqliteStore / orgSettingsStore / …)
ai/ — Semantic search (embedder, embeddingStore, lexicalSearch)
reports.js — Report generation logic
ui/
index.html — SPA shell (Atlassian Dark Theme)
app.js — All render functions, ~6000 lines vanilla JS
style.css — CSS variables, dark theme
data/ — JSON files / SQLite DB (gitignored)
docs/
ISMS-build-documentation.md — Full architecture reference
architecture/ — C4 diagrams, data model, OpenAPI 3.0.3 spec
tests/ — Jest + Supertest (176 tests, --runInBand)
```
- **인증:** JWT 쿠키(`sm_session`), bcrypt 비밀번호, TOTP 2FA(조직 전체에 강제 적용 가능)
- **RBAC:** `reader` → `editor` / `dept_head` → `contentowner` / `auditor` → `admin`
- **영속성:** JSON 파일(기본값, 권장) 또는 SQL 데이터베이스: `better-sqlite3`를 통한 SQLite, MariaDB/MySQL, PostgreSQL
- **AI:** 선택적 로컬 Ollama(nomic-embed-text), 키워드 검색은 항상 대체 수단으로 사용 가능
- **감사 로그:** 모든 생성/수정/삭제/로그인 작업 기록, 필터링 및 내보내기 가능
---
[Read more](https://github.com/coolstartnow/isms-builder)