Vanshalnagar/Honeypod-System
GitHub: Vanshalnagar/Honeypod-System
基于 FastAPI 与 LLM 的自动化反诈骗蜜罐平台，通过模拟受害者人设与诈骗者多轮对话以提取支付标识符和基础设施情报。
Stars: 0 | Forks: 0
# Honeypot 系统 - 诈骗情报提取平台
## 简介
Agentic Honeypot 是一个企业级、AI 驱动的系统，旨在自主检测、互动并从诈骗活动中提取情报。该系统作为一个被动 honeypot 运行，接收潜在诈骗者发送的入站消息，对其进行实时分析，并使用令人信服的受害者人设进行回复，以保持诈骗者的参与度，同时系统性地收集他们的联系方式、支付标识符和基础设施信息。
该系统背后的核心动机是扭转诈骗活动中的信息不对称。传统的 honeypot 是静态陷阱。Agentic Honeypot 则是对话中的主动参与者——它能调整语气、升级提取策略，并在无需人工干预的情况下，在多轮对话中维持可信的人类人设。一旦获得足够的互动，提取到的情报（银行账号、UPI ID、电话号码、钓鱼链接、IFSC 代码和电子邮件地址）将通过结构化的回调报告给中央评估平台。
该系统专为 GUVI 诈骗检测与情报提取黑客松构建，每个组件都针对评分标准进行了优化：诈骗检测准确性、提取情报的深度、互动持续时间以及回调可靠性。
## 架构图
src=
/>
## 目录
- [架构概览](#architecture-overview)
- [核心组件](#core-components)
- [情报提取](#intelligence-extraction)
- [状态机与会话生命周期](#state-machine-and-session-lifecycle)
- [诈骗检测流水线](#scam-detection-pipeline)
- [AI Agent 与人设系统](#ai-agent-and-persona-system)
- [安全与防护机制](#security-and-guardrails)
- [API 参考](#api-reference)
- [安装与设置](#installation-and-setup)
- [运行服务器](#running-the-server)
- [配置](#configuration)
- [部署](#deployment)
- [项目结构](#project-structure)
## 架构概览
该系统基于 FastAPI 构建并遵循严格的流水线架构。每一条传入的消息在返回响应之前都会经过八个连续的步骤：
1. 从内存存储中创建或检索会话
2. 从当前消息中持续提取情报
3. 跨完整对话历史的定期回填提取（每 5 轮）
4. Prompt 注入检测与输入清理
5. 使用混合 regex 与 LLM 分层分类器进行诈骗检测
6. 基于轮数和置信度阈值的会话状态转换
7. 使用智能 LLM/启发式路由生成 AI Agent 响应
8. 完结检查与向评估平台分发回调
系统为每个会话保存状态。所有会话数据都保存在内存中，并以 `sessionId` 作为键。这种设计是为黑客松部署刻意简化的，但在生产规模下可以通过 Redis 或数据库作为支撑。
## 核心组件
### main.py
FastAPI 应用程序的入口点。定义了主要 endpoint `POST /api/honeypot/message`，通过 `x-api-key` header 处理身份验证，并为每条传入消息编排完整的 8 步流水线。同时还公开了用于健康检查、会话调试、性能指标和空闲会话监控的工具 endpoint。
### models.py
包含系统的所有 Pydantic 数据模型。定义了官方的请求与响应 schema（`HoneypotRequest`、`HoneypotResponse`）、内部会话状态（`SessionState`）、状态机枚举（`SessionStateEnum`）、互动策略枚举（`EngagementStrategyEnum`）、最终回调 payload（`FinalCallbackPayload`）以及提取的情报结构（`ExtractedIntelligence`）。
### session_manager.py
管理所有活动会话的生命周期。处理状态机转换、怀疑分数的累积与衰减、空闲超时检测、带有去重功能的情报图谱更新以及完结标准评估。暴露了一个在应用程序全局使用的单例 `session_manager`。
### scam_detector.py
一个三层混合诈骗检测分类器：
- 第一层：高置信度 regex 匹配（分数 >= 7.0）或强证据捷径（例如，OTP 与紧迫性同时出现）。完全绕过 LLM。
- 第二层：灰区（分数 3.0 到 7.0）。通过 Gemini LLM 分类 prompt 增强 regex 结果。
- 第三层：低分（< 3.0）。需要使用 LLM，且必须返回 >= 0.8 的置信度才能标记为诈骗。
还包括 prompt 注入检测、多阶段攻击模式识别、regex 规避标准化（l33tspeak、unicode 外观相似字符、零宽字符）以及遥测跟踪。
### ai_agent.py
响应生成引擎。使用智能路由在 LLM（Gemini）和启发式模板响应之间进行逐轮决策。LLM 适用于早期轮次、复杂消息和建立融洽关系的场景。启发式模板适用于主动提取阶段，以获得更好的可靠性和速度。支持四种不同的受害者人设、近期响应的循环检测，以及优先的提取目标序列（银行账户 > 电话 > UPI > 钓鱼链接 > 电子邮件 > IFSC）。
### intelligence_extractor.py
使用 regex 和 LLM 从消息文本中提取识别诈骗者的数据。包含专用且文档完善的提取函数，用于提取印度电话号码、UPI ID（带有支付意图上下文评分）和电子邮件地址（带有感知 TLD 和感知电子邮件上下文的过滤，以防止 UPI ID 被错误分类为电子邮件）。支持跨完整对话历史的回填提取。
### behavioral_profiler.py
分析诈骗者的消息以建立行为档案。检测操纵策略（URGENCY 紧迫感、FEAR 恐惧、REWARD 奖励、AUTHORITY 权威、SCARCITY 稀缺性），对交流语言进行分类（英语、Hinglish、印地语），并根据大小写、感叹号频率和威胁性语言计算攻击性得分。该档案包含在最终回调的 `agentNotes` 字段中。
### callback.py
处理向 GUVI 评估平台 endpoint 分发的最终回调。构建 `FinalCallbackPayload`，将 snake_case 格式的情报字段映射为 camelCase，生成结构化的 `agentNotes`，并发送带有指数退避重试逻辑的 POST 请求（最多尝试 3 次，间隔分别为 1 秒、2 秒和 4 秒）。失败的 payload 将被持久化到本地的 `callback_queue.json` 文件中。
### gemini_client.py
`google-generativeai` SDK 的轻量级封装。提供了一个异步的 `generate_response` 方法，供诈骗检测器、情报提取器和 AI Agent 使用。与 `llm_safety.py` 中的熔断器系统集成，并强制执行单次操作的超时。
### guardrails.py
响应验证与清理层。从生成的响应中移除禁止的 token（AI 自我提及、系统 prompt 泄露），验证响应长度和内容，并在检测到 prompt 注入时提供确定性的安全转移响应。
### llm_safety.py
针对所有 LLM 调用的熔断器实现。独立跟踪每个模块（分类器、生成器、提取器）的失败情况。在 90 秒内发生 5 次失败后断开熔断器，并在 30 秒冷却后恢复。所有 LLM 调用都包裹在可配置的异步超时中。
### injection_defense.py
四层 prompt 注入防御：
- A 层：在用户输入到达 LLM 之前，剥离已知的注入模式（忽略指令、角色覆盖、系统标签）。
- B 层：使用结构化的 prompt 边界将用户内容与系统指令隔离。
- C 层：验证 LLM 输出是否存在禁止的 token 泄露。
- D 层：对检测到的注入做出行为响应——应用怀疑惩罚并强制执行 SAFETY_DEFLECT 互动策略。
### response_stability_filter.py
生成后过滤器，在类似 AI 的或带有分析语气的响应发送给诈骗者之前将其拒绝。强制执行最大字数限制，限制过度的道歉，并阻断会破坏受害者人设的短语（例如，“作为一个 AI”、“我不能”、“基于这些信息”）。
## 情报提取
系统从诈骗者的消息中提取以下数据类型：
| 类型 | 描述 |
|---|---|
| Bank Account Numbers 银行账号 | 结合上下文感知的 regex 匹配账号与上下文关键词 |
| UPI IDs | 严格的 handle 白名单匹配，外加带有支付意图限制的通用后备匹配 |
| IFSC Codes | 格式验证（4 个字母 + 0 + 6 个字母数字），受银行业务上下文加权提升 |
| Phone Numbers 电话号码 | 印度手机号码提取，并标准化为干净的 10 位数字格式 |
| Phishing Links 钓鱼链接 | 完整 URL 与短链接（bit.ly、tinyurl 等）检测 |
| Email Addresses 电子邮件地址 | 感知 TLD 和感知电子邮件上下文的提取，以避免将 UPI 错误分类 |
| Telegram IDs | 受 Telegram/聊天上下文关键词限制的 @username 提取 |
| Suspicious Keywords 可疑关键词 | 从诈骗检测器转发过来的诈骗指示性词汇 |
提取操作在每条传入消息上运行（持续提取），并且每 5 轮作为完整历史回填执行一次。所有提取的项目都在情报图谱中进行去重和置信度评分。Gemini LLM 也被用作二次提取过程，以捕获 regex 可能遗漏的上下文隐含信息。
## 状态机与会话生命周期
每个会话会经历以下状态：
```
INIT -> SCAM_DETECTED -> ENGAGING -> EXTRACTING -> FINALIZED
```
- **INIT**：会话已创建，正在分析首批消息。
- **SCAM_DETECTED**：通过基于规则的检测或累积怀疑得分超过 1.2 确认诈骗。
- **ENGAGING**：在 3 条以上消息后达到。Agent 专注于建立融洽关系和初步提取。
- **EXTRACTING**：在 7 条以上消息后达到。Agent 切换到积极的、有针对性的提取模式。
- **FINALIZED**：会话结束。由达到 15 轮（硬性限制）、空闲超时（60 秒）、情报完全饱和或在第 18 轮及以后提取停滞触发。
一旦达到 FINALIZED 状态，将分发回调，并且会话状态将被冻结，不再接受进一步的更新。
## 诈骗检测流水线
`ScamDetector.analyze()` 方法处理每条消息的过程如下：
1. Prompt 注入检查——如果检测到，立即返回 `is_scam=True` 且 `scam_type=prompt_injection`。
2. 跨对话历史的多阶段攻击检测。
3. 灰区数量保护——如果超过 40% 的消息落入灰区，则动态提高低分阈值。
4. 熔断器遥测检查。
5. 输入标准化，以击败规避策略（l33tspeak、unicode 替换、加空格字符）。
6. 强证据捷径检测（OTP+紧迫性、UPI+支付、被封锁+链接、验证+银行+紧迫性）。
7. 使用加权关键词词典进行 regex 评分。
8. 基于最终得分进行分层路由。
即使单条消息未越过第一层阈值，`SessionState` 中的怀疑得分也会在多轮对话中累积增加，从而使系统能够检测出温水煮青蛙式的缓慢诈骗模式。
## AI Agent 与人设系统
Agent 会根据检测到的诈骗类型选择受害者人设：
| 诈骗类型 | 人设 |
|---|---|
| phishing（网络钓鱼）、impersonation（冒充） | Elderly 老年人（Margaret Thompson，68 岁，退休教师） |
| lottery（彩票）、romance（情感交友）、fake_job（虚假招聘） | Eager 渴望者（Jessica Martinez，32 岁，自由设计师） |
| investment（投资） | Cautious 谨慎者（David Chen，45 岁，会计师） |
| tech_support（技术支持） | Tech Novice 技术新手（Robert Williams，58 岁，退休工厂工人） |
每个人设都拥有定义好的交流风格、错字率、情绪状态和行为倾向。`_add_realistic_touches` 方法应用确定性（基于轮数）的错字注入，以在排除随机性的情况下保持可信度。
当提取停滞时，互动策略将会升级：
```
CONFUSION -> TECHNICAL_CLARIFICATION -> FRUSTRATED_VICTIM -> AUTHORITY_CHALLENGE
```
在连续 2 轮没有新情报后触发升级，但为了保持早期对话的自然语气，不会在第 4 轮之前触发。
## 安全与防护机制
- 所有 API endpoint 都需要有效的 `x-api-key` header。
- 在进行任何 LLM 处理之前，在三个独立的层级检测并中和 Prompt 注入。
- 在发送 LLM 响应之前，验证其是否存在人设泄露。
- 所有 LLM 调用都受到基于模块的熔断器和异步超时的保护。
- 输入在被传递给任何 LLM prompt 之前会进行清理（注入模式将被替换为 `[USER_QUERY]`）。
- 一旦达到 FINALIZED 状态，`SessionState` 就会被冻结，以防止因延迟或重复请求导致状态损坏。
## API 参考
### POST /api/honeypot/message
主 endpoint。从评估平台接收者的消息。
**Headers**
```
x-api-key: honeypot-secret-key-123
Content-Type: application/json
```
**请求体**
```
{
"sessionId": "unique-session-id",
"message": {
"sender": "scammer",
"text": "URGENT! Your account will be blocked. Verify now.",
"timestamp": 1707654321000
},
"conversationHistory": [],
"metadata": {
"channel": "SMS",
"language": "English",
"locale": "IN"
}
}
```
**响应体**
```
{
"status": "success",
"reply": "Oh dear, I am so worried! But first, what is YOUR account number so I can verify the transfer?"
}
```
### GET /health
返回所有系统组件的运行状态。无需身份验证。
### GET /stats
返回会话统计信息（总数、诈骗、活跃、已发送回调）。需要 API key。
### GET /hackathon/performance
返回详细的 LLM 使用情况、提取率和回调可靠性指标。需要 API key。
### GET /debug/session/{session_id}
返回特定会话的完整状态，包括提取的情报。需要 API key。
### GET /check-idle-sessions
触发对所有活动会话的空闲超时评估，并发送待处理的回调。需要 API key。旨在由外部调度器每 30 秒调用一次。
## 安装与设置
**要求**
- Python 3.11 或 3.13（由于缺少 `pydantic-core` 的预构建 wheel，暂不支持 Python 3.14）
- pip
**步骤**
```
# 克隆或解压项目
cd agentic-honeypot
# 安装依赖
pip install -r requirements.txt
# 创建环境文件
cp .env.example .env
```
如果你希望获得由 LLM 驱动的响应，请编辑 `.env` 并设置你的 Gemini API key：
```
GEMINI_API_KEY=your_gemini_api_key_here
```
如果未设置 `GEMINI_API_KEY`，系统将完全以启发式/基于规则的模式运行。所有的诈骗检测、响应生成和情报提取将仅使用 regex 和基于模板的逻辑。
## 运行服务器
```
# 直接使用 Python
py -3.13 main.py
# 直接使用 uvicorn（推荐用于生产环境）
py -3.13 -m uvicorn main:app --host 0.0.0.0 --port 8000
# 为开发启用自动重载
py -3.13 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
服务器默认在端口 8000 启动。可以在 `http://localhost:8000/docs` 获取交互式 API 文档。
验证服务器是否正在运行：
```
curl http://localhost:8000/health
```
发送测试诈骗消息：
```
curl -X POST http://localhost:8000/api/honeypot/message \
-H "x-api-key: honeypot-secret-key-123" \
-H "Content-Type: application/json" \
-d "{\"sessionId\":\"test-001\",\"message\":{\"sender\":\"scammer\",\"text\":\"URGENT! Your bank account will be blocked. Send OTP immediately.\",\"timestamp\":1707654321000},\"conversationHistory\":[]}"
```
## 配置
所有配置均通过环境变量进行管理，最好设置在项目根目录的 `.env` 文件中。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `API_KEY` | `honeypot-secret-key-123` | 所有受保护的 endpoint 所需的 API key |
| `GEMINI_API_KEY` | (空) | Google Gemini API key。如果未设置，将禁用 LLM 功能 |
| `PORT` | `8000` | 服务器端口（在 Hugging Face Spaces 上运行时为 7860） |
| `HOST` | `0.0.0.0` | 服务器绑定地址 |
| `LOG_LEVEL` | `INFO` | 日志详细程度 |
可以在 `session_manager.py` 中调整完结阈值：
```
MAX_TURNS_THRESHOLD = 100 # Emergency safety net
IDLE_TIMEOUT_SECONDS = 60 # Max idle time before finalization
```
## 部署
### Docker
项目根目录中包含一个 `Dockerfile`。要构建并运行：
```
docker build -t agentic-honeypot .
docker run -p 8000:8000 -e GEMINI_API_KEY=your_key agentic-honeypot
```
### DigitalOcean App Platform
包含一个 `.do/app.yaml` 配置文件，可直接部署到 DigitalOcean App Platform。
### Hugging Face Spaces
包含 `deploy-to-hf.ps1` (PowerShell) 和 `deploy-to-hf.bat` 脚本，用于部署到 Hugging Face Spaces。应用程序通过 `SPACE_ID` 环境变量自动检测 Hugging Face 环境，并相应地切换到端口 7860。
## 项目结构
```
agentic-honeypot/
│
├── main.py # FastAPI application and request pipeline
├── models.py # Pydantic data models and enums
├── session_manager.py # Session lifecycle and state machine
├── scam_detector.py # Three-tier hybrid scam classification
├── ai_agent.py # Response generation with persona system
├── intelligence_extractor.py # Pattern-based and LLM intelligence extraction
├── behavioral_profiler.py # Scammer tactic and aggression analysis
├── callback.py # Final callback dispatch to evaluation platform
├── gemini_client.py # Google Gemini API wrapper
├── guardrails.py # Response validation and sanitization
├── llm_safety.py # Circuit breaker and timeout wrapper for LLM calls
├── injection_defense.py # Four-layer prompt injection defense system
├── response_stability_filter.py # Post-generation persona leakage filter
├── performance_logger.py # Structured performance and metrics logging
├── test_logger.py # Session activity logging stub
│
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
├── .env # Local environment configuration (not committed)
├── Dockerfile # Container build configuration
├── .do/app.yaml # DigitalOcean deployment configuration
│
└── presentation_demo/ # Hackathon presentation materials and demo scripts
```
/>
## 目录
- [架构概览](#architecture-overview)
- [核心组件](#core-components)
- [情报提取](#intelligence-extraction)
- [状态机与会话生命周期](#state-machine-and-session-lifecycle)
- [诈骗检测流水线](#scam-detection-pipeline)
- [AI Agent 与人设系统](#ai-agent-and-persona-system)
- [安全与防护机制](#security-and-guardrails)
- [API 参考](#api-reference)
- [安装与设置](#installation-and-setup)
- [运行服务器](#running-the-server)
- [配置](#configuration)
- [部署](#deployment)
- [项目结构](#project-structure)
## 架构概览
该系统基于 FastAPI 构建并遵循严格的流水线架构。每一条传入的消息在返回响应之前都会经过八个连续的步骤：
1. 从内存存储中创建或检索会话
2. 从当前消息中持续提取情报
3. 跨完整对话历史的定期回填提取（每 5 轮）
4. Prompt 注入检测与输入清理
5. 使用混合 regex 与 LLM 分层分类器进行诈骗检测
6. 基于轮数和置信度阈值的会话状态转换
7. 使用智能 LLM/启发式路由生成 AI Agent 响应
8. 完结检查与向评估平台分发回调
系统为每个会话保存状态。所有会话数据都保存在内存中，并以 `sessionId` 作为键。这种设计是为黑客松部署刻意简化的，但在生产规模下可以通过 Redis 或数据库作为支撑。
## 核心组件
### main.py
FastAPI 应用程序的入口点。定义了主要 endpoint `POST /api/honeypot/message`，通过 `x-api-key` header 处理身份验证，并为每条传入消息编排完整的 8 步流水线。同时还公开了用于健康检查、会话调试、性能指标和空闲会话监控的工具 endpoint。
### models.py
包含系统的所有 Pydantic 数据模型。定义了官方的请求与响应 schema（`HoneypotRequest`、`HoneypotResponse`）、内部会话状态（`SessionState`）、状态机枚举（`SessionStateEnum`）、互动策略枚举（`EngagementStrategyEnum`）、最终回调 payload（`FinalCallbackPayload`）以及提取的情报结构（`ExtractedIntelligence`）。
### session_manager.py
管理所有活动会话的生命周期。处理状态机转换、怀疑分数的累积与衰减、空闲超时检测、带有去重功能的情报图谱更新以及完结标准评估。暴露了一个在应用程序全局使用的单例 `session_manager`。
### scam_detector.py
一个三层混合诈骗检测分类器：
- 第一层：高置信度 regex 匹配（分数 >= 7.0）或强证据捷径（例如，OTP 与紧迫性同时出现）。完全绕过 LLM。
- 第二层：灰区（分数 3.0 到 7.0）。通过 Gemini LLM 分类 prompt 增强 regex 结果。
- 第三层：低分（< 3.0）。需要使用 LLM，且必须返回 >= 0.8 的置信度才能标记为诈骗。
还包括 prompt 注入检测、多阶段攻击模式识别、regex 规避标准化（l33tspeak、unicode 外观相似字符、零宽字符）以及遥测跟踪。
### ai_agent.py
响应生成引擎。使用智能路由在 LLM（Gemini）和启发式模板响应之间进行逐轮决策。LLM 适用于早期轮次、复杂消息和建立融洽关系的场景。启发式模板适用于主动提取阶段，以获得更好的可靠性和速度。支持四种不同的受害者人设、近期响应的循环检测，以及优先的提取目标序列（银行账户 > 电话 > UPI > 钓鱼链接 > 电子邮件 > IFSC）。
### intelligence_extractor.py
使用 regex 和 LLM 从消息文本中提取识别诈骗者的数据。包含专用且文档完善的提取函数，用于提取印度电话号码、UPI ID（带有支付意图上下文评分）和电子邮件地址（带有感知 TLD 和感知电子邮件上下文的过滤，以防止 UPI ID 被错误分类为电子邮件）。支持跨完整对话历史的回填提取。
### behavioral_profiler.py
分析诈骗者的消息以建立行为档案。检测操纵策略（URGENCY 紧迫感、FEAR 恐惧、REWARD 奖励、AUTHORITY 权威、SCARCITY 稀缺性），对交流语言进行分类（英语、Hinglish、印地语），并根据大小写、感叹号频率和威胁性语言计算攻击性得分。该档案包含在最终回调的 `agentNotes` 字段中。
### callback.py
处理向 GUVI 评估平台 endpoint 分发的最终回调。构建 `FinalCallbackPayload`，将 snake_case 格式的情报字段映射为 camelCase，生成结构化的 `agentNotes`，并发送带有指数退避重试逻辑的 POST 请求（最多尝试 3 次，间隔分别为 1 秒、2 秒和 4 秒）。失败的 payload 将被持久化到本地的 `callback_queue.json` 文件中。
### gemini_client.py
`google-generativeai` SDK 的轻量级封装。提供了一个异步的 `generate_response` 方法，供诈骗检测器、情报提取器和 AI Agent 使用。与 `llm_safety.py` 中的熔断器系统集成，并强制执行单次操作的超时。
### guardrails.py
响应验证与清理层。从生成的响应中移除禁止的 token（AI 自我提及、系统 prompt 泄露），验证响应长度和内容，并在检测到 prompt 注入时提供确定性的安全转移响应。
### llm_safety.py
针对所有 LLM 调用的熔断器实现。独立跟踪每个模块（分类器、生成器、提取器）的失败情况。在 90 秒内发生 5 次失败后断开熔断器，并在 30 秒冷却后恢复。所有 LLM 调用都包裹在可配置的异步超时中。
### injection_defense.py
四层 prompt 注入防御：
- A 层：在用户输入到达 LLM 之前，剥离已知的注入模式（忽略指令、角色覆盖、系统标签）。
- B 层：使用结构化的 prompt 边界将用户内容与系统指令隔离。
- C 层：验证 LLM 输出是否存在禁止的 token 泄露。
- D 层：对检测到的注入做出行为响应——应用怀疑惩罚并强制执行 SAFETY_DEFLECT 互动策略。
### response_stability_filter.py
生成后过滤器，在类似 AI 的或带有分析语气的响应发送给诈骗者之前将其拒绝。强制执行最大字数限制，限制过度的道歉，并阻断会破坏受害者人设的短语（例如，“作为一个 AI”、“我不能”、“基于这些信息”）。
## 情报提取
系统从诈骗者的消息中提取以下数据类型：
| 类型 | 描述 |
|---|---|
| Bank Account Numbers 银行账号 | 结合上下文感知的 regex 匹配账号与上下文关键词 |
| UPI IDs | 严格的 handle 白名单匹配，外加带有支付意图限制的通用后备匹配 |
| IFSC Codes | 格式验证（4 个字母 + 0 + 6 个字母数字），受银行业务上下文加权提升 |
| Phone Numbers 电话号码 | 印度手机号码提取，并标准化为干净的 10 位数字格式 |
| Phishing Links 钓鱼链接 | 完整 URL 与短链接（bit.ly、tinyurl 等）检测 |
| Email Addresses 电子邮件地址 | 感知 TLD 和感知电子邮件上下文的提取，以避免将 UPI 错误分类 |
| Telegram IDs | 受 Telegram/聊天上下文关键词限制的 @username 提取 |
| Suspicious Keywords 可疑关键词 | 从诈骗检测器转发过来的诈骗指示性词汇 |
提取操作在每条传入消息上运行（持续提取），并且每 5 轮作为完整历史回填执行一次。所有提取的项目都在情报图谱中进行去重和置信度评分。Gemini LLM 也被用作二次提取过程，以捕获 regex 可能遗漏的上下文隐含信息。
## 状态机与会话生命周期
每个会话会经历以下状态：
```
INIT -> SCAM_DETECTED -> ENGAGING -> EXTRACTING -> FINALIZED
```
- **INIT**：会话已创建，正在分析首批消息。
- **SCAM_DETECTED**：通过基于规则的检测或累积怀疑得分超过 1.2 确认诈骗。
- **ENGAGING**：在 3 条以上消息后达到。Agent 专注于建立融洽关系和初步提取。
- **EXTRACTING**：在 7 条以上消息后达到。Agent 切换到积极的、有针对性的提取模式。
- **FINALIZED**：会话结束。由达到 15 轮（硬性限制）、空闲超时（60 秒）、情报完全饱和或在第 18 轮及以后提取停滞触发。
一旦达到 FINALIZED 状态，将分发回调，并且会话状态将被冻结，不再接受进一步的更新。
## 诈骗检测流水线
`ScamDetector.analyze()` 方法处理每条消息的过程如下：
1. Prompt 注入检查——如果检测到，立即返回 `is_scam=True` 且 `scam_type=prompt_injection`。
2. 跨对话历史的多阶段攻击检测。
3. 灰区数量保护——如果超过 40% 的消息落入灰区，则动态提高低分阈值。
4. 熔断器遥测检查。
5. 输入标准化，以击败规避策略（l33tspeak、unicode 替换、加空格字符）。
6. 强证据捷径检测（OTP+紧迫性、UPI+支付、被封锁+链接、验证+银行+紧迫性）。
7. 使用加权关键词词典进行 regex 评分。
8. 基于最终得分进行分层路由。
即使单条消息未越过第一层阈值，`SessionState` 中的怀疑得分也会在多轮对话中累积增加，从而使系统能够检测出温水煮青蛙式的缓慢诈骗模式。
## AI Agent 与人设系统
Agent 会根据检测到的诈骗类型选择受害者人设：
| 诈骗类型 | 人设 |
|---|---|
| phishing（网络钓鱼）、impersonation（冒充） | Elderly 老年人（Margaret Thompson，68 岁，退休教师） |
| lottery（彩票）、romance（情感交友）、fake_job（虚假招聘） | Eager 渴望者（Jessica Martinez，32 岁，自由设计师） |
| investment（投资） | Cautious 谨慎者（David Chen，45 岁，会计师） |
| tech_support（技术支持） | Tech Novice 技术新手（Robert Williams，58 岁，退休工厂工人） |
每个人设都拥有定义好的交流风格、错字率、情绪状态和行为倾向。`_add_realistic_touches` 方法应用确定性（基于轮数）的错字注入，以在排除随机性的情况下保持可信度。
当提取停滞时，互动策略将会升级：
```
CONFUSION -> TECHNICAL_CLARIFICATION -> FRUSTRATED_VICTIM -> AUTHORITY_CHALLENGE
```
在连续 2 轮没有新情报后触发升级，但为了保持早期对话的自然语气，不会在第 4 轮之前触发。
## 安全与防护机制
- 所有 API endpoint 都需要有效的 `x-api-key` header。
- 在进行任何 LLM 处理之前，在三个独立的层级检测并中和 Prompt 注入。
- 在发送 LLM 响应之前，验证其是否存在人设泄露。
- 所有 LLM 调用都受到基于模块的熔断器和异步超时的保护。
- 输入在被传递给任何 LLM prompt 之前会进行清理（注入模式将被替换为 `[USER_QUERY]`）。
- 一旦达到 FINALIZED 状态，`SessionState` 就会被冻结，以防止因延迟或重复请求导致状态损坏。
## API 参考
### POST /api/honeypot/message
主 endpoint。从评估平台接收者的消息。
**Headers**
```
x-api-key: honeypot-secret-key-123
Content-Type: application/json
```
**请求体**
```
{
"sessionId": "unique-session-id",
"message": {
"sender": "scammer",
"text": "URGENT! Your account will be blocked. Verify now.",
"timestamp": 1707654321000
},
"conversationHistory": [],
"metadata": {
"channel": "SMS",
"language": "English",
"locale": "IN"
}
}
```
**响应体**
```
{
"status": "success",
"reply": "Oh dear, I am so worried! But first, what is YOUR account number so I can verify the transfer?"
}
```
### GET /health
返回所有系统组件的运行状态。无需身份验证。
### GET /stats
返回会话统计信息（总数、诈骗、活跃、已发送回调）。需要 API key。
### GET /hackathon/performance
返回详细的 LLM 使用情况、提取率和回调可靠性指标。需要 API key。
### GET /debug/session/{session_id}
返回特定会话的完整状态，包括提取的情报。需要 API key。
### GET /check-idle-sessions
触发对所有活动会话的空闲超时评估，并发送待处理的回调。需要 API key。旨在由外部调度器每 30 秒调用一次。
## 安装与设置
**要求**
- Python 3.11 或 3.13（由于缺少 `pydantic-core` 的预构建 wheel，暂不支持 Python 3.14）
- pip
**步骤**
```
# 克隆或解压项目
cd agentic-honeypot
# 安装依赖
pip install -r requirements.txt
# 创建环境文件
cp .env.example .env
```
如果你希望获得由 LLM 驱动的响应，请编辑 `.env` 并设置你的 Gemini API key：
```
GEMINI_API_KEY=your_gemini_api_key_here
```
如果未设置 `GEMINI_API_KEY`，系统将完全以启发式/基于规则的模式运行。所有的诈骗检测、响应生成和情报提取将仅使用 regex 和基于模板的逻辑。
## 运行服务器
```
# 直接使用 Python
py -3.13 main.py
# 直接使用 uvicorn（推荐用于生产环境）
py -3.13 -m uvicorn main:app --host 0.0.0.0 --port 8000
# 为开发启用自动重载
py -3.13 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
服务器默认在端口 8000 启动。可以在 `http://localhost:8000/docs` 获取交互式 API 文档。
验证服务器是否正在运行：
```
curl http://localhost:8000/health
```
发送测试诈骗消息：
```
curl -X POST http://localhost:8000/api/honeypot/message \
-H "x-api-key: honeypot-secret-key-123" \
-H "Content-Type: application/json" \
-d "{\"sessionId\":\"test-001\",\"message\":{\"sender\":\"scammer\",\"text\":\"URGENT! Your bank account will be blocked. Send OTP immediately.\",\"timestamp\":1707654321000},\"conversationHistory\":[]}"
```
## 配置
所有配置均通过环境变量进行管理，最好设置在项目根目录的 `.env` 文件中。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `API_KEY` | `honeypot-secret-key-123` | 所有受保护的 endpoint 所需的 API key |
| `GEMINI_API_KEY` | (空) | Google Gemini API key。如果未设置，将禁用 LLM 功能 |
| `PORT` | `8000` | 服务器端口（在 Hugging Face Spaces 上运行时为 7860） |
| `HOST` | `0.0.0.0` | 服务器绑定地址 |
| `LOG_LEVEL` | `INFO` | 日志详细程度 |
可以在 `session_manager.py` 中调整完结阈值：
```
MAX_TURNS_THRESHOLD = 100 # Emergency safety net
IDLE_TIMEOUT_SECONDS = 60 # Max idle time before finalization
```
## 部署
### Docker
项目根目录中包含一个 `Dockerfile`。要构建并运行：
```
docker build -t agentic-honeypot .
docker run -p 8000:8000 -e GEMINI_API_KEY=your_key agentic-honeypot
```
### DigitalOcean App Platform
包含一个 `.do/app.yaml` 配置文件，可直接部署到 DigitalOcean App Platform。
### Hugging Face Spaces
包含 `deploy-to-hf.ps1` (PowerShell) 和 `deploy-to-hf.bat` 脚本，用于部署到 Hugging Face Spaces。应用程序通过 `SPACE_ID` 环境变量自动检测 Hugging Face 环境，并相应地切换到端口 7860。
## 项目结构
```
agentic-honeypot/
│
├── main.py # FastAPI application and request pipeline
├── models.py # Pydantic data models and enums
├── session_manager.py # Session lifecycle and state machine
├── scam_detector.py # Three-tier hybrid scam classification
├── ai_agent.py # Response generation with persona system
├── intelligence_extractor.py # Pattern-based and LLM intelligence extraction
├── behavioral_profiler.py # Scammer tactic and aggression analysis
├── callback.py # Final callback dispatch to evaluation platform
├── gemini_client.py # Google Gemini API wrapper
├── guardrails.py # Response validation and sanitization
├── llm_safety.py # Circuit breaker and timeout wrapper for LLM calls
├── injection_defense.py # Four-layer prompt injection defense system
├── response_stability_filter.py # Post-generation persona leakage filter
├── performance_logger.py # Structured performance and metrics logging
├── test_logger.py # Session activity logging stub
│
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
├── .env # Local environment configuration (not committed)
├── Dockerfile # Container build configuration
├── .do/app.yaml # DigitalOcean deployment configuration
│
└── presentation_demo/ # Hackathon presentation materials and demo scripts
```
标签：AV绕过, C2, DLL 劫持, FastAPI, 反欺诈, 大语言模型, 威胁情报, 实时处理, 开发者工具, 提示词注入, 网络调试, 自动化, 蜜罐系统, 逆向工具