Skip to content

About

로그 분석 지원을 위한 에이전트입니다.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

CIRF-AI-Agent

AWS 로그 분석 지원 에이전트

Python 3.11+ LangGraph FastAPI Elasticsearch


목차


프로젝트 개요

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 호출 추적 및 모니터링
  • (디버깅) 비용 및 성능 메트릭 자동 수집

주요 기능

1. 자연어 쿼리 해석

사용자가 입력한 자연어 질의를 Elasticsearch 쿼리로 자동 변환합니다.

예시:

사용자 입력: "kwanwoo 사용자의 최근 24시간 실패한 로그인 로그 조회"

자동 생성된 SearchPlan:
{
  "time_range": {"gte": "now-24h", "lte": "now"},
  "filters": {
    "actor": ["kwanwoo"],
    "activity": ["ConsoleLogin"],
    "outcome": ["Failure"]
  },
  "types": ["cloudtrail"],
  "limit": 200000
}

2. 3가지 실행 모드

모드 설명 LLM 호출 ES 조회 응답 시간 용도
Fetch API 파라미터만 생성 1회 없음 ~1-2초 빠른 쿼리 생성
Summary 로그 조회 + 요약 다수 있음 ~5-15초 로그 파악
Analysis 요약 + 분석 가장 많음 있음 ~10-25초 분석 지원

3. 대량 로그 처리 (Map-Reduce)

최대 200,000건의 로그를 병렬 처리하여 요약합니다.

  • Map 단계: 로그를 800건씩 청크로 분할하여 병렬 요약 (최대 5개 동시 처리)
  • Reduce 단계: 생성된 요약을 계층적으로 병합 (50개씩 배치 처리)
  • 성능 최적화: 비동기 처리 및 토큰 사용량 최적화

4. MITRE ATT&CK 기반 위협 분석

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 버킷 접근 로그 상세 조사"
  ]
}

5. 품질 검증 시스템

3가지 검증 패턴으로 출력 품질을 개선합니다:

  • 요약 품질 검증: 불충분한 요약 재생성 (최대 2회 재시도)
  • 이벤트 추출 검증: 중요 필드(actor, activity, time) 누락 확인
  • MITRE 매핑 검증: 잘못된 매핑 필터링 및 자기 검증 (최대 3회 재시도)

6. 후속 질의 처리

이전 분석 결과에 대한 추가 질문을 지능적으로 처리합니다:

  • 설명 요청: "T1078.004가 뭐야?" → Elasticsearch 조회 없이 MITRE 기법 설명
  • 드릴다운 분석: "suspicious-user 상세 분석" → 추가 로그 조회 및 심층 분석
  • 새로운 분석: 완전히 새로운 질의 → 새 워크플로우 실행

7. Pivot 분석 (상관분석)

분석 결과를 바탕으로 향후 분석 방향을 제안합니다.

Pivot 제안 예시:

{
  "pivotSuggestions": [
    {
      "type": "temporal_expansion",
      "description": "suspicious-user의 전후 7일 활동 조사",
      "query": "suspicious-user 최근 7일 로그"
    },
    {
      "type": "related_entities",
      "description": "suspicious-user가 접근한 리소스 목록",
      "query": "suspicious-user가 접근한 S3 버킷 목록"
    }
  ]
}

8. 실시간 스트리밍 및 모니터링

  • 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+ 데이터 모델 및 검증

주요 Python 라이브러리

# 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)

1. 저장소 클론

git clone https://github.com/BOB-CIRF/CIRF-AI-Agent.git
cd CIRF-AI-Agent

2. Python 가상환경 설정

# 가상환경 생성
python3 -m venv venv

# 가상환경 활성화
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

3. 의존성 설치

pip install --upgrade pip
pip install -r requirements.txt

4. 환경 변수 설정

.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 4

Health Check

curl http://localhost:8000/

예상 응답:

{
  "status": 200,
  "message": "CIRF AI Agent API is running",
  "data": {
    "service": "CIRF AI Agent API",
    "version": "1.0.0"
  }
}

사용 예시

1. Fetch 모드 (API 파라미터만 생성)

요청:

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
    }
  }
}

2. Summary 모드 (로그 조회 + 요약)

요청:

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
    }
  }
}

3. Analysis 모드 (요약 + 위협 분석)

요청:

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가지 워크플로우를 제공합니다:

1. Summary Workflow (로그 요약)

자연어 질의 → SearchPlan 변환 → 로그 수집 → Map-Reduce 요약

상세 문서: docs/workflows/workflow_summary.md

2. Fetch Workflow (API 파라미터 변환)

자연어 질의 → SearchPlan 변환 (ES 조회 없음, 빠른 응답)

상세 문서: docs/workflows/workflow_fetch.md

3. Analysis Workflow (분석 지원)

Summary + 침해사고 분석 + MITRE ATT&CK 매핑 + Pivot 분석 + 후속 질의

상세 문서: docs/workflows/workflow_analysis.md

실시간 워크플로우 시각화 (LangGraph Studio)

  • VSCode 확장 또는 Desktop 앱으로 사용 가능
  • 노드별 입출력 확인, Step-by-Step 디버깅 지원

API 문서

REST API 엔드포인트

엔드포인트 메서드 설명 응답 형식
/ 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 명세는 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 추적 활성화

배포 가이드

빠른 시작 (5분)

QUICKSTART.md를 참조하여 EC2에 빠르게 배포할 수 있습니다.

Systemd 서비스 등록 (Ubuntu/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

Git Commit Convention

커밋 메시지 양식

[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]

관련 문서

가이드


CIRF-AI-Agent - AI-Powered AWS Log Analysis Agent

About

로그 분석 지원을 위한 에이전트입니다.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages