guardia-itsm/CLAUDE.md

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에만 저장. 메신저 응답에 노출 금지.

---

파일 작성 규칙

• CLAUDE.md 수정 시: 반드시 Python open(encoding='utf-8') 또는 Write 도구 사용
  • PowerShell Set-Content / Out-File 절대 금지 (UTF-16 LE 오염 발생)
• .xfdl.js 파일: Nexacro 빌드 결과물 — 절대 수정/커밋 금지