kshield: Linux OS 보안 강화 Agent

✅ Agent 역할: kshield-claude Manager의 TIER 4 실행 엔진

프로젝트 역할:

• kshield (본 프로젝트): Linux 호스트의 에이전트
• kshield-claude: Windows Manager 서버에서 중앙 관제
• 통신: SSH를 통한 Manager → Agent 명령 실행

최신 업데이트 (2026-01-20):

• ✅ 72개 규칙 호스트 검증 완료 (100% 성공률)
• ✅ 동적 YAML 규칙 로딩 지원
• ✅ 자동 승인 환경변수 (KSHIELD_AUTO_APPROVE=true)
• ✅ 인코딩 이슈 완벽 해결 (Unicode→ASCII)
• ✅ 모든 문서 최신화 및 폴더 정리 완료

🏗️ 시스템 아키텍처

┌──────────────────────────────────────┐
│ kshield-claude (Manager)             │
│ Windows 관리 서버                    │
│                                      │
│ • TIER 1-4 오케스트레이션            │
│ • 중앙 계획 및 모니터링              │
│ • SSH로 Agent 제어                   │
└──────────────┬───────────────────────┘
               │ SSH 원격 명령 실행
       ┌───────▼──────────┐
       │ SSH 포트 22      │
       └───────┬──────────┘
               │
┌──────────────▼───────────────────────┐
│ kshield (본 프로젝트 - Agent)         │
│ Linux 호스트들 (/opt/kshield/)      │
│                                      │
│ • 보안 규칙 실행 (72개 KISA 규칙)  │
│ • 현재 상태 정보 수집 및 보고       │
│ • 규칙 적용 로그 생성                │
│ • Manager 명령 처리                  │
│ • 상태/결과 보고                     │
└──────────────────────────────────────┘

주요 특징

✅ Agent 설계

• Manager와 SSH를 통한 명령-응답 구조
• systemd 서비스로 백그라운드 실행
• CentOS, RHEL, Ubuntu 지원
• KISA 2021 표준 규칙 (72개)

✅ 3가지 실행 모드 (Manager의 지시에 따름)

• 검증 모드: 현재 설정 검증만 수행
• 드라이런 모드: 변경 사항 시뮬레이션
• 적용 모드: 실제 설정 변경 적용

✅ 상세한 보고

• JSON 기반 결과 출력
• 규칙별 상세 증거 수집
• 상태 정보 Manager에 보고
• 로그 파일 관리 (/var/log/kshield/)

빠른 시작

설치 시나리오

시나리오 1: Manager에서 자동 배포 (권장)

Windows의 kshield-claude Manager에서 자동으로 모든 호스트에 에이전트를 배포합니다:

# Windows CLI Manager에서
python cli_manager.py agent deploy --all-hosts

# 또는 특정 호스트에만
python cli_manager.py agent deploy --hostname 10.0.1.10

시나리오 2: 수동 설치 (각 Linux 호스트에서)

# 1. kshield 저장소 다운로드
git clone https://github.com/henryGTI/kshield.git /tmp/kshield
cd /tmp/kshield

# 2. 설치
sudo bash install_agent.sh
# 또는
sudo python install_agent.py

# 3. 서비스 시작 및 활성화
sudo systemctl start kshield-agent
sudo systemctl enable kshield-agent

# 4. 상태 확인
sudo systemctl status kshield-agent
sudo tail -f /var/log/kshield/agent.log

에이전트 디렉토리 구조

/opt/kshield/                        # 에이전트 설치 경로
├── agent.py                         # Agent 메인 프로세스
├── config/
│   ├── agent.conf                   # 에이전트 설정
│   └── rules.d/                     # 규칙 정의 디렉토리
├── logs/
│   ├── agent.log                    # 운영 로그
│   └── rules/                       # 규칙별 실행 로그
├── cache/
│   ├── state.json                   # 현재 상태
│   └── applied_rules.json           # 적용된 규칙 목록
└── lib/                             # 라이브러리

systemd 서비스:
/etc/systemd/system/kshield-agent.service

Manager와의 통신

Agent는 Manager의 지시에 따라 실행됩니다:

# Manager가 Agent에 보내는 명령 예시 (SSH를 통해):

# 1. 현재 상태 수집
ssh kshield@host /opt/kshield/agent.py status

# 2. 규칙 검증 (Dry-run)
ssh kshield@host /opt/kshield/agent.py verify --rules U-01,U-02

# 3. 규칙 적용
ssh kshield@host /opt/kshield/agent.py apply --rules U-01,U-02 --wave 1

# 4. 로그 수집
ssh kshield@host /opt/kshield/agent.py logs --since "1 day"

# 5. 상태 보고
ssh kshield@host /opt/kshield/agent.py report

KISA 2021 규칙 (72개)

kshield 에이전트는 72개의 Linux 보안 규칙을 구현하고 있습니다.

규칙 범주

