id: shodan
name: Shodan
version: 1.0.2
description: "Shodan — host & network intelligence: IP enrichment, search, DNS lookups, domain info, and on-demand scanning."
changelog: "1.0.2 — Re-publish to regenerate form-based command scripts (fixes 'script not found' on install). 1.0.1 — Added test_connection for the instance Test button. 1.0.0 — Initial release: host lookup, search, count, DNS resolve/reverse, domain info, api-info, scan status, and active scan."
category: enrichment

config_schema:
  properties:
    base_url:
      type: string
      description: Shodan REST API base URL
      default: https://api.shodan.io
    api_key:
      type: string
      description: Shodan API key (Account → API key)
      x-soar-sensitive: true
  required:
    - api_key

# Shodan authenticates with the API key as the `key` query parameter on every request.
auth:
  - id: apikey
    type: api_key
    in: query
    name: key
    value_template: "{{secret}}"
    secret_field: api_key

commands:
  # ── Enrichment / read ─────────────────────────────────────────────────────
  - id: host_lookup
    name: shodan-host-lookup
    description: All services Shodan has observed on an IP (open ports, banners, vulns, org, location).
    risk: read
    inputs_schema:
      properties:
        ip: { type: string, description: "IPv4 or IPv6 address" }
        history: { type: string, description: "Set to true to include historical banners" }
        minify: { type: string, description: "Set to true for a slimmed-down result" }
      required: [ip]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /shodan/host/{ip}
      query: [history, minify]
      auth_ref: apikey

  - id: search
    name: shodan-search
    description: Search the Shodan database for hosts matching a query (consumes query credits).
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "Shodan search query, e.g. 'apache port:443 country:FR'" }
        facets: { type: string, description: "Comma-separated facets for a summary, e.g. 'country,org'" }
        page: { type: number, description: "Result page (100 results per page, 1-based)" }
      required: [query]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /shodan/host/search
      query: [query, facets, page]
      auth_ref: apikey

  - id: host_count
    name: shodan-host-count
    description: Count results for a query without returning hosts (does not consume query credits).
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "Shodan search query" }
        facets: { type: string, description: "Comma-separated facets for a summary" }
      required: [query]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /shodan/host/count
      query: [query, facets]
      auth_ref: apikey

  - id: dns_resolve
    name: shodan-dns-resolve
    description: Resolve hostnames to IP addresses.
    risk: read
    inputs_schema:
      properties:
        hostnames: { type: string, description: "Comma-separated hostnames, e.g. 'google.com,example.com'" }
      required: [hostnames]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /dns/resolve
      query: [hostnames]
      auth_ref: apikey

  - id: dns_reverse
    name: shodan-dns-reverse
    description: Reverse-DNS lookup for IP addresses.
    risk: read
    inputs_schema:
      properties:
        ips: { type: string, description: "Comma-separated IP addresses" }
      required: [ips]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /dns/reverse
      query: [ips]
      auth_ref: apikey

  - id: domain_info
    name: shodan-domain-info
    description: Subdomains and DNS records Shodan has gathered for a domain.
    risk: read
    inputs_schema:
      properties:
        domain: { type: string, description: "Domain, e.g. 'example.com'" }
        type: { type: string, description: "Filter by DNS record type, e.g. 'A', 'MX'" }
        page: { type: number, description: "Result page (1-based)" }
      required: [domain]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /dns/domain/{domain}
      query: [type, page]
      auth_ref: apikey

  - id: api_info
    name: shodan-api-info
    description: Plan, remaining query/scan credits and usage limits for the API key (use as a connectivity test).
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /api-info
      auth_ref: apikey

  - id: scan_status
    name: shodan-scan-status
    description: Check the progress of an on-demand scan by its id.
    risk: read
    inputs_schema:
      properties:
        id: { type: string, description: "Scan id returned by shodan-scan" }
      required: [id]
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /shodan/scan/{id}
      auth_ref: apikey

  # ── Active action ─────────────────────────────────────────────────────────
  # Code-first (scripts/scan.py): Shodan's scan endpoint requires an
  # application/x-www-form-urlencoded body, which the form-based generator
  # (JSON body) cannot produce. Marked destructive: it triggers an active,
  # outbound crawl of the target and consumes scan credits.
  # ── Connectivity test ─────────────────────────────────────────────────────
  - id: test_connection
    name: shodan-test-connection
    description: "Verify connectivity and credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }
    request:
      method: GET
      path: /api-info
      auth_ref: apikey

  - id: scan
    name: shodan-scan
    description: Request Shodan to actively crawl an IP or netblock (consumes scan credits).
    risk: destructive
    inputs_schema:
      properties:
        ips: { type: string, description: "Comma-separated IPs or CIDR netblocks to scan" }
        service: { type: string, description: "Optional advanced service list, e.g. '22/tcp'" }
      required: [ips]
    outputs_schema: { properties: {} }