antonizick/Citadel
GitHub: antonizick/Citadel
一款结合 AI 驱动的主题监控与 IOC 追踪的自托管威胁情报平台，实现自动化搜索、智能摘要生成与多渠道报告分发的一体化工作流。
Stars: 0 | Forks: 0
# Nx-Citadel
**自托管智能监控平台。** 追踪主题、人物、技术和可信来源——由 AI 驱动的搜索、摘要和分发功能提供支持。
Nx-Citadel 定期运行 Web 搜索，将结果提供给 LLM (Anthropic Claude)，生成执行摘要，并通过 Email、Slack、SMS 或 Discord 进行分发。它还维护着一个从公开威胁情报源提取的 IOC (Indicators of Compromise，妥协指标) 数据库。
## 功能
- **兴趣监控** — 定义主题（人物、公司、技术、事件、自定义术语）。每个主题按设定的计划运行，搜索网络并生成 AI 摘要报告。
- **可信资源监控** — 指向任何 URL（网站、RSS 源、X/Twitter 个人资料）。AI 使用可配置的 prompt 提取并结构化过去 48 小时内的资讯。
- **执行摘要报告** — 将多个兴趣报告综合成跨主题简报，并按独立计划运行。
- **IOC 追踪** — 每日自动从 Feodo Tracker、URLhaus、MalwareBazaar 和 OpenPhish 获取数据。支持带严格验证的批量 CSV 上传。
- **多渠道分发** — Email (SMTP/Gmail)、Slack webhook、SMS (Twilio)、Discord webhook。支持按兴趣单独配置。
- **基于角色的访问** — user / manager / admin 角色，具备会话认证和 TOTP MFA 功能（manager/admin 首次登录时强制启用）。
- **完整备份与恢复** — 通过 UI 进行基于 ZIP 的完整备份和粒度化备份。
- **自动更新** — 通过 SSE 流实现一键更新，保留所有用户数据。
- **深色/浅色主题** — 默认深色模式，切换状态持久化至 localStorage。
## 快速开始
### 前置条件
- Linux 下的 **Python 3.10+**
- **Anthropic API key** (用于 Claude LLM)
- 可选：SMTP 配置信息、Twilio 账号、Slack/Discord webhook、Brave Search 或 SerpAPI key
### 本地运行
```
# 1. Clone 并创建 virtual environment
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# 2. 启动 server (端口 8000)
python run.py
# 3. 打开 http://localhost:8000
# 默认 login: admin / admin
```
### 作为后台服务运行
```
# 开发 (带 PID 跟踪)
bash StartCitadel.sh
# 停止
bash StopCitadel.sh
# 生产 (systemd)
sudo cp citadel.service /etc/systemd/system/
sudo systemctl enable --now citadel
```
### 在服务器上安装
```
curl -fsSL https://www.antonizick.com/nxcitadel/get.sh | sudo bash
```
选项：`--port 9000`、`--dir /opt/nxcitadel`、`--user nxcitadel`
## 架构
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT (Browser) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SPA (index.html + app.js + main.css) │ │
│ │ • Tabbed navigation (Dashboard / Interests / Resources │ │
│ │ / Summary Reports / IOCs / Settings / Admin / Logs) │ │
│ │ • Axios → /api/* • Auth via session cookies │ │
│ │ • Theme toggle (dark/light, localStorage) │ │
│ │ • SSE tail (admin self-update stream) │ │
│ └─────────────────────────────────────────────────────────┘ │
└────────────────────────────────┬────────────────────────────────────────────┘
│ HTTPS (behind reverse proxy)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ NX-CITADEL APPLICATION SERVER │
│ FastAPI + uvicorn :8000 (0.0.0.0) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Lifespan (startup/shutdown) │ │
│ │ • setup_logging() • _seed_admin() • APScheduler start │ │
│ │ • IOC maintenance cron (02:00 UTC) • IOC collection cron (03:00) │ │
│ │ • Per-interest / per-resource / per-summary schedule reload │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ auth │ │interests │ │resources │ │summary │ │ iocs │ │
│ │_router │ │ (router) │ │ (router) │ │_reports │ │ (router) │ │
│ │ │ │ │ │ │ │ (router) │ │ │ │
│ │ /login │ │ CRUD │ │ CRUD │ │ CRUD │ │ CRUD │ │
│ │ /api/ │ │ run │ │ run │ │ run │ │ bulk CSV │ │
│ │ auth/* │ │ reports │ │ reports │ │ reports │ │ config │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ users │ │ settings │ │ logs │ │ admin │ │ioc_config │ │
│ │ (router) │ │ (router) │ │ (router) │ │ (router) │ │ (router) │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ CRUD │ │ CRUD │ │ tail │ │ backup │ │ source │ │
│ │ MFA reset│ │ test LLM │ │ archive │ │ restore │ │ sync │ │
│ │ │ │ test SMS │ │ │ │ build-pkg│ │ status │ │
│ │ │ │ test email│ │ │ │ reset │ │ │ │
│ │ │ │ test disc│ │ │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Auth Middleware (main.py) │ │
│ │ • Session cookie validation (12h TTL) • bcrypt password check │ │
│ │ • TOTP MFA enforcement (manager/admin) • bypass /login, /static │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌────────────────┐ ┌─────────────────────────────────┐
│ SERVICES │ │ SERVICES │ │ SERVICES │
├───────────────┤ ├───────────────┤ ├──────────────────────────────┤
│ ai_service │ │ search_service │ │ scheduler_service │
│ │ │ │ │ │
│ • summarize_ │ │ • search_multi │ │ • run_interest() │
│ results() │ │ • search_web() │ │ • run_resource() │
│ • summarize_ │ │ • search_trusted│ │ • run_summary_report() │
│ resource() │ │ _resource() │ │ • _build_trigger() │
│ │ │ (DDG/Brave/Serp)│ │ • reload_all_schedules() │
│ SYSTEM_PROMPT: │ │ │ │ │
│ "use only │ │ OUTPUT CHANNELS:│ │ ioc_collector │
│ provided │ │ deliver_outputs │ │ │
│ results, cite │ │ • email (aiosmtp)│ │ • Feodo Tracker │
│ every claim" │ │ • slack webhook │ │ • URLhaus │
└───────┬────────┘ │ • sms (Twilio) │ │ • MalwareBazaar │
│ │ • discord wh │ │ • OpenPhish │
│ └────────┬────────┘ └────────────────┬────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ OUTPUT LAYER │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ output_service / summary_service │ │
│ │ │ │
│ │ deliver_outputs(): │ │
│ │ 1. save report (.md → data/reports//) │ │
│ │ 2. deliver to channels (email/slack/sms/discord) │ │
│ │ 3. enrich with recent resource reports (data/resource_reports/) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ logger_service │ │
│ │ • setup_logging() → logs/citadel.log (daily rotation) │ │
│ │ • log_user_action() │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ STORAGE LAYER │
│ (markdown files with YAML frontmatter — no DB) │
├──────────────────────────────────────────────────────────────────────────────────┤
│ │
│ markdown_store.py ──→ Generic CRUD for .md + frontmatter │
│ ioc_store.py ──→ IOC-specific + dedup + maintenance │
│ user_store.py ──→ User CRUD │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ data/interests/ ──→ .md (watch topic defs) │ │
│ │ data/reports// ──→ .md (generated reports) │ │
│ │ data/resources/ ──→ .md (trusted resource monitors) │ │
│ │ data/resource_reports// ──→ .md (resource reports) │ │
│ │ data/summary_reports// ──→ defs + generated reports │ │
│ │ data/iocs/ ──→ ips.md, domains.md, urls.md, hashes.md │ │
│ │ data/users/ ──→ User accounts (bcrypt) │ │
│ │ data/config/ ──→ settings.yaml, ioc_sources.yaml, │ │
│ │ ioc_sync_status.yaml │ │
│ │ logs/ ──→ citadel.log + daily archives (.gz) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL INTEGRATIONS │
├─────────────────────┬──────────────┬──────────────┬─────────────────┬────────────┤
│ Anthropic │ DuckDuckGo │ aiosmtplib │ Twilio │ Discord │
│ Claude API │ Brave API │ (email) │ (SMS) │ webhook │
│ │ SerpAPI │ │ │ │
│ • AI summarization │ │ │ │
│ • SYSTEM_PROMPT │ │ │ │
│ enforcement │ │ │ │
└───────────────┴──────────────┴──────────────┴──────────────┴───────────────┘
```
**关键数据流：**
1. **兴趣运行 pipeline**：`scheduler_service.run_interest()` → `search_service.search_multi()` (DDG/Brave/SerpAPI) → `ai_service.summarize_results()` (Anthropic Claude) → `output_service.deliver_outputs()` → 保存报告 + 可选分发渠道。摘要会结合 `data/resource_reports/` 中最近的受信资源报告进行丰富。
2. **资源监控 pipeline**：`run_resource()` → 使用 `[SOURCE]` 替换渲染 prompt → `search_multi()` → `summarize_resource()` → `deliver_resource_outputs()` → 保存至 `data/resource_reports//`。
3. **执行摘要 pipeline**：`run_summary_report()` → 收集所有兴趣报告 → LLM 综合 → 通过配置的渠道分发。
4. **IOC pipeline**：计划收集任务（每日 UTC 03:00）从 Feodo Tracker、URLhaus、MalwareBazaar、OpenPhish 拉取数据 → 去重后存入 `ioc_store` → 日常维护任务（每日 UTC 02:00）清理过期/低优先级条目。
5. **认证流程**：Session cookies（12 小时 TTL） → bcrypt 密码 + TOTP MFA（对 manager/admin 强制启用） → `main.py` 中的 middleware 保护所有 `/api/*` 路径（auth 路径除外）。
### 目录结构
```
nxcitadel/
├── app/ # Application code
│ ├── main.py # FastAPI entry point, auth middleware
│ ├── auth.py # Sessions, bcrypt, TOTP
│ ├── models.py # Pydantic models
│ ├── config.py # settings.yaml loader
│ ├── routers/ # API endpoints (CRUD, run, reports)
│ ├── services/ # Business logic (AI, search, scheduler, IOC)
│ └── storage/ # Markdown CRUD layer
├── data/ # All user data (markdown + YAML)
│ ├── interests/ # Watch topic definitions
│ ├── resources/ # Trusted resource monitor definitions
│ ├── reports/ # Generated interest reports
│ ├── resource_reports/ # Generated resource monitor reports
│ ├── summary_reports/ # Summary report definitions + generated reports
│ ├── iocs/ # IOC data (ips, domains, urls, hashes)
│ ├── users/ # User accounts
│ └── config/ # settings.yaml, ioc_sources.yaml
├── templates/index.html # SPA shell (Jinja2)
├── static/ # CSS + JS + assets
├── deploy/ # Install script, build scripts, packages
├── logs/ # Application logs (daily rotation)
├── run.py # Dev entry point
├── requirements.txt # Python dependencies
└── citadel.service # Systemd unit file
```
## 配置
所有设置均位于 `data/config/settings.yaml` 中。可通过 Settings UI 创建或手动创建：
```
llm:
provider: anthropic
api_key: sk-ant-...
model: claude-sonnet-4-6
search:
provider: duckduckgo # duckduckgo | brave | serpapi
max_results: 10
brave_api_key: ""
serpapi_key: ""
email:
smtp_host: smtp.gmail.com
smtp_port: 587
smtp_user: you@gmail.com
smtp_password: your-app-password
from_address: you@gmail.com
use_tls: true
slack:
default_webhook: ""
discord:
default_webhook: ""
sms:
provider: twilio
account_sid: ""
auth_token: ""
from_number: ""
system_state: production # set to "dev" to suppress scheduled LLM calls
```
### 开发模式
在活跃开发期间，将 `system_state` 设置为 `dev` 可阻止所有计划任务的触发。手动运行（UI 中的 "Run" 按钮）仍可正常使用。可通过 API 切换：
```
POST /api/admin/system-state {"system_state": "dev"}
GET /api/admin/system-state
```
## 调度
每个兴趣、资源和摘要报告都有各自的调度计划：
```
schedule:
type: interval # interval | weekly | cron | manual
interval_value: 1
interval_unit: days # minutes | hours | days | weeks
run_time: "20:00" # HH:MM UTC (weekly type)
days_of_week: [0,1,2] # 0=Mon … 6=Sun (weekly type)
cron_expression: "0 20 * * *" # (cron type)
```
系统任务（始终处于激活状态）：
- **IOC 维护** — 每日 UTC 02:00，清理过期条目
- **IOC 收集** — 每日 UTC 03:00，拉取所有已启用的源
## API
运行时可通过 `http://localhost:8000/docs` 查看基于 OpenAPI 的完整 API 文档。除 `/login`、`/health`、`/static/*` 和 `/api/auth/*` 外，所有 endpoint 均需进行会话认证。
| Router | Prefix | 用途 |
|---|---|---|
| `auth_router` | (无) | 登录页面、MFA、登出、`/api/auth/me` |
| `interests` | `/api/interests` | CRUD、运行、报告、活动 |
| `resources` | `/api/resources` | CRUD、运行、报告 |
| `summary_reports` | `/api/summary-reports` | CRUD、运行、报告文件 |
| `iocs` | `/api/iocs` | IOC CRUD、统计、批量 CSV 上传 |
| `ioc_config` | `/api/ioc-config` | Feed 源配置、同步状态、手动拉取 |
| `users` | `/api/users` | User CRUD、MFA 重置 (admin) |
| `settings` | `/api/settings` | Settings CRUD、测试 endpoint (LLM、Email、SMS、Discord) |
| `logs` | `/api/logs` | 最新日志、归档列表 |
| `admin` | `/api/admin` | 备份/恢复、构建包、自更新、恢复出厂设置 |
## 开发
```
# 创建 venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# 启动 (前台，无 reload)
python run.py
# 启动 (后台，带 PID 跟踪)
bash StartCitadel.sh
# 停止
bash StopCitadel.sh
# 查看 logs
tail -f logs/citadel.log
```
本项目没有测试套件、代码检查工具、类型检查器或格式化工具。验证过程为手动——启动服务器并操作 UI 或 API。
## 部署
### 构建包
```
bash deploy/build_package.sh
# → deploy/nxcitadel-.tar.gz
# → deploy/nxcitadel-latest.tar.gz (symlink)
```
或通过 UI 操作：Admin panel → **Build Package** → **Download Package**。
### 在任意 Linux 服务器上一行命令安装
```
curl -fsSL https://www.antonizick.com/nxcitadel/get.sh | sudo bash
```
### 自更新（通过应用内部）
Admin panel → **Update** — 下载最新包，备份数据，通过 rsync 解压，重新安装依赖并重启服务。所有过程均通过 SSE 流式传输。
### 生产环境建议
- 在反向代理 (nginx, Caddy) 之后运行以处理 HTTPS 终止
- 无内置速率限制——请在代理层添加
- 立即更改默认的 `admin / admin` 凭据
- 在所有账号上启用 MFA
## 安全
- 有效期为 12 小时的 Session cookie
- 使用 bcrypt 哈希的密码
- 对 manager/admin 角色强制要求 TOTP MFA（5 分钟待处理验证过期时间）
- 管理员可被标记为 `mfa_exempt` (免 MFA)
- Auth middleware 在所有路径上运行，除了 login、health、static 和 auth API
- 首次启动时初始化默认管理员——**请立即更改密码**
## 许可证
有关许可证详细信息，请参阅代码仓库。
标签：AI摘要, Anthropic, APScheduler, AV绕过, CIS基准, Claude, CSV导入, CVE检测, Discord集成, ESC4, FastAPI, Feodo Tracker, HTTP/HTTPS抓包, IOC追踪, MalwareBazaar, MFA多因素认证, OpenPhish, OSINT, Python, RBAC, RSS监控, Slack集成, SSE, TOTP, Twilio短信, URLhaus, Webhook, Web监控, 力导向图, 多渠道通知, 失陷指标, 威胁情报, 威胁监控, 实时处理, 开发者工具, 开源情报收集, 态势感知, 情报共享, 情报平台, 数据备份, 无后门, 明网监控, 暗网情报, 网络安全, 自动化报告, 自托管, 角色权限控制, 逆向工具, 邮件通知, 隐私保护