Skip to content

binary-handling.md

Latest commit

 

History

History
109 lines (78 loc) · 4.98 KB

binary-handling.md

File metadata and controls

109 lines (78 loc) · 4.98 KB
Raw

Binary File Handling

Tip

TL;DR

Binaries are classified by extension and magic bytes, then tiered as inert, archive, structured, or unknown. Opaque binaries lower the analyzability score -- a fail-closed posture where what cannot be inspected is flagged rather than trusted. VirusTotal integration provides reputation-based validation.

Overview

Skill Scanner treats opaque binaries as reduced-visibility risk, not immediate proof of malware. Binary handling is split across static analysis, analyzability scoring, optional VirusTotal checks, and policy knobs.

Classification Flowchart

flowchart TD
    FILE["File discovered"] --> IS_BINARY{"Binary?\n(extension or\nUTF-8 decode fails)"}
    IS_BINARY -->|No| SKIP["Handled by text analyzers"]
    IS_BINARY -->|Yes| IS_INERT{"Inert extension?\n(image, font, etc.)"}
    IS_INERT -->|Yes| INERT_SKIP["Skipped from binary findings\n(policy: skip_inert_extensions)"]
    IS_INERT -->|No| IS_ARCHIVE{"Archive extension?\n(.zip, .tar, etc.)"}
    IS_ARCHIVE -->|Yes| ARCHIVE["ARCHIVE_FILE_DETECTED\n(MEDIUM)"]
    IS_ARCHIVE -->|No| IS_STRUCTURED{"Structured extension?\n(SVG, PDF, etc.)"}
    IS_STRUCTURED -->|Yes| STRUCT_SKIP["Skipped from unknown-binary findings\n(handled by specific checks)"]
    IS_STRUCTURED -->|No| UNKNOWN["BINARY_FILE_DETECTED\n(INFO)"]
    UNKNOWN --> MAGIC{"Extension/content\nmismatch?"}
    MAGIC -->|Yes| MISMATCH["FILE_MAGIC_MISMATCH\n(severity varies)"]
    UNKNOWN --> VT_ENABLED{"VirusTotal\nenabled?"}
    VT_ENABLED -->|Yes| VT_CHECK["Hash lookup\n(optionally upload)"]
    VT_CHECK --> VT_CLEAN{"Clean?"}
    VT_CLEAN -->|Yes| SUPPRESS["Suppress\nBINARY_FILE_DETECTED"]
    VT_CLEAN -->|No| VT_FINDING["VirusTotal finding"]
    VT_ENABLED -->|No| ANALYZABILITY["Analyzability scoring\n(UNANALYZABLE_BINARY at MEDIUM)"]
Loading

Current Implementation

1. Loader Classification

skill_scanner/core/loader.py classifies files as binary when:

  • extension matches known binary extensions (.exe, .so, .dylib, .dll, .bin)
  • file content cannot be decoded as UTF-8 during discovery

2. Static Analyzer Binary Checks

skill_scanner/core/analyzers/static.py::_check_binary_files applies tiered behavior:

  • Extension/content mismatch (FILE_MAGIC_MISMATCH): generated for mismatches on any file, severity depends on mismatch type/confidence
  • Inert extensions: skipped (images/fonts/etc., policy-controlled)
  • Structured extensions: skipped from unknown-binary findings (for example SVG/PDF buckets, policy-controlled)
  • Archive extensions: ARCHIVE_FILE_DETECTED at MEDIUM
  • Unknown binary files: BINARY_FILE_DETECTED at INFO

3. Analyzer-Agnostic Risk Escalation

skill_scanner/core/scanner.py adds analyzability-based findings:

  • UNANALYZABLE_BINARY at MEDIUM for non-inert opaque binaries
  • LOW_ANALYZABILITY aggregate findings when too much content is opaque

This is the primary fail-closed behavior for binary-heavy skills.

4. VirusTotal Integration

When --use-virustotal is enabled:

  • binaries are hashed and checked against VirusTotal
  • optionally upload unknown files with --vt-upload-files
  • BINARY_FILE_DETECTED can be suppressed for binaries validated by VirusTotal

Policy Controls

Binary behavior is tuned through scan policy sections:

  • file_classification.inert_extensions
  • file_classification.structured_extensions
  • file_classification.archive_extensions
  • file_classification.skip_inert_extensions
  • analysis_thresholds.min_confidence_pct (magic mismatch confidence gate)
  • disabled_rules (for example BINARY_FILE_DETECTED, UNANALYZABLE_BINARY)
  • severity_overrides (for example promoting BINARY_FILE_DETECTED to MEDIUM/HIGH)

Practical Guidance

  • Keep binaries out of skill packages whenever possible; prefer auditable source scripts.
  • If binaries are necessary, use --use-virustotal in CI and document provenance.
  • Use policy overrides for org posture (strict compliance vs internal-trusted workflows).

Example Commands

# Default scan (core analyzers)
skill-scanner scan /path/to/skill

# Include VirusTotal hash checks
skill-scanner scan /path/to/skill --use-virustotal

# Upload unknown binaries to VirusTotal as well
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Apply stricter policy posture
skill-scanner scan /path/to/skill --policy strict

Related Pages