مرجع المطورين

عامل اكتشاف النطاقات الفرعية

استكشف توثيق API الخاص بـ عامل اكتشاف النطاقات الفرعية، بما في ذلك معلمات الطلب وحقول الاستجابة وأمثلة الشفرة ومعالجة الأخطاء لتكاملات DomScan.

عامل اكتشاف النطاقات الفرعية

لا. هذه تغطية سلبية على قدر ما تتيحه المصادر. لن تظهر الأسماء الداخلية ولا المضيفون العامون الغائبون عن مجموعات بيانات المصادر، كما أن التحقق عبر DNS لا يبحث عن أسماء إضافية.

استخدم GET /v1/subdomains?domain=example.com&sources=ct. تختار القيمة ct مسار التوافق، بينما يعرض كل إدخال مصدر دليله الفعلي. تُرجع الطلبات المقيدة بالتخزين المؤقت 202 عند عدم وجود نتيجة، وتُرجع الواجهة 503 عند فشل كل المصادر. تُرد الأرصدة في الحالتين.

GET /v1/subdomains

معاملات الاستعلام

المعاملالنوعDescription
domain مطلوب string النطاق الجذري للعثور على النطاقات الفرعية (مثال: "github.com")
prefer_cache اختياري boolean token إرجاع النتائج المخزنة مؤقتًا فقط. إذا لم توجد بيانات حديثة أو قديمة في التخزين المؤقت، تُرجع الواجهة 202 وتضع تحديثًا في الخلفية في قائمة الانتظار وترد أرصدة الطلب. القيم المقبولة: true وfalse و1 و0 وyes وno. القيمة الافتراضية: false.
sources اختياري string محدد للتوافق. لا تُقبل إلا القيمة ct. تبدأ هذه القيمة مسار الاكتشاف السلبي، لكن كل نتيجة تعرض مزود الدليل: crtsh أو crtname أو hackertarget أو threatminer أو wayback أو certspotter. قد تعرض نتائج التخزين المؤقت القديمة القيمة ct.
verify اختياري boolean token يفحص DNS للأسماء المختارة مسبقًا للاستجابة فقط. لا يكتشف التحقق أسماء إضافية. القيم المقبولة: true وfalse و1 و0 وyes وno. القيمة الافتراضية: false.
include_wildcards اختياري boolean token يُرجع أدلة شهادات أحرف البدل في مصفوفة wildcards منفصلة. لا تختلط أحرف البدل بنتائج أسماء المضيفين المحددة. القيم المقبولة: true وfalse و1 و0 وyes وno. القيمة الافتراضية: false.
limit اختياري integer الحد الأقصى لسجلات أسماء المضيفين المحددة التي ستُرجع. أدخل عددًا صحيحًا من 1 إلى 2000. القيمة الافتراضية: 500.
cursor اختياري string قيمة next_cursor من الصفحة السابقة. راجع ترقيم الصفحات.

حالات الاستخدام

  • رسم سطح الهجوم وتدقيقات الأمان
  • راجع أسماء المضيفين التي قد تكون منسية أو تابعة لتقنية معلومات الظل
  • التدقيق التقني قبل الاستحواذ
  • تحليل البنية التحتية التنافسي
  • استطلاع مكافآت الأخطاء

حقول الرد

الحقلDescription
subdomains[].nameاسم المضيف المُرجع. قد يظهر النطاق الأساسي إذا كان المصدر يتضمنه.
subdomains[].sourceراجع أدلة أسماء المضيفين العامة مع توضيح مصدر كل دليل
subdomains[].first_seenتعرض الإدخالات المدعومة ببيانات CT أقدم قيمة not-before عُثر عليها في الشهادات. وقد تُرجع إدخالات المصادر السلبية البديلة null.
subdomains[].verifiedتكون القيمة true فقط عند تفعيل verify ونجاح حل DNS (A أو AAAA أو CNAME) لاسم المضيف المُرجع. وتكون null عند تفعيل verify دون أن يجيب DNS في الوقت المناسب. وتكون false في غير ذلك.
subdomains[].dns_recordsسجلات A وAAAA وCNAME الناتجة عن التحقق الاختياري من اسم المضيف المُرجع، أو null. لا يضيف هذا الحقل أسماء إلى النتيجة.
summary.total_foundإجمالي سجلات أسماء المضيفين المحددة التي عُثر عليها قبل تطبيق حد الاستجابة، بما فيها النطاق الأساسي إذا تضمنه المصدر.
summary.verified_countعدد أسماء المضيفين المُرجعة التي نجح حلها أثناء التحقق الاختياري عبر DNS.

رموز حالة HTTP

رموز حالة HTTPDescription
200 OKنجح الطلب
202 مقبولتم قبول عدم العثور على نتيجة مخزنة مؤقتًا للنطاقات الفرعية في وضع التخزين المؤقت فقط لتحديثها في الخلفية. لا تُخصم أي أرصدة؛ أعد المحاولة بعد مدة Retry-After.
400 طلب غير صالحمعلمات غير صالحة
402 الدفع مطلوبلا توجد أرصدة كافية لتنفيذ هذا الطلب.
503 الخدمة غير متاحةالخدمة الخلفية غير متاحة أو تفرض تحديد معدل مؤقتًا.
504 انتهت مهلة البوابةانتهت مهلة الطلب إلى الخدمة الخلفية.

