phase 1 개발중

Author: saranf

README.md

@@ -26,13 +26,19 @@
 - 초기에는 **non-agent core**, 이후 조사 보조용 **limited agent**를 제한적으로 추가
 
 상세 설계와 단계별 구현 계획은 `docs/SECURITY_DATA_QUERY_PLATFORM.md`를 참고하세요.
+Phase 1 입력 소스/스키마/질의 초안은 `docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md`에 정리합니다.
+Phase 1 논리 테이블 설계 초안은 `docs/PHASE1_LOGICAL_SCHEMA.md`에 정리합니다.
+Postgres 기준 초기 DDL 초안은 `schema/001_phase1_initial.sql`에 정리합니다.
 
 ## 참고 문서
 
 - `docs/FUNCTIONAL_SPEC.md`: 기능 정의서 원문
 - `docs/SECURITY_CONTROL_MAPPING.md`: 보안 통제(Security Controls) 매핑 문서
 - `docs/IMPLEMENTATION_ROADMAP.md`: 기능 정의서 기준 구현 로드맵
 - `docs/SECURITY_DATA_QUERY_PLATFORM.md`: 데이터 중심 보안 질의 플랫폼 설계 및 단계별 구현 계획
+- `docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md`: Phase 1 입력 소스 명세, 공통 스키마 초안, 1차 질의 카탈로그
+- `docs/PHASE1_LOGICAL_SCHEMA.md`: Phase 1 논리 스키마, 테이블 관계, 인덱스 초안
+- `schema/001_phase1_initial.sql`: Phase 1 Postgres 초기 DDL 초안
 - `docs/ZABBIX_AGENT_ACTIVE_SETUP.md`: PC/단말 Zabbix Agent Active 등록 가이드
 - `docs/TRIVY_USAGE.md`: Trivy 파일시스템/이미지 스캔 가이드
 - `docs/DEPLOYMENT.md`: 서버 배포/운영/트러블슈팅 가이드
@@ -90,6 +96,11 @@
 - `generate-indexer-certs.yml`: Wazuh 인증서 생성용 compose 파일
 - `docs/SECURITY_CONTROL_MAPPING.md`: 보안 통제 매핑 문서
 - `docs/SECURITY_DATA_QUERY_PLATFORM.md`: 데이터 중심 보안 질의 플랫폼 설계 문서
+- `docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md`: Phase 1 입력 소스/스키마/질의 명세 문서
+- `docs/PHASE1_LOGICAL_SCHEMA.md`: Phase 1 논리 테이블/관계 설계 문서
+- `schema/001_phase1_initial.sql`: Phase 1 초기 SQL 스키마 파일
+- `src/mori_soc/*`: Phase 1 Python 구현 골격(모델, collector 계약, API 계약, 질의 카탈로그)
+- `tests/*`: Phase 1 collector / query service / ingestion 단위 테스트
 - `docs/ZABBIX_AGENT_ACTIVE_SETUP.md`: Zabbix Agent 온보딩 문서
 - `docs/TRIVY_USAGE.md`: Trivy 활용 가이드
 - `docs/FLEET_MACBOOK_ENROLLMENT_AND_TEST.md`: Fleet macOS 등록/검증/대시보드 확인 문서
@@ -250,6 +261,36 @@ Grafana Explore에서 Loki로 아래 쿼리를 확인합니다.
 - Fleet status 로그: `{job="fleetdm", log_type="status"}`
 - Fleet result 로그: `{job="fleetdm", log_type="result"}`
 
