id: virustotal
name: VirusTotal
version: 1.1.0
description: "VirusTotal API v3 — reputation for IPs, domains, files and URLs, plus rescan/scan, intelligence search, analysis results, file behaviour (sandbox) reports, passive DNS and comments."
changelog: "1.1.0 — Full v3 coverage: added file and URL reputation, file rescan, URL scan, search, analysis-get, file sandbox (behaviour) report, passive DNS and comments (get/add/get-by-id/delete). Commands are now script-based (URL base64, form-encoded scans, comment resource routing). 1.0.2 — Re-publish to regenerate form-based command scripts. 1.0.1 — Added test_connection. 1.0.0 — Initial release: IP and domain reputation lookups."
category: enrichment

config_schema:
  properties:
    base_url:
      type: string
      description: VirusTotal API v3 base URL
      default: https://www.virustotal.com/api/v3
    api_key:
      type: string
      description: VirusTotal API key
      x-soar-sensitive: true
  required:
    - api_key

auth:
  - id: apikey
    type: api_key
    in: header
    name: x-apikey
    value_template: "{{secret}}"
    secret_field: api_key

commands:
  # ── Reputation ──────────────────────────────────────────────────────────────
  - id: get_ip_report
    name: virustotal-ip
    description: "Reputation and last-analysis stats for an IP address."
    risk: read
    inputs_schema:
      properties:
        ip: { type: string, description: "IP address to look up" }
      required: [ip]
    outputs_schema: { properties: {} }

  - id: get_domain_report
    name: virustotal-domain
    description: "Reputation and last-analysis stats for a domain."
    risk: read
    inputs_schema:
      properties:
        domain: { type: string, description: "Domain to look up" }
      required: [domain]
    outputs_schema: { properties: {} }

  - id: file
    name: virustotal-file
    description: "Reputation and analysis for a file hash (MD5, SHA1, SHA256)."
    risk: read
    inputs_schema:
      properties:
        file: { type: string, description: "File hash" }
      required: [file]
    outputs_schema: { properties: {} }

  - id: url
    name: virustotal-url
    description: "Reputation and analysis for a URL (base64-id resolved automatically)."
    risk: read
    inputs_schema:
      properties:
        url: { type: string, description: "URL to look up" }
      required: [url]
    outputs_schema: { properties: {} }

  # ── Scans ───────────────────────────────────────────────────────────────────
  - id: file_rescan
    name: virustotal-file-rescan
    description: "Re-analyse an already-submitted file by hash. Use analysis_get to fetch results."
    risk: safe_write
    inputs_schema:
      properties:
        file: { type: string, description: "File hash to rescan" }
      required: [file]
    outputs_schema: { properties: {} }

  - id: url_scan
    name: virustotal-url-scan
    description: "Submit a URL for scanning. Use analysis_get to fetch results."
    risk: safe_write
    inputs_schema:
      properties:
        url: { type: string, description: "URL to scan" }
      required: [url]
    outputs_schema: { properties: {} }

  - id: analysis_get
    name: virustotal-analysis-get
    description: "Get the result of an analysis (from file_rescan or url_scan) by ID."
    risk: read
    inputs_schema:
      properties:
        id: { type: string, description: "Analysis ID" }
      required: [id]
    outputs_schema: { properties: {} }

  # ── Intelligence / relationships ──────────────────────────────────────────
  - id: search
    name: virustotal-search
    description: "Search VirusTotal for a file hash, URL, domain, IP, or tag."
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "Search query" }
        limit: { type: number, description: "Maximum number of results (default 10)" }
      required: [query]
    outputs_schema: { properties: {} }

  - id: file_sandbox_report
    name: virustotal-file-sandbox-report
    description: "Retrieve sandbox behaviour reports for a file hash."
    risk: read
    inputs_schema:
      properties:
        file: { type: string, description: "File hash" }
        limit: { type: number, description: "Maximum number of reports (default 10)" }
      required: [file]
    outputs_schema: { properties: {} }

  - id: passive_dns
    name: virustotal-passive-dns-data
    description: "Passive DNS resolutions for an IP address or a domain."
    risk: read
    inputs_schema:
      properties:
        resource: { type: string, description: "IP address or domain" }
        limit: { type: number, description: "Maximum number of resolutions (default 10)" }
      required: [resource]
    outputs_schema: { properties: {} }

  # ── Comments ──────────────────────────────────────────────────────────────
  - id: comments_get
    name: virustotal-comments-get
    description: "Get comments for an IP, domain, URL or file."
    risk: read
    inputs_schema:
      properties:
        resource: { type: string, description: "The IP, domain, URL or file hash" }
        resource_type: { type: string, description: "Resource type: ip, domain, url or file (auto-detected if omitted)" }
        limit: { type: number, description: "Maximum number of comments (default 10)" }
      required: [resource]
    outputs_schema: { properties: {} }

  - id: comments_add
    name: virustotal-comments-add
    description: "Add a comment to an IP, domain, URL or file."
    risk: safe_write
    inputs_schema:
      properties:
        resource: { type: string, description: "The IP, domain, URL or file hash" }
        resource_type: { type: string, description: "Resource type: ip, domain, url or file (auto-detected if omitted)" }
        comment: { type: string, description: "Comment text" }
      required: [resource, comment]
    outputs_schema: { properties: {} }

  - id: comments_get_by_id
    name: virustotal-comments-get-by-id
    description: "Get a single comment by its ID."
    risk: read
    inputs_schema:
      properties:
        id: { type: string, description: "Comment ID" }
      required: [id]
    outputs_schema: { properties: {} }

  - id: comments_delete
    name: virustotal-comments-delete
    description: "Delete a comment by its ID."
    risk: destructive
    inputs_schema:
      properties:
        id: { type: string, description: "Comment ID" }
      required: [id]
    outputs_schema: { properties: {} }

  # ── Connectivity test ─────────────────────────────────────────────────────
  - id: test_connection
    name: virustotal-test-connection
    description: "Verify connectivity and credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }