rajarshidattapy/headsup
GitHub: rajarshidattapy/headsup
HeadsUp 是一款终端原生的 AI 威胁记忆引擎，通过长期记忆和实时威胁情报持续监控设备安全并在攻击执行前进行预测。
Stars: 0 | Forks: 0
# HeadsUp
&& cd headsup
pip install -e . # or: pip install psutil rich watchdog openai requests send2trash
cp .env.example .env # optional — add API keys if you have them (see Configuration)
headsup # live threat-memory dashboard (Rich TUI)
```
**HeadsUp 支持完全离线运行**，具备平滑降级功能 —— 无需 API 密钥：
| 功能 | 有密钥 | 无密钥 |
|---|---|---|
| 威胁记忆 (**HydraDB**) | HydraDB 云端 (`HYDRADB_API_KEY` + `HYDRADB_TENANT_ID`)；可选通过 `HYDRA_URL` 使用 Postgres | 位于 `~/.headsup/headsup.db` 的本地 SQLite |
| AI 推理 (**Gemma/Cerebras**) | Cerebras 上的 Gemma 4 (`CEREBRAS_API_KEY`) → OpenAI 降级 (`OPENAI_API_KEY`) | 确定性启发式算法 |
| 威胁情报 (**Anakin**) | 实时 AI 网络搜索 (`ANAKIN_API_KEY`) | 内置样例活动推送 |
| 警报 (**Telegram**) | 推送警报 (`TELEGRAM_BOT_TOKEN`) | 仅限界面显示 |
横幅会反映当前激活的状态，例如
`HydraDB 云端 + SQLite · Gemma 4 · Cerebras gemma-3-12b-it · Anakin 实时`。
## 命令行界面
```
headsup # live threat-memory dashboard (Rich TUI)
headsup --copilot # natural-language AI security copilot (REPL)
headsup --resolve # dashboard with reverse-DNS on remote IPs
headsup --auto # auto-execute remediation on CRITICAL verdicts
headsup --once # render one snapshot and exit (CI / smoke test)
headsup timeline [N] # print the recent memory timeline and exit
headsup intel # ingest + list the latest threat intelligence
headsup reset [-y] # clear local HydraDB memory (asks to confirm; -y skips)
```
## 终端仪表板
```
┌──────────────────── ◈ HEADSUP SECURITY CENTER ────────────────────┐
│ ACTIVE CONNS 193 THREAT SCORE HEALTHY 98/100 │
│ SUSPICIOUS PROC 0 VPN ✗ NONE │
│ OPEN INCIDENTS 0 HOST LAPTOP-… │
│ NEW INTEL (24h) 5 PUBLIC IP … │
└───────────────────────────────────────────────────────────────────┘
ACTIVE CONNECTIONS · risk · flags (★ new ⚠ suspicious C/S AI verdict)
⏱ THREAT TIMELINE 🌐 THREAT INTEL FEED
⚡ AI THREAT INTELLIGENCE (live verdicts · 🔮 prediction · 🌐 web intel)
● AI COPILOT (press T to chat)
```
| 面板 | 显示内容 |
|---|---|
| **安全中心** | 活动连接、可疑进程、未解决的事件、新情报、0–100 的**威胁评分** (健康 / 警惕 / 中等 / 严重)、VPN/主机/IP |
| **活动连接** | 带有风险、GeoIP 国家、端口标签、进程和标志的实时连接：`★` 新增，`⚠` 可疑路径，`C`/`S` AI 判定 (严重/可疑) |
| **威胁时间线** | 观察到的每个事件（进程 / 网络 / 注册表 / 启动项 / 下载 / 文件）的最新优先流 |
| **威胁情报推送** | 来自 Anakin（或内置推送）的最新活动 + 当您的机器匹配到活动时显示的“类似于 X (NN%)”横幅 |
| **AI 威胁情报** | 每个连接的实时判定、当前行为链的**🔮 预测**、关于匹配活动的**🌐 实时网络情报**，以及修复日志 |
| **AI Copilot** | 自然语言聊天 — 按 `T` 键打开 |
**键盘快捷键：** `T` 打开 copilot · `j`/`k` 或 `↑`/`↓` 滚动连接 · 在聊天中：`Enter` 发送，`Esc` 取消，`↑`/`↓` 滚动历史记录 · `Ctrl+C` 退出。
## AI Copilot
在仪表板中按 `T` 键，或运行 `headsup --copilot`。提出简单的英文问题或发出
指令 —— 答案将基于实时的机器状态**加上**您的 HydraDB 记忆。
| 提问 / 指令 | 功能说明 |
|---|---|
| `what changed today?` | 总结今天的活动并标记任何风险 |
| `have I seen 45.33.32.156 before?` / `seen ` | 将 IP/进程与长期记忆进行关联 |
| `predict` / `what happens next?` | 预测当前行为链的下一阶段攻击 |
| `search latest ransomware` / `web ` | 带引用来源的 **Anakin AI 网络搜索** |
| `intel` | 列出最新摄取的威胁情报 |
| `show foreign` / `show high` | 列出当前的境外 / 高风险连接 |
| `is this process dangerous?` (自由文本) | Gemma 基于上下文 + 记忆提供的解释 |
| `kill ` · `suspend ` · `block ` · `close port ` | 修复操作 |
| `quarantine ` · `inspect ` | 将文件移动到回收站 / 计算哈希值并检查它 |
## 工作原理
```
┌─────────────────────────────┐
│ Rich Terminal UI │ panels · copilot · alerts
└──────────────┬──────────────┘
▼
┌─────────────────────────────┐
│ Monitoring Engine │ psutil + watchdog + winreg (1s poll)
└──────────────┬──────────────┘
▼
┌─────────────────────────────┐ ┌────────────────────┐
│ HydraDB │◀────▶│ HydraDB Cloud │ long-term,
│ local SQLite / Postgres │ │ (usecortex) │ cross-session
└──────────────┬──────────────┘ └────────────────────┘ memory
▼
┌─────────────────────────────┐
│ Gemma 4 (Cerebras) │ explain · correlate · predict · summarize
└──────────────┬──────────────┘
▼
┌─────────────────────────────┐ Internet threat sources
│ Predictions & Explanations │◀──── Anakin AI web search ──┐
└─────────────────────────────┘ │
▲ ▼
└──────────── matched campaign ◀──── threat_intelligence
```
**预测流程** —— 当检测到相关的可疑活动时：
```
Downloaded executable
↓
New registry / startup entry → HydraDB stores every step
↓
Foreign network connection → correlate with machine history
↓
Anakin matches a malware campaign ──────► "resembles Lumma Stealer (83%)"
↓
Gemma reasons over the evidence ──────► opens an Incident + Prediction:
• Persistence likely
• Browser credential theft likely
• Data exfiltration possible
↓
Anakin web search on the campaign ──────► fresh, cited intel attached to the
incident (and pushed to Telegram)
```
## 监控引擎
1 秒轮询加上事件驱动的文件监视器，会规范化每一次观察，评估其风险，
并将其写入 HydraDB。
| 来源 | 详情 |
|---|---|
| **进程** | 新执行项 — 名称 / pid / 父进程 / 路径；标记临时/下载路径中的二进制文件 |
| **网络** | 出站/监听连接、GeoIP 国家、反向 DNS 域名、风险评估 |
| **启动项** | Windows 启动文件夹更改 |
| **注册表** | `HKCU/HKLM …\Run` 键值差异 (持久化) |
| **下载** | 下载文件夹中出现的新文件（可执行文件会被标记） |
| **文件** | 创建/移动的可执行文件和脚本（通过 `watchdog`） |
## HydraDB — 威胁记忆
HydraDB 是一个**过目不忘**的层。它在两个协同的层级中运行：
* **本地存储** — 零配置的 **SQLite**，位于 `~/.headsup/headsup.db`（或通过
`HYDRA_URL` 使用 **Postgres**）。支持实时仪表板的快速查询（时间线、健康分数、关联），并且
是离线降级方案。
* **HydraDB 云端** (usecortex) — 当设置了 `HYDRADB_API_KEY` + `HYDRADB_TENANT_ID` 时，每个事件
也会作为具有结构化元数据的持久化、**跨会话 / 跨机器**的语义记忆被摄取到 HydraDB 中，
AI Copilot 会从中进行回忆。
**数据表：** `process_events`, `network_events`, `system_events`, `threat_intelligence`,
`incidents`, `predictions`。
**云端元数据 schema：** 事件使用结构化的 `tenant_metadata`
（`event_type`, `severity`, `risk_score`, `process_name`, `remote_ip`, `threat_name`,
`incident_id`, `resolved`, …）进行标记，以便对回忆进行过滤。在
创建您的 HydraDB 租户时，将
[`hydradb.tenant-schema.json`](hydradb.tenant-schema.json) 粘贴到 **Metadata Schema** 字段中。
## Cerebras 上的 Gemma 4 — 推理引擎
分析师使用兼容 OpenAI 的 Cerebras endpoint（`CEREBRAS_API_KEY`，通过
`GEMMA_MODEL` 设置模型），依次降级到 OpenAI（`OPENAI_API_KEY`），最后降级到确定性的离线启发式算法。
它提供：
* **解释** — "为什么这个进程可疑？"
* **关联** — "我以前见过这种行为吗？"（查询 HydraDB）
* **预测** — "接下来可能会发生什么？"（下一阶段攻击链）
* **总结** — "今天我的电脑上发生了什么？"
* **建议** — 删除 / 隔离 / 监控 / 忽略 / 阻止
## Anakin — AI 网络搜索与新兴威胁情报
HeadsUp 通过两种方式使用 Anakin 驱动的 AI 网络搜索（`https://api.anakin.io/v1/search`）：
1. **威胁情报摄取** — 在网络上搜索最新的活动、CVE 和公告
(CISA, Microsoft, BleepingComputer, The Hacker News, …)，（通过 Gemma）将结果结构化
到 `threat_intelligence` schema 中，并将其存储在 HydraDB 中。
2. **Copilot 网络搜索** — `search ` 返回简明且**带引用**的答案。
本地行为会与已知活动进行匹配，以显示如下信息：
当事件触发匹配的活动时，HeadsUp 会自动运行针对该活动的后台 Anakin 网络
搜索，并将最新的、带引用的情报附加到预测中。
如果没有 `ANAKIN_API_KEY`，HeadsUp 将使用内置的样例推送
（[`core/data/sample_intel.json`](core/data/sample_intel.json)），以确保匹配功能始终可用。
## 配置
所有设置都是可选的，可从 `.env` 中读取（参见 [`.env.example`](.env.example)）。
| 变量 | 用途 |
|---|---|
| `CEREBRAS_API_KEY` | Cerebras 上的 Gemma 4 推理 (主要 AI) |
| `GEMMA_MODEL` | Cerebras 模型 ID (默认 `gemma-3-12b-it`) |
| `OPENAI_API_KEY` / `OPENAI_MODEL` | 降级推理提供程序 |
| `HYDRADB_API_KEY` / `HYDRADB_TENANT_ID` | HydraDB 云端长期记忆 |
| `HYDRADB_SUB_TENANT_ID` / `HYDRADB_API_BASE` | 可选的子租户 / 自托管 endpoint |
| `HYDRA_URL` | 为本地存储使用 Postgres 替代 SQLite |
| `ANAKIN_API_KEY` | Anakin AI 网络搜索 + 实时威胁情报 |
| `ANAKIN_API_URL` | Anakin endpoint (默认 `https://api.anakin.io/v1/search`) |
| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | 可选的推送警报 |
## 项目结构
```
headsup/
├─ headsup.py # CLI launcher (dashboard / copilot / timeline / intel / reset)
├─ hydradb.tenant-schema.json # HydraDB cloud metadata schema (paste at tenant creation)
├─ .env.example # configuration template
└─ core/
├─ headsup.py # Rich TUI, orchestration & predictive engine
├─ monitor.py # multi-source monitoring engine (1s poll + watchdog)
├─ hydradb.py # threat memory: SQLite/Postgres + HydraDB cloud
├─ analyst.py # Gemma-on-Cerebras reasoning (+ OpenAI / offline fallback)
├─ anakin.py # Anakin AI web search + threat-intel ingestion
├─ telegram_alert.py # optional Telegram alerts
└─ data/sample_intel.json # bundled threat-intel fallback feed
```
## 技术栈
| 层级 | 技术 |
|---|---|
| 语言 | Python 3.10+ |
| 终端 UI | [Rich](https://github.com/Textualize/rich) |
| 监控 | `psutil`, `watchdog`, `winreg` |
| AI 推理 | Cerebras Inference 上的 Gemma 4 (兼容 OpenAI 的客户端) |
| 记忆 | HydraDB 云端 + SQLite / Postgres |
| 威胁情报 | Anakin AI 网络搜索 |
| 警报 | Telegram (可选) |
## 隐私与安全
* 所有监控和本地记忆数据库都保留**在您的机器上**。云端功能（HydraDB、
Cerebras, Anakin, Telegram）仅在您提供相应的密钥时才会激活。
* `.env` 和 `~/.headsup/` 被配置为 git-ignore。`headsup reset` 可根据需要清除本地记忆。
* 修复操作（终止 / 阻止 / 隔离）需要管理员权限，并且仅
在您的指令下执行（或者在您选择加入 `--auto` 的 `CRITICAL` 判定时执行）。
## 路线图
* **SkillMake.xyz 安全技能** — 可插拔的 IOC 提取、恶意软件总结、风险评分
和报告生成，无需更改核心即可扩展 HeadsUp。
* 可选的 **FastAPI / REST** 界面，用于远程仪表板和集成。
* 更多的收集器（DNS 嗅探、计划任务、服务、浏览器扩展更改）。
* macOS / Linux 收集器功能对齐。
## 愿景
HeadsUp 开创了网络安全软件的新类别：
HeadsUp 不是在损害造成后才检测到恶意软件，而是能够**记忆、学习并预测**。
## 一句话推介
**HeadsUp 是一个终端原生的 AI 安全分析师，它能记住您的计算机所的一切，
从网络上不断涌现的网络威胁中学习，并在攻击完全执行之前对其进行预测。**
为您的计算机打造的终端原生 AI 威胁记忆引擎
了解您的机器，记住每一次异常，摄取实时威胁情报，并在攻击真正发生之前进行预测。
终端优先 · 记忆驱动 · AI 原生 · 可解释性
Python · Rich TUI · Cerebras 上的 Gemma 4 · HydraDB · Anakin web 搜索
标签：AI驱动, Petitpotam, 威胁情报, 开发者工具, 终端应用, 逆向工具, 靶机