Hybrid Analysis Batch Submission Script

This Python script recursively scans a folder and submits executable, script, document, and other relevant files to Hybrid Analysis (Falcon Sandbox) for automated malware analysis.

Features

• Recursively walks through directories
• Submits only supported file types (see list below)
• Skips empty, oversized, or previously submitted files
• Prevents path traversal attacks – ensures files are within the scan root
• Skips symbolic links to avoid duplicate or unintended submissions
• Uses a persistent requests Session for efficient API communication
• Stores cache in a dedicated user directory (~/.hybrid_analysis_submitter/) to avoid polluting scanned folders
• Uses a local SHA‑256 cache to avoid duplicate submissions
• Handles API rate limiting (429 errors) gracefully
• Stops automatically when the API quota is exhausted
• Supports command‑line configuration of folder, file size limit, environment ID, and cache file name
• Reads API key from a .env file for security

Requirements

• Python 3.6+
• A valid Hybrid Analysis API key (free tier available)

Installation

1. Clone or download this script to your local machine.

2. Install required packages:

pip install requests python-dotenv

3. Create a .env file in the same directory as the script with your API key:

HYBRID_API_KEY=your_api_key_here

You can obtain an API key by registering at Hybrid Analysis.

Usage

Run the script from the command line, specifying the folder to scan:

python submit_to_hybrid.py /path/to/folder

Command‑line Arguments

Examples

Scan a folder with default settings:

python submit_to_hybrid.py C:\suspicious_files

Scan a folder but increase the size limit to 200 MB and use a different environment (e.g., Android):

python submit_to_hybrid.py /home/user/samples --max-file-size 200 --environment-id 300

Use a custom cache file name:

python submit_to_hybrid.py ./malware --cache-file my_cache.json

Example Output

Scanning folder: C:\suspicious_files

Submitting: C:\suspicious_files\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\suspicious_files\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\suspicious_files\malware.exe
Skipping symlink: C:\suspicious_files\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

Supported File Types

• Windows executables (PE): .exe, .scr, .pif, .dll, .com, .cpl
• Installers & packages: .msi
• Windows scripts: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, ,

For the official list of all supported file types, check the Hybrid Analysis FAQ.

How It Works

1. Recursive walk – The script uses os.walk() to traverse every subfolder.
2. Security checks – It verifies that each file resolves to a path inside the scan root (prevents path traversal) and skips symbolic links.
3. File filtering – It checks the file extension, size (0 bytes or > --max-file-size are skipped), and whether the file has been submitted before (SHA‑256 cache).
4. Submission – Each file is uploaded to the https://hybrid-analysis.com/api/v2/submit/file endpoint using a persistent requests Session with your API key.
5. Rate limiting – After each submission the script sleeps for 2 seconds. If it receives an HTTP 429 (Too Many Requests) response, it counts the error. After 3 consecutive 429 errors, the scan stops automatically.
6. Cache persistence – Successfully submitted files are stored in a JSON cache file inside ~/.hybrid_analysis_submitter/ so they are not re‑submitted in future runs. The cache is saved sorted for human readability.

Rate Limiting & Quotas

• Hybrid Analysis free accounts have hourly/daily submission limits.
• The script detects HTTP 429 responses and stops after 3 such errors to avoid endless retries.
• A 2‑second delay is added between submissions to be respectful of the API.

Important Notes

• The API key is read only from the .env file – do not hardcode it.
• Empty files (0 bytes) are always skipped.
• Files larger than --max-file-size are skipped.
• Only files with extensions in ALLOWED_EXTENSIONS are submitted.
• Symbolic links are skipped to prevent duplicate submissions and path confusion.
• Path traversal is prevented – the script will skip any file that resolves outside the specified scan directory.
• The cache prevents re‑submitting identical files across multiple runs and is stored in your user directory (~/.hybrid_analysis_submitter/).
• The script uses a 120‑second timeout for each HTTP request.
• Cache files are stored in a dedicated directory – not mixed with scanned content.

Troubleshooting

License

This script is provided as‑is for educational and security analysis purposes. Use responsibly and in accordance with Hybrid Analysis Terms of Service.

Disclaimer

Submitting files to a third‑party sandbox may expose potentially sensitive content. Ensure you have the right to share the files before uploading.