Muskan-2504/Argus-IDS
GitHub: Muskan-2504/Argus-IDS
Argus 是一个自托管的实时入侵检测平台，通过多引擎分析日志数据并将其映射到 MITRE ATT&CK 框架以实现威胁可视化与告警分诊。
Stars: 0 | Forks: 0
# Argus — 入侵检测系统
Argus 是一个实时的入侵检测平台：它摄取真实的日志数据，通过多层检测引擎（特征规则 + 统计异常检测 + 机器学习）进行处理，将结果映射到 **MITRE ATT&CK** 框架，利用地理定位和威胁情报丰富源 IP 信息，并将评分后的警报流式传输到实时的分析师仪表板。
[](https://github.com/USERNAME/argus-ids/actions/workflows/ci.yml)
## 起源 — 这是一次从零开始的重建
Argus 最初是 **Muskan Gupta** 在第 3 学期完成的一个 **DBMS 实验室微型项目**（*“入侵检测系统”*，2024 年 10 月）。原版本在 [`docs/legacy/`](docs/legacy/) 中被原封不动地保留了下来，它只是一个学习原型：检测逻辑只是少量在浏览器 JavaScript 中硬编码的行数启发式规则，PHP/MySQL 后端实际上从未连接到前端，“身份验证”只是切换了一个 `
`，而且每个数据库查询都容易受到 SQL 注入的攻击。
**Argus 是一次彻底重建**，而不是补丁。它保留了原版的*意图* —— 检测常见的网络攻击、解释它们、将它们可视化 —— 并将其正确实现：一个连接的 pipeline、一个真正的检测引擎、默认安全的代码，以及原报告只是声称过的功能。有关完整的前后对比，请参阅 [`docs/legacy/README.md`](docs/legacy/README.md)。
## 架构
```
flowchart LR
subgraph Sources
A1[auth.log]
A2[nginx / apache]
A3[suricata json]
A4[attack simulator]
end
subgraph Engine["Detection Engine (FastAPI / Python)"]
I[Ingest] --> N[Normalize] --> E[Enrich
GeoIP + AbuseIPDB] E --> D[Detect
Rules + Stats + ML] D --> S[Score + MITRE map] S --> P[(PostgreSQL)] S --> R[(Redis pub/sub)] end subgraph Dashboard["Dashboard (React / TS)"] F1[Live alert feed] F2[Time-series + D3 map] F3[Triage: ack / resolve / FP] end Sources --> I R -->|WebSocket| Dashboard P --> Dashboard ``` ## 技术栈 | 层级 | 技术 | |---|---| | 检测 + API | Python 3.12+、FastAPI、Pydantic v2 | | 数据库 | PostgreSQL 16、SQLAlchemy 2.0、Alembic | | 缓存 / 实时 | Redis（速率限制窗口、警报发布/订阅） | | 认证 | OAuth2 + JWT、Argon2id 哈希、RBAC | | 机器学习 / 统计 | scikit-learn (Isolation Forest)、滑动窗口 + z-score | | 检测内容 | Sigma 风格的 YAML 规则、MITRE ATT&CK 映射 | | 信息丰富 | MaxMind GeoLite2、AbuseIPDB | | 前端 | React、TypeScript、Vite、Tailwind、Chart.js + D3 | | 质量 / DevOps | pytest、ruff、mypy、Docker、GitHub Actions | ## 快速开始 ``` # 启动 Postgres + Redis + API cp .env.example .env docker compose up --build # API: http://localhost:8000 # Swagger UI: http://localhost:8000/docs # Health: http://localhost:8000/api/health ``` 本地后端开发（不使用 Docker）： ``` cd backend python -m venv .venv && .venv\Scripts\activate # Windows pip install -e ".[dev]" alembic upgrade head # create the schema python -m app.cli create-admin \ # seed the first admin --username admin --email admin@argus.local --password 'change-me-123' uvicorn app.main:app --reload pytest -q ``` ## API (M1) 交互式文档位于 `/docs`。身份验证采用 OAuth2 密码流程 → JWT bearer token；访问权限受角色层级 **viewer < analyst < admin** 控制。 | 方法 | 路径 | 角色 | 用途 | |---|---|---|---| | `POST` | `/api/auth/register` | 公开 | 自助注册（始终创建为 `viewer`） | | `POST` | `/api/auth/login` | 公开 | 交换凭证以获取 JWT | | `GET` | `/api/auth/me` | 任意 | 当前用户资料 | | `GET`/`POST` | `/api/users` | admin | 列出/创建具有明确角色的用户 | | `PATCH` | `/api/users/{id}/role` | admin | 更改其他用户的角色 | | `POST` | `/api/ingest` | analyst | 摄取 JSON 批量的原始日志行 | | `POST` | `/api/ingest/file` | analyst | 摄取上传的日志文件 | 摄取功能会将真实的日志格式 —— Linux `auth.log`、nginx/Apache 组合访问日志以及 Suricata EVE JSON —— 解析为标准化且已建立索引的事件。 密码使用 Argon2id 进行哈希处理，且每个查询都是参数化的：[原项目](docs/legacy/) 中的 SQL 注入和伪造身份验证已不复存在。 ## 仓库布局 ``` argus-ids/ ├── backend/ FastAPI app, detection engine, models, tests │ ├── app/ │ │ ├── api/ routes (auth, users, ingest) + deps (auth/RBAC) │ │ ├── core/ config, security (JWT/Argon2) │ │ ├── crud/ data-access layer (parameterized queries) │ │ ├── db/ SQLAlchemy engine, session, portable types │ │ ├── models/ database models │ │ ├── schemas/ Pydantic request/response models │ │ ├── detection/ rule engine + anomaly + MITRE (rules/*.yml, M2+) │ │ ├── ingest/ parsers (auth.log, nginx, suricata) + service │ │ ├── enrich/ GeoIP + threat-intel (M4) │ │ └── cli.py admin bootstrap (create-admin) │ ├── alembic/ database migrations │ └── tests/ pytest suite (SQLite-backed) ├── frontend/ React + TS dashboard (built at M3) ├── simulator/ attack-replay harness (built at M6) ├── data/samples/ sample logs (auth / nginx / suricata) ├── docs/legacy/ the original college project, preserved └── .github/workflows/ CI (lint, type-check, migrate, test) ``` ## 路线图 - [x] **M0 — 脚手架：** 仓库、Docker、CI、数据模型、可运行的 API - [x] **M1 — 安全核心：** 摄取 API + 解析器、Argon2 认证 + RBAC、全面参数化、迁移 - [ ] **M2 — 规则引擎：** Sigma 风格的 YAML 规则（DoS / 暴力破解 / 端口扫描 / SQLi）、持久化警报 - [ ] **M3 — 仪表板：** React UI、警报列表、图表、分诊工作流 - [ ] **M4 — 实时 + 信息丰富：** WebSocket 推送、GeoIP / AbuseIPDB、D3 攻击地图 - [ ] **M5 — 智能：** 统计 + 机器学习异常检测、MITRE ATT&CK 映射、严重性评分 - [ ] **M6 — 演示完善：** 攻击重放工具、误报调优循环、演示 GIF ## 许可证 MIT © 2026 Muskan Gupta — 详见 [LICENSE](LICENSE)。
GeoIP + AbuseIPDB] E --> D[Detect
Rules + Stats + ML] D --> S[Score + MITRE map] S --> P[(PostgreSQL)] S --> R[(Redis pub/sub)] end subgraph Dashboard["Dashboard (React / TS)"] F1[Live alert feed] F2[Time-series + D3 map] F3[Triage: ack / resolve / FP] end Sources --> I R -->|WebSocket| Dashboard P --> Dashboard ``` ## 技术栈 | 层级 | 技术 | |---|---| | 检测 + API | Python 3.12+、FastAPI、Pydantic v2 | | 数据库 | PostgreSQL 16、SQLAlchemy 2.0、Alembic | | 缓存 / 实时 | Redis（速率限制窗口、警报发布/订阅） | | 认证 | OAuth2 + JWT、Argon2id 哈希、RBAC | | 机器学习 / 统计 | scikit-learn (Isolation Forest)、滑动窗口 + z-score | | 检测内容 | Sigma 风格的 YAML 规则、MITRE ATT&CK 映射 | | 信息丰富 | MaxMind GeoLite2、AbuseIPDB | | 前端 | React、TypeScript、Vite、Tailwind、Chart.js + D3 | | 质量 / DevOps | pytest、ruff、mypy、Docker、GitHub Actions | ## 快速开始 ``` # 启动 Postgres + Redis + API cp .env.example .env docker compose up --build # API: http://localhost:8000 # Swagger UI: http://localhost:8000/docs # Health: http://localhost:8000/api/health ``` 本地后端开发（不使用 Docker）： ``` cd backend python -m venv .venv && .venv\Scripts\activate # Windows pip install -e ".[dev]" alembic upgrade head # create the schema python -m app.cli create-admin \ # seed the first admin --username admin --email admin@argus.local --password 'change-me-123' uvicorn app.main:app --reload pytest -q ``` ## API (M1) 交互式文档位于 `/docs`。身份验证采用 OAuth2 密码流程 → JWT bearer token；访问权限受角色层级 **viewer < analyst < admin** 控制。 | 方法 | 路径 | 角色 | 用途 | |---|---|---|---| | `POST` | `/api/auth/register` | 公开 | 自助注册（始终创建为 `viewer`） | | `POST` | `/api/auth/login` | 公开 | 交换凭证以获取 JWT | | `GET` | `/api/auth/me` | 任意 | 当前用户资料 | | `GET`/`POST` | `/api/users` | admin | 列出/创建具有明确角色的用户 | | `PATCH` | `/api/users/{id}/role` | admin | 更改其他用户的角色 | | `POST` | `/api/ingest` | analyst | 摄取 JSON 批量的原始日志行 | | `POST` | `/api/ingest/file` | analyst | 摄取上传的日志文件 | 摄取功能会将真实的日志格式 —— Linux `auth.log`、nginx/Apache 组合访问日志以及 Suricata EVE JSON —— 解析为标准化且已建立索引的事件。 密码使用 Argon2id 进行哈希处理，且每个查询都是参数化的：[原项目](docs/legacy/) 中的 SQL 注入和伪造身份验证已不复存在。 ## 仓库布局 ``` argus-ids/ ├── backend/ FastAPI app, detection engine, models, tests │ ├── app/ │ │ ├── api/ routes (auth, users, ingest) + deps (auth/RBAC) │ │ ├── core/ config, security (JWT/Argon2) │ │ ├── crud/ data-access layer (parameterized queries) │ │ ├── db/ SQLAlchemy engine, session, portable types │ │ ├── models/ database models │ │ ├── schemas/ Pydantic request/response models │ │ ├── detection/ rule engine + anomaly + MITRE (rules/*.yml, M2+) │ │ ├── ingest/ parsers (auth.log, nginx, suricata) + service │ │ ├── enrich/ GeoIP + threat-intel (M4) │ │ └── cli.py admin bootstrap (create-admin) │ ├── alembic/ database migrations │ └── tests/ pytest suite (SQLite-backed) ├── frontend/ React + TS dashboard (built at M3) ├── simulator/ attack-replay harness (built at M6) ├── data/samples/ sample logs (auth / nginx / suricata) ├── docs/legacy/ the original college project, preserved └── .github/workflows/ CI (lint, type-check, migrate, test) ``` ## 路线图 - [x] **M0 — 脚手架：** 仓库、Docker、CI、数据模型、可运行的 API - [x] **M1 — 安全核心：** 摄取 API + 解析器、Argon2 认证 + RBAC、全面参数化、迁移 - [ ] **M2 — 规则引擎：** Sigma 风格的 YAML 规则（DoS / 暴力破解 / 端口扫描 / SQLi）、持久化警报 - [ ] **M3 — 仪表板：** React UI、警报列表、图表、分诊工作流 - [ ] **M4 — 实时 + 信息丰富：** WebSocket 推送、GeoIP / AbuseIPDB、D3 攻击地图 - [ ] **M5 — 智能：** 统计 + 机器学习异常检测、MITRE ATT&CK 映射、严重性评分 - [ ] **M6 — 演示完善：** 攻击重放工具、误报调优循环、演示 GIF ## 许可证 MIT © 2026 Muskan Gupta — 详见 [LICENSE](LICENSE)。
标签：Apex, AV绕过, FastAPI, IP 地址批量处理, React, Syscalls, 入侵检测系统, 威胁情报, 安全数据湖, 安全运营, 开发者工具, 扫描框架, 搜索引擎查询, 机器学习, 测试用例, 请求拦截, 逆向工具