README.md

---
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