hybridanalysis

Python library and CLI for the Hybrid Analysis (Falcon Sandbox) API v2

Overview

hybridanalysis is a Python toolkit to submit samples to and query the Hybrid Analysis (Falcon Sandbox) service through its API v2. It ships both a synchronous and an asynchronous client with identical surfaces, a full-featured CLI, and a typed exception hierarchy — covering every current (non-deprecated) endpoint across all ten API tags.

Key Features

Supported Surface

Clients      HybridAnalysisClient (sync), AsyncHybridAnalysisClient (async)
Tags         feed · key · overview · quick-scan · submit · report
             search · file-collection · abuse-reports · system
Downloads    sample, pcap, certificate, dropped files, memory strings (bytes/text)
Config       HYBRIDANALYSIS env var · ~/.config/hybridanalysis/config.toml
Errors       AuthenticationError · NotFoundError · RateLimitError · APIError
             NetworkError · ConfigError (all subclass HybridAnalysisError)

Installation

From PyPI

pip install hybridanalysis

From Source

git clone https://github.com/seifreed/hybridanalysis.git
cd hybridanalysis
python3.14 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt  # runtime + dev tooling; use `pip install -e .` for runtime only

Requires Python 3.14+. Runtime dependencies are httpx, click, and toon-format.

Configuration

The API key is resolved from, in order:

1. The HYBRIDANALYSIS environment variable.

2. A local TOML file — ./.hybridanalysis.toml or ~/.config/hybridanalysis/config.toml:

   [hybridanalysis]
   api_key = "your-api-key"
   # base_url   = "https://hybrid-analysis.com/api/v2"  # optional
   # user_agent = "Falcon Sandbox"                      # optional
   # timeout    = 60                                    # optional, seconds
   

Every field also has an environment variable that takes precedence over the file: HYBRIDANALYSIS_URL, HYBRIDANALYSIS_USER_AGENT, and HYBRIDANALYSIS_TIMEOUT.

Quick Start

export HYBRIDANALYSIS="your-api-key"

# System / key info
hybridanalysis system version
hybridanalysis key current

# Submit a sample and poll its report
hybridanalysis submit file sample.exe environment_id=160
hybridanalysis report summary <job-id>

Usage

Command Line Interface

# Look up a hash (any format -> SHA256) and its reports
hybridanalysis search hash <md5|sha1|sha256>

# Search by behaviour / infrastructure
hybridanalysis search terms host=8.8.8.8
hybridanalysis search terms vx_family=nemucod verdict=5
hybridanalysis search terms uses_technique=T1055

# Submit for analysis
hybridanalysis submit file sample.exe environment_id=160
hybridanalysis quick-scan file sample.exe --scan-type all

# Download binary artifacts (to a file, or stdout when --out is omitted)
hybridanalysis report pcap <job-id> --out capture.pcap
hybridanalysis overview sample <sha256> --out sample.gz

--api-key, --base-url, and --config override the resolved configuration. python -m hybridanalysis works as an alternative to the hybridanalysis command.

Output Formats

Every JSON-returning command accepts -f / --format:

hybridanalysis overview get <sha256> --format toon    # token-efficient JSON
hybridanalysis report summary <job-id> --format sarif # SARIF 2.1.0 findings

Command Groups

Python Library

Synchronous

from hybridanalysis import HybridAnalysisClient

with HybridAnalysisClient.from_env() as client:
    print(client.system.version())

    # Submit a file and poll its report
    submitted = client.submit.file("sample.exe", environment_id="160")
    job_id = submitted["job_id"]
    print(client.report.state(job_id))
    print(client.report.summary(job_id))

    # Download binary artifacts (returned as bytes)
    pcap = client.report.pcap(job_id)

    # Search (verdict is numeric 1-5, 5 = malicious)
    client.search.terms(filetype="peexe", verdict="5")

Asynchronous

import asyncio
from hybridanalysis import AsyncHybridAnalysisClient

async def main():
    async with AsyncHybridAnalysisClient.from_env() as client:
        print(await client.system.version())
        results = await asyncio.gather(*(client.overview.get(h) for h in hashes))

asyncio.run(main())

Errors raise subclasses of HybridAnalysisError: AuthenticationError, NotFoundError, RateLimitError, APIError, NetworkError, and ConfigError.

Requirements

• Python 3.14+
• See pyproject.toml for dependencies and extras

Support the Project

If this project is useful in your workflows, you can support development:

License

This project is licensed under the MIT license. See LICENSE.

Attribution

• Author: Marc Rivero López | @seifreed
• Repository: github.com/seifreed/hybridanalysis

_{Built for practical malware analysis and security automation}