EASS-HIT-PART-A-2026-CLASS-IX/Cygnal

# 🛡️ Cygnal — 网络威胁情报 API [](https://fastapi.tiangolo.com) [](https://www.python.org) [](https://www.docker.com) [](https://github.com/astral-sh/uv) **Cygnal** 是一个用于管理和共享网络威胁指标 (IOCs) 的集中式平台。 作为 **EASS-HIT 2026** 课程的一部分构建，它使安全分析师能够追踪恶意的 IP、域名、URL、文件哈希和电子邮件地址——并提供置信度评分、标签和威胁行为者归因功能。 ## 🌟 核心功能 - **🔍 IOC 管理** – 针对 5 种类型的威胁指标提供完整的 CRUD 操作：IP、域名、URL、哈希、电子邮件 - **📊 置信度评分** – 将指标可靠性评定为 0 到 100 的分数 - **🏷️ 标签系统** – 使用诸如 `ransomware`、`APT29`、`phishing` 等标签对指标进行标记 - **🎯 威胁行为者归因** – 将指标与已知的威胁行为者关联 - **⏱️ 时间线追踪** – 为每个指标提供 `created_at` 时间戳 - **🧪 自动化测试** – 完整的 pytest 测试套件，测试之间具有隔离状态 - **🐳 Docker 就绪** – 在本地和容器中运行表现完全一致 - **📊 Streamlit 仪表板** – 用于管理和浏览 IOC 的可视化界面 - **📥 CSV 导出** – 一键导出所有指标 ## 🚀 API 参考 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/health` | 健康检查 | | `GET` | `/indicators` | 列出所有指标 | | `POST` | `/indicators` | 创建新指标 | | `GET` | `/indicators/{id}` | 通过 ID 获取指标 | | `DELETE` | `/indicators/{id}` | 删除指标 | ## 🏗️ 项目结构 ``` Cygnal/ ├── backend/ │ ├── init.py # Package marker │ ├── config.py # Environment settings │ ├── database.py # SQLite + SQLModel engine │ ├── models.py # SQLModel schemas (Indicator, IndicatorCreate) │ ├── repository.py # Database operations │ └── main.py # FastAPI routes & app entrypoint ├── frontend/ │ ├── init.py # Package marker │ ├── client.py # Typed HTTP client (httpx) │ └── dashboard.py # Streamlit dashboard ├── tests/ │ ├── init.py │ ├── conftest.py # Pytest fixtures (client, in-memory DB) │ ├── test_main.py # Backend API test suite │ └── test_frontend.py # Frontend client test suite ├── .env.example # Environment variable template ├── .gitignore ├── .python-version ├── Dockerfile ├── docker-compose.yml ├── examples.http # VS Code REST Client playground ├── seed.py # Sample data seeder ├── pyproject.toml ├── uv.lock └── README.md ``` ## 🛠️ 技术栈 | 层级 | 技术 | |-------|-----------| | 框架 | FastAPI | | 校验 | Pydantic v2 + SQLModel | | 存储 | SQLite | | 前端 | Streamlit | | HTTP 客户端 | httpx | | 包管理器 | uv | | 测试 | pytest + TestClient | | 容器 | Docker | ## 🚦 快速开始 ### 1. 安装 uv (如果尚未安装) ``` curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 2. 同步环境 ``` uv sync ``` ### 3. 在本地运行 API ``` uv run uvicorn backend.main:app --reload ``` API 访问地址：`http://127.0.0.1:8000` 交互式文档 (Swagger)：`http://127.0.0.1:8000/docs` ### 4. 填充示例数据 (可选) 确保 API 正在运行，然后在另一个终端中执行： ``` uv run python seed.py ``` ## 🖥️ 同时运行 API + 仪表板 打开两个单独的终端： **终端 1 – 启动 API：** ``` uv run uvicorn backend.main:app --reload ``` **终端 2 – 启动 Streamlit 仪表板：** ``` uv run streamlit run frontend/dashboard.py ``` 然后在浏览器中打开： - API 文档 (Swagger)：`http://127.0.0.1:8000/docs` - Cygnal 仪表板：`http://localhost:8501` ## 🧪 运行测试 ``` uv run pytest ``` ## 🐳 使用 Docker 运行 ``` # 构建 docker build -t cygnal-app . # 运行 docker run -p 8000:8000 cygnal-app ``` ## 🤖 AI 辅助 本项目是在 **Claude (Anthropic)** 的辅助下开发的。 AI 工具的用途包括： - 设计项目结构和数据模型 - 实现基于 SQLite 持久化的 SQLModel 架构 - 构建 Streamlit 仪表板和类型化的 HTTP 客户端 - 编写基于 fixture 实现 DB 隔离的 pytest 测试套件 - 生成和格式化技术文档 *所有 AI 生成的代码在提交前均已在本地进行了审查、理解和验证。* *由 Agneta Gavrielov 为 EASS-HIT 2026 — 高级软件解决方案工程 创建*

标签：AMSI绕过, AV绕过, DAST, Docker, EASS-HIT, FastAPI, IOC管理, IP追踪, Kubernetes, PB级数据处理, pytest, Python, REST API, Streamlit, URL分析, uv, 威胁指标, 威胁检测, 威胁行为者归属, 安全规则引擎, 安全运维, 安全防御评估, 密码管理, 恶意域名, 恶意软件分析, 恶意邮箱, 情报共享, 文件哈希, 无后门, 标签系统, 网络威胁情报, 网络安全, 网络测绘, 置信度评分, 访问控制, 请求拦截, 运行时操纵, 逆向工具, 隐私保护