triage-sandbox

Typed Python library and CLI for the Triage (tria.ge) malware analysis sandbox

Overview

triage-sandbox is a Python toolkit to submit, search, inspect and download malware analyses from the Triage sandbox, covering the complete tria.ge API. It gives you a typed model layer, ergonomic CLI workflows and a small, dependency-light library. It works against both the public cloud (api.tria.ge) and Private Triage (private.tria.ge).

Key Features

Supported Outputs

Typed models    Sample, Task, AnalysisProfile (from listings, search, submissions)
Raw JSON        Overview / static / task reports and event streams (free-form)
Downloads       Original sample, artifact archive (tar/zip), pcap, single task files
Status lines    Human-readable, control-character-escaped terminal output

Installation

From PyPI

pip install triage-sandbox-cli

From Source

git clone https://github.com/seifreed/triage-sandbox.git
cd triage-sandbox
python3.14 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install .

Or run straight from a checkout without installing:

python triage-sandbox.py --help

Development Extras

pip install -e '.[dev]'   # black, ruff, mypy, bandit, pip-audit, pytest

Authentication

Get an API token from your tria.ge account. The selected deployment requires its own token and API URL.

# Public Triage
export TRIAGE_INSTANCE=public
export TRIAGE_PUBLIC_TOKEN=YOUR_PUBLIC_TOKEN
export TRIAGE_PUBLIC_API_URL=https://api.tria.ge

# Private Triage
export TRIAGE_INSTANCE=private
export TRIAGE_PRIVATE_TOKEN=YOUR_PRIVATE_TOKEN
export TRIAGE_PRIVATE_API_URL=https://private.tria.ge/api

Both deployments can be defined at once. Use TRIAGE_INSTANCE=public,private (or public|private) to verify both credentials in a single triage-sandbox status. A .env file in the working directory is also loaded — see .env.example.

Quick Start

# Verify your credentials
triage-sandbox status

# Submit a file for analysis
triage-sandbox submit file malware.exe --password infected --tag ransomware

# Search the public feed with the tria.ge query language
triage-sandbox search "family:agenttesla" --limit 5

Usage

Command Line Interface

# Submissions
triage-sandbox submit file malware.exe --password infected --tag ransomware
triage-sandbox submit url http://evil.example
triage-sandbox submit fetch http://evil.example/payload.exe

# Samples
triage-sandbox samples list --subset public --limit 10
triage-sandbox samples get SAMPLE_ID
triage-sandbox samples select-profile SAMPLE_ID --auto

# Reports
triage-sandbox report overview SAMPLE_ID
triage-sandbox report task SAMPLE_ID behavioral1

# Downloads
triage-sandbox download sample SAMPLE_ID -o sample.bin
triage-sandbox download archive SAMPLE_ID --format zip
triage-sandbox download pcap SAMPLE_ID behavioral1

# Analysis profiles
triage-sandbox profiles create --name win10 --tag windows --timeout 300

# Real-time event stream for all samples
triage-sandbox events

Run any command with --help for the full option list.

Main Commands

Useful Options

Notes from real use. --all on a broad query (e.g. family:lockbit) can be many thousands of samples, so prefer --limit unless you truly want everything. Some operations (--subset org, deleting samples, API-key management) depend on your account tier and otherwise return a permissions error. profiles update changes only the fields you pass, leaving the rest at their stored values.

Python Library

Basic Usage

Samples and analysis profiles come back as typed objects, so no caller needs to know the API's JSON field names:

from triage_sandbox import SubmissionOptions, TriageClient, environment_credentials

credentials = environment_credentials()
client = TriageClient(credentials.token, credentials.api_url)

# Submit and inspect
options = SubmissionOptions(password="infected", tags=("incident-42",))
submitted = client.submit_file("malware.exe", options=options)
print(submitted.id, client.sample_status(submitted.id))

# Iterate with automatic pagination
for sample in client.iter_samples(subset="owned", max_items=50):
    print(sample.id, sample.status, sample.target)

# Search
for sample in client.iter_search("family:agenttesla", max_items=10):
    print(sample.id, sample.target)

# Downloads
archive = client.download_archive("SAMPLE_ID", as_zip=True)
pcap = client.download_pcap("SAMPLE_ID", "behavioral1")

# Reports and events stay raw JSON documents: free-form analysis output
overview = client.overview_report("SAMPLE_ID")
for event in client.sample_events("SAMPLE_ID"):
    print(event)

Errors raise a typed hierarchy: TriageError, TriageAuthError, TriageNotFoundError, TriageRateLimitError, TriageServerError. See examples/usage_example.py for a runnable example.

Architecture

The package is layered, and dependencies only ever point inwards:

The domain imports no third-party package at all; requests appears only in infrastructure/transport.py, and every API field name lives only in infrastructure/mapping.py. These rules are executable: tests/test_architecture.py parses each module and fails the build if a layer imports an outer one, if the domain touches a framework, if requests escapes the transport, if a wire format reaches the CLI, or if any public method returns a raw dict instead of a model.

Development

All dependencies (runtime and development) are declared in a single pyproject.toml. Every gate must pass clean, with no suppressions:

black --check .
ruff check .
mypy .
bandit -r .
pip-audit
pytest          # 100% coverage enforced, no mocks (real in-process HTTP server)

Requirements

• Python 3.14+
• Runs on Windows, Linux and macOS (x64 and ARM)
• Runtime dependencies: click, requests, rich, pyyaml, python-dotenv

Contributing

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

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/triage-sandbox

_{Built for practical malware triage and security automation}