malwagon

Submit a file to the Malwagon malware analysis sandbox from the command line, wait for the detonation to finish, and print the verdict.

$ malwagon suspicious.exe
uploading suspicious.exe (412.0 KB) to malwagon.com
scan 48213 queued
waiting for the sandbox, usually 90 to 300 seconds
  queued       0s elapsed
  running      12s elapsed
  analyzing    2m 18s elapsed

  MALICIOUS  score 88/100
  sha256 354fd5f5e4afc2280a19c8541fd4abe38bf8fb73efbeb3c2b0a4f2b1d9e0c7a1
  report https://malwagon.com/s/48213

Install

pip install malwagon

Works on Linux, macOS and Windows, on Python 3.8 and newer. It has no dependencies - the standard library makes the request.

An API key

Every scan needs one. Mint it in the console under Settings -> API tokens, give it the submit permission, then store it once:

$ malwagon login
Malwagon API key for malwagon.com: 
key accepted and saved to ~/.config/malwagon/config.json

Or keep it in the environment instead, which is what CI usually wants:

export MALWAGON_API_KEY=mwg_...

There is deliberately no --api-key flag. A key on the command line is visible to every process on the machine and is written verbatim into your shell history.

Usage

malwagon FILE [options]

malwagon --help lists all of them.

The sandbox is chosen from the file, not from a flag. A Windows binary detonates on Windows, an ELF or a Python package on the Linux sandbox, a driver reaches the kernel analyzer. Pass --os only when you want to override that.

Exit codes

So a pipeline can gate on it:

malwagon build/output.exe --quiet || echo "do not ship this"

Machine-readable output

$ malwagon sample.dll --json
{
  "limitations": [],
  "report_url": "https://malwagon.com/s/48213",
  "scan_id": 48213,
  "score": 88,
  "sha256": "354fd5f5e4afc2280a19c8541fd4abe38bf8fb73efbeb3c2b0a4f2b1d9e0c7a1",
  "size": 421888,
  "status": "completed",
  "verdict": "malicious",
  "verdict_raw": null
}

Progress goes to stderr and the result to stdout, so | jq works while you still see the wait.

Plans

A Community key works and runs a network isolated scan: no internet egress from the sandbox, and no threat intelligence or AI layer on the report. The tool says so under the verdict when a layer did not run, rather than leaving an empty section to be read as "the sample did nothing". A paid plan adds egress, reputation lookups and the AI narrative.

What this client will not do

• It will not send your key over plain HTTP, or to a host other than the one the key was stored for.
• It has no --insecure. TLS is verified, always. --ca-bundle exists for a private deployment.
• It does not follow redirects, because that is how a bearer token walks onto somebody else's host.
• It refuses a symlink, a device, a pipe and anything that looks like a private key or a credential file, unless you insist.
• It treats everything the server sends as untrusted text: terminal escapes, overwrite characters and bidirectional overrides are removed before anything is printed, and the verdict is looked up in a fixed table rather than printed as the server spelled it.

Links

• Platform: https://malwagon.com
• API reference: https://malwagon.com/docs/api