diff --git a/16_API_명세서.md b/16_API_명세서.md index 29d9597..52a2dd3 100644 --- a/16_API_명세서.md +++ b/16_API_명세서.md @@ -1,6 +1,6 @@ # GUARDiA ITSM — 전체 기능 목록 및 API 명세서 -> **버전:** 2.0.0 | **총 라우트:** 588개 | **기준일:** 2026-05-30 +> **버전:** 2.1.0 | **총 라우트:** 617개 | **기준일:** 2026-05-31 > **Base URL:** `http://localhost:8001` > **인증:** JWT Bearer Token (`POST /api/auth/login` → `access_token`) @@ -30,6 +30,9 @@ | 18 | [인프라 확장](#18-인프라-확장) | 7 | | 19 | [메신저 봇](#19-메신저-봇) | 2 | | 20 | [라이선스](#20-라이선스) | 6 | +| 21 | [DR 자동화](#21-dr-자동화) | 11 | +| 22 | [네트워크 장비 관리](#22-네트워크-장비-관리) | 10 | +| 23 | [CSAP 보안 점검](#23-csap-보안-점검) | 8 | --- @@ -683,6 +686,73 @@ POST /api/messenger/bot/command --- +## 21. DR 자동화 + +재해복구(DR) 시나리오 관리, 복구 테스트, 백업 무결성 검증, RTO/RPO 추적. + +| Method | Endpoint | 권한 | 설명 | +|--------|----------|------|------| +| GET | `/api/dr/scenarios` | ENGINEER+ | 시나리오 목록 | +| POST | `/api/dr/scenarios` | ADMIN | 시나리오 등록 | +| GET | `/api/dr/scenarios/{id}` | ENGINEER+ | 시나리오 상세 | +| PUT | `/api/dr/scenarios/{id}` | ADMIN | 시나리오 수정 | +| POST | `/api/dr/test` | ENGINEER+ | 복구 테스트 실행 | +| GET | `/api/dr/test/{id}` | ENGINEER+ | 테스트 결과 조회 | +| GET | `/api/dr/tests` | ENGINEER+ | 테스트 이력 목록 | +| POST | `/api/dr/backup-verify` | ENGINEER+ | 백업 무결성 검증 (SHA-256) | +| POST | `/api/dr/failover/{id}` | ADMIN | Failover 실행 | +| GET | `/api/dr/rto-rpo` | ENGINEER+ | RTO/RPO 목표 대비 실적 | +| GET | `/api/dr/dashboard` | ENGINEER+ | DR 전체 현황 대시보드 | + +**시나리오 타입:** `SERVER_FAILURE` / `SITE_FAILURE` / `DATA_CORRUPTION` +**테스트 상태:** `RUNNING` → `PASS` / `FAIL` / `PARTIAL` + +--- + +## 22. 네트워크 장비 관리 + +스위치·라우터·방화벽·L4 장비 인벤토리, SSH 설정 백업, 변경 감지, 명령 실행. + +| Method | Endpoint | 권한 | 설명 | +|--------|----------|------|------| +| GET | `/api/network/devices` | ENGINEER+ | 장비 목록 (inst_id, device_type 필터) | +| POST | `/api/network/devices` | ADMIN | 장비 등록 (AES-256 암호화 저장) | +| GET | `/api/network/devices/{id}` | ENGINEER+ | 장비 상세 (자격증명 제외) | +| PUT | `/api/network/devices/{id}` | ADMIN | 장비 수정 | +| DELETE | `/api/network/devices/{id}` | ADMIN | 장비 비활성화 | +| POST | `/api/network/devices/{id}/backup` | ENGINEER+ | 설정 백업 실행 + diff 비교 | +| GET | `/api/network/devices/{id}/backups` | ENGINEER+ | 백업 이력 목록 | +| GET | `/api/network/devices/{id}/diff` | ENGINEER+ | 설정 변경 비교 (최근 2개) | +| POST | `/api/network/devices/{id}/command` | ENGINEER+ | SSH 명령 실행 (안전 명령만) | +| GET | `/api/network/topology` | ENGINEER+ | 토폴로지 (기관별 장비 분류) | + +**지원 벤더:** CISCO / HUAWEI / JUNIPER / PIOLINK / SECUI / RADWARE +**OS 타입:** `cisco_ios` / `huawei_vrp` / `junos` / `linux` +**백업 타입:** `MANUAL` / `SCHEDULED` / `PRE_CHANGE` + +--- + +## 23. CSAP 보안 점검 + +CSAP/ISMS-P 공공기관 보안 체크리스트 자동 점검, 증적 수집, Excel/HTML 보고서. + +| Method | Endpoint | 권한 | 설명 | +|--------|----------|------|------| +| POST | `/api/compliance/csap/scan` | ADMIN | 전체 자동 점검 실행 | +| GET | `/api/compliance/csap/items` | ALL | 점검 항목 목록 (category, auto_only 필터) | +| GET | `/api/compliance/csap/results` | ALL | 점검 결과 목록 (inst_id 필터) | +| GET | `/api/compliance/csap/results/{scan_id}` | ALL | 배치별 상세 결과 | +| POST | `/api/compliance/csap/evidence/{item_id}` | ALL | 수동 증적 업로드 | +| GET | `/api/compliance/csap/report/html` | ALL | HTML 보고서 (scan_id 필수) | +| GET | `/api/compliance/csap/report/excel` | ALL | Excel 보고서 (scan_id 필수) | +| GET | `/api/compliance/csap/dashboard` | ALL | 기관별 준수율 대시보드 | + +**scan_id 형식:** `CSAP-YYYYMMDD-HHMMSS` +**결과 상태:** `PASS` / `FAIL` / `PARTIAL` / `MANUAL_REQUIRED` / `N_A` +**준수율 등급:** A(90%+) / B(70~89%) / C(50~69%) / D(50% 미만) + +--- + ## 공통 규칙 ### 인증 diff --git a/39_DR_네트워크장비_CSAP_운영가이드.md b/39_DR_네트워크장비_CSAP_운영가이드.md new file mode 100644 index 0000000..f312460 --- /dev/null +++ b/39_DR_네트워크장비_CSAP_운영가이드.md @@ -0,0 +1,540 @@ +# GUARDiA ITSM — DR 자동화 · 네트워크 장비 관리 · CSAP 점검 운영가이드 + +**문서 버전**: 1.0 +**작성일**: 2026-05-31 +**대상**: 시스템 운영자, 보안 담당자, IT 관리자 + +--- + +## 목차 + +1. [DR 자동화 (재해복구)](#1-dr-자동화-재해복구) +2. [네트워크 장비 관리](#2-네트워크-장비-관리) +3. [CSAP 공공기관 보안 자동 점검](#3-csap-공공기관-보안-자동-점검) +4. [통합 운영 시나리오](#4-통합-운영-시나리오) + +--- + +## 1. DR 자동화 (재해복구) + +### 1.1 개요 + +GUARDiA ITSM의 DR(Disaster Recovery) 자동화 모듈은 공공기관 BCP(업무 연속성 계획) 요건을 충족하기 위해 다음 기능을 제공합니다. + +| 기능 | 설명 | +|------|------| +| DR 시나리오 관리 | 서버별 Failover 절차 사전 정의 | +| 복구 테스트 자동화 | SSH 기반 단계별 복구 시뮬레이션 | +| 백업 무결성 검증 | SSH → SHA-256 해시 자동 검증 | +| RTO/RPO 추적 | 목표 대비 실적 대시보드 | + +### 1.2 DR 시나리오 등록 + +```http +POST /api/dr/scenarios +Authorization: Bearer {admin_token} +Content-Type: application/json + +{ + "name": "WAS-01 장애 시나리오", + "scenario_type": "SERVER_FAILURE", + "primary_server_id": 3, + "standby_server_id": 7, + "rto_minutes": 120, + "rpo_minutes": 30, + "failover_steps": [ + {"name": "서비스 중단 확인", "type": "http", "url": "http://was01/health"}, + {"name": "대기 서버 활성화", "type": "ssh", "command": "systemctl start tomcat"}, + {"name": "로드밸런서 전환", "type": "http", "url": "http://lb/switch/was01/was02"} + ], + "healthcheck_url": "http://was02/health" +} +``` + +**시나리오 타입:** + +| 타입 | 설명 | +|------|------| +| `SERVER_FAILURE` | 단일 서버 장애 (기본) | +| `SITE_FAILURE` | 데이터센터 전체 장애 | +| `DATA_CORRUPTION` | 데이터 손상/삭제 복구 | + +### 1.3 복구 테스트 실행 + +```http +POST /api/dr/test +Authorization: Bearer {engineer_token} +Content-Type: application/json + +{ + "scenario_id": 1, + "test_type": "RECOVERY" +} +``` + +**테스트 결과 예시:** +```json +{ + "test_id": 42, + "status": "PASS", + "rto_actual_minutes": 18, + "steps": [ + {"step": 1, "name": "서비스 중단 확인", "status": "OK", "elapsed_sec": 2.1}, + {"step": 2, "name": "대기 서버 활성화", "status": "OK", "elapsed_sec": 45.3}, + {"step": 3, "name": "로드밸런서 전환", "status": "OK", "elapsed_sec": 1.8}, + {"step": 4, "name": "헬스체크", "status": "OK", "elapsed_sec": 3.0} + ] +} +``` + +### 1.4 백업 무결성 검증 + +```http +POST /api/dr/backup-verify +Authorization: Bearer {engineer_token} +Content-Type: application/json + +{ + "server_name": "DB-01" +} +``` + +**응답 예시:** +```json +{ + "success": true, + "server_name": "DB-01", + "latest_file": "db_backup_20260531.tar.gz", + "file_size_mb": 4821, + "sha256": "a3f2c8d1...", + "modified_at": "May 31 02:00" +} +``` + +> **중요:** `ip_addr`, `backup_path` 등 서버 정보는 응답에 포함되지 않습니다. + +### 1.5 RTO/RPO 현황 조회 + +```http +GET /api/dr/rto-rpo +Authorization: Bearer {engineer_token} +``` + +**응답 예시:** +```json +{ + "scenarios": [ + { + "scenario_name": "WAS-01 장애 시나리오", + "rto_target": 120, + "rto_actual_avg": 18.5, + "rto_met": true, + "last_test_result": "PASS" + } + ] +} +``` + +### 1.6 Failover 실행 (긴급 시) + +```http +POST /api/dr/failover/{scenario_id} +Authorization: Bearer {admin_token} +``` + +> **주의:** ADMIN 전용. 긴급 상황 외 반드시 복구 테스트(`/api/dr/test`)로 먼저 검증 후 실행. + +### 1.7 운영 절차 + +**정기 DR 테스트 (권장: 분기 1회)** + +1. 대시보드에서 시나리오 목록 확인: `GET /api/dr/dashboard` +2. 테스트 실행: `POST /api/dr/test` (test_type: RECOVERY) +3. 결과 확인: `GET /api/dr/test/{id}` +4. 백업 검증: `POST /api/dr/backup-verify` +5. CSAP O-02 항목 자동 갱신 확인 + +**공공기관 BCP 권장 기준:** + +| 등급 | RTO | RPO | +|------|-----|-----| +| 1등급 (중요) | 4시간 이내 | 1시간 이내 | +| 2등급 (보통) | 8시간 이내 | 4시간 이내 | +| 3등급 (낮음) | 24시간 이내 | 24시간 이내 | + +--- + +## 2. 네트워크 장비 관리 + +### 2.1 개요 + +스위치·라우터·방화벽·L4 등 네트워크 장비를 SSH 기반으로 에이전트 없이 관리합니다. + +| 기능 | 설명 | +|------|------| +| 장비 인벤토리 | 기관별 네트워크 장비 목록 | +| 설정 백업 | 벤더별 표준 명령어로 설정 자동 백업 | +| 변경 감지 | 이전 백업과 diff 비교, 변경 시 알림 | +| SSH 명령 실행 | 안전 명령만 허용 (위험 명령 차단) | +| 토폴로지 조회 | 기관별 장비 타입 분류 | + +### 2.2 지원 장비 + +| 장비 타입 | 벤더 | OS 타입 | +|----------|------|---------| +| SWITCH | CISCO | cisco_ios | +| SWITCH | HUAWEI | huawei_vrp | +| ROUTER | CISCO | cisco_ios | +| FIREWALL | PIOLINK | linux | +| FIREWALL | SECUI | linux | +| LOAD_BALANCER | RADWARE | linux | +| SWITCH | JUNIPER | junos | + +### 2.3 장비 등록 + +```http +POST /api/network/devices +Authorization: Bearer {admin_token} +Content-Type: application/json + +{ + "device_name": "Core-Switch-01", + "device_type": "SWITCH", + "vendor": "CISCO", + "model": "Catalyst 9300", + "os_type": "cisco_ios", + "ip_addr": "10.0.1.1", + "ssh_user": "admin", + "ssh_password": "sw_password_2026", + "ssh_port": 22, + "location": "서울시청 IDC 2층 랙 A-03", + "inst_id": 1 +} +``` + +> **보안:** `ip_addr`, `ssh_user`, `ssh_password`는 AES-256-GCM 암호화 저장. API 응답에 미포함. + +### 2.4 설정 백업 + +```http +POST /api/network/devices/{id}/backup +Authorization: Bearer {engineer_token} +``` + +**응답 예시:** +```json +{ + "success": true, + "device_name": "Core-Switch-01", + "backup_id": 15, + "config_hash": "a3f2c8d1e4b7...", + "changed_lines": 0, + "backed_up_at": "2026-05-31T14:30:00" +} +``` + +- `changed_lines > 0`: 이전 백업 대비 설정 변경 감지 +- 변경 10줄 이상: MEDIUM 알림 발송 +- 변경 50줄 이상: HIGH 알림 발송 + +### 2.5 설정 변경 비교 + +```http +GET /api/network/devices/{id}/diff +Authorization: Bearer {engineer_token} +``` + +최근 2개 백업 자동 비교. `old_id`, `new_id` 파라미터로 특정 버전 간 비교 가능. + +**응답 예시:** +```json +{ + "changed": true, + "added_lines": 3, + "removed_lines": 1, + "diff": [ + "--- 이전 설정", + "+++ 현재 설정", + "@@ -105,7 +105,10 @@", + "- switchport access vlan 10", + "+ switchport access vlan 20", + "+ switchport mode access" + ] +} +``` + +### 2.6 SSH 명령 실행 + +```http +POST /api/network/devices/{id}/command +Authorization: Bearer {engineer_token} +Content-Type: application/json + +{ + "command": "show interfaces status", + "timeout": 30 +} +``` + +**차단 명령어 (실행 불가):** +- `write erase`, `factory-reset`, `reload`, `reboot` +- `rm -rf`, `mkfs`, `fdisk`, `delete flash:` + +### 2.7 토폴로지 조회 + +```http +GET /api/network/topology?inst_id=1 +Authorization: Bearer {engineer_token} +``` + +### 2.8 운영 절차 + +**정기 설정 백업 (권장: 주 1회)** + +``` +1. 기관별 장비 목록 확인: GET /api/network/devices?inst_id={기관ID} +2. 장비별 설정 백업 실행: POST /api/network/devices/{id}/backup +3. 변경 감지 시 diff 확인: GET /api/network/devices/{id}/diff +4. 무단 변경 발견 시 → 변경관리 CAB 등록 + 감사 기록 +``` + +--- + +## 3. CSAP 공공기관 보안 자동 점검 + +### 3.1 개요 + +CSAP(클라우드보안인증제) + ISMS-P 기반의 공공기관 보안 체크리스트를 자동으로 점검합니다. + +| 구분 | 항목 수 | 자동 점검 | 수동 확인 | +|------|---------|---------|---------| +| 관리적 보안 (M) | 5개 | - | 5개 | +| 기술적 보안 (T) | 12개 | 10개 | 2개 | +| 운영 보안 (O) | 5개 | 4개 | 1개 | +| 물리적 보안 (P) | 3개 | 1개 | 2개 | +| **합계** | **25개** | **15개** | **10개** | + +> 실제 구현은 CSAP_ITEMS 확장으로 최대 100개 항목까지 지원. + +### 3.2 자동 점검 실행 + +```http +POST /api/compliance/csap/scan +Authorization: Bearer {admin_token} +Content-Type: application/json + +{ + "inst_id": 1 +} +``` + +**응답 예시:** +```json +{ + "scan_id": "CSAP-20260531-143022", + "inst_id": 1, + "total_items": 25, + "pass": 18, + "fail": 4, + "partial": 1, + "manual_required": 2, + "compliance_rate": 82.0, + "grade": "B", + "critical_findings": [ + "T-03: SSH root 직접 로그인 차단", + "T-05: 보안 패치 최신화 (30일 이내)" + ] +} +``` + +### 3.3 준수율 등급 기준 + +| 준수율 | 등급 | 공공기관 의미 | +|--------|------|-------------| +| 90% 이상 | **A (우수)** | 보안감사 대응 양호 | +| 70~89% | **B (보통)** | 개선 권고 | +| 50~69% | **C (미흡)** | 개선 계획 즉시 수립 | +| 50% 미만 | **D (부적합)** | 즉시 조치 필요 | + +### 3.4 점검 항목 조회 + +```http +GET /api/compliance/csap/items?category=기술적&auto_only=true +Authorization: Bearer {token} +``` + +### 3.5 점검 결과 상세 조회 + +```http +GET /api/compliance/csap/results/{scan_id} +Authorization: Bearer {token} +``` + +### 3.6 수동 항목 증적 업로드 + +자동 점검 불가 항목(M-01 정보보호 정책 등)은 담당자가 수동으로 증적을 업로드합니다. + +```http +POST /api/compliance/csap/evidence/{item_id} +Authorization: Bearer {token} +Content-Type: application/json + +{ + "item_id": "M-01", + "inst_id": 1, + "finding": "정보보호 정책서 2026년 개정본 확인", + "evidence_note": "첨부파일: 정보보호정책_2026.pdf (SharePoint 저장)", + "status": "PASS" +} +``` + +### 3.7 보고서 생성 + +**HTML 보고서 (웹 열람·인쇄용):** +``` +GET /api/compliance/csap/report/html?scan_id=CSAP-20260531-143022 +``` + +**Excel 보고서 (공문 첨부용):** +``` +GET /api/compliance/csap/report/excel?scan_id=CSAP-20260531-143022 +``` + +Excel 파일명: `CSAP_CSAP-20260531-143022_20260531.xlsx` + +### 3.8 기관별 준수율 대시보드 + +```http +GET /api/compliance/csap/dashboard +Authorization: Bearer {token} +``` + +**응답 예시:** +```json +{ + "institutions": [ + {"inst_id": 1, "compliance_rate": 82.0, "grade": "B", "scanned_at": "2026-05-31T14:30:22"}, + {"inst_id": 2, "compliance_rate": 91.5, "grade": "A", "scanned_at": "2026-05-30T09:15:00"} + ] +} +``` + +### 3.9 자동 점검 항목 상세 + +| 항목ID | 항목명 | 자동 점검 방법 | +|--------|--------|-------------| +| T-03 | SSH root 로그인 차단 | SSH → sshd_config `PermitRootLogin no` 확인 | +| T-11 | 취약점 정기 스캔 | tb_vuln_scan 90일 이내 이력 확인 | +| O-01 | 로그 보존 6개월 | tb_audit_log 최오래된 레코드 날짜 확인 | +| O-02 | 백업 무결성 검증 | tb_dr_test 90일 이내 PASS 이력 확인 | +| O-03 | 변경 관리 이행 | tb_change_request 등록 건수 확인 | +| P-02 | DR 테스트 이행 | tb_dr_test 1년 이내 PASS 이력 확인 | + +### 3.10 운영 절차 + +**분기별 CSAP 점검 절차:** + +``` +1. CSAP 자동 점검 실행 + POST /api/compliance/csap/scan {"inst_id": 기관ID} + +2. 결과 확인 및 FAIL 항목 조치 + GET /api/compliance/csap/results/{scan_id} + → FAIL 항목별 개선 조치 시행 + +3. 수동 항목 증적 업로드 + POST /api/compliance/csap/evidence/{item_id} + → M-01 정책서, M-02 조직도, P-01 출입통제 기록 등 + +4. 보고서 생성 및 배포 + GET /api/compliance/csap/report/excel?scan_id=... + → 부서장 보고 / 보안감사 대비 보관 + +5. 대시보드 모니터링 + GET /api/compliance/csap/dashboard + → 기관별 준수율 추이 확인 +``` + +--- + +## 4. 통합 운영 시나리오 + +### 시나리오 1: 장애 발생 → DR 실행 → CSAP 업데이트 + +``` +[인시던트 발생] + → POST /api/incidents (인시던트 등록) + → POST /api/dr/failover/{scenario_id} (긴급 Failover, ADMIN) + → GET /api/dr/rto-rpo (RTO 실적 확인) + → POST /api/compliance/csap/scan (P-02 DR 테스트 항목 자동 갱신) +``` + +### 시나리오 2: 네트워크 변경 → 자동 감지 → 변경관리 연계 + +``` +[설정 변경 의심] + → POST /api/network/devices/{id}/backup (최신 백업 실행) + → GET /api/network/devices/{id}/diff (변경 내역 확인) + → POST /api/change (변경관리 CAB 등록) + → POST /api/audit/record (감사 기록) +``` + +### 시나리오 3: 분기별 보안 감사 준비 + +``` +[분기 점검 시작] + → POST /api/dr/test (DR 복구 테스트) + → POST /api/network/devices/{id}/backup (전 장비 설정 백업) + → POST /api/compliance/csap/scan (CSAP 전체 점검) + → POST /api/compliance/csap/evidence/* (수동 증적 업로드) + → GET /api/compliance/csap/report/excel (보고서 생성) +``` + +--- + +## API 빠른 참조 + +### DR 자동화 (`/api/dr`) + +| Method | Endpoint | 권한 | 설명 | +|--------|----------|------|------| +| GET | `/api/dr/scenarios` | ENGINEER+ | 시나리오 목록 | +| POST | `/api/dr/scenarios` | ADMIN | 시나리오 등록 | +| POST | `/api/dr/test` | ENGINEER+ | 복구 테스트 실행 | +| GET | `/api/dr/test/{id}` | ENGINEER+ | 테스트 결과 | +| GET | `/api/dr/tests` | ENGINEER+ | 테스트 이력 | +| POST | `/api/dr/backup-verify` | ENGINEER+ | 백업 무결성 검증 | +| POST | `/api/dr/failover/{id}` | ADMIN | Failover 실행 | +| GET | `/api/dr/rto-rpo` | ENGINEER+ | RTO/RPO 현황 | +| GET | `/api/dr/dashboard` | ENGINEER+ | DR 전체 현황 | + +### 네트워크 장비 (`/api/network`) + +| Method | Endpoint | 권한 | 설명 | +|--------|----------|------|------| +| GET | `/api/network/devices` | ENGINEER+ | 장비 목록 | +| POST | `/api/network/devices` | ADMIN | 장비 등록 | +| PUT | `/api/network/devices/{id}` | ADMIN | 장비 수정 | +| DELETE | `/api/network/devices/{id}` | ADMIN | 장비 비활성화 | +| POST | `/api/network/devices/{id}/backup` | ENGINEER+ | 설정 백업 | +| GET | `/api/network/devices/{id}/backups` | ENGINEER+ | 백업 이력 | +| GET | `/api/network/devices/{id}/diff` | ENGINEER+ | 설정 변경 비교 | +| POST | `/api/network/devices/{id}/command` | ENGINEER+ | SSH 명령 실행 | +| GET | `/api/network/topology` | ENGINEER+ | 토폴로지 조회 | + +### CSAP 점검 (`/api/compliance/csap`) + +| Method | Endpoint | 권한 | 설명 | +|--------|----------|------|------| +| POST | `/api/compliance/csap/scan` | ADMIN | 전체 자동 점검 | +| GET | `/api/compliance/csap/items` | ALL | 점검 항목 목록 | +| GET | `/api/compliance/csap/results` | ALL | 점검 결과 목록 | +| GET | `/api/compliance/csap/results/{id}` | ALL | 배치 상세 결과 | +| POST | `/api/compliance/csap/evidence/{id}` | ALL | 수동 증적 업로드 | +| GET | `/api/compliance/csap/report/html` | ALL | HTML 보고서 | +| GET | `/api/compliance/csap/report/excel` | ALL | Excel 보고서 | +| GET | `/api/compliance/csap/dashboard` | ALL | 준수율 대시보드 | + +--- + +*Copyright © 2026 GUARDiA All Rights Reserved.*