Malware Explorer

開源的惡意樣本管理與特徵分析平台：集中管理樣本、標註與查詢特徵，並以 LLM 輔助程式碼片段的行為摘要與特徵匹配。

🚀 Quick Start

cp example.env .env
# 請在 .env 設定 GOOGLE_API_KEY
docker compose up -d

• Web UI: http://localhost
• API Docs (Swagger): http://localhost/api/docs
• OpenAPI JSON: http://localhost/openapi.json
• pgAdmin: http://localhost:5050

預設管理員：admin / password（在生產環境請修改密碼部署）

目錄

• Quick Start
• 架構與技術棧
• 安裝與部署
• 產生前端 API Client
• 測試與 CI
• 授權條款

架構與技術棧

技術棧：

• Backend：FastAPI、SQLModel、Alembic、PyJWT
• LLM：LangChain + Gemini
• Frontend：Next.js、React、Tailwind、@hey-api/openapi-ts
• Infra：Docker Compose、Nginx、PostgreSQL、pgAdmin

系統架構：

graph LR
  U[Browser] -->|HTTP| Nginx
  Nginx -->|/| FE[Frontend]
  Nginx -->|/api & /openapi.json| BE[Backend]
  BE -->|SQL| PG[(PostgreSQL)]
  Admin[pgAdmin] --> PG
  BE <--> LLM[(Google Gemini via LangChain)]

Loading

安裝與部署

前置需求：Docker、Docker Compose。

1. 以 Docker Compose 啟動

cp example.env .env
# 必填：GOOGLE_API_KEY
docker compose up -d

啟動後服務：

• Nginx 80 port：
  • / -> Frontend（Next.js）
  • /api/ -> Backend（FastAPI，root_path=/api）
  • /openapi.json -> Backend 的 OpenAPI 文件

2. 本機開發（簡要，詳見 DEVELOP.md）

• FastAPI 後端：

  cd backend
  uv run fastapi dev

• Alembic 資料庫遷移：

  cd backend
  uv run alembic upgrade head

• Next.js 前端：

  cd frontend
  pnpm dev

產生前端 API Client（OpenAPI）

專案提供腳本以後端 OpenAPI 自動產生前端 SDK：

./scripts/generate-client.sh

流程說明：

1. 由後端匯出 OpenAPI (backend/app/main.py → openapi.json)
2. 移動至 frontend/openapi.json
3. 以 @hey-api/openapi-ts 生成 typed client 並格式化

測試與 CI

• 後端測試：

  cd backend
  uv run pytest -q

• 前端品質：

  cd frontend
  pnpm lint
  pnpm format:check

• CI：規劃採用 GitHub Actions（後端單元測試 + 前端 Lint/Build + Docker Build）。

授權條款

本專案以 MIT 授權釋出，詳見 LICENSE。

Star History