id: circl_hashlookup
name: CIRCL hashlookup
version: 1.0.0
description: "CIRCL hashlookup — tells whether a file hash belongs to known software: NSRL, Linux distribution packages, Windows updates and other trusted sets (6.5 billion hashes). The fastest way to rule out a false positive on a file alert. Free public service, no API key; the server is open source and can be self-hosted (set base_url). Stdlib-only. As an enrichment rule: command lookup_hash, score field `score`, benign threshold 0 and malicious threshold 100 — a known file reads benign, a record CIRCL flags as KnownMalicious reads malicious, and an unknown hash is an answer (not found), never a failure. Add the summary `Known file ${FileName} (${source})` (Riposte 0.299+) to see which file it is."
changelog: "1.0.0 — Initial release: single lookup (MD5, SHA-1, SHA-256), bulk lookup (MD5, SHA-1), test connection."
category: enrichment

config_schema:
  properties:
    base_url:
      type: string
      description: "hashlookup server (default https://hashlookup.circl.lu — set it to a self-hosted instance to keep hashes in-house)"
      default: https://hashlookup.circl.lu
    insecure:
      type: boolean
      description: "Trust any TLS certificate (not secure — a self-hosted instance with a private CA only)"
      default: false
  required: []

commands:
  - id: lookup_hash
    name: hashlookup-lookup-hash
    description: "Look up one MD5, SHA-1 or SHA-256 hash. Returns the CIRCL record (file name, product, source set, hashlookup:trust) plus `known: true` and `score` (0 = known file, 100 = flagged KnownMalicious). An unknown hash returns HTTP 404, which Riposte's enrichment reads as 'no record'."
    risk: read
    inputs_schema:
      properties:
        hash: { type: string, description: "MD5 (32 hex), SHA-1 (40 hex) or SHA-256 (64 hex)" }
      required: [hash]
    outputs_schema: { properties: {} }

  - id: bulk_lookup
    name: hashlookup-bulk-lookup
    description: "Look up many MD5 / SHA-1 hashes at once (the bulk API does not take SHA-256; those are looked up one by one). Returns `known` (records found) and `unknown` (hashes CIRCL has no record of)."
    risk: read
    inputs_schema:
      properties:
        hashes: { type: string, description: "Hashes separated by commas, spaces or new lines (a JSON array also works)" }
      required: [hashes]
    outputs_schema: { properties: {} }

  - id: test_connection
    name: hashlookup-test-connection
    description: "Reach the server's /info endpoint (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }