malware-hash

What this skill does

Accepts a file hash (MD5/SHA1/SHA256) or file path and queries the VirusTotal API v3 for malware reputation. Parses detection ratio, per-vendor results, tags, and first-seen date to summarize the threat level.

When to use

• Quickly checking whether a suspicious file is a known malware sample
• Assessing the threat level of hashes collected during incident response
• Bulk-querying hashes from an IOC list
• Prioritizing files before forensic analysis

Prerequisites

• curl (HTTP requests)
• python3 (JSON parsing)
• VirusTotal API key: environment variable SECSKILL_VT_API_KEY

API key setup (in priority order)

# Method 1: Set environment variable directly (current session)
export SECSKILL_VT_API_KEY="your_api_key_here"

# Method 2: Persistent config file
mkdir -p ~/.config/security-skill
echo 'SECSKILL_VT_API_KEY=your_api_key_here' >> ~/.config/security-skill/secrets.env
chmod 600 ~/.config/security-skill/secrets.env

# Method 3: If neither above method is available, the skill will prompt interactively at runtime

Inputs

Field	Description	Example
HASH_OR_FILE	MD5/SHA1/SHA256 hash string or file path	44d88612fea8a8f36de82e1278abb02f

Workflow

Step 1: Verify API key credentials

# Credential resolution: environment variable → config file → interactive input
resolve_vt_api_key() {
    if [ -n "$SECSKILL_VT_API_KEY" ]; then
        echo "[+] API key: loaded from environment variable"
        return 0
    fi

    local secrets_file="$HOME/.config/security-skill/secrets.env"
    if [ -f "$secrets_file" ]; then
        source "$secrets_file"
        if [ -n "$SECSKILL_VT_API_KEY" ]; then
            echo "[+] API key: loaded from $secrets_file"
            return 0
        fi
    fi

    echo "[!] VirusTotal API key not found."
    echo "    Get a free key at https://www.virustotal.com/gui/my-apikey"
    read -rsp "Enter API key: " SECSKILL_VT_API_KEY
    echo
    export SECSKILL_VT_API_KEY

    read -rp "Save this key to $secrets_file? [y/N] " save_key
    if [[ "$save_key" =~ ^[Yy]$ ]]; then
        mkdir -p "$(dirname "$secrets_file")"
        echo "SECSKILL_VT_API_KEY=$SECSKILL_VT_API_KEY" >> "$secrets_file"
        chmod 600 "$secrets_file"
        echo "[+] API key saved"
    fi
}

resolve_vt_api_key