+## 12. 집에서 이어서 작업할 때 사용할 프롬프트
+
+다른 장소에서 이 저장소 작업을 다시 이어갈 때는,
+현재 목표와 읽어야 할 파일, 그리고 바로 다음 작업 범위를 한 번에 적어주면 가장 빠르게 이어집니다.
+
+### 짧은 버전
+
+- `이 저장소는 MORI SOC-lite이고 지금은 Security Data Query Platform Phase 1 구현 중이야.`
+- `README, docs/SECURITY_DATA_QUERY_PLATFORM.md, docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md, docs/PHASE1_LOGICAL_SCHEMA.md를 먼저 읽고 현재 상태를 요약해줘.`
+- `그 다음 src/mori_soc와 tests를 보고 마지막 구현 다음 단계부터 코드와 테스트까지 이어서 진행해줘.`
+
+### 추천 시작 프롬프트
+
+- `이 저장소는 MORI SOC-lite이며, 현재 목표는 FleetDM/Wazuh/Zabbix/host log를 수집·정규화해서 자연어로 조회할 수 있는 Security Data Query Platform을 만드는 것이다. 지금은 Phase 1(Data Collection/Normalization Core) 구현 중이다. 먼저 README, docs/SECURITY_DATA_QUERY_PLATFORM.md, docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md, docs/PHASE1_LOGICAL_SCHEMA.md, schema/001_phase1_initial.sql, src/mori_soc, tests를 읽고 현재 구현 상태를 요약해줘. 그 다음 아직 구현되지 않은 다음 단계 하나를 제안하고 바로 구현과 테스트까지 진행해줘.`
+
+### 같이 적으면 좋은 추가 정보
+
+- 이번에 하고 싶은 범위
+  - 예: `Fleet collector 고도화`, `repository 추가`, `Wazuh collector 시작`
+- 이번 턴 목표
+  - 예: `코드 작성 + unit test 통과까지`
+- 실행 허용 범위
+  - 예: `safe한 unit test는 바로 실행해도 됨`
+
+### 예시
+
+- `Phase 1 계속하자. 이번에는 src/mori_soc 기준으로 Wazuh alert collector stub와 테스트를 추가해줘. 변경 후 unit test까지 실행해줘.`
+
+이렇게 시작하면 이전 대화가 길더라도 저장소 상태 기준으로 맥락을 빠르게 복원할 수 있습니다.
+
 Starter dashboard에도 아래 패널이 표시됩니다.
 
 - `Fleet Status Logs`

docs/PHASE1_INPUT_SOURCES_AND_SCHEMA.md

