## 功能特性

- **多协议支持**：HTTP/HTTPS、SOCKS4、SOCKS5 代理
- **多种检测方法**：支持多种代理验证技术
- **并发处理**：可配置工作线程数，实现快速扫描
- **灵活输入**：支持单个代理、文件或标准输入
- **详细输出**：提供多种详细程度级别
- **导出选项**：支持 JSON、CSV 和纯文本格式
- **超时控制**：可配置的连接和响应超时
- **重试机制**：自动重试失败的请求
- **地理位置查询**：可选的代理地理位置查询
- **匿名级别检测**：检测代理匿名级别

## 安装

### 从源码安装

```bash
git clone https://github.com/yourusername/proxy-checker.git
cd proxy-checker
pip install -r requirements.txt

pip install proxy-checker

docker build -t proxy-checker .
docker run proxy-checker --help

# 检查单个代理
python proxy_checker.py -p 192.168.1.1:8080

# 从文件检查多个代理
python proxy_checker.py -f proxies.txt

# 从标准输入检查代理
cat proxies.txt | python proxy_checker.py

# 检查特定协议
python proxy_checker.py -f proxies.txt -t socks5

# 使用自定义设置进行并发检查
python proxy_checker.py -f proxies.txt -c 50 -t 10 -r 3

# 导出结果到多种格式
python proxy_checker.py -f proxies.txt -o results.json --csv results.csv --txt results.txt

# 启用地理位置查询和详细输出
python proxy_checker.py -f proxies.txt -g -v

# 使用特定检测方法
python proxy_checker.py -f proxies.txt -m httpbin,ipinfo,google

用法: proxy_checker.py [-h] [-p PROXY] [-f FILE] [-t TYPE] [-c CONCURRENCY]
                       [-T TIMEOUT] [-r RETRIES] [-o OUTPUT] [--csv CSV]
                       [--txt TXT] [-m METHODS] [-g] [-v] [--quiet]
                       [--no-color] [--user-agent USER_AGENT]
                       [--max-fails MAX_FAILS] [--version]

选项:
  -h, --help            显示此帮助信息并退出
  -p PROXY, --proxy PROXY
                        要检查的单个代理 (格式: host:port 或 protocol://host:port)
  -f FILE, --file FILE  包含代理列表的文件 (每行一个)
  -t TYPE, --type TYPE  代理类型: http, https, socks4, socks5, all (默认: all)
  -c CONCURRENCY, --concurrency CONCURRENCY
                        并发检查数 (默认: 20)
  -T TIMEOUT, --timeout TIMEOUT
                        连接超时时间（秒） (默认: 10)
  -r RETRIES, --retries RETRIES
                        失败请求的重试次数 (默认: 2)
  -o OUTPUT, --output OUTPUT
                        将结果保存到 JSON 文件
  --csv CSV             将结果保存到 CSV 文件
  --txt TXT             将结果保存到文本文件
  -m METHODS, --methods METHODS
                        逗号分隔的检测方法 (httpbin,ipinfo,google,cloudflare)
  -g, --geo             启用地理位置查询
  -v, --verbose         详细输出
  --quiet               静默模式（仅显示结果）
  --no-color            禁用彩色输出
  --user-agent USER_AGENT
                        自定义 User-Agent 字符串
  --max-fails MAX_FAILS
                        最大连续失败次数 (默认: 5)
  --version             显示程序版本号并退出

# 基本格式
192.168.1.1:8080

# 带协议
http://192.168.1.1:8080
https://192.168.1.1:8080
socks4://192.168.1.1:1080
socks5://192.168.1.1:1080

# 带认证
http://username:[email protected]:8080
socks5://username:[email protected]:1080

# 仅端口（使用默认主机）
:8080

{
  "proxy": "192.168.1.1:8080",
  "type": "http",
  "status": "working",
  "response_time": 0.523,
  "ip": "192.168.1.1",
  "country": "United States",
  "city": "New York",
  "anonymous": true,
  "timestamp": "2024-01-01T12:00:00Z"
}

proxy,type,status,response_time,ip,country,city,anonymous,timestamp
192.168.1.1:8080,http,working,0.523,192.168.1.1,United States,New York,true,2024-01-01T12:00:00Z

192.168.1.1:8080 - 可用 (响应时间: 0.523s)
192.168.1.2:8080 - 不可用 (连接超时)
192.168.1.3:1080 - 可用 (响应时间: 1.234s)

export PROXY_CHECKER_TIMEOUT=15
export PROXY_CHECKER_CONCURRENCY=30
export PROXY_CHECKER_USER_AGENT="Custom User Agent"

{
  "timeout": 10,
  "concurrency": 20,
  "retries": 2,
  "methods": ["httpbin", "ipinfo"],
  "user_agent": "ProxyChecker/1.0",
  "max_fails": 5
}

# 创建代理列表
cat > proxies.txt << EOF
192.168.1.1:8080
192.168.1.2:8080
socks5://192.168.1.3:1080
http://user:[email protected]:8080
EOF

# 检查所有代理
python proxy_checker.py -f proxies.txt -v

# 仅检查可用的代理
python proxy_checker.py -f proxies.txt --quiet

# 导出可用代理
python proxy_checker.py -f proxies.txt -o working.json --csv working.csv

# 与 curl 配合使用
curl -s https://example.com/proxies.txt | python proxy_checker.py --quiet

# 与 grep 配合使用
python proxy_checker.py -f proxies.txt | grep "可用"

# 与 jq 配合使用
python proxy_checker.py -f proxies.txt -o results.json
jq '.[] | select(.status=="working")' results.json

from proxy_checker import ProxyChecker

# 初始化检查器
checker = ProxyChecker(
    timeout=10,
    concurrency=20,
    retries=2
)

# 检查单个代理
result = checker.check_proxy("192.168.1.1:8080")
print(result)

# 检查多个代理
results = checker.check_proxies([
    "192.168.1.1:8080",
    "192.168.1.2:8080"
])

# 从文件检查
results = checker.check_file("proxies.txt")

# 导出结果
checker.export_json(results, "output.json")
checker.export_csv(results, "output.csv")

proxy-checker/
├── proxy_checker.py      # 主脚本
├── requirements.txt      # Python 依赖
├── config.json          # 配置文件
├── Dockerfile           # Docker 配置
├── README.md            # 文档
├── LICENSE              # 许可证
└── tests/               # 测试文件
    ├── test_checker.py
    └── test_utils.py

# 增加超时时间
python proxy_checker.py -f proxies.txt -T 30

# 减少并发数
python proxy_checker.py -f proxies.txt -c 10

# 使用多种检测方法
python proxy_checker.py -f proxies.txt -m httpbin,ipinfo,google

在检索到的上下文到达模型之前对其进行扫描：```python
res = shield.protect(user_prompt, my_llm, context=retrieved_docs)
if res.action == "block":
    ...   # a poisoned document was caught before the model saw it

