security_demo/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an AI SOC (Security Operations Center) Analyst platform consisting of a Vue 3 frontend and FastAPI backend. It's designed for security threat detection and analysis, allowing users to upload alert data and receive intelligent analysis reports.

Development Commands

Frontend (Vue 3 + TypeScript + Vite)

# Install dependencies
npm install

# Start development server (default: http://localhost:5173)
npm run dev

# Build for production (includes TypeScript compilation)
npm run build

# Preview production build
npm run preview

Backend (FastAPI + Python)

# Quick start with automated setup (recommended)
python run_backend.py

# Manual setup
cd backend
pip install -r requirements.txt
uvicorn app.api_main:app --host 0.0.0.0 --port 8000 --reload

# API documentation available at:
# - Swagger UI: http://localhost:8000/docs  
# - ReDoc: http://localhost:8000/redoc

Quick Start with One-Click Launcher

# Start both frontend and backend with automatic setup
python start_both.py

# Alternative: Use the shell script
./start_both.sh

Testing & Development Scripts

# Test graph implementation
python test_graph_implementation.py

# Simple graph testing
python simple_graph_test.py

# Standalone graph testing
python standalone_graph_test.py

Testing

The project includes comprehensive test data in test-data/:

• Upload sample-alerts.json or sample-alerts.csv to test the complete analysis pipeline
• Test data represents a realistic multi-stage APT attack scenario covering:
  • Phishing → malware execution → C2 communication
  • Cloud credential theft → resource reconnaissance
  • Backdoor user creation → privilege escalation
  • Kubernetes compromise → container control

Architecture & Code Structure

Frontend Architecture (/src)

• main.ts: Application entry point with Naive UI setup
• App.vue: Root component managing theme and layout
• types.ts: TypeScript definitions for API contracts, UI components
• api.ts: HTTP client with mock/real API switching via VITE_USE_MOCK
• mocks/fixtures.ts: Complete mock data system for development
• components/:
  • AppContent.vue: Main application content container
  • UploadPanel.vue: File upload with drag-drop support
  • PipelinePanel.vue: Analysis pipeline control and monitoring
  • ReportList.vue: Threat reports display with filtering
  • ReportDetail.vue: Detailed analysis results drawer
  • ThreatGraph.vue: Entity relationship visualization
  • ScoringRules.vue: Risk scoring configuration interface
  • ConfigManager.vue: Configuration management interface with full CRUD operations and syntax highlighting

Backend Architecture (/backend/app)

• api_main.py: Main FastAPI application with all endpoints
• main.py: Alternative entry point for FastAPI application
• storage.py: In-memory storage system for development
• api/v1/: API route modules (upload, reports, analysis, config, scoring, graph)
• models/: SQLAlchemy database models (alert, entity, analysis, ingestion)
• schemas/: Pydantic models for request/response validation
• services/: Business logic modules:
  • alert_processor.py: Alert data ingestion and processing
  • entity_extractor.py: Security entity extraction
  • graph_analyzer.py: Attack chain analysis using NetworkX
  • llm_service.py: AI-powered threat analysis
  • report_generator.py: Analysis report generation
  • config_loader.py: Configuration management
• dsl/: Domain-specific language for alert preprocessing:
  • engine.py: Main preprocessing engine
  • jsonpath.py: JSONPath extraction utilities
  • csvread.py: CSV parsing utilities
  • functions.py: Functional expressions (map, filter, etc.)
  • loader.py: Configuration file loader
• core/: Core application modules (config.py)
• edges.py: Graph edge construction from alerts
• scoring.py: Risk scoring algorithms
• generate.py: Report generation system
• llm.py: LLM integration layer

Key Technologies

• Frontend: Vue 3 Composition API, TypeScript, Naive UI, Tailwind CSS, Vite
• Backend: FastAPI, SQLAlchemy (async), PostgreSQL/In-memory storage, NetworkX, Anthropic Claude integration
• Data Processing: JSONPath expressions, YAML-driven configuration, CSV/JSON parsing
• Graph Analysis: NetworkX for entity relationship modeling and attack chain detection
• Risk Scoring: Custom scoring algorithms with configurable weights and thresholds

Configuration System

Alert Preprocessing (/configs)

The system uses YAML-based configuration for flexible alert data processing:

