kay-freeman/incident-signal

# Incident Signal [](https://github.com/kay-freeman/incident-signal/actions/workflows/tests.yml) 一个可配置的事件检测系统，能够识别支持工单中出现的新兴模式，区分相关活动的不同时间段，并分配可解释的严重级别。 ## 问题背景 支持团队通常通过单个客户工单收到服务问题的初步迹象。当这些工单被单独处理时，正在发展的事件可能会被忽视，直到工单数量变得难以应对。 Incident Signal 根据问题类别对工单进行分组，并评估其时间戳以识别异常集群。这为支持和运营团队提供了一个更早的信号，表明多个客户可能正在经历相同的问题。 该系统能够区分涉及同一问题类别的独立事件。例如，上午的登录中断和当天下午晚些时候的另一次登录中断将被报告为两个独立事件，而不是被合并在一起或遗漏掉较小的集群。 每个检测到的事件也会收到基于数量的严重级别，以便团队可以优先处理影响较大的活动。 ## 工作原理 默认检测规则在以下情况会标记潜在事件： - 至少有三张工单属于同一类别。 - 这些工单发生在 30 分钟的时间窗口内。 长于配置窗口的静默期会将活动划分为不同的集群。每个集群必须独立满足检测阈值，然后才能成为一个事件。 ``` flowchart TD A[JSON ticket file] --> B[Validate input] B --> C[Group by category] C --> D[Separate activity clusters] D --> E[Apply threshold window] E --> F[Assign severity] F --> G[Build text or JSON report] ``` 包含的示例数据集包含 11 张虚构工单： - 上午 9:02 到 9:21 之间的六次登录失败报告 - 两个不相关的支持请求 - 下午 4:02 到 4:17 之间的三次额外登录失败报告 Incident Signal 将上午和下午的登录集群识别为两个独立的事件，为它们分配不同的严重级别，并忽略不相关的工单。 ## 文本输出示例 ``` Input file: data/sample_tickets.json Analyzed 11 support tickets. Detection rule: 3 tickets within 30 minutes. Detected 2 potential incident(s): Category: login_failure Severity: high Ticket count: 6 First seen: 2026-07-26 09:02:00 Last seen: 2026-07-26 09:21:00 Tickets: TKT-1001, TKT-1002, TKT-1003, TKT-1004, TKT-1005, TKT-1006 Category: login_failure Severity: medium Ticket count: 3 First seen: 2026-07-26 16:02:00 Last seen: 2026-07-26 16:17:00 Tickets: TKT-1009, TKT-1010, TKT-1011 ``` ## JSON 输出示例 ``` { "input_file": "data/sample_tickets.json", "summary": { "tickets_analyzed": 11, "incidents_detected": 2 }, "detection_rule": { "threshold": 3, "window_minutes": 30 }, "incidents": [ { "category": "login_failure", "severity": "high", "ticket_count": 6, "first_seen": "2026-07-26T09:02:00", "last_seen": "2026-07-26T09:21:00", "ticket_ids": [ "TKT-1001", "TKT-1002", "TKT-1003", "TKT-1004", "TKT-1005", "TKT-1006" ] }, { "category": "login_failure", "severity": "medium", "ticket_count": 3, "first_seen": "2026-07-26T16:02:00", "last_seen": "2026-07-26T16:17:00", "ticket_ids": [ "TKT-1009", "TKT-1010", "TKT-1011" ] } ] } ``` ## 项目结构 ``` incident-signal/ ├── .github/ │ └── workflows/ │ └── tests.yml ├── data/ │ └── sample_tickets.json ├── src/ │ ├── __init__.py │ ├── detection.py │ ├── ingestion.py │ ├── main.py │ ├── models.py │ └── reporting.py ├── tests/ │ ├── __init__.py │ ├── test_detection.py │ ├── test_ingestion.py │ └── test_reporting.py ├── requirements.txt └── README.md ``` ## 设计决策 ### 确定性检测 该系统使用透明的阈值规则而不是人工智能。这使得每个事件信号都具有可解释性，并允许可靠地测试检测行为。 ### 滑动时间窗口 滑动窗口验证在配置的时间范围内是否发生了所需数量的相关工单。这比将工单划分为固定的时间块更灵活。 ### 多事件检测 工单首先按类别分组，并按时间顺序排序。长于配置检测窗口的静默间隔将启动一个新的活动集群。 每个活动集群必须独立包含符合条件的阈值窗口。这允许 Incident Signal： - 检测涉及同一类别的独立事件。 - 防止工单在多个事件中被重复计算。 - 忽略从未达到所需密度的缓慢活动。 - 保留与符合条件的活动期相关的所有工单。 ### 可解释的严重性评分 严重级别基于相对于配置检测阈值的工单数量。 | 相对于阈值的数量 | 严重性 | |---|---| | 至少 1× 但小于 2× | `medium` | | 至少 2× 但小于 3× | `high` | | 至少 3× | `critical` | 使用默认的三张工单阈值时： | 工单数量 | 严重性 | |---:|---| | 3–5 | `medium` | | 6–8 | `high` | | 9 或更多 | `critical` | 由于严重性随配置的阈值进行缩放，团队可以更改检测规则，而不会产生不一致的严重性行为。 ### 可配置的业务规则 无需修改源代码，即可通过命令行选项更改检测阈值。这允许同一系统支持具有不同工单数量和升级要求的团队。 ### 可配置的输入 用户可以通过 `--input` 选项分析不同的 JSON 工单文件。检测引擎不仅仅局限于包含的示例数据集。 ### 独立的报告层 报告生成与摄取和检测分离。这允许以不同的格式呈现事件结果，而无需更改底层的业务规则。 ### 机器可读的输出 `--format json` 选项生成稳定的 JSON 结构，可由其他应用程序、webhook、仪表板或事件管理工作流使用。 ### 输入验证 摄取层验证： - 所选的输入文件存在。 - 文件包含有效的 JSON。 - 顶层 JSON 值是一个列表。 - 每张工单都是一个 JSON 对象。 - 每张工单都包含必填字段。 - 必填值包含非空文本。 - 时间戳使用有效的 ISO 格式。 - 工单 ID 是唯一的。 无效的输入会产生清晰的操作错误，而不是被静默处理。 ### 合成数据 所有示例工单都是虚构的。此仓库不包含任何客户信息、雇主数据或专有支持记录。 ## 运行项目 ### 1. 克隆仓库 ``` git clone https://github.com/kay-freeman/incident-signal.git cd incident-signal ``` ### 2. 创建并激活虚拟环境 ``` python3 -m venv .venv source .venv/bin/activate ``` ### 3. 安装测试依赖 ``` python -m pip install -r requirements.txt ``` ### 4. 运行 Incident Signal 使用默认设置运行包含的示例数据： ``` python -m src.main ``` 选择 JSON 工单文件： ``` python -m src.main --input data/sample_tickets.json ``` 自定义工单阈值和时间窗口： ``` python -m src.main \ --input data/sample_tickets.json \ --threshold 4 \ --window 45 ``` 生成机器可读的 JSON 报告： ``` python -m src.main \ --input data/sample_tickets.json \ --format json ``` 可用选项： - `--input` 选择 JSON 工单文件。 - `--threshold` 控制所需的最少相关工单数量。 - `--window` 以分钟为单位控制检测窗口。 - `--format` 选择 `text` 或 `json` 输出。 查看命令行帮助： ``` python -m src.main --help ``` ### 5. 运行自动化测试 ``` pytest -v ``` ## 错误处理 如果所选文件不存在，Incident Signal 会返回一个简明的错误： ``` Error: Input file not found: data/does_not_exist.json ``` 格式错误的 JSON、缺失字段、无效时间戳、空值、重复的工单 ID、无效的检测设置以及不支持的输出格式也会被拒绝，并显示清晰的错误信息。 ## 测试覆盖率 自动化套件包含 16 个测试，覆盖了检测、摄取和报告层。 测试验证系统能够： - 检测符合条件的工单集群。 - 检测同一类别中的多个事件。 - 防止缓慢的活动产生误报事件。 - 分配 medium、high 和 critical 严重级别。 - 忽略低于配置阈值的类别。 - 忽略超出配置时间窗口的工单。 - 拒绝无效的检测设置。 - 加载有效的 JSON 工单数据。 - 拒绝无效的底层数据结构。 - 拒绝缺失的必填字段。 - 拒绝无效的时间戳。 - 拒绝重复的工单 ID。 - 拒绝格式错误的 JSON。 - 报告缺失的输入文件。 - 在结构化的 JSON 报告中包含严重性。 - 在未检测到事件时生成有效的 JSON 报告。 ## 持续集成 GitHub Actions 会在每次推送和拉取请求时自动安装项目依赖项并运行所有 16 个测试。当更改破坏了现有的检测、摄取或报告行为时，这会提供即时反馈。 此 README 顶部的测试状态徽章反映了 `main` 分支的最新工作流结果。 ## 未来增强功能 - 摄取 CSV 导出和 webhook 有效负载。 - 将报告直接保存到输出文件。 - 向事件管理或通信系统发送警报。 - 可视化工单数量和检测到的事件时间线。 ## 展示的技能 - 需求转化 - 系统分析 - 数据建模 - 可配置的系统设计 - 输入验证 - 错误处理 - 基于规则的自动化 - 时间窗口分析 - 多事件检测 - 可解释的严重性评分 - 误报预防 - 关注点分离 - 机器可读的报告 - Python 开发 - 自动化测试 - 使用 GitHub Actions 进行持续集成 - 技术文档 - 面向集成的设计

标签：IT运维, Socks5代理, 事件检测, 代码示例, 安全规则引擎, 客服支持, 数据分析, 自动化报告, 逆向工具