fengyun-agent-task 0.1.0__tar.gz

fengyun_agent_task-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CncertAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fengyun_agent_task-0.1.0/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: fengyun-agent-task
+Version: 0.1.0
+Summary: CncertAgent local WSS log cache, offline analysis, submission, and API adapter toolkit.
+Author: CncertAgent contributors
+License-Expression: MIT
+Keywords: fengyun,security,logs,sqlite,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.9
+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.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.7.0
+Dynamic: license-file
+
+# task 本地 WSS 缓存与离线分析工具
+
+该目录是独立实现。
+
+## 目标
+
+- WSS 接收大量日志时优先本地落盘，避免在线分析拖慢接收。
+- SQLite WAL 保存结构化缓存，支持多进程读写。
+- JSONL 保存原始 WSS 消息和原始日志，便于灾备和复盘。
+- 告警与攻击链先进入本地 outbox，再由提交命令统一提交。
+
+## 什么是 `--dry-run`
+
+`--dry-run` 表示“试运行 / 演练模式”。
+
+适用命令：
+
+- `submit-alerts`
+- `submit-chains`
+- `replay`
+
+开启 `--dry-run` 后会：
+
+- 按 `--status`、`--kind`、`--limit` 等参数筛选本地待提交记录。
+- 打印将要提交的 payload，便于检查内容。
+- 不向远端服务端发送提交请求。
+- 不更新 `submission_records` 中的提交状态。
+- 不记录提交尝试。
+- 不写入 `submitted_alerts.jsonl` / `submitted_chains.jsonl`。
+
+例如：
+
+```bash
+python -m task.cli replay --kind all --status failed --dry-run
+```
+
+含义是：从本地提交记录中找出 `failed` 状态的告警和攻击链，打印将要重新提交的 payload，但不实际提交、不改变本地提交状态。
+
+## 命令总览
+
+| 命令 | 用途 | 是否修改本地数据 | 是否提交到服务端 |
+|---|---|---|---|
+| `init-db` | 初始化 SQLite WAL 数据库 | 是 | 否 |
+| `reset-db` | 删除并重建 SQLite 数据库 | 是，破坏性操作 | 否 |
+| `status` | 查看本地缓存统计 | 否 | 否 |
+| `receive` | 接收 WSS 日志并写入 JSONL + SQLite | 是 | 否 |
+| `import-sample-data` | 导入样例日志 | 是 | 否 |
+| `analyze-alerts` | 分析日志并生成本地告警候选 | 是 | 否 |
+| `analyze-chains` | 基于告警候选生成攻击链候选 | 是 | 否 |
+| `submit-alerts` | 提交本地告警 outbox | 会更新提交状态 | 是，除非 `--dry-run` |
+| `submit-chains` | 提交本地攻击链 outbox | 会更新提交状态 | 是，除非 `--dry-run` |
+| `replay` | 重放 pending/failed/submitted 提交记录 | 会更新提交状态 | 是，除非 `--dry-run` |
+| `show-log` | 打印本地日志原文 | 否 | 否 |
+| `show-chain` | 打印本地攻击链日志列表 | 否 | 否 |
+
+## 命令参考
+
+所有命令都通过以下入口执行：
+
+```bash
+python -m task.cli <command> [args]
+```
+
+### `init-db`
+
+初始化本地 SQLite 数据库，并启用 WAL 模式。
+
+```bash
+python -m task.cli init-db
+```
+
+参数：无。
+
+### `reset-db`
+
+删除并重建本地 SQLite 数据库。
+
+```bash
+python -m task.cli reset-db --yes
+```
+
+参数：
+
+| 参数 | 默认值 | 说明 |
+|---|---:|---|
+| `--yes` | `False` | 确认删除旧 SQLite 数据库；不提供会拒绝执行。 |
+
+注意：这是破坏性操作，会删除：
+
+- `task/data/log_cache.sqlite3`
+- `task/data/log_cache.sqlite3-wal`
+- `task/data/log_cache.sqlite3-shm`
+
+不会删除 JSONL 原始备份文件。
+
+### `status`
+
+查看本地缓存统计，输出 JSON 格式统计信息。
+
+```bash
+python -m task.cli status
+```
+
+参数：无。
+
+### `receive`
+
+接收 WSS 日志流，写入 JSONL 原始备份和 SQLite 本地缓存。
+
+```bash
+python -m task.cli receive
+python -m task.cli receive --max-batches 1
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `--max-batches` | int | `0` | 最多接收多少个 `log_batch`；`0` 表示不限。 |
+
+说明：该命令只负责接收和落盘，不做告警分析，也不提交到服务端。
+
+### `import-sample-data`
+
+导入样例 JSON 日志到 SQLite。
+
+```bash
+python -m task.cli import-sample-data
+python -m task.cli import-sample-data --data-dir data
+python -m task.cli import-sample-data --data-dir data --no-raw-backup
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `--data-dir` | string | `data` | 样例数据目录。 |
+| `--no-raw-backup` | flag | `False` | 只导入 SQLite，不追加写入 `raw_messages.jsonl` / `raw_logs.jsonl`。 |
+
+默认会同时追加写入 `raw_messages.jsonl` 和 `raw_logs.jsonl` 原始备份。
+
+### `analyze-alerts`
+
+分析未处理日志，生成本地告警候选。
+
+```bash
+python -m task.cli analyze-alerts
+python -m task.cli analyze-alerts --limit 10000
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `--limit` | int | `1000` | 本轮最多分析多少条未处理日志。 |
+
+说明：该命令只生成本地告警候选，不直接提交到服务端。
+
+### `analyze-chains`
+
+基于本地告警候选生成攻击链候选。
+
+```bash
+python -m task.cli analyze-chains
+python -m task.cli analyze-chains --max-logs-per-chain 2000
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `--max-logs-per-chain` | int | `2000` | 每条候选攻击链最多纳入多少条日志。 |
+
+说明：该命令只生成本地攻击链候选，不直接提交到服务端。
+
+### `submit-alerts`
+
+提交本地告警 outbox。
+
+```bash
+python -m task.cli submit-alerts
+python -m task.cli submit-alerts --dry-run --limit 10
+python -m task.cli submit-alerts --status failed --limit 100
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 可选值 | 说明 |
+|---|---|---:|---|---|
+| `--limit` | int | `100` | 任意整数 | 本次最多处理多少条告警提交记录。 |
+| `--status` | string | `pending` | `pending` / `failed` / `submitted` | 筛选要处理的提交状态。 |
+| `--dry-run` | flag | `False` | - | 只打印 payload，不实际提交、不更新提交状态。 |
+
+### `submit-chains`
+
+提交本地攻击链 outbox。
+
+```bash
+python -m task.cli submit-chains
+python -m task.cli submit-chains --dry-run
+python -m task.cli submit-chains --status failed --limit 50
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 可选值 | 说明 |
+|---|---|---:|---|---|
+| `--limit` | int | `100` | 任意整数 | 本次最多处理多少条攻击链提交记录。 |
+| `--status` | string | `pending` | `pending` / `failed` / `submitted` | 筛选要处理的提交状态。 |
+| `--dry-run` | flag | `False` | - | 只打印 payload，不实际提交、不更新提交状态。 |
+
+### `replay`
+
+重放已保存在本地 outbox 中的提交 payload。
+
+```bash
+python -m task.cli replay
+python -m task.cli replay --kind all --status failed --dry-run
+python -m task.cli replay --kind alert --status failed --limit 20
+python -m task.cli replay --kind chain --status pending
+```
+
+参数：
+
+| 参数 | 类型 | 默认值 | 可选值 | 说明 |
+|---|---|---:|---|---|
+| `--kind` | string | `all` | `all` / `alert` / `chain` | 重放类型：全部、仅告警、仅攻击链。 |
+| `--status` | string | `failed` | `pending` / `failed` / `submitted` | 选择要重放的提交状态。 |
+| `--limit` | int | `100` | 任意整数 | 每类最多处理多少条；`--kind all` 时 alert 和 chain 分别最多处理该数量。 |
+| `--dry-run` | flag | `False` | - | 只打印将要重放的 payload，不实际提交、不更新状态。 |
+
+说明：`replay` 是“重试/重放已保存的提交 payload”，不是重新接收日志，也不是重新分析日志。
+
+常用失败重放流程：
+
+```bash
+python -m task.cli replay --kind all --status failed --dry-run
+python -m task.cli replay --kind all --status failed
+```
+
+第一条先预览将要重新提交的内容；第二条才真正提交。
+
+### `show-log`
+
+打印本地日志原文 JSON。
+
+```bash
+python -m task.cli show-log WAF0000001
+```
+
+参数：
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `log_id` | positional string | 要查看的本地日志 ID。 |
+
+### `show-chain`
+
+打印本地攻击链关联日志列表。
+
+```bash
+python -m task.cli show-chain CHAIN_LOCAL_xxx
+```
+
+参数：
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `chain_id` | positional string | 要查看的本地攻击链 ID。 |
+
+输出内容包括时间、日志源、日志 ID。
+
+## 推荐使用流程
+
+### 1. 初始化
+
+```bash
+python -m task.cli init-db
+python -m task.cli status
+```
+
+### 2. 导入样例数据
+
+```bash
+python -m task.cli import-sample-data --data-dir data
+```
+
+如果只想导入 SQLite，不追加 JSONL 备份：
+
+```bash
+python -m task.cli import-sample-data --data-dir data --no-raw-backup
+```
+
+SQLite schema 和字段含义见：
+
+```text
+task/SQLITE_SCHEMA.md
+```
+
+### 3. 接收日志
+
+```bash
+python -m task.cli receive
+```
+
+联调只接收一批：
+
+```bash
+python -m task.cli receive --max-batches 1
+```
+
+### 4. 分析和提交
+
+```bash
+python -m task.cli analyze-alerts --limit 10000
+python -m task.cli submit-alerts --dry-run --limit 10
+python -m task.cli submit-alerts --limit 200
+
+python -m task.cli analyze-chains
+python -m task.cli submit-chains --dry-run
+python -m task.cli submit-chains
+```
+
+### 5. 复盘查询
+
+```bash
+python -m task.cli show-log WAF0000001
+python -m task.cli show-chain CHAIN_LOCAL_xxx
+```
+
+## 常用环境变量
+
+```bash
+export GX_SERVER=https://172.17.35.21:18080
+export GX_TEAM_ID=TEAM001
+export GX_TOKEN=team001-demo-token
+export GX_VERIFY_CERT=0
+export TASK_DATA_DIR=task/data
+```
+
+## 代码结构
+
+- `config.py`：环境变量、默认路径、接口 endpoint 和日志源映射。
+- `db.py`：SQLite 连接、初始化、轻量迁移和重置。
+- `json_utils.py`：JSON/JSONL 序列化、容错解析和原始备份写入。
+- `repository.py`：本地 SQLite 仓储主入口，负责日志入库/查询、攻击链元数据、payload 构造和 CLI/离线流程兼容导出。
+- `submission_repository.py`：`submission_records` outbox、提交记录和重试状态。
+- `analyze.py`：本地黑日志分析和攻击链聚合入口。
+- `api_repository.py`：Flask 后端和前端 API 兼容适配层。
+- `cli.py`：命令行入口，包含 replay、show-log、show-chain 等 CLI 辅助命令。
+
+## 重要说明
+
+- `raw_messages.jsonl` 和 `raw_logs.jsonl` 是 append-only 原始备份，不会自动删除。
+- WSS 接收命令只做落盘，不做网络提交。
+- 每个命令单独打开 SQLite 连接，不要跨进程共享连接。
+- 第一版检测和攻击链逻辑是基线启发式，后续可以在 `detectors.py` 和 `analyze.py` 中增强。