DNS 拦截检测 API 对接文档

1. 接口概述

该接口用于检测指定域名是否被安全 DNS 拦截、DNS 污染、DNS 劫持，支持多 DNS 服务商（联通、114 安全、腾讯安全、阿里安全等）并行检测，可返回 JSON 格式的结构化检测结果或 HTML 可视化页面。

2. 接口信息

表格

项⽬	说明
接口地址	`https://api.afmax.cn/so/safety/index.php`
请求方式	GET
数据格式	JSON（参数`j`）/ HTML（参数`r`）
字符编码	UTF-8

3. 请求参数

3.1 核心参数

表格

参数名	是否必填	类型	说明
j	否（JSON 请求必填）	字符串	要检测的域名，传入该参数时接口返回 JSON 格式数据，优先级高于`r`
r	否（HTML 请求必填）	字符串	要检测的域名，传入该参数时接口返回 HTML 可视化页面，仅用于前端展示

3.2 域名格式要求

支持纯域名（如example.com），自动过滤http:///https://等前缀、路径、参数
仅允许包含字母、数字、.、-，长度不超过 253 个字符
示例：so.com、baidu.com、test-domain.com

4. 响应说明

4.1 HTTP 状态码

表格

状态码	说明
200	请求成功
400	缺少域名参数（仅 JSON 请求）

4.2 业务状态码（overall_status_id）

表格

状态码	名称	说明
1	安全	当前域名未见明显安全 DNS 拦截
2	异常	安全 DNS 未正常放行 / 异常，部分 DNS 返回空或异常，可能存在拦截
3	封控	触发安全 DNS 封控，检测到明确的拦截行为
4	未知	检测结果未知（如 DNS 查询超时、降级模式下无数据），建议稍后重试

4.3 JSON 响应结构

{
  "domain": "检测的域名",
  "timestamp": "检测时间（ISO 8601格式，如2025-01-01T12:00:00+08:00）",
  "overall_status_id": "业务状态码（1/2/3/4）",
  "baseline": {
    "dns": "1.1.1.1", // 基准DNS服务器
    "ips": ["基准DNS解析的IP列表"],
    "degraded": false, // 是否启用降级查询模式（dig不可用时）
    "failed": false // 基准DNS查询是否失败
  },
  "summary": {
    "overall_status": "状态标识（safe/suspicious/dangerous/unknown）",
    "overall_status_id": "业务状态码",
    "overall_message": "总体评级说明",
    "total_checked": "检测的DNS服务商数量"
  },
  "results": [
    {
      "name": "DNS服务商名称（如联通-北京）",
      "dns_ip": "DNS服务器IP",
      "ips": ["该DNS解析的IP列表"],
      "blocked_by_ip": false, // 是否命中拦截IP池
      "degraded": false, // 是否启用降级查询模式
      "status": "该DNS检测状态（safe/suspicious/dangerous/unknown）",
      "status_id": "该DNS检测状态码",
      "raw": ["该DNS解析的原始记录"]
    }
  ]
}

5. 请求示例

5.1 JSON 请求示例

GET https://api.afmax.cn/so/safety/index.php?j=so.com

5.2 HTML 请求示例

GET https://api.afmax.cn/so/safety/index.php?r=so.com

6. 响应示例

6.1 JSON 成功响应示例

json

{
  "domain": "so.com",
  "timestamp": "2025-01-01T12:00:00+08:00",
  "overall_status_id": 1,
  "baseline": {
    "dns": "1.1.1.1",
    "ips": ["123.125.81.6"],
    "degraded": false,
    "failed": false
  },
  "summary": {
    "overall_status": "safe",
    "overall_status_id": 1,
    "overall_message": "总体评级：安全",
    "total_checked": 13
  },
  "results": [
    {
      "name": "联通-北京",
      "dns_ip": "123.125.81.6",
      "ips": ["123.125.81.6"],
      "blocked_by_ip": false,
      "degraded": false,
      "status": "safe",
      "status_id": 1,
      "raw": [{"type":"A","ip":"123.125.81.6"}]
    }
  ]
}

6.2 缺少参数响应示例

plaintext

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "缺少域名参数"
}

7. 缓存说明

表格

接口类型	缓存时长	说明
JSON 接口	7 天（604800 秒）	降低服务器压力，如需最新数据可重新请求
HTML 页面	30 天（2592000 秒）	仅前端展示使用，数据与 JSON 接口同步

8. 补充说明

检测规则：基于黑洞 IP、114 劫持白名单、已知拦截 IP 池判断是否被拦截；
检测的 DNS 服务商列表：联通 - 北京、114 - 安全、腾讯 - 安全、阿里 - 安全、百度、Cloudflare - 家庭、Quad9 - 威胁、OpenDNS - 家庭盾、Comodo - 家庭、Yandex - 家庭、AdGuard - 家庭、SafeDNS-Protective、ControlD-Malware；
降级模式：当服务器dig命令不可用时，自动切换为 PHP 内置dns_get_record函数查询，可能影响部分 DNS 服务商的检测精度；
检测结果仅供参考，请勿用于非法用途，开发者需自行承担使用风险。