id: urlscan
name: urlscan.io
version: 1.0.0
description: "urlscan.io (API v1) — submit URLs for scanning, retrieve scan results (verdicts, page metadata, screenshot and DOM references) and search historical scans. API-key authentication; stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: URL submission, result retrieval and historical search."
category: enrichment

config_schema:
  properties:
    api_key:
      type: string
      description: "urlscan.io API key"
      x-soar-sensitive: true
  required:
    - api_key

commands:
  - id: submit
    name: urlscan-submit
    description: "Submit a URL for scanning. Returns a scan UUID; retrieve the report with urlscan-get-result once the scan finishes (usually ~10-30s)."
    inputs_schema:
      properties:
        url: { type: string, description: "URL to scan" }
        visibility: { type: string, description: "public, unlisted or private (default public)" }
        tags: { type: string, description: "Comma-separated tags to attach to the scan" }
      required: [url]
    outputs_schema: { properties: {} }
  - id: get_result
    name: urlscan-get-result
    description: "Retrieve the result of a completed scan by UUID (404 while the scan is still running)."
    risk: read
    inputs_schema:
      properties:
        uuid: { type: string, description: "Scan UUID (from urlscan-submit)" }
      required: [uuid]
    outputs_schema: { properties: {} }
  - id: search
    name: urlscan-search
    description: "Search historical scans with a query (e.g. domain:example.com, ip:1.2.3.4)."
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "urlscan search query" }
        size: { type: number, description: "Maximum results (default 20, max 10000)" }
        search_after: { type: string, description: "Pagination cursor (sort values from the previous page, comma-separated)" }
      required: [query]
    outputs_schema: { properties: {} }

  - id: test_connection
    name: urlscan-test-connection
    description: "Verify the API key (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }