---
name: virustotal-security-scanner-df55159b9960
description: Scan files and URLs using VirusTotal API via curl or Python utilities. Check hashes, upload files, and manage comments.
homepage: https://www.virustotal.com/
metadata: {"clawdbot":{"emoji":"🦠","requires":{"bins":["curl","jq","sha256sum","python3"],"env":["VT_API_KEY"]}}}
---

# VirusTotal Scanner Skill

Interact with VirusTotal API using either standard system tools (curl) or Python utilities.

## Setup

1. Get your API key: https://www.virustotal.com/gui/user/[your-username]/apikey
2. Set the environment variable:
   ```bash
   export VT_API_KEY="your-api-key-here"
   ```

## Privacy Warning

**CRITICAL**: This skill involves sending data to VirusTotal, a public threat intelligence service.
1.  **Never upload files without explicit user consent.**
2.  **Do not include PII (Personally Identifiable Information)** in comments or descriptions.
3.  **Warn the user** that uploaded files are shared with the security community and can be downloaded by other researchers.

## Best Practices: Caching Results

To avoid unnecessary API calls and stay within rate limits, it is recommended to cache the JSON results locally. Use `~/.vt/` to store these reports.

```bash
# Create cache directory
mkdir -p ~/.vt

# Save a report to cache
HASH="your-file-hash"
curl --request GET \
     --url "https://www.virustotal.com/api/v3/files/$HASH" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY" > ~/.vt/$HASH.json

# Query the cache instead of the API (if jq available)
cat ~/.vt/$HASH.json | jq '.data.attributes.last_analysis_stats'
```

## Usage: Curl (Standard and use it by default)

### 1. Hash a file (Required for checks)
Calculate the SHA256 hash of a file to check if it exists in VirusTotal.
```bash
# Linux
sha256sum /path/to/file

# MacOS
shasum -a 256 /path/to/file

# Windows (PowerShell)
Get-FileHash /path/to/file -Algorithm SHA256
```

### 2. Check File Report
Check if a file hash is already known to VirusTotal.
```bash
curl --request GET \
     --url "https://www.virustotal.com/api/v3/files/{hash}" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY"
```

### 3. Upload File
**Privacy Note**: Only upload files if you have the user's explicit permission.

#### Small Files (< 32MB)
```bash
curl --request POST \
     --url "https://www.virustotal.com/api/v3/files" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY" \
     --form "file=@/path/to/file"
```

#### Large Files (> 32MB)
First, get a unique upload URL:
```bash
curl --request GET \
     --url "https://www.virustotal.com/api/v3/files/upload_url" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY"
```
Then upload to that URL:
```bash
curl --request POST \
     --url "{upload_url_from_previous_step}" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY" \
     --form "file=@/path/to/large_file"
```

### 4. File Comments
**Privacy Warning**: Do NOT include PII (Personally Identifiable Information) or sensitive data in comments. Context about the file origin or downloader is useful.

#### Get Comments
```bash
curl --request GET \
     --url "https://www.virustotal.com/api/v3/files/{hash}/comments?limit=10" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY"
```

#### Add Comment
```bash
curl --request POST \
     --url "https://www.virustotal.com/api/v3/files/{hash}/comments" \
     --header "accept: application/json" \
     --header "content-type: application/json" \
     --header "x-apikey: $VT_API_KEY" \
     --data '{"data": {"type": "comment", "attributes": {"text": "File found in /tmp directory via downloader script."}}}'
```

### 5. URL Scanning

#### Scan a URL
```bash
curl --request POST \
     --url "https://www.virustotal.com/api/v3/urls" \
     --header "accept: application/json" \
     --header "content-type: application/x-www-form-urlencoded" \
     --header "x-apikey: $VT_API_KEY" \
     --data "url={url_to_analyze}"
```

#### Get URL Report
Note: The ID for a URL is usually its SHA256 hash.
```bash
curl --request GET \
     --url "https://www.virustotal.com/api/v3/urls/{url_id_or_hash}" \
     --header "accept: application/json" \
     --header "x-apikey: $VT_API_KEY"
```

## Usage: Python Utilities

If system libraries are missing or you prefer Python, use the provided helper scripts.

### Install Requirements
```bash
pip install requests
```

### 1. Calculate Hash
```bash
python3 vt-scanner/calc_hash.py /path/to/file
```

### 2. API Client (`vt_client.py`)
This script wraps the API endpoints for easier usage.

#### Check File
```bash
python3 vt-scanner/vt_client.py check-file {hash}
```

#### Upload File
Handles both small and large file upload flows automatically.
```bash
python3 vt-scanner/vt_client.py upload-file /path/to/file
```

#### Get Comments
```bash
# For a file
python3 vt-scanner/vt_client.py get-comments {file_hash}

# For a URL
python3 vt-scanner/vt_client.py get-comments {url_id} --url
```

#### Add Comment
```bash
python3 vt-scanner/vt_client.py add-comment {id} "Your comment here"
```

#### Scan URL
```bash
python3 vt-scanner/vt_client.py scan-url "http://example.com"
```

#### Check URL Report
```bash
python3 vt-scanner/vt_client.py check-url {url_id}
```


---
Source attribution: kbarbel640-del
Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/aleph8/virustotal-security/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 clawdbot

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: kbarbel640-del
Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/aleph8/virustotal-security/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Development & Engineering
Roles: Data Analyst, Security Engineer
Specialties: API
Tools: Virustotal
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: cb3360dd0c9a83254aa7db7abf03147a742b4e48980bc9630781e004a652ce62