将决策一次性接入日志记录，每次调用都会被记录：```python
from reasongate import Shield, log_sink, file_sink

shield = Shield(audit_hook=log_sink)                    # -> "reasongate.audit" logger
shield = Shield(audit_hook=file_sink("audit.jsonl"))    # -> JSON-Lines, SIEM-ready

- Shield 关闭，投毒记录：记录被发送给攻击者，并触发一次转账。
  这些是真实的副作用，已写入磁盘。
- Shield 开启，投毒记录：间接扫描在模型被调用之前捕获了载荷。无副作用。
- Shield 开启，干净记录：代理正常应答。
- Shield 开启，**改写后的**攻击：载荷被改写为一条普通的业务备注，因此签名层*不会*匹配它——然而仍然没有发生副作用，因为动作门（见下文）阻止了工具调用：其目标（外泄地址、账户）引自不可信内容，这是任何改写都无法隐藏的。

要清楚每一层的作用。签名匹配有一个真实的局限：把注入改写得不匹配任何已知模式，规则核心就抓不到它——这就是为什么核心只是第一道过滤器，而不是边界。第四次运行是对这一局限的诚实回答：它不假装检测能力有所提升；检测仍然漏掉改写后的攻击。阻止入侵的是一个*不同的*层，它推理的是动作背后数据的可信度，而不是文本的措辞。所有四个条件都作为 CI 不变量强制执行，因此演示不会悄悄退化。

还有一个在线演练场：<https://reasongate-demo-nvgo.onrender.com>。它运行零依赖核心，不需要 API 密钥，也不会把任何数据发送到服务器之外。

## 核心中的检测器

- **规范化 / 去混淆。** 去除零宽字符、西里尔同形字、leet 语（`1gn0re`）、带空格和点分隔的字母（`i.g.n.o.r.e`）以及 base64 载荷，因此被伪装的已知措辞会被规范化回模式层能够匹配的形式。
- **注入 / 越狱模式。** 针对已知措辞的规则层。
- **间接注入。** 在检索到的文档和工具输出到达模型之前，对它们运行同样的扫描。
- **输出泄露与金丝雀。** 在输出路径上标记机密和 PII。在系统提示中植入的金丝雀令牌使系统提示泄露可被证明，而不是靠猜测。

策略引擎用经过校准的 noisy-OR 融合这些信号，因此多个弱信号可以累加为一次阻断，而来自合法提示的孤立噪声则不会。

## 动作门（代理工具调用）

检测器问的是“这段文本是注入吗？”——一个可能因改写而失守的问题。动作门问的是一个不同的、与措辞无关的问题：*鉴于产生该动作的数据的可信度，这个动作可以继续吗？* 这是针对间接注入的基于能力的防御——打破不可信内容、敏感能力与出路构成的“致命三要素”——并且它能抓住签名层漏掉的改写攻击。```python
from reasongate import ToolGate, ToolPolicy, Segment

