Skip to content

README.en.md

Latest commit

Β 

History

History
189 lines (138 loc) Β· 6.01 KB

README.en.md

File metadata and controls

189 lines (138 loc) Β· 6.01 KB
Raw

AlphaMapping

Industrial-Grade Cyberspace Asset Situational Awareness Platform

License: MIT Python 3.8+ Docker

δΈ­ζ–‡ | English

AlphaMapping Logo

AlphaMapping is a next-generation cyberspace asset query and intelligent analysis system. It deeply integrates multi-platform asset mapping (FOFA, ZoomEye) with AI large language models (LLM), providing natural language interaction, real-time situational awareness dashboards, and automated security risk assessment.

πŸ“Έ Interface Preview: Immersive Situational Awareness Visualization Dashboard

AlphaMapping Dashboard

πŸ’‘ Design Philosophy: Standing on the Shoulders of Giants

AlphaMapping does NOT perform any active scanning. Instead, it fully leverages the data capabilities of mature cyberspace mapping platforms like FOFA and ZoomEye. We focus on:

  • πŸ”— Data Aggregation: Unified multi-platform API interface, eliminating redundant queries
  • 🧠 Intelligent Analysis: AI-powered deep analysis of asset exposure risks
  • πŸ“Š Visualization: Transform complex data into intuitive situational awareness dashboards

✨ Key Features

πŸ–₯️ Situational Awareness Dashboard

  • Cyberpunk Design: Glassmorphism dark-themed dashboard designed for SOC monitoring centers
  • Real-time Visualization: ECharts dynamic charts β€” port distribution, protocol analysis, global geo heatmap
  • Interactive Linking: Click charts to filter asset list, map scatter points highlight asset cards
  • 5-Column Grid Layout: Compact asset cards displaying more information per screen

πŸ€– AI Intelligence Engine

  • NL2CSEQL Translation: Natural language β†’ Platform query syntax (e.g., "Find Nginx servers in Beijing" -> [FOFA]:city="Beijing" && product="NGINX")
  • Security Risk Reports: AI auto-analyzes asset exposure, generates risk levels, vulnerability correlations, remediation recommendations
  • Single Asset Deep Analysis: One-click AI security assessment for individual assets

πŸ“‘ Multi-Source Data Fusion

  • Multi-Platform Support: Currently supports FOFA and ZoomEye, with more data sources planned
  • Smart Caching: Same queries hit local cache first, saving API quota
  • Data Deduplication: IP:Port unique constraint with automatic Upsert updates

πŸ“Š Data Management

  • Advanced Filtering: Multi-dimensional filtering by keyword, country, protocol, port
  • Multi-Format Export: CSV / Excel / JSON one-click download
  • Scheduled Tasks: Cron expression configuration for automated asset updates

🐳 Ready to Deploy

  • Docker One-Click Deployment: docker-compose up -d to start
  • PowerShell Scripts: Windows environment automation
  • OpenAPI Documentation: FastAPI auto-generated interactive API docs

πŸ—οΈ Architecture

Layer Tech Stack
Backend FastAPI, SQLAlchemy, Pydantic, OpenAI SDK, APScheduler
Frontend Vanilla JS (ES6+), CSS3, ECharts 5
Database SQLite (dev) / PostgreSQL (production-ready)
Deployment Docker, docker-compose, Nginx, PowerShell
Testing pytest, pytest-cov, pytest-asyncio 
AlphaMapping/
β”œβ”€β”€ backend/           # FastAPI Backend
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ core/      # Configuration, Database
β”‚   β”‚   β”œβ”€β”€ models/    # ORM Models
β”‚   β”‚   β”œβ”€β”€ services/  # Business Logic
β”‚   β”‚   └── main.py    # API Routes
β”‚   └── tests/         # Unit Tests
β”œβ”€β”€ frontend/          # Static Frontend
β”œβ”€β”€ docker/            # Container Configuration
└── scripts/           # Automation Scripts

πŸš€ Quick Start

Prerequisites

  • Python 3.8+
  • Git
  • (Optional) Docker & Docker Compose

Local Development

# 1. Clone repository
git clone https://github.com/Und3r1ine/AlphaMapping.git
cd AlphaMapping

# 2. Configure API keys
cp backend/.env.example backend/.env
# Edit backend/.env with FOFA_KEY, ZOOMEYE_KEY, OPENAI_API_KEY

# 3. Start services
# Windows (PowerShell)
./scripts/run.ps1

# Linux / macOS
chmod +x scripts/*.sh
./scripts/run.sh

# Access
# - Frontend: http://localhost:3000
# - API Docs: http://localhost:8000/docs

# Stop services
# Windows: ./scripts/stop.ps1
# Linux/macOS: ./scripts/stop.sh

Docker Deployment

# Configure environment
cp backend/.env.example .env
# Edit .env with your keys

# Start containers
docker-compose up -d

# Access
# - Frontend: http://localhost
# - API: http://localhost:8000

βš™οΈ Configuration

Create .env file with:

# FOFA API
FOFA_EMAIL=your_email
FOFA_KEY=your_api_key

# ZoomEye API
ZOOMEYE_KEY=your_api_key

# LLM Configuration (OpenAI-compatible)
OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4

πŸ§ͺ Testing

cd backend
pip install -r requirements.txt
pytest tests/ -v --cov=app

πŸ“– API Overview

Endpoint Method Description
/query POST Execute asset query
/assets GET List assets with filters
/assets/export GET Export assets (csv/excel/json)
/analyze/{query_id} POST Generate AI analysis report
/scheduled-tasks CRUD Manage scheduled tasks
/stats GET Dashboard statistics

Full API documentation available at /docs when running.

🀝 Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct.

πŸ”’ Security

For security issues, please see our Security Policy.

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ“‹ Changelog

See CHANGELOG.md for version history.

AlphaMapping - Mapping the Unknown in Cyberspace.