# SentinelBlue

**Repository Path**: uniomo/SentinelBlue

## Basic Information

- **Project Name**: SentinelBlue
- **Description**: SentinelBlue · 蓝鲸之眼
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SentinelBlue
## 蓝方实时威胁监测与自动化响应平台

> 当警报响起，蓝方最宝贵的不是工具，而是**时间线**。
> SentinelBlue 让每一次进程生灭、每一条异常外连、每一次阻断动作，都留下可回溯、可取证、可复盘的电子痕迹——并在命中规则的那一刻，给出可执行、可确认的处置方案。

---

### 一、它解决什么问题

红方的攻击是**一条有时间顺序的链路**：投递 → 落地 → 执行 → 反弹 → 驻留。
传统防守最大的痛点是"看见了却没记全、记全了却来不及断"。
SentinelBlue 把这件事做成一条**实时闭环**：

```
监测(monitor) → 记录(recorder) → 分析(analyzer) → 阻断(responder) → 报告(report)
      ↑                                                              │
      └────────────────────── 全程留痕 / 可溯源 ─────────────────────┘
```

- **记录**：SQLite 结构化事件库 + JSONL 导出，所有行为可追溯；
- **分析**：规则引擎对进程名、命令行、高危端口、资源占用、文件完整性做实时研判；
- **阻断**：对命中项自动生成处置方案（kill / 封 IP / 隔离文件），含三种安全模式；
- **实时**：逐 tick 打印执行流，新进程、异常连接即时上屏；
- **报告**：运行结束一键生成 Markdown 战报 + HTML 态势图。

---

### 二、架构与目录结构

```
sentinelblue/
├── config.yaml          # 作战参数（端口/进程名/阈值/响应模式/基线/告警）
├── requirements.txt     # 依赖（psutil、PyYAML）
├── main.py              # 主程序：run / baseline-build / rollback 三个子命令
├── core/
│   ├── __init__.py      # 包声明
│   ├── recorder.py      # 审计记录（SQLite 全程留痕 + 回滚快照表）
│   ├── monitor.py       # 监测引擎（进程/网络/文件快照，含学习期基线）
│   ├── rules.py         # 检测规则引擎 + Finding 数据模型
│   ├── analyzer.py      # 分析引擎（攻击链回溯、完整性校验、进程生灭）
│   ├── responder.py     # 响应阻断（kill/封IP/隔离文件 + 回滚）
│   ├── report.py        # 报告生成（Markdown / HTML）
│   ├── baseline.py      # 安全基线哈希（可执行文件完整性校验）
│   └── notifier.py      # 邮件 / Webhook 实时告警推送
└── logs/                # 运行期生成：audit.db、baseline.json、报告、隔离区
```

| 模块 | 职责 | 关键类 / 函数 |
|------|------|----------------|
| `monitor.Monitor` | 每个 tick 采集进程、网络连接、关键目录文件事件；首个快照登记"学习期基线进程名" | `snapshot()`、`_collect_processes()`、`_collect_connections()`、`_collect_fs()` |
| `rules.RuleEngine` | 按规则产出结构化 `Finding`（含严重等级与处置建议） | `evaluate()`、`Finding` |
| `analyzer.Analyzer` | 组装上下文、判新进程/消亡进程、补全攻击链与完整性信息、广度扫描篡改 | `analyze()`、`_attack_chain()`、`_enrich_findings()`、`_integrity_findings()` |
| `responder.Responder` | 把处置建议落地为 kill / 封 IP / 隔离文件，阻断前自动快照、支持回滚 | `handle()`、`_kill()`、`_block_ip()`、`_quarantine()`、`rollback()` |
| `recorder.EventStore` | 事件与回滚记录的写入/查询/导出 | `record()`、`query()`、`save_rollback()`、`get_rollback()`、`list_rollbacks()`、`export_jsonl()` |
| `baseline.BaselineManager` | 对系统二进制建立 SHA-256 基线并做 mtime 优先的篡改校验 | `build()`、`load()`、`check()` |
| `notifier.Notifier` | 命中发现的 SMTP 邮件 / Webhook 推送，含等级过滤与节流 | `should_alert()`、`alert_finding()` |

---

### 三、安装与快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 建立完整性基线（可选，首次 run 若缺失且 auto_build=true 会自动建立）
sudo python main.py -c config.yaml baseline-build

# 3. 试运行（dry_run：只记录，不真正执行阻断；跑 60 秒后出报告）
python main.py -c config.yaml run --mode dry_run -d 60 --report logs/ops