gate = ToolGate([
    ToolPolicy("transfer_funds", sensitive=True, destination_args=("to_account",)),
    ToolPolicy("send_email",     sensitive=True, destination_args=("to",)),
])

record = Segment(text=retrieved_doc, source="crm", trust="untrusted")
decision = gate.authorize(
    {"name": "transfer_funds", "args": {"to_account": "9900", "amount": "$84,200"}},
    context=[record],
)
decision.allowed       # False — the destination account is quoted from untrusted content
print(decision.explain())

授权并不能洗白被污染的终点：`authorized=True` 会清除共现，因为主体请求了该操作——但它不会清除可追溯到不可信内容的参数值，因为主体并未选择该值。

### 将其接入现有 agent```python
from reasongate.adapters.toolcalls import from_anthropic, refusal_result
from reasongate.catalog import infer_policies, describe

print(describe(infer_policies([t["name"] for t in tools])))   # draft policies, then correct them

for call in from_anthropic(response.content):
    decision = session.authorize(call)
    if not decision.allowed:
        results.append(refusal_result(call, decision))        # the model is told why
    else:
        results.append(run(call))

**此包不附带任何模型评判器。** 判断一句话是否与散文策略冲突需要模型；未配置时，门禁返回*“未评估”*而非允许，因为未经检查的请求绝不能看起来像已放行的请求。模型评判器本身也是注入目标，而这是建议性的——无法被争辩的那一层是 `ToolGate`，它约束智能体可以*做什么*。

### 在 AgentDojo 上的测量

