id: virustotal_hunting
name: VirusTotal Hunting
version: 1.0.0
description: "VirusTotal Hunting (Premium API v3) — ingest Livehunt notification files as findings, list Livehunt notifications, and list finished Retrohunt jobs and their matching files."
changelog: "1.0.0 — Initial release: Livehunt notification-file ingestion (livehunt_files) with an OCSF mapper, Livehunt notifications listing, and Retrohunt job + matching-file listing."
category: enrichment

# Per-instance configuration. Authenticated with a VirusTotal API key (Premium
# subscription required for Hunting features).
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 (Premium)"
      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:
  # ── Ingestion ───────────────────────────────────────────────────────────────
  - id: livehunt_files
    name: vt-livehunt-files
    description: "Fetch file objects matched by Livehunt notifications. Used for ingestion: results path = data. Deduplicated by file ID (sha256)."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "Filter on the notification tags / ruleset name (exact name). Leave empty for all." }
        limit: { type: number, description: "Maximum number of files to fetch (default 10, max 40)" }
      required: []
    outputs_schema: { properties: {} }
    ingest:
      results_path: data
      dedup_key: id

  - id: livehunt_notifications
    name: vt-livehunt-notifications
    description: "List Livehunt notifications (metadata), optionally filtered by tag."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "Filter on the notification tags" }
        limit: { type: number, description: "Maximum number of notifications (default 10, max 40)" }
      required: []
    outputs_schema: { properties: {} }

  - id: retrohunt_jobs
    name: vt-retrohunt-jobs
    description: "List Retrohunt jobs (finished by default)."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "Job filter (default status:finished)" }
        limit: { type: number, description: "Maximum number of jobs (default 10)" }
      required: []
    outputs_schema: { properties: {} }

  - id: retrohunt_matching_files
    name: vt-retrohunt-matching-files
    description: "List the files matched by a Retrohunt job."
    risk: read
    inputs_schema:
      properties:
        job_id: { type: string, description: "Retrohunt job ID" }
        limit: { type: number, description: "Maximum number of files (default 40)" }
      required: [job_id]
    outputs_schema: { properties: {} }

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

ingestion:
  command: livehunt_files
  mapper: livehunt_files
  default_incident_type: "VirusTotal Hunting File"