# 4. 正式值守（需 root 才能 kill 他人进程 / 写 iptables）
sudo python main.py -c config.yaml
```

> ⚠️ 阻断动作（终止进程、iptables 封 IP）需要 **root 权限**；
> 没有 root 时平台会自动降级（仅能看到自身进程连接），不会崩溃。

---

### 四、命令参考

主程序 `main.py` 的可用子命令如下（`-c/--config` 为全局参数，默认 `config.yaml`）：

| 命令 | 参数 | 说明 |
|------|------|------|
| `run`（默认） | `-d/--duration 秒`（0=持续，直到 Ctrl+C）<br>`-m/--mode dry_run\|manual\|auto`（覆盖配置中的 mode）<br>`--report 路径前缀`（运行结束生成 `.md` 与 `.html`） | 启动实时监测闭环；不写子命令时默认进入 `run` |
| `baseline-build` | 无 | 立即建立/重建可执行文件完整性基线 |
| `rollback` | `<id>`（回滚记录自增 id，整数） | 按回滚快照逆向恢复一次处置（撤销封禁 / 移回文件 / 重启进程） |

```bash
# 误杀后回滚（示例 id=7）
sudo python main.py -c config.yaml rollback 7
```

---

### 五、三种响应模式

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| `dry_run` | 仅记录、打印动作，不执行任何阻断 | 试运行、规则调优、教学演示 |
| `manual` | 每个阻断动作交互确认（`y/N`） | 正式值守、人工把关（默认） |
| `auto` | 自动执行；当 `require_confirm: true` 时关键动作仍需确认 | 高置信规则下的无人值守 |

所有动作无论成功/失败/跳过/拒绝，都会写入审计库 —— **哪怕阻断失败，也有据可查**。
每一条成功执行的阻断动作都会带上 `rollback_id`，可在报告"可回滚快照"章节查看。

---

### 六、四大扩展能力（已内置）

1. **进程树关联（攻击链回溯）**：每个进程快照采集父进程 PID（`ppid`），命中发现时 `analyzer._attack_chain()` 自动从可疑进程沿 `ppid` 向上回溯到根进程（如 `systemd → sshd → bash → xmrig`）后反向呈现，在告警与报告中输出完整攻击链。
2. **安全基线哈希（完整性校验）**：对 `/bin`、`/sbin`、`/usr/bin`、`/usr/sbin` 等可信二进制目录建立 SHA-256 基线（`baseline-build` 或 `auto_build` 自动建立），运行期对进程可执行文件做篡改校验；基线内文件被替换/删除时由 `_integrity_findings()` 产出 `INTEGRITY-TAMPER`（高危）告警。`check()` 先比 `mtime`、仅在变化时重新哈希，运行期开销极低。
3. **邮件 / Webhook 实时告警推送**：命中发现即时经 SMTP 邮件或 Webhook（企业微信 / 钉钉 / Slack / 自研平台，POST JSON）推送；支持 `min_severity` 最小严重等级过滤与 `min_interval` 同规则节流，避免告警风暴；推送全部走标准库（`smtplib` / `urllib`），失败静默降级，绝不阻断主链路；`dry_run` 试运行默认不推送（可由 `alert_in_dry_run` 开启）。
4. **回滚式处置（误杀可恢复）**：每次阻断（kill / 封 IP / 隔离文件）真正改系统前自动把原状态快照入库（`recorder.rollbacks` 表，仅非 `dry_run` 模式留痕）；误杀后执行 `rollback <id>` 即可撤销 iptables 封禁、移回被隔离文件、或按原命令行重启进程。

---

### 七、检测规则一览

规则引擎（`core/rules.py`）内置以下规则，命中即产出 `Finding` 并驱动响应：

| 规则 ID | 严重级 | 类别 | 触发条件 |
|---------|--------|------|----------|
| `PROC-SUSPECT-NAME` | high | process | 进程名命中 `suspicious_names`（xmrig/miner/hydra/sqlmap…） |
| `PROC-SUSPECT-CMD` | high | cmdline | 命令行命中 `suspicious_cmd_keywords`（`/dev/tcp/`、`bash -i`、`nc -e`…） |
| `NET-SUSPECT-PORT` | high | network | 到 `suspicious_ports`（4444/1337/31337…）的 **已建立** 连接 |
| `NET-CONN-FLOOD` | medium | network | 单进程外连数超过 `max_connections`（默认 200） |
| `RES-CPU` | medium | resource | 单进程 CPU 占用 ≥ `cpu_alert_pct`（默认 85%，挖矿特征） |
| `RES-MEM` | low | resource | 单进程内存占用 ≥ `mem_alert_pct`（默认 80%） |
| `INTEGRITY-TAMPER` | high | integrity | 基线内系统二进制哈希变化或文件消失（需开启 `baseline`） |

#### 如何扩展检测能力

新增一条规则，只需在 `core/rules.py` 里加一个 `_check_xxx` 方法，并在 `evaluate()` 中登记一行，平台其余部分无需改动（开闭原则）：

```python
def _check_my_rule(self, ctx):
    out = []
    for pid, p in ctx["processes"].items():
        if "evil" in (p.get("name") or "").lower():
            out.append(Finding(
                rule_id="PROC-EVIL",
                title=f"命中自定义规则：{p.get('name')}",
                severity="high", category="process", target=str(pid),
                evidence={"name": p.get("name")},
                recommendation=f"终止进程 PID={pid}",
            ))
    return out
