Infrastructure Scanning Guide

Note: Scanning is an asynchronous operation. You must make one request to start the scan and a second to retrieve the results. See the Async Operations & Jobs guide

‍

Core Endpoints

• POST /v1/ops/scan: Initiates a new infrastructure scan.
• GET /v1/ops/jobs/{jobId}: Poll this endpoint to get the status and results of your scan.

Workflow & Example

‍

Step 1: Initiate the Scan

‍

Make a POST request specifying the domain and the type of scan. A comprehensive scan is recommended for a full assessment.

‍

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domain": "example.com", "type": "comprehensive"}' \
     "https://api.whisper.security/v1/ops/scan"

‍

The API will immediately return a 202 Accepted response with a job object, indicating the scan has been queued.

‍

Initial Response:

‍

{
  "id": "77fd1a87-c337-4967-ba9f-cdf4cc894d03",
  "status": "PENDING",
  "type": "infra_scan",
  ...
}

‍

Step 2: Poll for and Retrieve Results

‍

Poll the GET /v1/ops/jobs/{jobId} endpoint until the status field changes to COMPLETED or FAILED. A successful, completed job response will look like this:

‍

{
  "id": "77fd1a87-c337-4967-ba9f-cdf4cc894d03",
  "status": "COMPLETED",
  "type": "infra_scan",
  "params": {
    "domain": "example.com",
    "scanType": "comprehensive",
    ...
  },
  "result": {
    "domain": "example.com",
    "scanType": "comprehensive",
    "status": "completed",
    "subdomains": [],
    "dns": null,
    "ssl": {
      "hasSSL": true,
      "protocol": "TLSv1.3",
      "cipher": "TLS_AES_256_GCM_SHA384",
      "issuer": "Let's Encrypt",
      "validFrom": "2024-01-01T00:00:00Z",
      "validTo": "2025-01-01T00:00:00Z",
      "daysRemaining": 90,
      "isValid": true
    },
    "technologies": [
      {"category": "Web Server", "name": "nginx", "version": "1.21.0"},
      {"category": "Programming Language", "name": "PHP", "version": "8.0"},
      {"category": "CMS", "name": "WordPress", "version": "6.0"},
      {"category": "Analytics", "name": "Google Analytics"},
      {"category": "CDN", "name": "Cloudflare"}
    ],
    "whois": {
      "registrar": "RESERVED-Internet Assigned Numbers Authority",
      "registrant": "",
      "createdDate": "1995-08-14",
      "expiryDate": "2023-08-13",
      "updatedDate": "2022-08-14",
      "nameServers": ["a.iana-servers.net", "b.iana-servers.net"]
    },
    "summary": {
      "subdomainCount": 0,
      "dnsRecordCount": 0,
      "technologyCount": 5,
      "hasSSL": true
    }
  },
  "progress": {"current": 5, "total": 5, "message": "WHOIS scanned", "percentage": 100.0},
  "createdAt": "2025-11-06T11:24:43.914Z",
  "completedAt": "2025-11-06T11:24:45.190Z",
  ...
}

‍

Understanding the Scan Result

‍

The result object contains all findings:

• ssl: Full details on the SSL/TLS certificate, including issuer, validTo, and daysRemaining.

• technologies: An array of all detected technologies, categorized by category, name, and version.

• whois: Key WHOIS registration data, including registrar, createdDate, expiryDate, and nameServers.

• summary: A high-level count of discovered assets.

• subdomains & dns: (null in this example) Would be populated with discovered subdomains and DNS records.

Scan Types

‍

You can request different scan types for more targeted analysis. The available types are:

• comprehensive: (Default) Runs all modules.
• subdomains: Subdomain enumeration only.
• ports: Port scanning and service detection.
• technologies: Technology stack detection.
• vulnerabilities: Known vulnerability checks.
• ssl: SSL/TLS configuration analysis.
• dns: DNS configuration tests.
• whois: Registration information.

API Reference

‍

For full details, see the API Reference:

• Infrastructure Scan: POST /v1/ops/scan
• Get Job Status: GET /v1/ops/jobs/{jobId}

‍

‍

‍

‍

‍