该门禁现在有了自己的数字，基于为此威胁构建的基准（[AgentDojo](https://github.com/ethz-spylab/agentdojo)：四个使用工具的智能体套件，通过智能体读取的数据进行攻击）。循环中没有模型——基准自身的真实工具序列作为完全被劫持的智能体通过门禁重放，AgentDojo 自己的检查器对结果评分：

| | 攻击成功率 | 干净流量上的效用 |
|---|---:|---:|
| 无门禁 | 97.4% | 100% |
| 仅参数污点 | **12.6%** | 64.9% |
| 严格（共现） | 3.4% | 41.2% |

在循环中有模型的情况下（Claude Haiku 4.5，银行），情况更加清晰：模型自行拒绝了每一次注入，因此门禁没有增加安全性，却损失了 12.5 个百分点的效用——为模型判断失败的情况提供保险，明码标价。请同时阅读两列。门禁损失的 35 个百分点的效用是智能体从商店读取的合法目的地——它被要求支付的账单上的 IBAN——污点无法将其与同一文件中攻击者的 IBAN 区分开，因为它不看文字。漏过的是三种有记录的形式：目标是读取、目的地是查找而非引用、以及非目的地字段中的危害。方法、各套件数字和注意事项：[RESULTS.md → The gate on AgentDojo](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md#the-gate-on-agentdojo)。

这一层背后的推理——威胁模型、为什么文本检测在结构上不足，以及门禁的保证*和非保证*——写在 [docs/threat-model.md](https://github.com/cgrtml/reasongate/blob/main/docs/threat-model.md) 中。它仍然遗漏的内容，经过测量并从真实语料库中引用，见 [docs/coverage-gaps.md](https://github.com/cgrtml/reasongate/blob/main/docs/coverage-gaps.md)。

## 基准测试

完整方法、测试框架和负面结果见 [RESULTS.md](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md)。三个数字值得一起阅读：它过度拦截了什么、它捕获了什么，以及每次请求的成本。

**过度防御。** 许多防护会过度拦截仅仅包含*ignore*、*system* 或 *bypass* 等触发词的良性提示。在 [NotInject](https://huggingface.co/datasets/leolee99/NotInject)（339 个良性但充满触发词的提示）上，规则核心的**误报率为 0.0%**，离线良性准确率为 100%。

**已知模式的规避召回率。** 当已知攻击被混淆时，归一化能恢复大部分：

| | 规避下的召回率 | FPR | F1 |
|---|---:|---:|---:|
| 仅正则 | 21.2% | 3.3% | 0.349 |
| 核心（归一化 + 间接） | 78.1% | 6.7% | 0.871 |

这是对*核心已经知道的模式的混淆变体*的召回率。这不是对新表述的召回率——那是上面提到的 0% 数字。

**每次请求的成本。** 使用 `eval/latency.py` 测量（每条调用路径的 p50/p95，Apple M3 Pro）：

| 输入 | p50 | p95 |
|---|---:|---:|
| 聊天提示（60 字符） | 0.178 ms | 0.202 ms |
| 2 KB 文档，干净 | 8.51 ms | 8.94 ms |
| 50 KB 文档，干净（输入上限） | 211 ms | 216 ms |
| `ToolGate.authorize`（一次工具调用，任意大小） | 0.020 ms | 0.021 ms |

一个进程处理约 5,400 个聊天提示/秒，且核心不持有状态，因此它随进程数扩展。部署前值得了解的部分：**输入路径与输入长度呈线性关系——干净文档约每 KB 4.2 ms，一旦模式已经匹配则为 1.7 ms。** 在聊天规模下，这比基于模型的防护（ProtectAI deberta-v3，约 116 ms）便宜约 650 倍；在 50 KB 时则*更差*，因为 transformer 在 512 个 token 处截断，而我们扫描全部内容。交叉点大约在 25 KB——门禁整个文档就要为它们付出代价。动作门禁没有这个特性：它读取工具参数和片段信任，而不是散文，因此任何大小下都是免费的。

**ML 检测器（单独的附加组件）。** 基于嵌入的分类器处理规则核心无法处理的自然表述攻击。这些是它的数字，不是核心的：

| 设置 | 召回率 | FPR | F1 |
|---|---:|---:|---:|
| 留出测试（约 5.5k，合并真实数据） | 96.1% | 0.3% | 0.978 |
| 5 折交叉验证 | 95.5% ± 0.8 | 2.5% ± 1.3 | 0.963 ± 0.010 |
| 分布外（训练 A+B，测试未见过的 C） | 87.6% | 10.9% | 0.882 |

数据：`deepset/prompt-injections`、`jackhhao/jailbreak-classification`、`xTRam1/safe-guard-prompt-injection`。一个值得说明的负面结果：早期在合成数据上训练的模型得分为 0.98 F1，但消融实验显示仅标点和大小写就达到 0.96——该分数是数据生成器的产物。可解释分类器正是揭示这一点的东西。分布外从 0.97 下降到 0.88 是真正的泛化数字：它会退化，但不会崩溃。

复现其中任何一项——按每个脚本实际需要的内容分组，因为自 0.2.0 起，训练模型位于附加组件中，只有规则核心基准测试单独针对此仓库运行：```bash
# Offline, no key, no add-on — runs against this repo as-is:
python eval/public_bench.py     # over-defense on NotInject (339 benign)
python eval/adversarial.py      # evasion robustness of the rule core
python eval/latency.py          # cost per request: p50/p95/p99 and throughput

# Needs `pip install reasongate[eval]` and a VOYAGE_API_KEY (embeddings):
python eval/pipeline_real.py    # train/val/test with a validation-tuned threshold
python eval/validate.py         # leakage check, trivial baselines, 5-fold CV, 5x2cv

# Needs the enterprise add-on (the trained model moved there in 0.2.0):
python eval/ood_test.py         # out-of-distribution generalization
python eval/head_to_head.py     # vs ProtectAI deberta-v3

# Needs `pip install agentdojo` (Python 3.10+), no key — the action gate on AgentDojo:
python eval/agentdojo_gate.py   # ASR and utility, gate off / taint / strict