DikaArdnt/safesurf-php
GitHub: DikaArdnt/safesurf-php
一个用于检查 URL 安全性的 PHP 库，通过域名、DNS、TLS、页面内容及威胁情报等多维度分析，输出评分和判定原因。
Stars: 2 | Forks: 0
# SafeSurf（PHP 库）
## 免责声明
本项目是对仓库 [abhizaik/urlvet](https://github.com/abhizaik/urlvet) 的原生 PHP 重写。
SafeSurf for PHP 侧重于透明的分析结果（原因）、评分和判定。
## 功能
- 实时 URL 分析：重定向链、HTTP 状态、HSTS
- 域名与 DNS 信号：排名（top-1m）、IP 解析、NS/MX 有效性
- URL 信号：关键词、URL 缩短器、过长/过深、子域名数量、punycode
- TLS/SSL 信号：TLS 存在性、颁发者、证书年龄、链验证（尽力而为）
- 页面内容（尽力而为）：标题、登录/支付/个人表单检测、隐藏 iframe、品牌不匹配
- 威胁情报源：PhishTank（可选，取决于 API 可用性）
- 可选缓存：通过 phpfastcache 加速网络查询和数据解析
## 系统要求
- PHP >= 8.0
- PHP 扩展：`curl`、`openssl`、`dom`、`libxml`
## 安装（通过 Composer / Packagist）
```
composer require safesurf/safesurf
```
## 安装（从此源码仓库）
```
git clone https://github.com/DikaArdnt/safesurf-php.git
cd safesurf-php
composer install
```
## 快速开始
```
php examples/analyze.php example.com
```
## 在你的代码中使用（无缓存）
```
__DIR__ . '/storage/cache',
]));
$config = new Config(cache: new PhpFastCacheAdapter($pool));
$result = SafeSurf::analyze('https://example.com', $config);
echo json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) . PHP_EOL;
```
## 配置
主配置文件位于 [Config.php](./src/Config.php)。最常用的字段包括：
- `cache`：缓存实现（可选）。现成适配器：[PhpFastCacheAdapter.php](./src/Cache/PhpFastCacheAdapter.php)
- `rankCsvPath`：`assets/top-1m.csv` 的路径，用于排名查询
- `publicSuffixListPath`：PSL 路径（`storage/public_suffix_list.dat`），用于提取可注册域名和 TLD
- `httpTimeoutMs`、`httpHeaderTimeoutMs`、`maxRedirects`、`userAgent`：HTTP 请求控制
- 缓存 TTL：`ttlDomainRankSeconds`、`ttlIpResolutionSeconds`、`ttlDnsValiditySeconds`、`ttlWhoisSeconds`、`ttlHttpCombinedSeconds`、`ttlTlsCombinedSeconds`、`ttlContentSeconds`、`ttlAnalyzeResultSeconds`
- PhishTank（可选）：`phishTankApiKey`、`phishTankUserAgent`
## 输出（结果结构）
`SafeSurf::analyze()` 返回一个适合 `json_encode()` 的数组：
- `url`、`domain`
- `features`
- `rank`
- `tld`：包含 `tld`、`is_trusted_tld`、`is_risky_tld`、`is_icann`
- `url`：包含 `url_shortener`、`uses_ip`、`contains_punycode`、`too_long`、`too_deep`、`has_homoglyph`、`subdomain_count`、`keywords`
- `infrastructure`：包含 `ip_addresses`、`nameservers_valid`、`ns_hosts`、`mx_records_valid`、`mx_hosts`
- `domain_info`：RDAP/WHOIS 结果（若查询失败可能为 `null`）
- `analysis`：重定向链、HTTP 状态、HSTS
- `ssl_info` 和 `tls_info`：TLS/SSL 摘要
- `content_data`：HTML 解析摘要（可能为 `null`）
- `domain_randomness`：域名标签的熵/随机性结果
- `typosquat_result`：域名抢注/组合抢注结果
- `phishing`：PhishTank 检查结果（可能为 `null`）
- `result`：最终分数、判定和原因
- `performance`：总耗时和计时列表
- `incomplete`、`errors`：若部分任务失败（网络/超时）则存在
## 安全与操作说明
- SSRF 防护：HTTP 请求会解析 IP，并拒绝目标主机/IP 的私有、链路本地和回环 IP。
- TLS/SSL 验证为尽力而为：某些环境下因 CA 证书库或配置问题可能无法验证链。
- 部分模块需要互联网访问（IANA RDAP 引导、PSL 下载、PhishTank）。
- 内容分析会执行 请求和 HTML 解析；建议启用缓存以减少负载。
## 开发
运行测试：
```
cd safesurf-php
vendor/bin/phpunit
```
## 许可证
MIT 许可证。详见 [LICENSE](./LICENSE)。
标签：Composer, DNS检测, ffuf, HSTS, IP解析, MX检测, NS检测, PhishTank集成, PHP库, Punycode检测, Sigma 规则, TLS/SSL检测, URL安全检查, 关键字检测, 域名分析, 域名排名, 威胁情报, 实时URL分析, 开发者工具, 恶意网址检测, 短链接检测, 缓存支持, 网络安全, 表单检测, 证书验证, 重定向分析, 钓鱼检测, 隐私保护, 隐藏iframe检测, 页面内容分析