Shodan Scan Then Inspect Host

arazzo: 1.0.1
info:
  title: Shodan Scan Then Inspect Host
  summary: Submit a single-IP scan, poll until done, then pull the fresh host record.
  description: >-
    An end-to-end refresh-and-inspect pattern. The workflow submits an
    on-demand scan for a single IP, polls the scan status until the crawl
    finishes, and then retrieves the freshly updated host record so the latest
    banners and open ports are returned. Every step spells out its request
    inline so the flow can be read and executed without opening the underlying
    OpenAPI description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-620.40
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-620.40
      capability_name: Vulnerability Management
      spec: shodan-on-demand-scanning-api-openapi.yml
      confidence: 0.72
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: onDemandScanningApi
  url: ../openapi/shodan-on-demand-scanning-api-openapi.yml
  type: openapi
- name: searchMethodsApi
  url: ../openapi/shodan-search-methods-api-openapi.yml
  type: openapi
workflows:
- workflowId: scan-then-inspect-host
  summary: Re-crawl a single IP and read back its updated host record.
  description: >-
    Submits an on-demand scan for one IP, polls the scan until it is DONE, then
    retrieves the updated host record for that IP.
  inputs:
    type: object
    required:
    - apiKey
    - ip
    properties:
      apiKey:
        type: string
        description: Shodan API key passed as the `key` query parameter.
      ip:
        type: string
        description: The single IPv4 or IPv6 address to re-crawl and inspect.
  steps:
  - stepId: submitScan
    description: >-
      Request Shodan to crawl the supplied IP, consuming one scan credit.
    operationId: createScan
    requestBody:
      contentType: application/x-www-form-urlencoded
      payload:
        ips: $inputs.ip
    parameters:
    - name: key
      in: query
      value: $inputs.apiKey
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      scanId: $response.body#/id
  - stepId: pollScan
    description: >-
      Poll the scan status endpoint and repeat until the scan reaches the DONE
      state.
    operationId: getScan
    parameters:
    - name: key
      in: query
      value: $inputs.apiKey
    - name: id
      in: path
      value: $steps.submitScan.outputs.scanId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      status: $response.body#/status
    onSuccess:
    - name: scanComplete
      type: goto
      stepId: inspectHost
      criteria:
      - context: $response.body
        condition: $.status == "DONE"
        type: jsonpath
    - name: scanStillRunning
      type: goto
      stepId: pollScan
      criteria:
      - context: $response.body
        condition: $.status != "DONE"
        type: jsonpath
  - stepId: inspectHost
    description: >-
      Retrieve the freshly updated host record for the scanned IP, returning
      the latest indexed services and open ports.
    operationId: getHost
    parameters:
    - name: key
      in: query
      value: $inputs.apiKey
    - name: ip
      in: path
      value: $inputs.ip
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      ports: $response.body#/ports
      vulns: $response.body#/vulns
      lastUpdate: $response.body#/last_update
  outputs:
    scanId: $steps.submitScan.outputs.scanId
    ports: $steps.inspectHost.outputs.ports
    lastUpdate: $steps.inspectHost.outputs.lastUpdate