PerinbaBuilds/AnomalEye

# 👁 AnomalEye — 用于 AML 可疑活动检测的 Agentic AI AnomalEye 是一个**全栈、合规级别的 AML 平台**。其核心是一个 **自主 agent**：你只需用纯英文给它一个指令 —— *“查找 过去 30 天内的 structuring 模式”* —— 它就会**解析意图、构建 动态执行计划、仅调用该查询所需的工具**、检测 洗钱类型、进行风险评分，并返回一个**可解释的**裁决以及 建议的上报操作（`monitor` / `review` / `report`）。 它以一个基于 **FastAPI** 服务构建的 **React + TypeScript** 分析师控制台的形式发布，该服务公开了一个混合了 **规则 + 统计学 + 机器学习** 的检测 引擎 —— 每一个决策都可审计，每一个阈值都清晰明确。 ## 包含内容 ``` ┌──────────────────────────── Frontend (React + TS + Vite + Tailwind) ────────────────────────────┐ │ Dashboard · AI Agent Console · Alert Queue · Live Monitor · Link Analysis · Performance · Docs │ └───────────────────────────────────────────────┬──────────────────────────────────────────────────┘ │ REST / SSE ┌───────────────────────────────────────────────▼──────────────────────────────────────────────────┐ │ Backend (FastAPI) /api/overview · /api/agent/query · /api/alerts · /api/customers/{id} ... │ └───────────────────────────────────────────────┬──────────────────────────────────────────────────┘ │ ┌───────────────────────────────────────────────▼──────────────────────────────────────────────────┐ │ Engine (Python) Agent(planner + orchestrator) → EDA · Features · Anomaly · Risk · Explain │ └────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### 六大分析师视图 | 视图 | 功能 | |---|---| | **Dashboard** | 投资组合 KPI、风险分布、类型细分、CTR 区间直方图、标记活动趋势、优先案例 | | **AI Agent Console** | 核心亮点：输入查询 → 查看 agent 检测到的意图、过滤器、**工具 pipeline**、规划依据以及解释性发现 | | **Alert Queue** | 案例分流 —— 按风险区间 / 操作 / 类型进行过滤、分页、深入了解任何实体 | | **Live Monitor** | 通过 **Server-Sent Events** 实时进行评分的交易 blotter | | **Link Analysis** | 交易对手网络图（漏斗型 = smurfing，链型 = layering）+ 已发现的 layering 链 | | **Entity 360** | 单个客户的风险指标、纯英文解释、证据、网络、完整的交易历史 | | **Model Performance** | 精确率 / 召回率 / F1 以及基于注入的 ground truth 的各类型召回率 | | **Methodology** | 每一条规则、权重和阈值 —— 可审计的规则手册 | ## 为什么它是一个 *agent*，而不是 pipeline Agent 会读取查询，提取意图 / 过滤器 / 实体 / 类型，并 **动态构建计划** —— 仅对必要的数据切片运行必要的工具： | 用户查询 | Agent 决定做什么 | |---|---| | `Analyse this dataset for suspicious activity` | 完整 pipeline：EDA → 特征 → 混合检测（规则 + ML）→ 风险 → 解释 | | `Find structuring patterns in the last 30 days` | 应用 30 天过滤器 → **仅**运行 structuring 检测器 → 跳过 EDA 和 ML | | `Which customers made 10+ transactions under $10,000?` | 纯聚合规则；**无 ML** | | `Is customer ID 1528 suspicious?` | 单实体查询；**仅针对该客户**按需计算风险 | | `Flag high-risk customers` | 完整的混合套件，**仅**返回高风险区间的结果 | 所选定的计划会显示在每次响应的 `tools_invoked` 和 `planning_rationale` 中。 ### LLM 驱动的规划（Groq）及自动后备 规划器以以下两种模式之一运行： - **LLM agent** —— 当设置了 `GROQ_API_KEY` 时，查询将由 LLM（[Groq](https://groq.com) 上的 Llama 3.3，兼容 OpenAI）通过**真实的 工具调用**进行理解：模型会调用 `submit_execution_plan` 函数来选择 意图、过滤器、实体、类型和工具，并撰写一份关于发现结果的 自然语言分析师摘要。这可以处理杂乱、开放式的 查询 —— *“向我展示任何通过挪动小额现金来逃避报告的人”*。 - **基于规则** —— 在没有密钥（或者 LLM 调用失败/超时）的情况下，将交由 确定性的正则表达式规划器接管。该应用程序完全在离线状态下持续运行。 **启用它：** 将 `.env.example` 复制到 `.env` 并设置 `GROQ_API_KEY`（可在 获取免费密钥）。覆盖 `LLM_MODEL` / `LLM_BASE_URL` 以指向 任何兼容 OpenAI 的提供商。 ## 快速开始 **前置条件：** Python 3.10+ 和 Node 18+。 ### 一条命令（生产构建 + 服务） ``` # Windows scripts\start.bat # macOS / Linux ./scripts/start.sh ``` 这将安装依赖，构建 React 应用，并通过 FastAPI 在 **http://localhost:8000** 提供整个产品（UI + API）的服务。 ### 开发模式（热重载） ``` # Windows scripts\dev.bat # macOS / Linux ./scripts/dev.sh ``` 后端运行在 `:8000`，带有热重载功能的 Vite 开发服务器在 **http://localhost:5173** （它将 `/api` 代理到后端）。 ### 手动操作 ``` pip install -r requirements.txt # Python deps python -m anomaleye.data.generate # (optional) regenerate the dataset cd frontend && npm install && npm run build && cd .. python -m uvicorn backend.main:app --port 8000 # open http://localhost:8000 ``` ### 部署 整个应用（API + UI）在根目录下的单个 `Dockerfile` 中运行。包含了一个 `render.yaml` 蓝图，用于一键部署： ``` docker build -t anomaleye . && docker run -p 8000:8000 anomaleye # local ``` 有关 Render / Railway / Fly.io 的步骤，请参阅 **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)**。 ### CLI（无需 UI） ``` python -m anomaleye "Analyse this dataset for suspicious activity" python -m anomaleye --demo # run all example queries python -m anomaleye.evaluate # detection quality metrics ``` ## 检测方法论（混合） **规则 + 统计学类型检测器**（每个都会输出结构化的*证据*）： - **Structuring** —— 30 天内有 ≥3 笔 `$9,000–$9,999` 之间的现金交易。 - **Smurfing** —— 7 天内有 ≥6 个不同的小额汇款人，总金额超过 `$10,000`。 - **Rapid cash-out** —— 一笔大额入账在 72 小时内被抽走 ≥80%。 - **Layering** —— 价值在 ≤48 小时内流经 ≥3 个账户；每个账户都会被标记。 - **Velocity spike** —— 24 小时内爆发达到群体水平的 ≥3σ。 - **High-risk geography** —— FATF 标记的司法管辖区风险敞口（放大器）。 **机器学习：** 针对每个客户的 13 维行为指纹进行无监督的 **Isolation Forest** 检测。 **风险评分：** 每种类型的最强信号的可审计加权混合， 上限为 100，映射为 `low < 40 ≤ medium < 70 ≤ high`。所有的权重和 阈值都位于 `anomaleye/config.py` 中。 ### 实测性能（`python -m anomaleye.evaluate`） | 指标（客户级别，≥ 中等风险） | 数值 | |---|---| | 精确率 | **0.77** | | 召回率 | **0.91** | | F1 | **0.84** | 各类型召回率：structuring **1.0**、smurfing **1.0**、rapid cash-out **1.0**、layering **0.8**。 ## API 参考（部分） | 方法 | 路径 | 用途 | |---|---|---| | `GET` | `/api/overview` | Dashboard KPI、分布、直方图 | | `POST` | `/api/agent/query` | 运行自然语言 agent 查询 | | `GET` | `/api/alerts?level=&typology=&escalation=` | 过滤后的告警队列 | | `GET` | `/api/customers/{id}` | Entity 360（画像、评估、时间轴、网络） | | `GET` | `/api/customers/{id}/network` | 交易对手链接图 | | `GET` | `/api/layering-chains` | 已发现的 layering 路径 | | `GET` | `/api/performance` | 基于对比 ground truth 的精确率/召回率 | | `GET` | `/api/methodology` | 阈值、权重、风险区间 | | `GET` | `/api/stream/transactions` | SSE 实时评分数据流 | 服务器运行时的交互式文档位于 **http://localhost:8000/docs**。 ## 项目布局 ``` anomaleye/ # detection engine (importable, tested) config.py # all thresholds & weights (single source of truth) agent/ # planner (NL→plan) + orchestrator (dynamic execution) tools/ # eda · features · anomaly · risk · explain · network data/ # synthetic generator + loader cli.py evaluate.py backend/ # FastAPI app + cached analysis service frontend/ # React + TS + Vite + Tailwind console src/pages/ # Dashboard, AgentConsole, Alerts, Entity360, ... src/components/ # Layout, NetworkGraph, ScoreGauge, ui primitives scripts/ # start / dev launchers (Windows + Unix) tests/ # 36 tests: planner, detectors, agent, API, eval gate ``` ## 测试 ``` python -m pytest # 36 backend/engine tests cd frontend && npm run typecheck # frontend type safety ``` ## 设计原则 - **构造即解释** —— 每一个标记都会引用触发它的确切数字； 风险评分按信号进行分解。 - **可审计** —— 所有业务逻辑都在 `config.py` 中，并在 Methodology 视图中展示。 - **确定性与离线** —— 无需外部 API 密钥；相同的查询始终 产生相同的计划和裁决。 - **对 ground truth 诚实** —— 生成器会为其注入的作案手法打上标签，因此 检测质量是经过测量的，而非断言的。

标签：AV绕过, FastAPI, React, Syscalls, 反洗钱, 异常检测, 请求拦截, 逆向工具, 金融风控