Metadata-Version: 2.4
Name: fengyun-agent-task
Version: 0.4.1
Summary: CncertAgent local WSS log cache, offline analysis, submission, and API adapter toolkit.
Author: Fengyun-AI-Agent
License-Expression: MIT
Keywords: fengyun,security,logs,mongodb,wss
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: hyperscan>=0.7.0
Requires-Dist: pymongo>=4.10.0
Provides-Extra: transfer
Requires-Dist: zstandard<1,>=0.23.0; extra == "transfer"
Requires-Dist: Brotli<2,>=1.1.0; extra == "transfer"
Provides-Extra: publish
Requires-Dist: build>=1.2.2; extra == "publish"
Requires-Dist: twine>=5.1.1; extra == "publish"
Dynamic: license-file



## 架构

```text
WSS / JSONL
    │
    ▼
logs ──单告警分析──> label / entities
  │      ├─ judge（默认）
  │      └─ expert-first（专家命中直接赋值，未命中再 judge）
  │
  ├─攻击链分析 association（默认）──> chain_id + attack_chains
  └─攻击链分析 expert ─────────────> 按专家链生成 attack_chains
  │
  └──前端专家标注双写 expert_annotations 与人工字段

告警/攻击链分析 ──逐条增量写 final_results outbox
submit ──────────读取统一 outbox──> 比赛服务
```

MongoDB 使用四个业务集合：

- `logs`：原始日志以及自动/专家研判字段。
- `expert_annotations`：单日志专家标注和专家攻击链。
- `attack_chains`：自动分析生成的核心攻击链 payload。
- `final_results`：统一的最终 payload 和提交状态，不按 Judge/专家区分。

`expert_annotations` 不保存 payload，也不直接生成提交结果。

单告警分析按批量 bulk write 保存，攻击链分析保存时增量写入 `final_results`。`submit` 只读取统一
outbox 并发送，不读取或区分结果来自 Judge、关联规则还是专家记录。



PyPI 包只包含 `src/fengyun_ai_agent` 分析框架、规则数据（包括该目录内的
`.jsonl`）和命令行工具，不包含
`frontend`、`backend_py`、测试数据或本地运行结果：

```bash
python -m pip install fengyun-agent-task
fengyun-task --help
```

需要共享目录高压缩加密归档功能时安装可选依赖：

```bash
python -m pip install "fengyun-agent-task[transfer]"
fengyun-transfer --help
```

## 源码开发安装

```powershell
python -m pip install -e .
fengyun-task --help
```

配置 MongoDB。连接密码不要写入源码或提交到 Git：

```powershell
$env:MONGODB_URI = "mongodb://<user>:<password>@<host>:<port>/?authSource=admin"
fengyun-task init-db
```

Linux：

```bash
export MONGODB_URI='mongodb://<user>:<password>@<host>:<port>/?authSource=admin'
fengyun-task init-db
```

比赛环境只需设置统一环境变量，MongoDB 和模型服务会同时切换到生产配置：

```bash
export PRODUCTION=1  # 也兼容 production=1
fengyun-task init-db
fengyun-task pipeline
```

生产 MongoDB 默认对应比赛 Docker 配置：`127.0.0.1:27017`、用户 `admin`、
认证库 `admin`。生产模型默认切换到 `http://127.0.0.1:8100/v1` 的
`qwen3-8B`；可通过
`LLM_INTERNAL_BASE_URL` 和 `LLM_INTERNAL_MODEL` 覆盖。Mongo 运行在其它主机时，
使用 `MONGODB_PRODUCTION_HOST`、`MONGODB_PRODUCTION_PORT`，或直接设置
`MONGODB_PRODUCTION_URI`。显式 `MONGODB_URI`、`LLM_BASE_URL` 始终优先。

## 主流程

一键处理 MongoDB 中全部待研判日志和待关联种子：

```bash
fengyun-task pipeline
```

需要先从一个或多个备份 JSONL 导入时，可重复指定 `--import-path`：

```bash
fengyun-task pipeline \
  --import-path data/raw_logs/first/waf.jsonl \
  --import-path data/raw_logs/first/hids.jsonl
```

`pipeline` 当前流程为“可选导入 → 单包研判直至清空 → 攻击链分析直至清空”。
IP 已在单包研判保存时写入日志内嵌 `correlation_ips` 多键索引，不存在独立的
IP 索引构建或 IP 建链步骤。源码目录仍可使用兼容入口 `python run_full_pipeline.py`。

接收日志：

```bash
python -m fengyun_ai_agent.cli receive --batch first
```

单告警分析：

```bash
python -m fengyun_ai_agent.cli analyze-alerts --limit 100
python -m fengyun_ai_agent.cli analyze-alerts --limit 100 --watch
```

攻击链关联：

```bash
# 全量数据或关联规则调整后可先重建实体和 correlation_ips
python -m fengyun_ai_agent.cli re-extract-entities --workers 64

# 从日志内嵌 correlation_ips 和其余声明式规则递归关联
python -m fengyun_ai_agent.cli analyze-chains --limit 1000
python -m fengyun_ai_agent.cli analyze-chains --limit 1000 --watch
```

关联规则以 `chain.md` 为业务基准，在 `chain_rules.py` 中声明。支持黑种子关联
黑/白/灰候选、AND/OR 复合条件、前后时间窗口和 UTC 事件时间。规则默认会把
被关联的白/灰日志提升为黑，并保存原始标签和说明，`reset-analysis --scope chains`
时可以恢复。攻击链会记录命中的规则 ID、入口日志和 `needs_review`；没有
RASP/WAF/Web/Auth/Mail/DB Audit 入口的链会标记为需要人工检视。
时间属于日志而不是实体：`eventTimeDay/Hour/Minute` 不再写入 `entities`，统一
保存为顶层 BSON Date 字段 `event_time_utc`，MongoDB 时间范围查询使用
`(log_source, event_time_utc)` 轻量索引。

非直接-IP关联会把实体规范化为 `correlation_entities` 精确匹配键，并通过单一
多键复合索引查询；直接IP关联的时间和目标资产范围保持不变。

默认执行 Judge 告警分析：

```bash
python -m fengyun_ai_agent.cli analyze-alerts --mode judge --watch
```

专家优先告警分析：

```bash
python -m fengyun_ai_agent.cli analyze-alerts --mode expert-first --watch
```

默认关联分析与专家攻击链分析：

```bash
python -m fengyun_ai_agent.cli analyze-chains --mode association --watch
python -m fengyun_ai_agent.cli analyze-chains --mode expert --watch
```
