arefehkr/anomalyx-alert-engine

# AnomalyX 预警引擎 一个小型的端到端欺诈检测 pipeline：一个 Isolation Forest 用于标记异常的银行交易，而双层 AI agent 会将每个被标记的交易转化为供欺诈分析师查看的纯英文警报。  ## 功能说明 1. **检测异常。** 每笔交易的四个简单特征 —— 金额与该账户过去 30 天滚动平均值的偏差程度、该账户在过去一小时内进行的交易次数、是否发生在深夜，以及商户类别是否是该账户通常使用的类别 —— 这些特征将被输入到 Isolation Forest 中，后者会对每笔交易进行评分，并将其划分为 **红色 / 黄色 / 绿色**。 2. **通过双层 agent 进行解释。** - **A 层（Python，确定性）：** 一个小型的规则引擎会标记交易被标记的*原因*（例如“大额偏差”、“快速交易爆发”），检查该账户最近是否已经出现过警报（这样 4 笔交易的突发情况就不会产生 4 个警报），并决定 `dispatch_safe` —— **这在 Python 中完成，绝不通过 LLM 处理**。 - **B 层（通过 Ollama 运行的本地 Llama 模型，如果 Ollama 未运行则使用模板）：** 获取该上下文并撰写实际的警报 —— 标题、解释、建议操作、紧迫性。所有操作都在您的机器上运行 —— 无需 API key，无需成本，数据也不会离开您的笔记本电脑。 ## 设置说明 ``` pip install -r requirements.txt # 安装 Ollama（一次性，免费）：https://ollama.com/download ollama pull llama3.2 python run_pipeline.py ``` 即使未安装或未运行 Ollama 也能正常工作 —— B 层只会直接使用模板。您可以随时运行 `python src/generate_data.py` 来重新生成合成数据集。 ``` python run_pipeline.py --max-alerts 3 # cap alerts (useful while testing) pytest tests/ -v # 12 tests ``` ## 示例输出  这是在 Ollama 运行时执行 `python run_pipeline.py` 的真实输出 —— 下面的 `headline` 和 `explanation` 文本是由 Llama 3.2 撰写的，而非来自模板： [RED] High-Severity Transaction with Unusual Anomaly Score Account: Student Card | Amount: $67.44 | Score: 0.94 | Urgency: high Tags: Off-Hours Activity, Unfamiliar Merchant Category The transaction is a withdrawal of $67.44 from the Student Card account, which has an unusual anomaly score of 0.938, indicating potential suspicious activity. Action: Verify if the account holder intended to withdraw this amount and confirm the merchant category matches. Dispatch safe: True (No recent alert for this account -- safe to dispatch) Written by: llm [YELLOW] Potential General Statistical Anomaly on Student Card Account: Student Card | Amount: $43.53 | Score: 0.47 | Urgency: low Tags: General Statistical Anomaly The transaction is classified as a General Statistical Anomaly due to its low amount, suggesting possible fraud or error. This account's usage often has low values. Action: Verify the merchant and account details for accuracy before clearing the transaction. Dispatch safe: True (No recent alert for this account -- safe to dispatch) Written by: llm ## 结果（此合成演示数据集） 针对全部 464 笔交易进行的完整运行，共生成 47 个警报： | | | |---|---| | Recall | **100%** (42/42) —— 每个注入的异常都被标记了 | | Precision | **62.7%** (42/67) —— 大约三分之一的警报是误报 | | False negatives | **0** | 这种权衡是预期之内且客观存在的：捕捉所有异常意味着也会捕捉到一些合法但异常（非欺诈性）的消费。在实际部署中，应该根据成本模型（错误警报与遗漏欺诈的对比）来调整 `src/detector.py` 中的红/黄阈值，而不是一味追求两者的 100%。 ## 项目结构 ``` run_pipeline.py # the whole pipeline, start to finish src/ generate_data.py # synthetic accounts + transactions with injected anomalies features.py # 4 features: spend_ratio, txn_count_1h, is_night, merchant_mismatch detector.py # Isolation Forest + Red/Yellow/Green thresholds agent.py # Layer A (rules engine) + Layer B (Llama via Ollama / template) alerter.py # console formatting, JSON log, burst dedup, eval tests/test_pipeline.py # 12 tests ```

标签：AI风险缓解, DLL 劫持, LLM评估, Ollama, Python, 大语言模型, 安全规则引擎, 异常检测, 无后门, 欺诈检测, 逆向工具