- 프로젝트 개요
- 주요 기능
- 시스템 아키텍처
- 기술 스택
- 설치 방법
- 실행 방법
- 사용 예시
- 워크플로우
- API 문서
- 환경 설정
- 배포 가이드
- Git Commit Convention
- 관련 문서
CIRF-AI-Agent는 AWS 클라우드 환경의 다양한 로그를 요약하고 분석하는 AI 에이전트입니다. 자연어 질의를 통해 복잡한 Elasticsearch 쿼리를 생성하고, 대량의 로그 데이터를 효율적으로 요약하며, MITRE ATT&CK 프레임워크 기반의 공격 분석을 제공할 수 있습니다.
- 자연어 기반 로그 검색: 복잡한 쿼리 언어 없이 일상 언어로 로그 검색
- 침해사고 분석 지원: MITRE ATT&CK 프레임워크 기반 의심 공격 분석
- 대량 로그 처리: Map-Reduce 방식으로 최대 200,000건의 로그를 효율적으로 요약
- 실시간 진행 상황 제공: Server-Sent Events (SSE)를 통해 실시간 진행 상황 전송
- 컨텍스트 기반 대화: 이전 분석 결과를 기반으로 한 후속 질의 처리 제공
- LangGraph 기반
- Google Gemini LLM (그 외 다양한 LLM 모델 사용 가능)
- Elasticsearch 8.0+
- FastAPI 기반 REST API
- 피드백 루프로 답변 평가 후 개선
- (디버깅) LangSmith를 통한 LLM 호출 추적 및 모니터링
- (디버깅) 비용 및 성능 메트릭 자동 수집
사용자가 입력한 자연어 질의를 Elasticsearch 쿼리로 자동 변환합니다.
예시:
사용자 입력: "kwanwoo 사용자의 최근 24시간 실패한 로그인 로그 조회"
자동 생성된 SearchPlan:
{
"time_range": {"gte": "now-24h", "lte": "now"},
"filters": {
"actor": ["kwanwoo"],
"activity": ["ConsoleLogin"],
"outcome": ["Failure"]
},
"types": ["cloudtrail"],
"limit": 200000
}
| 모드 | 설명 | LLM 호출 | ES 조회 | 응답 시간 | 용도 |
|---|---|---|---|---|---|
| Fetch | API 파라미터만 생성 | 1회 | 없음 | ~1-2초 | 빠른 쿼리 생성 |
| Summary | 로그 조회 + 요약 | 다수 | 있음 | ~5-15초 | 로그 파악 |
| Analysis | 요약 + 분석 | 가장 많음 | 있음 | ~10-25초 | 분석 지원 |
최대 200,000건의 로그를 병렬 처리하여 요약합니다.
- Map 단계: 로그를 800건씩 청크로 분할하여 병렬 요약 (최대 5개 동시 처리)
- Reduce 단계: 생성된 요약을 계층적으로 병합 (50개씩 배치 처리)
- 성능 최적화: 비동기 처리 및 토큰 사용량 최적화
AWS 이벤트를 MITRE ATT&CK 기법에 자동 매핑하여 침해사고를 분석합니다.
매핑 예시:
ConsoleLogin→ T1078.004 (Valid Accounts: Cloud Accounts)DeleteTrail→ T1562.008 (Impair Defenses: Disable Cloud Logs)CreateAccessKey→ T1098.001 (Account Manipulation: Additional Cloud Credentials)GetObject→ T1530 (Data from Cloud Storage Object)
위협 분석 출력:
{
"suspectedAttacks": [
{
"actor": "suspicious-user",
"target": "arn:aws:s3:::sensitive-bucket",
"mitreTechniques": ["T1078.004", "T1530"],
"severity": "HIGH",
"description": "탈취된 계정으로 민감 S3 버킷 접근",
"evidence": ["비정상 시간대 로그인", "대량 GetObject 요청"],
"timeline": "2025-12-12 02:00 ~ 02:30"
}
],
"recommendations": [
"suspicious-user 계정 즉시 비활성화",
"S3 버킷 접근 로그 상세 조사"
]
}3가지 검증 패턴으로 출력 품질을 개선합니다:
- 요약 품질 검증: 불충분한 요약 재생성 (최대 2회 재시도)
- 이벤트 추출 검증: 중요 필드(actor, activity, time) 누락 확인
- MITRE 매핑 검증: 잘못된 매핑 필터링 및 자기 검증 (최대 3회 재시도)
이전 분석 결과에 대한 추가 질문을 지능적으로 처리합니다:
- 설명 요청: "T1078.004가 뭐야?" → Elasticsearch 조회 없이 MITRE 기법 설명
- 드릴다운 분석: "suspicious-user 상세 분석" → 추가 로그 조회 및 심층 분석
- 새로운 분석: 완전히 새로운 질의 → 새 워크플로우 실행
분석 결과를 바탕으로 향후 분석 방향을 제안합니다.
Pivot 제안 예시:
{
"pivotSuggestions": [
{
"type": "temporal_expansion",
"description": "suspicious-user의 전후 7일 활동 조사",
"query": "suspicious-user 최근 7일 로그"
},
{
"type": "related_entities",
"description": "suspicious-user가 접근한 리소스 목록",
"query": "suspicious-user가 접근한 S3 버킷 목록"
}
]
}- Server-Sent Events (SSE): 실시간 진행 상황 업데이트
- LangSmith 통합: LLM 호출 추적, 디버깅, 성능 모니터링
- 비용 추적: 토큰 사용량 및 API 비용 자동 계산
- 성능 메트릭: 실행 시간, 토큰 수, ES 쿼리 수 등 자동 수집
┌─────────────────────────────────────────────────────────────┐
│ 사용자 (자연어 질의) │
│ "kwanwoo의 최근 10000건 로그 분석" │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI REST API Server │
│ (api/server.py) │
│ │
│ GET / - Health Check │
│ POST /api/v1/agent - Standard Request │
│ POST /api/v1/agent/stream - SSE Streaming │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph Workflow Engine │
│ (core/workflow.py) │
│ │
│ ┌──────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │ Query 해석 │ │ Log 조회 │ │ Threat 분석 │ │
│ │ (LLM) │→ │(Elasticsearch)│→│ (LLM+MITRE) │ │
│ └──────────────┘ └─────────────┘ └────────────────┘ │
│ │
│ nodes/query.py → nodes/fetch_chunked.py → nodes/analysis.py│
└─────────────────────────────────────────────────────────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌──────────┐
│ LLM │ │Elasticsearch│ │ MITRE │
│ (Gemini/│ │ (로그 │ │ ATT&CK │
│ Claude) │ │ 저장소) │ │프레임워크 │
└─────────┘ └─────────────┘ └──────────┘
자연어 질의
│
▼
[interpret_query_node] ← LLM: 자연어 → SearchPlan 변환
│
▼
[validate_plan_node] ← SearchPlan 검증 및 기본값 설정
│
▼
[count_logs_node] ← Elasticsearch: 로그 건수 조회
│
▼
[decide_strategy_node] ← 전략 결정 (chunked vs too_large)
│
├─ (0~200K건) ──────────┐
│ ▼
│ [chunked_fetch_node] ← ES: 청크별 로그 조회
│ │
│ ▼
│ [summarize_chunked_logs_node] ← LLM: Map-Reduce 요약
│ │
│ ▼
│ [validate_summary_quality_node] ← 품질 검증
│ │
│ ▼
│ [analyze_threat_node] ← LLM: MITRE 매핑 + 위협 분석
│ │
│ ▼
│ [self_critique_threat_node] ← 자기 검증 (최대 3회)
│ │
│ ▼
│ [generate_pivot_suggestions_node] ← Pivot 제안
│ │
└────────────────────────┘
│
▼
[format_answer_node] ← 최종 출력 포맷팅
│
▼
[save_to_history] ← 대화 히스토리 저장
│
▼
END
| 카테고리 | 기술 | 버전 | 용도 |
|---|---|---|---|
| 웹 프레임워크 | FastAPI | 0.109+ | REST API 서버 |
| 워크플로우 엔진 | LangGraph | 0.2+ | 상태 기반 AI 워크플로우 |
| LLM 통합 | LangChain | 0.3+ | LLM 추상화 레이어 |
| LLM 제공자 | Google Gemini / Anthropic Claude | - | 자연어 처리 및 분석 |
| 검색 엔진 | Elasticsearch | 8.0+ | 로그 저장 및 검색 |
| ASGI 서버 | Uvicorn | 0.27+ | 고성능 HTTP 서버 |
| 모니터링 | LangSmith | - | LLM 호출 추적 및 디버깅 |
| 데이터 검증 | Pydantic | 2.0+ | 데이터 모델 및 검증 |
# LangChain & LangGraph
langgraph>=0.2.0 # 워크플로우 엔진
langchain>=0.3.0 # LLM 통합
langchain-anthropic # Claude API 지원
langchain-google-genai # Gemini API 지원
langchain-core # LangChain 코어
langchain-community # 커뮤니티 통합
# Elasticsearch
elasticsearch>=8.0.0 # ES 클라이언트
# FastAPI & Web Server
fastapi>=0.109.0 # REST API 프레임워크
uvicorn[standard]>=0.27.0 # ASGI 서버
# Utilities
python-dotenv>=1.0.0 # 환경 변수 관리
pydantic>=2.0.0 # 데이터 검증
pydantic-settings>=2.0.0 # 설정 관리- Python: 3.11 이상
- Elasticsearch: 8.0 이상
- LLM API 키: Google Gemini 또는 다른 LLM 모델의 API 키
- OS: Linux, macOS, Windows (WSL2)
git clone https://github.com/BOB-CIRF/CIRF-AI-Agent.git
cd CIRF-AI-Agent# 가상환경 생성
python3 -m venv venv
# 가상환경 활성화
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activatepip install --upgrade pip
pip install -r requirements.txt.env 파일을 프로젝트 루트에 생성하고 아래 내용을 입력합니다:
# Elasticsearch 설정
ES_HOST=your-elasticsearch-host
ES_PORT=9200
ES_INDEX=logs-tenant-*
ES_USER=elastic
ES_PASSWORD=your-password
# LLM 제공자 선택
LLM_PROVIDER=gemini
LLM_API_KEY=your-api-key
# Gemini 모델 설정 (선택사항)
GEMINI_MODEL=gemini-2.5-flash-lite
LLM_TEMPERATURE=0
# Anthropic 모델 설정 (선택사항)
ANTHROPIC_MODEL=claude-sonnet-4-20250514
# 처리 전략 임계값 (선택사항)
CHUNKED_THRESHOLD=200000 # 청크 처리 최대 로그 수
# 청크 처리 설정 (선택사항)
CHUNK_SIZE=800 # 청크당 로그 건수
MAX_PARALLEL_CHUNKS=5 # 동시 처리 청크 수
REDUCE_BATCH_SIZE=50 # Reduce 배치 크기
# LangSmith 모니터링 (선택사항)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langsmith-key
LANGCHAIN_PROJECT=AI_AGENT_TEST
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
# LangSmith 크기 제한 처리 (선택사항)
LANGSMITH_SIZE_THRESHOLD_MB=0.3
LANGSMITH_DISABLE_FOR_LARGE_DATA=false
# 디버그 모드 (선택사항)
DEBUG_MODE=false# 가상환경 활성화
source venv/bin/activate
# FastAPI 서버 실행 (Hot Reload)
uvicorn api.server:app --reload --host 0.0.0.0 --port 8000# 멀티워커 모드로 실행
uvicorn api.server:app --host 0.0.0.0 --port 8000 --workers 4curl http://localhost:8000/예상 응답:
{
"status": 200,
"message": "CIRF AI Agent API is running",
"data": {
"service": "CIRF AI Agent API",
"version": "1.0.0"
}
}요청:
curl -X POST http://localhost:8000/api/v1/agent \
-H "Content-Type: application/json" \
-H "userId: analyst123" \
-d '{
"query": "kwanwoo 사용자의 최근 24시간 로그 100건 조회",
"mode": "fetch"
}'응답:
{
"status": 200,
"message": "쿼리 파라미터 변환이 완료되었습니다.",
"data": {
"mode": "fetch",
"apiParams": {
"logType": "cloudtrail",
"keyword": "kwanwoo",
"startTime": "2025-12-12T00:00:00",
"endTime": "2025-12-13T00:00:00",
"limit": 100
},
"performanceMetrics": {
"totalDurationSeconds": 1.2,
"totalInputTokens": 1234,
"totalOutputTokens": 567,
"totalCostUsd": 0.0012
}
}
}요청:
curl -X POST http://localhost:8000/api/v1/agent \
-H "Content-Type: application/json" \
-H "userId: analyst123" \
-d '{
"query": "최근 24시간 실패한 로그인 로그 분석",
"mode": "summary"
}'응답:
{
"status": 200,
"message": "로그 요약이 완료되었습니다.",
"data": {
"mode": "summary",
"apiParams": {...},
"totalCountEstimate": 1234,
"summary": "최근 24시간 동안 총 1,234건의 실패한 로그인 시도가 발생했습니다. 주요 패턴은 다음과 같습니다:\n1. suspicious-user: 250회 실패 (비정상적으로 높음)\n2. 대부분 ap-northeast-2 리전에서 발생\n3. 새벽 2-4시 집중 발생",
"sampleLogs": [...],
"performanceMetrics": {
"totalDurationSeconds": 8.5,
"totalInputTokens": 25000,
"totalOutputTokens": 3500,
"totalCostUsd": 0.045
}
}
}요청:
curl -X POST http://localhost:8000/api/v1/agent/stream \
-H "Content-Type: application/json" \
-H "userId: analyst123" \
-d '{
"query": "suspicious-user의 최근 활동 분석",
"mode": "analysis"
}'SSE 스트리밍 응답:
event: progress
data: {"status":200,"message":"쿼리 해석 중...","data":{"type":"progress","step":"interpret_query","progress":10}}
event: progress
data: {"status":200,"message":"로그 조회 중...","data":{"type":"progress","step":"fetch","progress":40}}
event: progress
data: {"status":200,"message":"위협 분석 중...","data":{"type":"progress","step":"analysis","progress":80}}
event: complete
data: {"status":200,"message":"분석이 완료되었습니다.","data":{...}}
최종 응답 data:
{
"mode": "analysis",
"apiParams": {...},
"summary": "suspicious-user는 최근 24시간 동안...",
"threatAnalysis": {
"suspectedAttacks": [
{
"actor": "suspicious-user",
"target": "arn:aws:s3:::sensitive-bucket",
"mitreTechniques": ["T1078.004", "T1530"],
"mitreTactics": ["Initial Access", "Collection"],
"severity": "HIGH",
"description": "탈취된 계정으로 민감 S3 버킷 대량 접근",
"evidence": [
"비정상 시간대 로그인 (새벽 2시)",
"평소와 다른 지역에서 접근 (us-east-1)",
"1시간 내 1,000건 GetObject 요청"
],
"timeline": "2025-12-12 02:00 ~ 02:30"
}
],
"recommendations": [
"suspicious-user 계정 즉시 비활성화 및 액세스 키 회전",
"sensitive-bucket의 접근 로그 상세 조사",
"S3 버킷 ACL 및 버킷 정책 검토"
]
},
"pivotSuggestions": [
{
"type": "temporal_expansion",
"description": "suspicious-user의 전후 7일 활동 조사",
"query": "suspicious-user 최근 7일 로그"
}
],
"performanceMetrics": {...}
}이 프로젝트는 3가지 워크플로우를 제공합니다:
자연어 질의 → SearchPlan 변환 → 로그 수집 → Map-Reduce 요약
상세 문서: docs/workflows/workflow_summary.md
자연어 질의 → SearchPlan 변환 (ES 조회 없음, 빠른 응답)
상세 문서: docs/workflows/workflow_fetch.md
Summary + 침해사고 분석 + MITRE ATT&CK 매핑 + Pivot 분석 + 후속 질의
상세 문서: docs/workflows/workflow_analysis.md
- VSCode 확장 또는 Desktop 앱으로 사용 가능
- 노드별 입출력 확인, Step-by-Step 디버깅 지원
| 엔드포인트 | 메서드 | 설명 | 응답 형식 |
|---|---|---|---|
/ |
GET | Health Check | JSON |
/api/v1/agent |
POST | 일반 요청 (비스트리밍) | JSON |
/api/v1/agent/stream |
POST | SSE 스트리밍 요청 | Server-Sent Events |
- userId (필수): 사용자/분석가 ID (인증용)
- Content-Type:
application/json
{
"query": "자연어 질의 (필수)",
"mode": "fetch | summary | analysis (필수)",
"caseId": 1234567890123 // 선택사항, 사건 추적용
}전체 API 명세는 API_SPEC.md를 참조해주세요.
| 변수명 | 설명 | 예시 |
|---|---|---|
ES_HOST |
Elasticsearch 호스트 | 16.184.54.201 |
ES_PORT |
Elasticsearch 포트 | 9200 |
ES_INDEX |
로그 인덱스 패턴 | logs-tenant-* |
ES_USER |
ES 사용자명 | elastic |
ES_PASSWORD |
ES 비밀번호 | your-password |
LLM_PROVIDER |
LLM 제공자 | gemini 또는 anthropic |
LLM_API_KEY |
LLM API 키 | AIzaSy... |
| 변수명 | 기본값 | 설명 |
|---|---|---|
GEMINI_MODEL |
gemini-2.5-flash-lite |
Gemini 모델명 |
ANTHROPIC_MODEL |
claude-sonnet-4-20250514 |
Claude 모델명 |
LLM_TEMPERATURE |
0 |
LLM 출력 다양성 (0~1) |
CHUNK_SIZE |
800 |
청크당 로그 건수 |
MAX_PARALLEL_CHUNKS |
5 |
동시 처리 청크 수 |
CHUNKED_THRESHOLD |
200000 |
청크 처리 최대 로그 수 |
REDUCE_BATCH_SIZE |
50 |
Reduce 배치 크기 |
LANGCHAIN_TRACING_V2 |
false |
LangSmith 추적 활성화 |
QUICKSTART.md를 참조하여 EC2에 빠르게 배포할 수 있습니다.
sudo tee /etc/systemd/system/cirf-agent.service > /dev/null <<EOF
[Unit]
Description=CIRF AI Agent API Server
After=network.target
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/CIRF-AI-Agent
Environment="PATH=/home/ubuntu/CIRF-AI-Agent/venv/bin"
EnvironmentFile=/home/ubuntu/CIRF-AI-Agent/.env
ExecStart=/home/ubuntu/CIRF-AI-Agent/venv/bin/uvicorn api.server:app --host 0.0.0.0 --port 8000 --workers 2
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
# 서비스 시작
sudo systemctl daemon-reload
sudo systemctl enable cirf-agent
sudo systemctl start cirf-agent
# 상태 확인
sudo systemctl status cirf-agent# 로그 실시간 보기
sudo journalctl -u cirf-agent -f
# 서비스 재시작
sudo systemctl restart cirf-agent
# 서비스 중지
sudo systemctl stop cirf-agent[TYPE/ISSUE] 간결한 제목
예: [FEAT/KAN-47] CloudTrail 수집 기능 추가
- TYPE: 아래 표의 유형 (대문자)
- ISSUE: 이슈/티켓 키 (예: KAN-47)
| TYPE | 용도 설명 | 예시 Prefix |
|---|---|---|
| FEAT | 새로운 기능 추가 | [FEAT/KAN-47] |
| FIX | 버그 수정 | [FIX/KAN-102] |
| DOCS | 문서 수정 (README, 가이드, 주석 등) | [DOCS/KAN-58] |
| STYLE | 코드 포맷/세미콜론/공백 등, 로직 변경 없음 | [STYLE/KAN-63] |
| REFACTOR | 리팩터링 (동작 동일, 구조 개선/성능 향상) | [REFACTOR/KAN-75] |
| TEST | 테스트 코드 추가/수정 | [TEST/KAN-84] |
| CHORE | 빌드/배포/의존성/스크립트 등 개발환경 변경 | [CHORE/KAN-19] |
- API_SPEC.md: REST API 상세 명세서
- QUICKSTART.md: 5분 빠른 시작 가이드
CIRF-AI-Agent - AI-Powered AWS Log Analysis Agent