​

Scanners

​

What Scanners Actually Monitor

• scanners run on an hourly schedule
• the window is based on indexed_at, not pwned_at
• historical data is not replayed when you create a scanner
• material query changes reset the baseline and begin monitoring from the update time

​

Scanner Types

​

Query Config Rules

• allowed flat filters depend on scanner_type
• filter and filter_id are supported
• canonical JSON keys such as domain, email_domain, dbname, and username are preferred
• bracketed variants such as domain[] are also accepted
• runtime-only parameters are rejected because scanners manage them automatically:
  • from
  • to
  • cursor
  • page_size
  • format
  • debug
  • search_id
• scanners always search with date_field=indexed_at
• scanner configs must contain a durable search anchor, such as a concrete domain, email domain, dbname, username, password hash, log ID, or structured filter leaf
• wildcard-only, filter_id-only, or extra_params-only configs are rejected because they are not stable enough for hourly monitoring

• if the scanner can be described with exact-match fields, keep query_config flat
• if the scanner needs or, contains, exists, ranges, or nested groups, use query_config.filter

​

Notifications

​

Webhook Security Modes

• signed_json Default mode for new custom webhook scanners. OathNet signs the raw request body with the shared secret.
• signed_encrypted Signed and encrypted delivery for custom webhook scanners. OathNet signs the encrypted body and includes key metadata in headers.
• api_key Available only on existing scanners. New scanners should use signed delivery.

• only http and https are allowed
• IP addresses are rejected
• localhost and private-network hostnames are rejected
• Discord scanners must use a Discord webhook URL

​

Creating a Scanner

{
  "name": "Example breach monitor",
  "scanner_type": "breach",
  "query_config": {
    "filter": {
      "and": [
        { "field": "email_domain", "operator": "eq", "value": "example.com" },
        { "field": "dbname", "operator": "in", "value": ["twitter.com", "linkedin.com"] }
      ]
    }
  },
  "notification_type": "webhook",
  "webhook_url": "https://alerts.example.com/oathnet",
  "webhook_security_mode": "signed_json",
  "notify_on_zero_results": false
}

​

Delivery Payload

{
  "event": "scanner.results_found",
  "scanner": {
    "uid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example breach monitor",
    "type": "breach",
    "query_config": {
      "email_domain[]": ["example.com"]
    }
  },
  "run": {
    "uid": "660e8400-e29b-41d4-a716-446655440001",
    "search_from": "2026-04-18T00:00:00Z",
    "search_to": "2026-04-18T01:00:00Z"
  },
  "results": {
    "total_count": 5,
    "sample_count": 1,
    "sample": [
      {
        "email": "user@example.com",
        "dbname": "twitter.com",
        "indexed_at": "2026-04-18T00:45:00Z"
      }
    ]
  },
  "search_url": "https://oathnet.org/search?...",
  "timestamp": "2026-04-18T01:00:00Z"
}

​

Verifying Webhook Signatures

<timestamp>.<delivery_id>.<raw_body>

sha256=<hex_hmac_sha256>

​

Python Receiver Example

import hashlib
import hmac

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.hkdf import HKDF


def _derive_signing_key(secret: str) -> bytes:
    return HKDF(
        algorithm=hashes.SHA256(),
        length=32,
        salt=None,
        info=b"oathnet-scanner-signing-v1",
    ).derive(secret.encode("utf-8"))


def verify_oathnet_signature(headers: dict[str, str], raw_body: bytes, secret: str) -> bool:
    timestamp = headers["x-oathnet-timestamp"]
    delivery_id = headers["x-oathnet-delivery-id"]
    provided = headers["x-oathnet-signature"]

    message = timestamp.encode("utf-8") + b"." + delivery_id.encode("utf-8") + b"." + raw_body
    digest = hmac.new(_derive_signing_key(secret), message, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"
    return hmac.compare_digest(expected, provided)

​

Node.js Receiver Example

import { createHmac, hkdfSync, timingSafeEqual } from "node:crypto";

function verifyOathNetSignature(
  headers: Record<string, string>,
  rawBody: Buffer,
  secret: string
): boolean {
  const timestamp = headers["x-oathnet-timestamp"];
  const deliveryId = headers["x-oathnet-delivery-id"];
  const provided = headers["x-oathnet-signature"];

  const key = hkdfSync(
    "sha256",
    Buffer.from(secret, "utf8"),
    Buffer.alloc(0),
    Buffer.from("oathnet-scanner-signing-v1"),
    32
  );
  const message = Buffer.concat([
    Buffer.from(`${timestamp}.${deliveryId}.`, "utf8"),
    rawBody
  ]);
  const expected = `sha256=${createHmac("sha256", key).update(message).digest("hex")}`;

  return (
    provided.length === expected.length &&
    timingSafeEqual(Buffer.from(provided), Buffer.from(expected))
  );
}

​

Management Operations

• quota tells you how many scanners the account can still create
• test delivery sends a sample notification without waiting for the schedule
• manual trigger queues a real run for an active scanner
• pause stops scheduling without deleting the scanner
• resume restarts a paused or disabled scanner after the issue is fixed
• run history shows recent execution and notification outcomes
• run detail explains one specific run and its delivery attempts

​

Troubleshooting

​

No results found

• scanners only look for newly indexed data after the current baseline
• use regular search endpoints to inspect historical data
• verify that query_config contains valid filters for the scanner type
• verify that structured filters target allowed fields for that scanner type

​

Not receiving notifications

• run a delivery test before waiting for the hourly schedule
• check the saved webhook security configuration
• inspect run history for delivery failures
• verify the webhook target returns a 2xx response

​

Scanner disabled

• scanners are auto-disabled after repeated failures
• fix the delivery or query issue, then resume the scanner
• check quota and plan access if creation or execution is blocked

​

Scanner Management