Metadata-Version: 2.5
Name: malwagon
Version: 0.1.0
Summary: Submit a file to the Malwagon malware analysis sandbox and print the verdict.
Project-URL: Homepage, https://malwagon.com
Project-URL: Documentation, https://malwagon.com/docs/api
Author-email: Malwagon <info@malwagon.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,dfir,malware,malware-analysis,sandbox,security,threat-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# malwagon

Submit a file to the [Malwagon](https://malwagon.com) malware analysis sandbox
from the command line, wait for the detonation to finish, and print the verdict.

```console
$ 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

```console
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:

```console
$ 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:

```console
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

```console
malwagon FILE [options]
```

| | |
|---|---|
| `--json` | print one JSON object and nothing else |
| `--no-wait` | submit and exit with the scan id |
| `--private` | keep the report private (needs a plan that includes it) |
| `--internet` | detonate with internet access (paid plans only) |
| `--os KEY` | force a sandbox image |
| `--timeout-run N` | how long to let the sample run |
| `--quiet` | drop the progress lines, keep the result |

`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

| code | meaning |
|---|---|
| 0 | clean |
| 1 | malicious |
| 2 | error |
| 3 | suspicious |

So a pipeline can gate on it:

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

## Machine-readable output

```console
$ 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>
