Upload aetherargus_README.md

aetherargus_README.md

@@ -0,0 +1,294 @@
+---
+license: apache-2.0
+base_model:
+  - Qwen/Qwen3-4B-Instruct-2507
+base_model_relation: finetune
+library_name: transformers
+pipeline_tag: text-generation
+language:
+  - zh
+  - en
+tags:
+  - qlora
+  - peft
+  - cybersecurity
+  - security
+  - intrusion-detection
+  - structured-output
+  - json
+  - gguf
+  - ollama
+  - aetherguard
+  - aetherargus
+---
+
+# AetherArgus-4B
+
+**AetherArgus** 是 AetherGuard 平台面向 HTTP 请求与安全事件研判训练的本地安全判定模型。模型基于 **Qwen3-4B-Instruct-2507**，使用 QLoRA 完成领域对齐，主要输出攻击判定、攻击家族、风险等级、证据和建议动作。
+
+> 当前版本为研究与预览版本，适合实验、演示、离线评估和影子研判。它不应在缺少规则引擎、人工复核与安全闸门的情况下直接执行生产自动阻断。
+
+## Model summary
+
+- **Model name:** AetherArgus-4B
+- **Base model:** `Qwen/Qwen3-4B-Instruct-2507`
+- **Base revision:** `cdbee75f17c01a7cc42f958dc650907174af0554`
+- **Training method:** QLoRA / PEFT LoRA
+- **Primary language:** Chinese, with limited English input support
+- **Primary task:** Structured security verdict generation
+- **Project:** AetherGuard
+- **Status:** Preview / research
+
+AetherArgus 的目标不是替代 WAF、IDS、规则检测或硬件安全门，而是为这些系统增加一个可本地部署的语义研判层。
+
+## Intended input
+
+模型接收标准化的 HTTP 请求、安全上下文和规则信号，例如：
+
+```json
+{
+  "method": "GET",
+  "path": "/api/fetch",
+  "query": "url=http://127.0.0.1/admin",
+  "headers": {
+    "content-type": "application/json"
+  },
+  "body": "",
+  "sourceContext": {
+    "requestsLastMinute": 3,
+    "distinctPathsLastMinute": 1,
+    "recentFailureCount": 0,
+    "historicalRiskScore": 0.2
+  },
+  "ruleSignals": []
+}
+```
+
+## Output contract
+
+除专门的演示配置外，检测端点应只接受以下严格 JSON 输出：
+
+```json
+{
+  "verdict": "malicious",
+  "confidence": 0.96,
+  "attackFamily": "ssrf",
+  "severity": "critical",
+  "reasoning": "请求通过服务端资源获取接口访问本地管理地址，具有明确的 SSRF 风险",
+  "evidence": [
+    {
+      "field": "query",
+      "value": "url=http://127.0.0.1/admin",
+      "reason": "参数包含本地管理地址"
+    }
+  ],
+  "recommendedAction": "block"
+}
+```
+
+### Allowed values
+
+- `verdict`: `safe`, `suspicious`, `malicious`, `unknown`
+- `attackFamily`: `benign`, `sqli`, `xss`, `command_injection`, `path_traversal`, `ssrf`, `authentication`, `automation`, `api_abuse`, `deserialization`, `file_upload`, `protocol_attack`, `business_logic`, `other`
+- `severity`: `low`, `medium`, `high`, `critical`
+- `recommendedAction`: `allow`, `monitor`, `challenge`, `block`
+
+解析失败、Schema 校验失败或证据不足时，调用方应按 fail-safe 原则返回 `unknown`，不得自动修补为 `safe`。
+
+## Training data
+
+本次训练使用 1,200 条经过标准化、去重和分组切分的安全判定样本：
+
+| Split | Samples |
+|---|---:|
+| Train | 958 |
+| Validation | 122 |
+| Test | 120 |
+
+类别目标分布：
+
+| Category | Samples | Ratio |
+|---|---:|---:|
+| Attack | 420 | 35% |
+| Normal | 420 | 35% |
+| Hard negative | 240 | 20% |
+| Unknown | 120 | 10% |
+
+重要说明：
+
+- 训练和测试语料主要来自合成安全数据及确定性辅助模板。
+- 数据集尚未经过独立双人安全标注。
+- 切分按规范化 payload 模板、CVE、攻击家族、编码方式、来源场景和相似内容哈希分组。
+- 当前 manifest 未检测到跨 split 的共享泄漏组或完全相同内容。
+- 这些数据不能代表真实生产流量的完整分布。
+
+## Training configuration
+
+| Item | Value |
+|---|---|
+| Epochs | 1 |
+| Max sequence length | 768 |
+| LoRA rank | 8 |
+| LoRA alpha | 16 |
+| LoRA dropout | 0.05 |
+| Learning rate | `1e-4` |
+| Batch size | 1 |
+| Gradient accumulation | 16 |
+| Quantization | 4-bit NF4 + double quantization |
+| Compute dtype | BF16 |
+| Optimizer | `paged_adamw_8bit` |
+| Loss | Assistant-only causal language modeling |
+
+实测训练环境：
+
+- NVIDIA GeForce RTX 5070 Ti Laptop GPU
+- 11.94 GiB VRAM
+- 训练阶段峰值已分配显存约 5.38 GiB
+- 1 epoch 训练约 651 秒，验证约 24 秒
+
+## Evaluation
+
+以下指标来自同一套固定的 **120 条合成测试样本**，`do_sample=false`，随机种子为 42。指标只反映当前实验集表现，不能直接解释为生产环境准确率。
+
+### HF LoRA / PEFT
+
+| Metric | Result |
+|---|---:|
+| Verdict accuracy | 0.9000 |
+| Malicious precision | 0.8810 |
+| Malicious recall | 0.9024 |
+| Malicious F1 | 0.8916 |
+| Normal false-positive rate | 0.0455 |
+| JSON syntax success | 0.9917 |
+| Schema valid rate | 0.9833 |
+| Attack-family macro F1 | 0.6147 |
+| Recommended-action accuracy | 0.9000 |
+
+### GGUF Q4_K_M / Ollama
+
+| Metric | Result |
+|---|---:|
+| Verdict accuracy | 0.8417 |
+| Malicious precision | 0.7170 |
+| Malicious recall | 0.9268 |
+| Malicious F1 | 0.8085 |
+| Normal false-positive rate | 0.1970 |
+| JSON syntax success | 1.0000 |
+| Schema valid rate | 0.9833 |
+| Attack-family macro F1 | 0.5193 |
+| Average latency | 869 ms |
+
+Q4_K_M 版本推理明显更快，但对正常与硬负样本的误报显著增加。高精度场景优先使用原始 LoRA、合并模型或更高精度的 GGUF 量化，并重新独立评测。
+
+## Load the LoRA adapter
+
+由于该仓库当前为私有仓库，使用前需要先登录 Hugging Face：
+
+```bash
+hf auth login
+```
+
+参考加载方式：
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+from peft import PeftModel
+
+base_model_id = "Qwen/Qwen3-4B-Instruct-2507"
+adapter_id = "BreakFeelingAether/aetherargus"
+
+quantization_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_use_double_quant=True,
+    bnb_4bit_compute_dtype=torch.bfloat16,
+)
+
+tokenizer = AutoTokenizer.from_pretrained(adapter_id, use_fast=True)
+base_model = AutoModelForCausalLM.from_pretrained(
+    base_model_id,
+    quantization_config=quantization_config,
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+)
+model = PeftModel.from_pretrained(base_model, adapter_id)
+model.eval()
+```
+
+建议使用与训练阶段一致的 system prompt，并在调用端执行严格 JSON Schema 校验。模型输出无效时应回退为 `unknown + monitor`。
+
+## Ollama / GGUF
+
+当仓库中包含 GGUF 和 `Modelfile` 时，可下载后创建本地 Ollama 模型：
+
+```bash
+ollama create aetherargus -f Modelfile
+```
+
+推理示例：
+
+```bash
+ollama run aetherargus '{"method":"GET","path":"/api/fetch","query":"url=http://127.0.0.1/admin","headers":{},"body":"","sourceContext":{},"ruleSignals":[]}'
+```
+
+生产检测配置不应加入“身份询问时返回自然语言”等例外逻辑，否则请求正文可能诱导模型偏离 JSON 输出协议。
+
+## Recommended deployment pattern
+
+推荐采用影子模式逐步接入：
+
+```text
+Incoming request
+ ├─ Existing rules / WAF / IDS continue to operate
+ └─ AetherArgus produces a shadow verdict for logging and evaluation
+```
+
+在真实流量上完成独立评估前：
+
+- 不让模型直接执行阻断、断网、删除或修复操作。
+- 不绕过现有规则引擎、策略签名、硬件授权和 fail-closed 安全门。
+- 不将解析失败视为安全。
+- 对高风险动作保留人工或硬件级授权。
+
+## Known limitations
+
+1. 当前训练与测试数据以合成数据为主，缺少大规模真实脱敏流量验证。
+2. 测试集仅 120 条，部分攻击家族样本数很少，分类别指标方差较大。
+3. `api_abuse`、`file_upload`、业务逻辑攻击和复杂上下文型事件仍需更多高质量数据。
+4. Q4_K_M 量化明显提高了正常流量误报率。
+5. 模型可能受到提示词注入、日志投毒、混淆编码和分布外输入影响。
+6. `recommendedAction` 只是建议，不是可直接执行的安全策略。
+7. 该模型不是通用聊天模型，也不是漏洞利用或攻击执行模型。
+
+## Safety and acceptable use
+
+AetherArgus 用于授权环境下的防御性安全研究、流量研判和风险辅助分析。使用者应确保拥有处理相关日志、请求和资产数据的合法权限，并遵守适用的数据保护、网络安全、出口管制和软件许可要求。
+
+禁止将本模型用于：
+
+- 未经授权的入侵、扫描或攻击；
+- 凭据窃取、恶意软件部署或规避追踪；
+- 将模型判定作为缺少复核机制的唯一高风险决策依据；
+- 上传包含真实 Token、Cookie、API Key、客户隐私或商业秘密的数据。
+
+## License and attribution
+
+本仓库按 **Apache License 2.0** 发布。AetherArgus 基于 `Qwen/Qwen3-4B-Instruct-2507` 微调，使用时仍需遵守基座模型许可证及其适用条款。
+
+推荐引用方式：
+
+```text
+AetherArgus-4B, an AetherGuard security-domain model fine-tuned from
+Qwen3-4B-Instruct-2507 using QLoRA.
+```
+
+## Project links
+
+- Source project: `lizuyi-6/Networksafe`
+- Model repository: `BreakFeelingAether/aetherargus`
+
+## Version
+
+- **Current release:** AetherArgus-4B Preview 0.1
+- **Last model evaluation:** 2026-07-28