[Plugin] Create VirusTotal Checker Plugin using Plugin Framework

[crivetimihai]

Overview

Create a VirusTotal Checker Plugin that integrates with VirusTotal v3 API to check URLs, domains, IPs, and file hashes before fetching resources or processing tool outputs.

Plugin Requirements

Plugin Details

• Name: VirusTotalCheckerPlugin
• Type: Self-contained (native) plugin
• File Location: plugins/virus_total_checker/
• Complexity: High

Functionality

• Integration with VirusTotal v3 API for malware detection
• URL, domain, IP address, and file hash scanning
• Configurable threat verdict thresholds
• Automatic file upload for unknown files
• Comprehensive caching to reduce API calls
• Rate limiting and retry logic for API calls

Hook Integration

• Primary Hooks: resource_pre_fetch, resource_post_fetch, prompt_post_fetch, tool_post_invoke
• Purpose: Detect malware and malicious content before processing
• Behavior: Block or warn on malicious content based on configuration

Configuration Schema

plugins:
  - name: "VirusTotalChecker"
    kind: "plugins.virus_total_checker.scanner.VirusTotalCheckerPlugin"
    description: "Integrates with VirusTotal v3 to check URLs/domains/IPs before fetching"
    version: "0.1.0"
    hooks: ["resource_pre_fetch", "resource_post_fetch", "prompt_post_fetch", "tool_post_invoke"]
    mode: "enforce"
    priority: 30
    config:
      # VirusTotal API configuration
      api:
        enabled: true
        api_key_env: "VT_API_KEY"
        base_url: "https://www.virustotal.com/api/v3"
        timeout_seconds: 8.0
        max_retries: 3
        base_backoff: 0.5
        max_delay: 8.0
        jitter_max: 0.2
      
      # Scanning configuration
      scanning:
        check_url: true
        check_domain: true
        check_ip: true
        check_file_hash: true
        scan_if_unknown: false
        wait_for_analysis: false
        max_wait_seconds: 8
        poll_interval_seconds: 1.0
      
      # Threat detection thresholds
      threat_thresholds:
        block_on_verdicts: ["malicious"]
        min_malicious: 1
        min_suspicious: 3
        max_harmless_ratio: 0.8
        engines_to_ignore: ["Antiy-AVL", "MaxSecure"]
      
      # File scanning
      file_scanning:
        enable_file_checks: true
        file_hash_alg: "sha256"
        upload_if_unknown: false
        upload_max_bytes: 10485760  # 10MB
        scan_downloads: true
        scan_attachments: true
      
      # Content analysis
      content_analysis:
        scan_tool_outputs: true
        scan_prompt_outputs: true
        scan_resource_contents: true
        max_urls_per_call: 5
        url_pattern: "https?://[\\w\\-\\._~:/%#\\[\\]@!\\$&'\\(\\)\\*\\+,;=]+"
      
      # Caching
      caching:
        cache_ttl_seconds: 300
        cache_verdicts: true
        cache_unknown_results: false
        max_cache_entries: 1000
      
      # Policy configuration
      policy:
        override_precedence: "deny_over_allow"
        allow_url_patterns: ["https://github.com/*", "https://api.company.com/*"]
        deny_url_patterns: ["*/malware/*", "*/exploit/*"]
        allow_domains: ["trusted-domain.com"]
        deny_domains: ["known-malicious.com"]
        allow_ip_cidrs: ["8.8.8.0/24"]
        deny_ip_cidrs: ["192.168.0.0/16"]
      
      # Response handling
      response:
        block_message: "Content blocked by VirusTotal security scan"
        include_scan_details: false
        include_vendor_count: true
        log_detections: true
        alert_on_malicious: true
      
      # Integration settings
      integration:
        respect_rate_limits: true
        premium_account: false
        batch_requests: true
        parallel_scans: false
        
      # Monitoring and metrics
      monitoring:
        track_api_usage: true
        log_scan_results: true
        metrics_enabled: true
        performance_tracking: true