```

---

### 八、配置说明（`config.yaml`）

| 段 | 字段 | 默认值 | 说明 |
|----|------|--------|------|
| `monitor` | `interval` | 2 | 轮询间隔（秒） |
| | `enable_process` / `enable_network` / `enable_filesystem` | true | 三类采集开关 |
| `fs_watch_paths` | — | `/tmp /etc /home /var/www` | 重点盯防目录，文件创建/变更即记录 |
| `rules` | `cpu_alert_pct` / `mem_alert_pct` | 85 / 80 | 资源告警阈值 |
| | `max_connections` | 200 | 单进程外连数阈值 |
| | `suspicious_ports` | 见文件 | 高危 / 反弹 Shell / 矿池 / C2 端口 |
| | `suspicious_names` | 见文件 | 可疑进程名关键字 |
| | `suspicious_cmd_keywords` | 见文件 | 命令行可疑特征 |
| `response` | `mode` | manual | `dry_run`/`manual`/`auto` |
| | `kill_process` / `firewall_block` / `quarantine_file` | true | 三类动作开关 |
| | `require_confirm` | true | 自动模式下关键操作是否仍需确认 |
| `baseline` | `enabled` | true | 启用完整性校验 |
| | `paths` | `/bin /sbin /usr/bin /usr/sbin` | 参与校验的可信二进制目录 |
| | `excludes` | `*.pyc` | 跳过（fnmatch 通配） |
| | `algo` | sha256 | 哈希算法 |
| | `auto_build` | true | 首次运行且基线缺失时自动建立 |
| | `file` | `baseline.json` | 基线文件（相对 `log.dir` 或绝对路径） |
| `alerting` | `enabled` | false | 告警总开关 |
| | `min_severity` | medium | 仅推送 ≥ 该等级（info/low/medium/high/critical） |
| | `min_interval` | 60 | 同一 `rule_id` 最小推送间隔（秒） |
| | `alert_in_dry_run` | false | `dry_run` 试运行是否也推送 |
| | `email.*` / `webhook.*` | 见文件 | SMTP 与 Webhook 凭据（默认关闭） |
| `log` | `dir` / `level` | `logs` / `INFO` | 审计库、报告、隔离文件存放目录与日志级别 |

---

### 九、安全机制（避免误杀与系统瘫痪）

代码内置多重防护，确保阻断动作本身不会反噬系统：

- **保护关键进程**：`_kill` 拒绝终止 PID 0/1（调度器/init）、本进程及其父进程，避免系统或自身崩溃。
- **拒绝隔离系统二进制**：`_quarantine` 拒绝移动 `/bin`、`/sbin`、`/usr/bin`、`/usr/sbin`、`/lib`、`/lib64`、`/usr/lib`、`/usr/libexec`、`/usr/local/bin` 下的文件，避免误隔离导致系统瘫痪。
- **IP 合法性校验**：`_block_ip` 先用 `ipaddress.ip_address()` 校验格式，非法 IP 不下发 iptables 规则。
- **非 root 自动降级**：无 root 时 `psutil.net_connections()` 抛 `AccessDenied` 会被捕获，仅看到自身进程连接，平台不崩溃。
- **回滚兜底**：破坏性动作执行前先快照，误杀可即时恢复（见第六·4 节）。

---

### 十、合规与安全声明

本工具**仅面向蓝方 / 防守方**，用于授权环境下的资产监测、入侵检测与应急处置。
使用者须确保其对该系统拥有合法授权。阻断动作具有破坏性（终止进程、封禁 IP），
请在生产环境前先用 `dry_run` 验证规则，并妥善保管 `logs/audit.db` 审计记录与 `logs/baseline.json` 基线。