034301d3f2
Agents: - itsm-ui-refactor: dark theme CSS token overhaul (navy+cyan) - manager-ui-refactor: light theme React component styling Skills: - guardia-design-orchestrator: parallel pipeline orchestrator - itsm-design-overhaul: style.css token/sidebar/card/button/table guide - manager-design-overhaul: Sidebar/GNB/StatCard/DataTable/Dashboard guide Reference: C:/GUARDiA/screenshot (Variant design, #003366/#005A8C/#00A0C8) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
184 lines
9.2 KiB
Markdown
184 lines
9.2 KiB
Markdown
# GUARDiA ITSM — AI 기반 레거시 인프라 자율 운영 플랫폼
|
|
## Claude Code 프로젝트 마스터 컨텍스트
|
|
|
|
> 이 파일을 읽고 프로젝트 전체 구조와 규칙을 파악한 뒤 작업을 시작하라.
|
|
|
|
---
|
|
|
|
## 프로젝트 비전
|
|
|
|
1,000개 이상 다중 관공서(Multi-tenant) 레거시 인프라를 타겟으로 하는
|
|
**AI 기반 통합 ChatOps 오케스트레이션 플랫폼**.
|
|
|
|
- 메신저 한 줄 명령 → sLLM 파싱 → 에이전트리스(SSH/SFTP) 배포·운영 자동화
|
|
- 에이전트 설치 **불필요** — 표준 SSH/FTP 프로토콜만 활용
|
|
- 개발(Dev), SM 운영, PM 관리 세 역할의 워크플로우를 단일 메신저로 통합
|
|
- **온프레미스 전용**: 외부 클라우드 API 완전 금지 (Ollama 내부 LLM만 허용)
|
|
|
|
---
|
|
|
|
## 기술 스택
|
|
|
|
| 레이어 | 기술 | 비고 |
|
|
|--------|------|------|
|
|
| Backend API | Python 3.11+ / FastAPI | 비동기 WebSocket 처리 |
|
|
| LLM | Ollama localhost:11434 (codellama, llama3) | 외부 API 완전 금지 |
|
|
| Infra 연결 | paramiko (SSH/SFTP) | 에이전트리스 |
|
|
| Database | SQLite (dev) / PostgreSQL (prod) | SQLAlchemy async |
|
|
| 암호화 | AES-256-GCM (서버 자격증명) | |
|
|
| 인증 | JWT + 2FA/OTP | |
|
|
|
|
---
|
|
|
|
## 디렉토리 구조
|
|
|
|
```
|
|
C:\GUARDiA\
|
|
├── itsm/ # FastAPI 백엔드
|
|
│ ├── main.py # FastAPI 앱 진입점
|
|
│ ├── models.py # SQLAlchemy 모델
|
|
│ ├── auth.py # JWT 인증
|
|
│ ├── database.py # DB 연결
|
|
│ ├── core/ # 비즈니스 로직
|
|
│ │ ├── code_review.py # B-3: 코드 리뷰 엔진
|
|
│ │ ├── anomaly.py # B-1: 이상 탐지 엔진
|
|
│ │ └── notify.py # 알림 공통
|
|
│ ├── routers/ # API 라우터
|
|
│ └── .claude/ # 하네스 에이전트/스킬
|
|
├── projects/ # SM/SI 프로젝트 소스
|
|
│ ├── testcase-java-api/ # Spring Boot 테스트케이스
|
|
│ ├── testcase-py-api/ # FastAPI 테스트케이스
|
|
│ ├── testcase-js-frontend/ # HTML/JS 테스트케이스
|
|
│ └── testcase-php-legacy/ # PHP 레거시
|
|
└── docs/
|
|
```
|
|
|
|
---
|
|
|
|
## 보안 제약 (절대 불변)
|
|
|
|
1. **외부 API 완전 금지** — 모든 AI/LLM 호출은 내부 sLLM only (Ollama localhost:11434)
|
|
2. **서버 자격증명 노출 금지** — IP, 비밀번호, SSH 계정을 API 응답/메신저에 포함 금지
|
|
3. **AES-256-GCM 암호화** — tb_server.os_pw_enc 컬럼 필수 암호화
|
|
4. **root SSH 직접 접속 금지** — ssh_user != root 강제
|
|
5. **ServerOut 스키마 제외 필드** — ip_addr, ssh_user, os_pw_enc 절대 미포함
|
|
6. **스택트레이스 노출 금지** — 에러 응답은 SR ID + 요약 메시지만
|
|
7. **명령어 안전성 검증** — SSH 실행 전 위험 패턴 차단 (rm -rf /, mkfs, dd, shutdown 등)
|
|
8. **경로 순회 방지** — 첨부파일 경로 resolve().relative_to(UPLOAD_ROOT) 검증
|
|
|
|
---
|
|
|
|
## 30개 고도화 항목 진행 현황
|
|
|
|
| 코드 | 항목 | 상태 | 주요 파일 |
|
|
|------|------|------|-----------|
|
|
| A-1 | 알림 고도화 (WebSocket + 이메일) | ✅ DONE | routers/notify.py, core/notify.py |
|
|
| A-2 | 첨부 파일 관리 | ✅ DONE | routers/attachments.py |
|
|
| A-3 | 배포 승인 알림 (VibeSession 연동) | ✅ DONE | routers/vibe.py |
|
|
| A-4 | 운영 이벤트 타임라인 | ✅ DONE | routers/timeline.py |
|
|
| A-5 | 역할 기반 접근 제어 (RBAC) | ✅ DONE | auth.py, models.py |
|
|
| B-1 | AI 이상 탐지 (Anomaly Detection) | ✅ DONE | core/anomaly.py, routers/anomaly.py |
|
|
| B-2 | 자연어 SR 접수 챗봇 | ✅ DONE | core/chatbot.py, routers/chatbot.py |
|
|
| B-3 | 코드 리뷰 에이전트 (Ollama) | ✅ DONE | core/code_review.py, routers/code_review.py |
|
|
| B-4 | KB 자동 업데이트 에이전트 | ✅ DONE | core/kb_agent.py, routers/kb_agent.py |
|
|
| B-5 | 멀티 에이전트 협업 오케스트레이션 | ✅ DONE | core/orchestrator.py, routers/orchestrator.py |
|
|
| B-6 | 예측 유지보수 | ✅ DONE | core/predictive.py, routers/predictive.py |
|
|
| C-1 | CMDB (형상 관리 DB) | ✅ DONE | routers/cmdb.py (CI+관계+변경이력) |
|
|
| C-2 | 변경 관리 CAB | ✅ DONE | routers/change.py (RFC/CAB투표/동결기간) |
|
|
| C-3 | Problem Management | ✅ DONE | routers/problem.py (RCA/Known Error/PRB ID) |
|
|
| C-4 | 용량 관리 대시보드 | ✅ DONE | routers/capacity.py (예측/경보/확장시점) |
|
|
| C-5 | 서비스 카탈로그 | ✅ DONE | routers/catalog.py (SLA/SR자동생성/SVC ID) |
|
|
| D-1 | LDAP/AD 연동 | ✅ DONE | core/ldap_auth.py, routers/ldap.py (그룹→역할/env설정/동기화) |
|
|
| D-2 | 2FA / OTP | ✅ DONE | routers/otp.py |
|
|
| D-3 | 특권 접근 관리 (PAM) | ✅ DONE | routers/pam.py (세션발급/체크아웃/명령로깅/강제종료) |
|
|
| D-4 | 보안 취약점 자동 스캔 | ✅ DONE | core/vuln_scan.py, routers/vuln_scan.py (포트스캔/CVE/CVSS) |
|
|
| D-5 | 불변 감사 로그 (Hash Chain) | ✅ DONE | routers/audit.py (SHA-256체인/entity/IP해시/export) |
|
|
| E-1 | 월별 리포트 자동 생성 | ✅ DONE | routers/report.py |
|
|
| E-2 | 대시보드 분석 | ✅ DONE | routers/analytics.py |
|
|
| E-3 | SLA 대시보드 (실시간) | ✅ DONE | routers/sla.py |
|
|
| E-4 | Grafana 연동 (Prometheus) | ✅ DONE | routers/metrics.py |
|
|
| E-5 | FinOps 비용 분석 | ✅ DONE | routers/finops.py |
|
|
| F-1 | 멀티테넌트 데이터 격리 | ✅ DONE | middleware/tenant.py |
|
|
| F-2 | 모바일 반응형 UI | ✅ DONE | static/ |
|
|
| F-3 | 다국어 지원 (i18n) | ✅ DONE | core/i18n.py |
|
|
| F-4 | Mobile PWA | ✅ DONE | static/manifest.json |
|
|
| F-5 | OpenAPI 외부 연동 게이트웨이 | ✅ DONE | routers/gateway.py |
|
|
|
|
**완료: 30개 | 남은 항목: 0개 🎉**
|
|
|
|
---
|
|
|
|
## GUARDiA 하네스 구조 (.claude/)
|
|
|
|
### 에이전트 (agents/)
|
|
- **sr-manager.md**: SR 생성/조회/상태변경/담당자배정
|
|
- **code-reviewer.md**: B-3 코드 리뷰, quick-scan, findings 분석
|
|
- **deploy-engineer.md**: VibeSession 배포 파이프라인, Jenkins 연동
|
|
- **sla-guardian.md**: SLA 모니터링, 에스컬레이션
|
|
- **incident-responder.md**: 인시던트 생성, 온콜 호출, RCA
|
|
- **dr-coordinator.md**: DR 자동화, Failover, RTO/RPO
|
|
- **network-guardian.md**: 네트워크 장비 관리, 설정 백업
|
|
- **csap-auditor.md**: CSAP/ISMS 자동 점검, 보고서
|
|
- **validation-learner.md**: ITSM 소스 AST 파싱 → validation 규칙 학습
|
|
- **rpa-bot.md**: 학습 규칙 참조 → ITSM 반복 작업 자동화 실행
|
|
|
|
### 스킬 (skills/)
|
|
- **guardia-orchestrator/SKILL.md**: E2E SR→코드리뷰→배포 워크플로우 + RPA 위임
|
|
- **code-review/SKILL.md**: B-3 코드 리뷰 실행 가이드
|
|
- **sr-lifecycle/SKILL.md**: SR 상태 흐름, SLA 기준
|
|
- **deploy-pipeline/SKILL.md**: VibeSession 배포 단계 관리
|
|
- **dr-automation/SKILL.md**: DR 자동화, Failover 실행
|
|
- **network-devices/SKILL.md**: 네트워크 장비 SSH 관리
|
|
- **csap-compliance/SKILL.md**: CSAP/ISMS 점검 자동화
|
|
- **rpa-orchestrator/SKILL.md**: RPA 봇 E2E 워크플로우 (validation 학습 + 실행)
|
|
- **rpa-validation/SKILL.md**: 소스 기반 validation 규칙 학습
|
|
|
|
## 하네스: GUARDiA RPA 봇
|
|
|
|
**목표:** ITSM 반복 업무(SR 자동 접수, 승인, 점검 등)를 소스 기반 Validation 학습으로 안전하게 자동화
|
|
|
|
**트리거:** RPA, 봇 자동화, 반복 작업, validation 학습 요청 시 `rpa-orchestrator` 스킬을 사용하라.
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-05-31 | RPA 하네스 초기 구성 | validation-learner, rpa-bot, rpa-orchestrator, rpa-validation | RPA 봇 기능 추가 |
|
|
|
|
---
|
|
|
|
## 핵심 구현 원칙
|
|
|
|
1. **에이전트리스**: 대상 서버에 어떤 소프트웨어도 설치하지 않는다.
|
|
2. **결정론적 파싱**: sLLM은 JSON만 출력한다. 자연어 부연 설명 금지.
|
|
3. **Fail-Safe**: 모든 배포는 백업→배포→헬스체크→롤백 시퀀스를 따른다.
|
|
4. **감사 추적**: 모든 명령과 결과는 TB_AUDIT_LOG에 기록한다.
|
|
5. **최소 권한**: 관제 전용 일반 계정(opsagent) 사용. root SSH 직접 접속 금지.
|
|
6. **보안 우선**: 서버 자격증명은 암호화 DB에만 저장. 메신저 응답에 노출 금지.
|
|
|
|
---
|
|
|
|
## 하네스: GUARDiA 디자인 개편
|
|
|
|
**목표:** C:\GUARDiA\screenshot (Variant 스타일) 기준으로 ITSM + Manager UI 전면 개편.
|
|
색상 토큰 통일(#003366·#005A8C·#00A0C8), Playwright MCP Before/After 검증.
|
|
|
|
**트리거:** ITSM·Manager 디자인 개편, 색상 변경, UI 스타일 변경 요청 시 `guardia-design-orchestrator` 스킬을 사용하라.
|
|
|
|
**에이전트:**
|
|
- `itsm-ui-refactor`: ITSM style.css 다크테마 개편
|
|
- `manager-ui-refactor`: Manager React 컴포넌트 라이트테마 개편
|
|
- `visual-qa-tester`: Playwright MCP Before/After 캡처·비교
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-05-31 | 디자인 개편 하네스 초기 구성 | ITSM + Manager | Variant 스타일 적용 |
|
|
|
|
---
|
|
|
|
## 파일 작성 규칙
|
|
|
|
- **CLAUDE.md 수정 시**: 반드시 Python `open(encoding='utf-8')` 또는 Write 도구 사용
|
|
- PowerShell `Set-Content` / `Out-File` 절대 금지 (UTF-16 LE 오염 발생)
|
|
- **.xfdl.js 파일**: Nexacro 빌드 결과물 — 절대 수정/커밋 금지
|