@@ -0,0 +1,204 @@
+# MORI Phase 1 입력 소스 및 공통 스키마 초안
+
+## 1. 목적
+
+이 문서는 Phase 1인 **데이터 수집/정규화 코어**를 실제 구현하기 위한 세부 명세 초안입니다.
+
+정리 범위는 아래 3가지입니다.
+
+- 현재 저장소 기준으로 수집 가능한 입력 소스
+- 공통 엔터티 및 필수 필드 초안
+- 운영자 질문 기준 1차 질의 카탈로그
+
+## 2. Phase 1 범위 원칙
+
+- 먼저 **이미 저장소에 있는 수집 경로**를 기준으로 설계한다.
+- 초기 답변은 자유 생성보다 **템플릿 질의 + 근거 반환**에 집중한다.
+- 원본 데이터의 식별자와 링크를 반드시 유지한다.
+- 공통 식별자는 `host_id`를 중심으로 설계한다.
+
+## 3. 입력 소스 명세
+
+| 소스 | 수집 대상 | 현재 저장소 기준 접근 경로 | 현재 상태 | 정규화 대상 |
+| --- | --- | --- | --- | --- |
+| FleetDM | 호스트 인벤토리 | Fleet 서비스 (`:1337`) 기반 API/내부 DB 연계 예정 | 추가 구현 필요 | `host` |
+| FleetDM | osquery status 로그 | `/logs/osqueryd.status.log` → Fluent Bit → Loki (`job=fleetdm`, `log_type=status`) | 이미 수집 중 | `query_result`, `host_observation` |
+| FleetDM | osquery results 로그 | `/logs/osqueryd.results.log` → Fluent Bit → Loki (`job=fleetdm`, `log_type=result`) | 이미 수집 중 | `query_result` |
+| FleetDM | 취약점 정보 | Fleet 서비스/API 기반 수집 예정, 취약점 DB 볼륨 사용 중 | 추가 구현 필요 | `vulnerability` |
+| Wazuh | alert/rule 이벤트 | Wazuh Manager/API (`:55000`) 및 내부 indexer 연계 예정 | 추가 구현 필요 | `alert` |
+| Wazuh | agent inventory/status | Wazuh API 기반 수집 예정 | 추가 구현 필요 | `host`, `alert` |
+| Zabbix | host inventory | Zabbix Web/API (`:18081`) 연계 예정 | 추가 구현 필요 | `host` |
+| Zabbix | trigger/event | Zabbix API 기반 수집 예정 | 추가 구현 필요 | `alert`, `host_observation` |
+| Zabbix | metric snapshot | Zabbix API 기반 수집 예정 | 추가 구현 필요 | `host_observation` |
+| Host logs | 시스템/애플리케이션 로그 | `/var/log/*.log`, `/var/log/*/*.log` → Fluent Bit → Loki (`job=fluent-bit`, `source=host`) | 이미 수집 중 | `login_event`, `process`, `alert` |
+
+## 4. Source별 우선 구현 순서
+
+### 4-1. 즉시 활용 가능
+
+- Fleet status/result 로그
+- Host logs
+
+이 둘은 이미 Fluent Bit에서 Loki로 들어오고 있으므로,
+초기 Phase 1에서는 **정규화 규칙 정의 + 조회 템플릿화**부터 시작할 수 있습니다.
+
+### 4-2. 다음 연결 대상
+
+- Fleet 인벤토리/취약점
+- Wazuh alert/agent inventory
+- Zabbix host/trigger/metric
+
+이 구간은 별도 collector 또는 API pull 작업이 필요합니다.
+
+## 5. 공통 식별자 전략
+
+### 5-1. Canonical host_id
+
+`host_id`는 소스별 ID를 그대로 재사용하지 않고,
+하나의 정규화 레코드에 연결되는 **표준 자산 키**로 둡니다.
+
+추천 우선순위는 아래와 같습니다.
+
+1. 하드웨어/플랫폼 고유 식별자
+2. Fleet host 식별자
+3. Wazuh agent 식별자
+4. Zabbix host 식별자
+5. 정규화된 hostname 기반 fallback
+
+### 5-2. Source reference 보존
+
+각 엔터티는 원본 시스템의 식별자를 별도 필드로 남깁니다.
+
+- `fleet_host_id`
+- `fleet_query_id`
+- `wazuh_agent_id`
+- `wazuh_alert_id`
+- `zabbix_host_id`
+- `zabbix_event_id`
+
+## 6. 공통 엔터티 초안
+
+### 6-1. host
+
+| 필드 | 설명 |
+| --- | --- |
+| `host_id` | 정규화된 표준 호스트 ID |
+| `hostname` | 대표 호스트명 |
+| `platform` | macOS / Linux / Windows 등 |
+| `primary_ip` | 대표 IP |
+| `status` | online / offline / unknown |
+| `first_seen_at` | 최초 관측 시각 |
+| `last_seen_at` | 마지막 관측 시각 |
+| `fleet_host_id` | Fleet 원본 식별자 |
+| `wazuh_agent_id` | Wazuh 원본 식별자 |
+| `zabbix_host_id` | Zabbix 원본 식별자 |
+
+### 6-2. alert
+
+| 필드 | 설명 |
+| --- | --- |
+| `alert_id` | 정규화된 경보 ID |
+| `source` | `wazuh` / `zabbix` / `host_log` 등 |
+| `source_event_id` | 원본 이벤트 ID |
+| `host_id` | 연결된 호스트 |
+| `severity` | 표준 심각도 |
+| `rule_name` | 룰/트리거명 |
+| `message` | 요약 메시지 |
+| `observed_at` | 발생 시각 |
+| `raw_ref` | 원본 로그/이벤트 위치 |
+
+### 6-3. vulnerability
+
+| 필드 | 설명 |
+| --- | --- |
+| `vuln_id` | 정규화된 취약점 ID |
+| `host_id` | 연결된 호스트 |
+| `cve` | CVE 식별자 |
+| `severity` | 표준 심각도 |
+| `package_name` | 영향 패키지 |
+| `installed_version` | 현재 버전 |
+| `fixed_version` | 수정 버전 |
+| `detected_at` | 탐지 시각 |
+| `raw_ref` | 원본 취약점 레코드 참조 |
+
+### 6-4. query_result
+
+| 필드 | 설명 |
+| --- | --- |
+| `query_result_id` | 정규화된 결과 ID |
+| `source` | 기본값 `fleet` |
+| `host_id` | 연결된 호스트 |
+| `query_name` | 쿼리명 또는 pack 이름 |
+| `query_text` | 원본 쿼리 또는 식별자 |
+| `result_json` | 결과 원문 |
+| `observed_at` | 수집 시각 |
+| `raw_ref` | Loki 로그 또는 원본 경로 |
+
+### 6-5. host_observation
+
+| 필드 | 설명 |
+| --- | --- |
+| `observation_id` | 정규화된 관측 ID |
+| `source` | `fleet`, `zabbix`, `host_log` 등 |
+| `host_id` | 연결된 호스트 |
+| `observation_type` | status / metric / availability 등 |
+| `metric_name` | cpu, memory, disk, checkin 등 |
+| `metric_value` | 값 |
+| `unit` | %, bytes, state 등 |
+| `observed_at` | 관측 시각 |
+| `raw_ref` | 원본 이벤트 참조 |
+
+## 7. 공통 필드 규칙
+
+모든 이벤트성 엔터티는 가능하면 아래 필드를 공통으로 갖습니다.
+
+- `source`
+- `event_type`
+- `host_id`
+- `severity`
+- `message`
+- `observed_at`
+- `raw_ref`
+- `raw_payload`
+
+정규화 규칙:
+
+- 시간은 UTC 기준 ISO 8601로 저장
+- 심각도는 원본 값과 표준 값을 함께 보존
+- 원본 payload 삭제 금지
+- 사람이 읽는 요약과 원본 증거를 함께 저장
+
+## 8. 1차 질의 카탈로그
+
+Phase 1에서 먼저 템플릿화할 질문 후보는 아래와 같습니다.
+
+1. 지난 24시간 `high/critical` alert 수는 얼마인가?
+2. 현재 오프라인 또는 unavailable 상태인 호스트는 무엇인가?
+3. Fleet에 등록됐지만 최근 체크인이 없는 호스트는 무엇인가?
+4. 취약점이 가장 많은 호스트 Top 10은 무엇인가?
+5. 특정 호스트의 최근 24시간 타임라인을 보여줘.
+6. 특정 호스트에서 최근 발생한 Wazuh alert만 보여줘.
+7. 특정 호스트의 최근 Fleet query 결과를 보여줘.
+8. 최근 새로 탐지된 high 이상 취약점은 무엇인가?
+9. 경보가 많으면서 동시에 상태가 불안정한 호스트는 무엇인가?
+10. Fleet/Wazuh/Zabbix 중 하나라도 매핑되지 않은 자산은 무엇인가?
+11. 최근 로그인 실패가 많은 사용자 또는 호스트는 무엇인가?
+12. 최근 수집 오류 또는 상태 오류가 반복된 호스트는 무엇인가?
+
+## 9. 구현 순서 제안
+
+1. `host` 매핑 규칙과 source reference 필드를 먼저 확정
+2. Fleet/host log용 정규화 규칙부터 적용
+3. Wazuh/Zabbix collector 입력 스펙 추가
+4. 1차 질의 카탈로그를 API 템플릿으로 변환
+5. 이후 자연어 → intent/filter 매핑 추가
+
+## 10. 다음 바로 할 일
+
+이 문서 다음 단계는 아래 둘 중 하나입니다.
+
+1. **공통 스키마를 테이블 설계 수준으로 내리기**
+2. **collector / API / schema 디렉터리 구조를 저장소에 실제로 만들기**
+
+권장 순서는 **스키마 상세화 → 구현 골격 추가**입니다.
+세부 테이블 설계는 `docs/PHASE1_LOGICAL_SCHEMA.md`에서 이어집니다.