Port Scanning

The port scanning endpoints let you retrieve scan results showing which ports are open or closed on your server. This is useful for detecting unexpected open ports on any monitor with the port scanning check enabled.

You'll need a monitor ID for these endpoints.

Example request:

$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/monitors/1/ports-history-items \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

All endpoints below follow the same authentication pattern.

Port scan response fields #

Every port scan endpoint returns a scan result object with these fields:

{
  "id": 1,
  "scanned_host": "example.com",
  "expected_open_results": [
    {
      "port": 80,
      "status": "open",
      "response_time_ms": 15,
      "error_message": null
    },
    {
      "port": 443,
      "status": "open",
      "response_time_ms": 12,
      "error_message": null
    }
  ],
  "expected_closed_results": [
    {
      "port": 22,
      "status": "closed",
      "response_time_ms": null,
      "error_message": null
    },
    {
      "port": 3306,
      "status": "open",
      "response_time_ms": 8,
      "error_message": null
    }
  ],
  "issues": [
    {
      "name": "ExpectedClosedPortOpen",
      "ports": [3306]
    }
  ],
  "scan_time_ms": 1250,
  "created_at": "2024-06-15 14:30:00"
}

• id: unique identifier for this scan result
• scanned_host: the hostname that was scanned
• expected_open_results: results for ports expected to be open. Each entry includes port, status, response_time_ms, and error_message
• expected_closed_results: results for ports expected to be closed. Each entry includes port, status, response_time_ms, and error_message
• issues: array of detected issues. Each contains a name and a ports array listing the affected port numbers. Possible issue names: ExpectedClosedPortOpen, ExpectedOpenPortClosed
• scan_time_ms: total time the scan took in milliseconds
• created_at: when this scan was performed (UTC)

Get a specific scan result #

GET /api/monitors/{monitorId}/ports-history-items/{portsHistoryItemId}

Returns a single port scan result by its ID. The response follows the scan result shape above.

List port scan history #

GET /api/monitors/{monitorId}/ports-history-items

Returns a paginated list of port scan results for a monitor. Each item follows the same scan result shape above.

Query parameters:

• filter[created_at] (string, optional) -- only return results created at or after this timestamp in YmdHis format, in UTC (e.g., 20240615000000)