طلب مثال

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&sources=ct&include_wildcards=yes&limit=100"

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&sources=ct&verify=yes&limit=50"

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&prefer_cache=1"
import requests

domscan = requests.Session()
domscan.headers.update({"X-API-Key": "your-api-key"})

response = domscan.get(
    "https://domscan.net/v1/subdomains",
    params={
        "domain": "example.com",
        "sources": "ct",
        "verify": "yes",
        "include_wildcards": "yes",
        "limit": 100
    }
)
data = response.json()

print(f"Returned {data['summary']['returned']} hostname entries")
print(f"Verified: {data['summary']['verified_count']}")

live_subs = [s for s in data['subdomains'] if s['verified']]
for sub in live_subs[:10]:
    print(f"  {sub['name']}")
const domscanFetch = (url, options = {}) =>
  fetch(url, {
    ...options,
    headers: { ...options.headers, "X-API-Key": "your-api-key" },
  });

const response = await domscanFetch(
  'https://domscan.net/v1/subdomains?' + new URLSearchParams({
    domain: 'example.com',
    sources: 'ct',
    verify: 'yes',
    include_wildcards: 'yes',
    limit: '100'
  })
);
const data = await response.json();

console.log(`Returned ${data.summary.returned} hostname entries`);
console.log(`Verified: ${data.summary.verified_count}`);

data.subdomains
  .filter(s => s.verified)
  .forEach(s => console.log(`  ${s.name}`));

مثال الرد

{
  "domain": "example.com",
  "subdomains": [
    {
      "name": "api.example.com",
      "source": "crtsh",
      "first_seen": "2025-01-15T00:00:00Z",
      "verified": true,
      "dns_records": {
        "A": ["192.0.2.10"],
        "CNAME": null
      }
    }
  ],
  "wildcards": [
    {
      "pattern": "*.example.com",
      "source": "crtsh",
      "first_seen": "2024-11-20T00:00:00Z"
    }
  ],
  "summary": {
    "total_found": 1,
    "returned": 1,
    "verified_count": 1,
    "unverified_count": 0,
    "sources_used": ["crtsh"],
    "apex_included": false,
    "wildcard_suppressed_count": 1,
    "wildcard_returned_count": 1
  },
  "intelligence_summary": {
    "data_sources": ["crtsh"],
    "source_count": 1,
    "cache_status": "live",
    "returned_count": 1,
    "total_found": 1,
    "truncated": false,
    "limit": 100,
    "verification_requested": true,
    "include_wildcards": true,
    "verified_count": 1,
    "verified_ratio": 1,
    "live_dns_record_count": 1,
    "apex_included": false,
    "wildcard_suppressed_count": 1,
    "wildcard_returned_count": 1,
    "first_seen_oldest": "2025-01-15T00:00:00Z",
    "first_seen_newest": "2025-01-15T00:00:00Z",
    "warning_count": 0
  },
  "meta": {
    "query_time_ms": 184,
    "cached": false
  }
}

202 مقبول

{
  "status": "pending",
  "code": "CACHE_MISS_REFRESH_QUEUED",
  "message": "Try again in a moment",
  "domain": "example.com",
  "retry_after": 30,
  "credits_charged": 0,
  "billing_status": "not_charged",
  "request_id": "m8abc12-x9y8"
}
POST /v1/subdomains/bulk الرصيد: 4-5/item

معاملات الاستعلام

المعامل النوع مطلوب
dry_run string
القيم المسموحة true
اختياري

معاملات متن الطلب

المعامل النوع مطلوب
domains string[] مطلوب
verify boolean
الافتراضي false
اختياري
include_wildcards boolean
الافتراضي false
اختياري
limit integer
الافتراضي 500
اختياري

حقول الرد

الحقل النوع
results[] unknown[]
meta object
meta.total integer
meta.succeeded integer
meta.failed integer
meta.max_items integer
meta.credits_per_item integer
meta.duration_ms integer

طلب مثال

curl -X POST "https://domscan.net/v1/subdomains/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "domains": [
    "example.com",
    "cloudflare.com"
  ],
  "verify": false,
  "limit": 500
}'
const response = await fetch("https://domscan.net/v1/subdomains/bulk", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "domains": [
      "example.com",
      "cloudflare.com"
    ],
    "verify": false,
    "limit": 500
  }),
});
const data = await response.json();
console.log(data);
import os
import requests

response = requests.post(
    "https://domscan.net/v1/subdomains/bulk",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "domains": [
            "example.com",
            "cloudflare.com",
        ],
        "verify": False,
        "limit": 500,
    },
)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "domains": [
	    "example.com",
	    "cloudflare.com"
	  ],
	  "verify": false,
	  "limit": 500
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/subdomains/bulk", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status, string(data))
}
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/subdomains/bulk")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "domains" => [
    "example.com",
    "cloudflare.com"
  ],
  "verify" => false,
  "limit" => 500
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.pretty_generate(JSON.parse(response.body))

مثال الرد

{
  "results": [
    {
      "input": "example",
      "data": {}
    }
  ],
  "meta": {
    "total": 1,
    "succeeded": 1,
    "failed": 1,
    "max_items": 10,
    "credits_per_item": 1,
    "duration_ms": 1
  }
}

رموز حالة HTTP

  • 200 OK
  • 400 طلب غير صالح
  • 401 غير مصرح
  • 402 الدفع مطلوب
  • 409 HTTP 409
  • 422 HTTP 422
  • 429 طلبات كثيرة جداً