Hybrid Analysis Python GUI

A PyQt6 desktop workbench for submitting files to Hybrid Analysis, retrieving reports and PCAPs, extracting network IOCs, enriching domains with DNS/geolocation/threat intelligence context, and storing results in MySQL for investigation, reporting, and anomaly review.

This project is intended for authorized malware analysis, threat research, SOC enrichment, and lab workflows. Run it in a controlled environment and do not submit files or collect data unless you are allowed to analyze them.

What It Does

• Submits one or more files to Hybrid Analysis environments.
• Searches Hybrid Analysis reports by SHA256.
• Downloads report PCAPs by SHA256 and sandbox environment.
• Extracts report domains and related metadata.
• Resolves DNS records and enriches them with GeoLite2, ASN, VirusTotal, URLhaus, and ThreatFox data.
• Stores DNS and IOC enrichment results in MySQL.
• Provides a GUI database explorer, statistics dashboard, scheduled tasks, anomaly rules, workflow automation, and custom report templates.
• Maintains local analysis state, logs, and output folders for repeat investigations.

GUI Screenshots

Submit and configure	Retrieve and enrich

Explore and report	Automate and monitor

Runtime Architecture

flowchart LR
    analyst["Analyst"] --> gui["PyQt6 GUI"]
    gui --> client["HybridAnalysisClient"]
    client --> ha["Hybrid Analysis API"]
    ha --> reports["Reports, summaries, PCAPs"]
    reports --> ioc_worker["IOC worker"]
    ioc_worker --> dns["DNS resolver"]
    ioc_worker --> geo["GeoLite2 City, Country, ASN"]
    ioc_worker --> vt["VirusTotal domain API"]
    ioc_worker --> abuse["URLhaus and ThreatFox"]
    dns --> mysql["MySQL dns_records"]
    geo --> mysql
    vt --> mysql
    abuse --> mysql
    mysql --> explorer["Database Explorer"]
    mysql --> stats["Statistics Dashboard"]
    mysql --> reports_ui["Custom Reports"]

Loading

sequenceDiagram
    participant A as Analyst
    participant G as GUI
    participant H as Hybrid Analysis
    participant W as Worker Threads
    participant E as Enrichment APIs
    participant D as MySQL

    A->>G: Submit files or provide SHA256s
    G->>H: Submit/search/report API calls
    H-->>G: Submission IDs and report data
    G->>W: Start PCAP or IOC jobs
    W->>H: Fetch report summaries and PCAPs
    W->>E: Resolve DNS, GeoLite2, VT, URLhaus, ThreatFox
    W->>D: Upsert enriched DNS records
    D-->>G: Explorer, statistics, reports, anomaly checks

Loading

Project Layout

.
+-- Hybrid_Analysis_Python_GUI.py   # Main PyQt6 GUI and worker orchestration
+-- api/
|   +-- callers/                    # Endpoint-specific Hybrid Analysis API callers
+-- constants.py                    # Action constants
+-- exceptions.py                   # Shared project exceptions
+-- settings.example.json           # Safe configuration template
+-- requirements.txt                # Runtime Python dependencies
+-- assets/screenshots/             # GitHub README screenshot gallery
+-- docs/                           # Architecture, configuration, and database docs

Requirements

• Python 3.10 or newer.
• Hybrid Analysis API key.
• MySQL server for the dns_records database table.
• MaxMind GeoLite2 databases placed in the project root:
  • GeoLite2-City.mmdb
  • GeoLite2-Country.mmdb
  • GeoLite2-ASN.mmdb
• Optional API keys:
  • VIRUSTOTAL_API_KEY
  • ABUSECH_API_KEY

Quick Start

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item settings.example.json settings.json

Edit settings.json with your Hybrid Analysis key, MySQL connection, and optional enrichment keys. Then initialize the database:

mysql -u root -p < docs/database-schema.sql
python Hybrid_Analysis_Python_GUI.py

You can also provide secrets through environment variables instead of writing them into settings.json:

$env:HYBRID_ANALYSIS_API_KEY = "..."
$env:VIRUSTOTAL_API_KEY = "..."
$env:ABUSECH_API_KEY = "..."
$env:MYSQL_PASSWORD = "..."
python Hybrid_Analysis_Python_GUI.py

Configuration Notes

• settings.example.json is the safe template for new installs.
• settings.json, .env, logs, outputs, PCAPs, and GeoLite2 database files are ignored by .gitignore.
• Keep API keys private. The code defaults to environment variables or blank placeholders.
• The application writes operational artifacts to output/, logs/, analysis_state.json, and console.json during normal use.

More setup detail is available in docs/CONFIGURATION.md.

API Modules

Module	Purpose
api/callers/submit.py	Submit file endpoint wrapper.
api/callers/search.py	SHA256 report search wrapper.
api/callers/report.py	Summary and PCAP report wrappers.
api/callers/base.py	Reusable API caller base class.
api/callers/api_caller.py	Generic caller abstraction with response helpers.

Documentation

• Architecture
• Configuration
• Database schema
• MySQL schema SQL
• Screenshot index

GitHub Upload Checklist

• Keep settings.example.json, not a populated settings.json, in version control.
• Do not commit .env, logs/, output/, PCAP files, GeoLite2 .mmdb files, or MySQL dumps containing investigation data.
• Add the screenshots in assets/screenshots/ so the README renders correctly on GitHub.
• Run the syntax check before upload:

python -c "from pathlib import Path; [compile(p.read_text(encoding='utf-8'), str(p), 'exec') for p in Path('.').rglob('*.py') if '__pycache__' not in p.parts]"

License

Released under the MIT License. See LICENSE.