Unnathi-vithlani/Chronoscope_Enterprise
GitHub: Unnathi-vithlani/Chronoscope_Enterprise
将犯罪学日常活动理论应用于网络安全，通过行为分析对网络攻击背后的犯罪者进行画像、分类与追踪的实时威胁情报平台。
Stars: 0 | Forks: 0
# 🎯 CHRONOSCOPE 企业版
### 实时犯罪行为观测站
[](https://python.org)
[](https://fastapi.tiangolo.com)
[](https://docker.com)
[](https://chronoscope-enterprise.onrender.com/ws/live)
[](https://chronoscope-enterprise.onrender.com)
**将犯罪学的日常活动理论应用于网络安全威胁情报** *唯一专注于分析人类犯罪者特征——而非仅仅关注 IP 地址的威胁情报平台*
| 🌐 在线演示 | 📖 API 文档 | ⚡ 实时威胁 | 🤖 ML 预测 | |:---:|:---:|:---:|:---:| | [chronoscope-enterprise.onrender.com](https://chronoscope-enterprise.onrender.com) | [/docs](https://chronoscope-enterprise.onrender.com/docs) | [/threats/live](https://chronoscope-enterprise.onrender.com/threats/live) | [/predictions/global](https://chronoscope-enterprise.onrender.com/predictions/global) |
## 🧠 什么是 CHRONOSCOPE？
大多数威胁情报工具回答一个问题：
**CHRONOSCOPE 回答了一个根本不同的问题：**
这种转变——从**以 IP 为中心**到**以行为者为中心**的情报——正是区分被动拦截与主动犯罪学分析的关键。
### 传统威胁情报的问题
```
Traditional approach:
IP 185.220.101.42 detected → BLOCK → move on
CHRONOSCOPE approach:
IP 185.220.101.42 detected →
Timezone: Eastern Europe (UTC+2)
Work pattern: Professional — operates 08:00–12:00 daily
Sophistication: Expert (127 reports, consistent pattern)
Criminal type: PROFESSIONAL_ORGANIZED_CRIME
Risk level: HIGH — escalate immediately
Fingerprint: 34c6f9df7e8a9ff8
→ Same actor previously used IPs from RU, BG, NL
→ Predicted next attack: within 24h from eastern_europe
```
## 🔬 理论基础
CHRONOSCOPE 建立在两个应用于网络安全的犯罪学框架之上：
### 1. 日常活动理论 (Cohen & Felson, 1979)
```
Crime requires three elements converging in time and space:
┌─────────────────────────────────────────┐
│ Motivated Offender │
│ + Suitable Target │
│ + Absence of Capable Guardian │
│ ────────────────────────────── │
│ = Crime │
└─────────────────────────────────────────┘
CHRONOSCOPE maps this to:
Motivated Offender → Criminal behavioral fingerprint
Suitable Target → Vulnerable system/network
Absent Guardian → Security gap or monitoring blind spot
```
### 2. 对手时空体 (基于 Bakhtin 的改编)
犯罪活动的**时空体**（chronotope，即时间-空间）揭示了身份。职业网络犯罪分子像合法专业人士一样拥有**工作时间表**——而且该时间表在攻击时间戳中是可检测的。
```
# 东欧专业人员运营时间 06:00-14:00 UTC
# 西欧行为者运营时间 14:00-22:00 UTC
# 美洲行为者运营时间 22:00-06:00 UTC
avg_attack_hour = 10.3 → eastern_europe timezone
pattern = "consistent" → professional, not opportunistic
reports = 127 → expert sophistication
```
## 🏗️ 架构与数据流
*5 层流水线：原始威胁源 → 摄取 → 犯罪学分析 → 存储与 ML → API 输出*
### 层级分解
| 层级 | 组件 | 用途 |
|-------|-----------|---------|
| **1. 数据源** | AbuseIPDB, URLhaus, 演示模式 | 原始恶意 IP 源 |
| **2. 摄取** | `AbuseIPDBIngestor`, 异步循环 | 获取、去重、排队威胁 |
| **3. 分析** | `AdversarialChronotope`, `CriminalBehavioralFingerprint` | 分析人类行为者特征 |
| **4. 存储与 ML** | SQLite, `MLPredictor`, `profiles_db` | 持久化档案，预测下一个威胁 |
| **5. 输出** | FastAPI REST, WebSocket, Swagger | 向消费者提供情报 |
## 📊 犯罪分类系统
| 档案类型 | 风险 | 时区 | 特征 |
|-------------|------|----------|-----------------|
| `PROFESSIONAL_ORGANIZED_CRIME` (职业有组织犯罪) | 🔴 **高** | 东欧 | 固定工作时间，专业度高，100+ 报告，协同攻击 |
| `MODERATE_PROFESSIONAL` (中等职业化) | 🟠 **中高** | 西欧 | 半组织化，模式一致，50-100 报告 |
| `OPPORTUNISTIC_SCRIPT_KIDDIE` (机会主义脚本小子) | 🟡 **中** | 美洲 / 未知 | 时间不定，复杂度低，自动化工具 |
| `UNKNOWN` (未知) | ⚪ **低** | 未知 | 时间数据不足以分类 |
## 🔐 行为指纹识别
每个威胁行为者都会收到一个**唯一的、确定性的行为指纹**：
```
signature = {
"pattern": "professional",
"timezone": "eastern_europe",
"type": "PROFESSIONAL_ORGANIZED_CRIME",
"country": "RU",
"operational_hours": "08:00-12:00"
}
fingerprint_id = SHA256(json.dumps(signature, sort_keys=True))[:16]
# → "34c6f9df7e8a9ff8"
```
**为何这很重要：** 一个轮换使用 10 个不同 IP 地址的威胁行为者——这是一种常见的逃避技术——每次都会生成**相同的指纹**。CHRONOSCOPE 能透过 IP 轮换识别出潜在的行为者。
## 🚀 API 参考
Base URL: `https://chronoscope-enterprise.onrender.com`
### 端点
#### `GET /` — 服务状态
```
{
"service": "CHRONOSCOPE Enterprise",
"version": "2.0.0",
"status": "operational",
"mode": "DEMO",
"database": "sqlite",
"profiles_active": 5,
"cache_stats": {
"total_ips": 5,
"last_24h": 5,
"database": "sqlite"
}
}
```
#### `GET /threats/live` — 实时犯罪档案
```
{
"timestamp": "2026-03-21T14:29:10.843497",
"total": 5,
"mode": "DEMO",
"profiles": [
{
"fingerprint_id": "34c6f9df7e8a9ff8",
"criminal_profile": {
"type": "PROFESSIONAL_ORGANIZED_CRIME",
"timezone": "eastern_europe",
"work_pattern": "professional",
"risk_level": "high",
"sophistication": "expert",
"operational_hours": "08:00-12:00",
"geographic_origin": "RU"
},
"threat_data": {
"ip": "185.220.101.42",
"confidence": 95,
"reports": 127
},
"first_seen": "2026-03-21T14:29:10.843497"
}
]
}
```
#### `GET /predictions/global` — ML 预测
```
{
"active_profiles": 5,
"predictions": {
"predicted_timezone": "eastern_europe",
"predicted_criminal_type": "PROFESSIONAL_ORGANIZED_CRIME",
"confidence": 0.8,
"recommended_defenses": [
"Monitor eastern_europe timezone activity",
"Watch for PROFESSIONAL_ORGANIZED_CRIME patterns",
"Increase sensor coverage in predicted regions"
],
"generated_at": "2026-03-21T14:29:10.843497"
}
}
```
#### `WS /ws/live` — 实时 WebSocket 流
```
// On connect:
{ "type": "connected", "profiles_tracked": 5, "mode": "DEMO" }
// New threat profiled:
{ "type": "new_threat", "data": { ...ThreatProfile... }, "timestamp": "..." }
// Every 30 seconds:
{ "type": "heartbeat", "profiles": 5, "timestamp": "..." }
```
## 🗂️ 项目结构
```
Chronoscope_Enterprise/
│
├── 📄 main.py # Entry point — starts uvicorn server
├── 📄 requirements.txt # Minimal deps for free tier
├── 🐳 Dockerfile # Container definition
├── 🐳 docker-compose.yml # Local multi-service setup
├── 🌐 test_ws.html # Live WebSocket dashboard (open in browser)
│
├── 📁 api/
│ └── main.py # FastAPI app — all routes, Pydantic schemas,
│ # WebSocket handler, lifespan manager
│
├── 📁 config/
│ └── settings.py # Dataclass-based settings from env vars
│
├── 📁 core/
│ │
│ ├── 📁 criminology/
│ │ └── temporal_spatial.py # ⭐ AdversarialChronotope
│ │ # Routine Activity Theory engine
│ │ # Maps attack times → timezone → crime type
│ │
│ ├── 📁 profiler/
│ │ └── fingerprint.py # ⭐ CriminalBehavioralFingerprint
│ │ # SHA-256 actor fingerprinting
│ │ # Cross-IP actor linking
│ │
│ ├── 📁 ingestors/
│ │ └── abuseipdb.py # AbuseIPDB API client
│ │ # get_blacklist() + check_ip()
│ │ # Temporal pattern extraction
│ │
│ ├── 📁 database/
│ │ ├── local_cache.py # SQLite (free tier / default)
│ │ └── postgres_cache.py # PostgreSQL + Redis (enterprise stub)
│ │
│ ├── 📁 ml/
│ │ └── predictor.py # MLPredictor
│ │ # predict_next_targets()
│ │ # detect_anomalies()
│ │
│ ├── 📁 messaging/
│ │ └── kafka_client.py # Apache Kafka client (enterprise stub)
│ │
│ ├── 📁 workers/
│ │ └── celery_worker.py # Celery distributed workers (enterprise stub)
│ │
│ └── 📁 monitoring/
│ └── metrics.py # Prometheus metrics (enterprise stub)
│
├── 📁 docs/
│ └── architecture.png # Architecture diagram (this file)
│
└── 📁 k8s/
└── deployment.yaml # Kubernetes deployment manifest
```
## 🛠️ 快速开始
### 本地运行
```
# 1. Clone
git clone https://github.com/Unnathi-vithlani/Chronoscope_Enterprise.git
cd Chronoscope_Enterprise
# 2. 安装依赖
pip install -r requirements.txt
# 3. 配置环境
cp .env .env.local
# 编辑 .env — 添加来自 https://www.abuseipdb.com/account/api 的 ABUSEIPDB_KEY
# 4. 运行
python main.py
```
打开：
- API: http://localhost:8000
- 文档: http://localhost:8000/docs
- WebSocket 仪表板：在浏览器中打开 `test_ws.html`
### 切换到真实模式（实时数据）
```
# 在你的 .env 或 Render 环境变量中：
DEMO_MODE=False
ABUSEIPDB_KEY=your_actual_key_here
```
真实模式每 5 分钟从 AbuseIPDB 获取 50 个实时恶意 IP 并逐一进行分析。
## 🐳 Docker
```
# 构建
docker build -t chronoscope-enterprise .
# 在 demo 模式下运行
docker run -p 8000:8000 chronoscope-enterprise
# 使用真实数据运行
docker run -p 8000:8000 \
-e DEMO_MODE=False \
-e ABUSEIPDB_KEY=your_key \
chronoscope-enterprise
```
## ⚙️ 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `DEMO_MODE` | `True` = 5 个演示威胁。`False` = 实时 AbuseIPDB 源 | `True` |
| `ABUSEIPDB_KEY` | 来自 [abuseipdb.com](https://www.abuseipdb.com) 的 API key | — |
| `URLHAUS_KEY` | URLhaus key（公开 API，设为 `none`） | `none` |
| `DATABASE_URL` | 数据库连接字符串 | `sqlite:///chronoscope.db` |
| `REDIS_URL` | Redis URL（仅限企业版） | — |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka 服务器（仅限企业版） | — |
| `MAX_WORKERS` | 工作线程数 | `2` |
| `BATCH_SIZE` | 每次摄取周期处理的 IP 数 | `50` |
## 🏢 免费版与企业版
| 功能 | 🆓 免费版（当前） | 🏢 企业版 |
|---------|:-----------------:|:-------------:|
| 数据库 | SQLite | PostgreSQL + Redis |
| 流传输 | 进程内 | Apache Kafka |
| 工作进程 | 单进程 | Celery 分布式 |
| 监控 | 桩 (Stub) | Prometheus + Grafana |
| 扩展 | 单实例 | Kubernetes HPA |
| 威胁/周期 | 50 | 无限 |
| 运行时间 | 会休眠 | 24/7 零停机 |
## 💼 谁在使用？
| 利益相关者 | CHRONOSCOPE 如何提供帮助 |
|------------|----------------------|
| **SOC 团队** | 按行为者专业度进行分类——有组织犯罪的应对方式不同于脚本小子 |
| **威胁情报分析师** | 自动化的行为者分析节省了数小时的手动研究 |
| **事件响应人员** | 跨 IP 的行为者指纹将事件与同一威胁组织联系起来 |
| **执法部门** | 时区 + 行为模式提供调查线索 |
| **金融机构** | 风险评分档案直接输入欺诈响应工作流 |
| **网络保险商** | 职业与业余分类为风险溢价计算提供依据 |
| **安全研究人员** | 用于学术研究的新型跨学科框架 |
## 🧪 运行 WebSocket 仪表板
1. 解压项目 zip
2. 在 Chrome 或 Firefox 中打开 `test_ws.html`
3. 它会自动连接到 `wss://chronoscope-enterprise.onrender.com/ws/live`
4. 观察犯罪档案实时流入
5. 如果免费版实例处于休眠状态，每 10 秒自动重连
## 📚 学术参考
- Cohen, L. E., & Felson, M. (1979). *Social change and crime rate trends: A routine activity approach.* American Sociological Review, 44(4), 588–608.
- Bakhtin, M. M. (1981). *The Dialogic Imagination: Four Essays.* University of Texas Press.
- Felson, M., & Boba, R. (2010). *Crime and Everyday Life* (4th ed.). SAGE Publications.
## 👩💻 作者
**将犯罪学的日常活动理论应用于网络安全威胁情报** *唯一专注于分析人类犯罪者特征——而非仅仅关注 IP 地址的威胁情报平台*
| 🌐 在线演示 | 📖 API 文档 | ⚡ 实时威胁 | 🤖 ML 预测 | |:---:|:---:|:---:|:---:| | [chronoscope-enterprise.onrender.com](https://chronoscope-enterprise.onrender.com) | [/docs](https://chronoscope-enterprise.onrender.com/docs) | [/threats/live](https://chronoscope-enterprise.onrender.com/threats/live) | [/predictions/global](https://chronoscope-enterprise.onrender.com/predictions/global) |
**Unnathi Vithlani**
🎓 M.A. Criminology (犯罪学硕士) | M.S. Cybersecurity (网络安全硕士)
📧 [unnathi.vithlani@gmail.com](mailto:unnathi.vithlani@gmail.com)
🐙 [github.com/Unnathi-vithlani](https://github.com/Unnathi-vithlani)
💼 [LinkedIn](https://www.linkedin.com/in/unnathi-vithlani/)
*该项目源于一种罕见的跨学科视角——将犯罪学的人类行为科学应用于网络安全的技术领域，这是两个领域通常都未曾考虑过的结合方式。*
## 📄 许可证
MIT License —— 可免费用于研究、教育和商业用途，但需注明出处。
⭐ **如果你觉得这个概念有趣，请给这个仓库一个 Star！**
*使用 FastAPI · Python 3.11 · Pydantic · SQLite · Docker 构建 · 部署于 Render*
标签：Apex, API安全, AV绕过, Docker, FastAPI, HTTP/HTTPS抓包, JSON输出, Python, WebSocket, 企业安全, 依赖分析, 威胁情报, 子域名突变, 安全防御评估, 密码管理, 开发者工具, 态势感知, 搜索引擎查询, 攻击者追踪, 无后门, 日常活动理论, 机器学习, 测试用例, 犯罪学, 犯罪画像, 网络安全, 网络测绘, 网络资产管理, 请求拦截, 软件成分分析, 逆向工具, 防御规避检测, 隐私保护, 风险预测