• U-01 ~ U-10: 서비스 관리 및 권한 설정
• U-11 ~ U-20: 파일/디렉토리 권한
• U-21 ~ U-30: 계정 및 암호 정책
• U-31 ~ U-40: 네트워크 설정
• U-41 ~ U-50: 감사 및 모니터링
• U-51 ~ U-60: 암호화 및 SSL
• U-61 ~ U-72: 기타 보안 설정

규칙 실행 흐름

Manager가 규칙 목록 전송
         ↓
Agent이 규칙 해석
         ↓
각 규칙별로:
  1. 현재 상태 검증
  2. 필요시 변경 사항 계산
  3. Dry-run 모드면 시뮬레이션 (변경 없음)
  4. Apply 모드면 실제 적용
         ↓
결과 생성:
  - 성공/실패 상태
  - 변경 사항 상세 내용
  - 증거 정보 수집
         ↓
Manager에 결과 보고

안전성 보장

Agent의 안전 메커니즘

Pre-Execution 검증

1. 권한 확인: root 또는 sudo 권한 필요
2. OS 호환성: CentOS/RHEL/Ubuntu 버전 확인
3. 필수 패키지: 규칙 실행에 필요한 도구 확인

Dry-Run 모드 (Manager 지시)

1. Manager가 --dryrun 옵션으로 Agent에 명령
2. Agent는 변경 사항을 시뮬레이션만 수행
3. 실제 시스템 변경 없음

규칙 충돌 감지

1. 규칙 간 의존성 분석
2. 호스트 환경과의 호환성 검사

롤백 기능

• Manager 지시 시 이전 상태로 복구 가능
• 변경 이력 보관 (/opt/kshield/cache/)

개발 로드맵

Phase 15 (완료 ✅ - 2026-01-18)

• ✅ Agent 역할 정의 (Manager와의 통합)
• ✅ 72개 KISA 규칙 구현
• ✅ systemd 서비스 통합
• ✅ SSH 공개키 인증 안정화
• ✅ Manager-Agent 아키텍처 통합

Phase 16 (진행중 🔄)

• 🔄 Agent 상태 모니터링 개선
• 🔄 로그 수집 및 보고 최적화
• ⏳ 성능 모니터링 메트릭 추가
• ⏳ 하트비트 기반 헬스 체크

Phase 17 (계획됨)

• ⏳ 고급 롤백 기능
• ⏳ 규칙 간 의존성 분석
• ⏳ 실시간 모니터링
• ⏳ 웹 기반 상태 조회

프로젝트 구조

kshield-claude (Manager) ↔ kshield (Agent)

역할 분담:

Manager (kshield-claude - Windows)        Agent (kshield - Linux)
├─ TIER 1 분석                          ├─ 환경 정보 수집
├─ TIER 2 계획                          ├─ 규칙 호환성 확인
├─ TIER 3 승인                          ├─ 상태 전송
├─ TIER 4 실행 오케스트레이션          ├─ 규칙 실행
│  └─ Agent에 SSH 명령 전송            │  └─ 명령 처리
└─ 모니터링 및 보고                      └─ 로그 및 결과 보고

통신 프로토콜

Agent는 Manager로부터 SSH를 통해 명령을 수신합니다:

명령	설명	응답
status	현재 상태 조회	JSON 상태 정보
verify --rules X,Y	규칙 검증 (드라이런)	검증 결과
apply --rules X,Y --wave N	규칙 적용	적용 결과
rollback --rules X,Y	롤백 실행	롤백 결과
logs --since N	로그 수집	로그 파일
report	상태 보고	종합 보고서

관련 저장소

Manager 프로젝트:

• kshield-claude
  • 역할: Windows에서 TIER 1-4 오케스트레이션
  • 기능: 다중 호스트 관리, 중앙 계획, 승인 워크플로우
  • 문서: CLI 가이드, 운영 가이드

Agent 프로젝트:

• kshield (본 프로젝트)
  • 역할: Linux 호스트에서 규칙 실행
  • 기능: 72개 보안 규칙, 상태 수집, 로그 생성
  • 설치: systemd 서비스로 백그라운드 실행

---

📌 요약

kshield는 kshield-claude Manager가 제어하는 Linux 보안 강화 Agent입니다.

항목	내용
역할	TIER 4 실행 엔진 (Agent)
설치 위치	Linux 호스트 (/opt/kshield/)
실행 방식	systemd 서비스 (kshield-agent)
통신	SSH를 통한 Manager 명령 수신
기능	72개 KISA 규칙 실행 및 상태 보고
안전성	Dry-run 모드, 롤백 기능, 권한 검증

시작하기:

1. Manager (kshield-claude)에서 에이전트 배포: agent deploy --all-hosts
2. 또는 수동 설치: bash install_agent.sh
3. 서비스 시작: systemctl start kshield-agent

마지막 업데이트: 2026-01-18
버전: v0.8.0 (Agent)
상태: ✅ 프로덕션 준비 완료 (Manager와 통합)