Implementation Requirements

File Structure

plugins/virus_total_checker/
├── __init__.py
├── scanner.py             # Main plugin class
├── api/                   # VirusTotal API integration
│   ├── __init__.py
│   ├── client.py          # VT API client with retry logic
│   ├── models.py          # API response models
│   └── rate_limiter.py    # API rate limiting
├── scanners/              # Different scan types
│   ├── __init__.py
│   ├── url_scanner.py     # URL/domain scanning
│   ├── file_scanner.py    # File hash scanning
│   └── content_scanner.py # Content analysis
├── cache.py              # Result caching
├── policy.py             # Policy enforcement
├── extractors.py         # URL/hash extraction from content
├── plugin-manifest.yaml  # Plugin metadata
└── README.md             # Usage documentation

Core Features

1. Comprehensive Scanning

   • URL reputation checking
   • Domain reputation analysis
   • IP address reputation
   • File hash lookups
   • Content-embedded URL extraction

2. Advanced API Integration

   • Full VirusTotal v3 API support
   • Rate limiting and retry logic
   • Batch request optimization
   • Premium feature detection

3. Intelligent Caching

   • TTL-based result caching
   • API quota conservation
   • Unknown result handling
   • Cache invalidation policies

4. Flexible Policy Engine

   • Configurable threat thresholds
   • Allow/deny list overrides
   • Pattern-based filtering
   • Verdict aggregation logic

Usage Examples

URL Reputation Check

# Resource request for suspicious URL
resource_uri = "https://suspicious-domain.com/malware.zip"

# Plugin queries VirusTotal API
# VT Response: 15/70 engines detect as malicious
# Result: Blocked (exceeds min_malicious threshold of 1)

File Hash Verification

# Tool output containing file hash
output_content = "Download: file.exe (SHA256: d41d8cd98f00b204e9800998ecf8427e)"

# Plugin extracts hash and checks VirusTotal
# VT Response: Known malware detected by 45/70 engines
# Result: Content blocked with security warning

Content URL Scanning

# Tool output with embedded URLs
output_content = '''
Check this link: https://bit.ly/suspicious-link
And this one: http://malicious-site.com/payload
'''

# Plugin extracts URLs and scans each one
# First URL: Shortener resolved to malicious domain
# Second URL: Direct malicious domain match
# Result: Output blocked due to malicious content

Security Features

• Real-time Threat Detection: Integration with global threat intelligence
• Multi-engine Validation: Consensus-based verdict decisions
• Anti-evasion: URL shortener resolution and redirect following
• Privacy Protection: Optional hash-only scanning mode

Testing Requirements

• Unit tests for all scanning engines and API integration
• Mock VirusTotal API responses for testing
• Rate limiting and retry logic validation
• Cache behavior and expiration testing
• Policy enforcement testing with various verdicts
• Performance testing with large content volumes
• Security testing for API key handling

Documentation Requirements

• Plugin configuration guide with VirusTotal setup
• Threat detection tuning recommendations
• API quota optimization strategies
• Troubleshooting guide for common issues

Acceptance Criteria

• Plugin implements VirusTotalCheckerPlugin class
• Full VirusTotal v3 API integration
• URL, domain, IP, and file hash scanning
• Configurable threat detection thresholds
• Intelligent caching with TTL support
• Rate limiting and retry logic
• Content URL extraction and analysis
• Policy-based allow/deny overrides
• Comprehensive logging and metrics
• Plugin manifest and documentation created
• Unit tests with >95% coverage
• Integration tests with VirusTotal sandbox
• Performance benchmarks for large content analysis

Priority

High - Advanced security feature

Dependencies

• HTTP client libraries with retry support
• URL parsing and extraction utilities
• Caching libraries with TTL support
• Hash calculation libraries
• Rate limiting utilities

Security Considerations

• Secure API key storage and handling
• Rate limiting to prevent API abuse
• Privacy considerations for content scanning
• Audit logging for security decisions
• Error handling to prevent information disclosure