• splunk-es-alert-preprocessing.yaml: Complex JSON structure processing
• csv-alerts-preprocessing.yaml: Simplified CSV format processing
• edge_scoring.yaml: Risk scoring weights, thresholds, and entity-specific rules
• llm.yaml: LLM configuration and prompt templates

Key features:

• JSONPath field extraction with functional expressions (map, filter, distinct, concat)
• Entity standardization and mapping
• Attack stage classification
• Configurable risk scoring with burst detection
• Entity-specific scoring rules and thresholds

Environment Configuration

• Frontend: Uses .env for VITE_USE_MOCK toggle (mock vs real API)
• Backend: LLM API configuration via environment variables:
  • LLM_PROVIDER: LLM provider choice ("claude" or "ollama")
  • ANTHROPIC_AUTH_TOKEN: Claude API token
  • OLLAMA_BASE_URL: Ollama service URL
  • CONFIG_DIR: Configuration files directory path
  • BACKEND_PORT: Backend server port (default: 8100)
  • FRONTEND_PORT: Frontend dev server port (default: 5173)

Mock vs Real API

The frontend includes a complete mock system (src/mocks/fixtures.ts):

• Set VITE_USE_MOCK=true for development with realistic test data
• Set VITE_USE_MOCK=false to connect to real backend API
• Mock includes upload simulation, report generation, and download links

Security Data Flow

1. Data Ingestion: Upload JSON/CSV alert files through frontend
2. Preprocessing: YAML-driven field extraction and entity standardization
3. Analysis: Graph-based attack chain detection and risk scoring
4. LLM Enhancement: AI-powered threat insights and recommendations
5. Reporting: Structured analysis reports with evidence timeline

API Endpoints

Main API Routes (/api)

• POST /ingest - Upload and ingest alert data files
• POST /dry_run - Preview preprocessing results without storage
• POST /graph/build - Build entity relationship graph from alerts
• POST /scoring/run - Calculate entity and subgraph risk scores
• POST /reports/generate - Generate analysis reports with optional LLM enhancement
• GET /reports - List generated reports with filtering options
• GET /reports/{id} - Get detailed report with evidence and recommendations
• GET /status - System status and storage statistics

Analysis APIs (/api/v1)

• GET /analysis/entities/{id}/graph - Entity relationship visualization
• POST /analysis/llm-insights - AI-powered deep analysis
• GET /config/sources - Available data source configurations
• GET /scoring/weights - Current scoring configuration

Configuration Management System

The ConfigManager component provides full CRUD operations for YAML/JSON configuration files:

• Upload: Import new configuration files with validation
• View: Syntax-highlighted display of configuration content
• Edit: Real-time code editor with Tab support and auto-save detection
• Save: Persist changes with validation and error handling
• Delete: Remove configurations with confirmation dialogs
• Grouping: Files organized by type (告警预处理, 评分配置, LLM配置)

Data Processing Pipeline

1. Alert Ingestion: Upload JSON/CSV alert files through frontend
2. Preprocessing: YAML-driven field extraction and entity standardization
3. Analysis: Graph-based attack chain detection and risk scoring
4. LLM Enhancement: AI-powered threat insights and recommendations
5. Reporting: Structured analysis reports with evidence timeline

Report Authenticity and Analysis Quality

The AI-generated reports are based on real security analysis, not simulated templates:

• Realistic Attack Scenarios: Test data includes complete APT attack chains with genuine technical indicators
• Professional Analysis Algorithms: Risk scoring uses severity weights, attack stage classification, and time decay calculations
• Evidence-Based LLM Enhancement: AI analyzes actual alert data to generate specific threat insights and actionable recommendations
• MITRE ATT&CK Framework: Reports map attack stages to real security tactics and techniques

This is a functional SOC platform capable of processing real enterprise security alerts and generating professional threat intelligence reports.

Testing Strategy

The project includes realistic test scenarios covering:

• Phishing → malware execution → C2 communication
• Cloud credential theft → resource reconnaissance
• Backdoor user creation → privilege escalation
• Kubernetes compromise → container control

Use the test data to verify the complete analysis pipeline from ingestion to report generation.

Port Management

The system uses configurable ports to avoid conflicts:

• Default backend port: 8100 (configurable via BACKEND_PORT)
• Default frontend port: 5173 (configurable via FRONTEND_PORT)
• The start_both.py script automatically handles port cleanup and process management