malwagon 0.1.0__py3-none-any.whl

malwagon/__init__.py

@@ -0,0 +1,13 @@
+"""Malwagon command line client.
+
+Submits a file to the Malwagon malware analysis sandbox, waits for the
+detonation to finish, and prints the verdict.
+
+Standard library only, on purpose. A security tool that pulls four transitive
+dependencies to make one HTTPS request has widened its own supply chain for a
+convenience, and every one of those maintainer keys becomes a way into the
+machines this runs on.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

malwagon/cli.py

@@ -0,0 +1,407 @@
+"""malwagon <file> - submit a sample, wait for the detonation, print the verdict.
+
+The whole tool is one command with one argument. Everything else is a default
+that can be overridden, because the thing a person actually wants to type is
+
+    malwagon suspicious.exe
+
+and a tool that requires six flags to do its only job is a tool people wrap in a
+shell function and then misconfigure.
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+
+from . import __version__, config, localfile, render
+from .client import DEFAULT_API_URL, Client, host_of, normalise_url
+from .errors import MalwagonError
+
+#: Poll cadence. The server's read budget is 120 requests a minute per user, so
+#: a scan polled every 4 seconds costs 15 a minute and a dozen concurrent
+#: clients still fit. It widens as the wait grows: a scan that has been running
+#: two minutes is not about to finish in the next four seconds.
+_POLL_START = 4
+_POLL_MAX = 20
+
+#: What to tell the user to expect. Measured against the platform's own
+#: documentation: a pre-armed guest starts the sample about three seconds in,
+#: the default run is 120 seconds, and post-run collection (memory, rules,
+#: report) is the rest. A cold boot moves the whole thing by minutes, which is
+#: why this is stated as a range and called an estimate.
+_ESTIMATE_LOW = 90
+_ESTIMATE_HIGH = 300
+
+#: Long enough to cover a cold boot plus the 600 second maximum run plus
+#: collection, short enough that a wedged scan does not hold a terminal all day.
+_DEFAULT_DEADLINE = 1800
+
+EXIT_OK = 0
+EXIT_MALICIOUS = 1
+EXIT_ERROR = 2
+EXIT_SUSPICIOUS = 3
+
+
+def _duration(seconds):
+    seconds = int(seconds)
+    if seconds < 60:
+        return "%ds" % seconds
+    return "%dm %02ds" % (seconds // 60, seconds % 60)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="malwagon",
+        description="Submit a file to the Malwagon sandbox and print the verdict.",
+        epilog=(
+            "examples:\n"
+            "  malwagon suspicious.exe            submit, wait, print the verdict\n"
+            "  malwagon driver.sys --json         machine-readable output\n"
+            "  malwagon payload.elf --no-wait     submit and exit with the scan id\n"
+            "  malwagon login                     store the API key for this host\n"
+            "\n"
+            "the API key, in order of precedence:\n"
+            "  --api-key-file PATH   read the first line of a file\n"
+            "  --api-key-stdin       read the first line of stdin\n"
+            "  %-21s an environment variable\n"
+            "  the config file       written by 'malwagon login'\n"
+            "\n"
+            "there is deliberately no --api-key flag: a key on the command line is\n"
+            "visible in the process list and is written to your shell history.\n"
+            "\n"
+            "exit codes: 0 clean, 1 malicious, 2 error, 3 suspicious\n"
+            % config.ENV_KEY),
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    parser.add_argument("target", nargs="?", metavar="FILE",
+                        help="the file to scan, or 'login' / 'logout'")
+    parser.add_argument("--version", action="version",
+                        version="malwagon %s" % __version__)
+
+    api = parser.add_argument_group("api")
+    api.add_argument("--api-url", default=None, metavar="URL",
+                     help="base URL of the platform (default %s, or %s)"
+                          % (DEFAULT_API_URL, config.ENV_URL))
+    api.add_argument("--api-key-file", default=None, metavar="PATH",
+                     help="read the API key from the first line of this file")
+    api.add_argument("--api-key-stdin", action="store_true",
+                     help="read the API key from the first line of stdin")
+    api.add_argument("--ca-bundle", default=None, metavar="PATH",
+                     help="verify TLS against this CA bundle instead of the system store")
+    api.add_argument("--proxy", default=None, metavar="URL",
+                     help="send the request through this proxy")
+    api.add_argument("--timeout", type=int, default=120, metavar="SECONDS",
+                     help="per-request timeout (default 120)")
+
+    scan = parser.add_argument_group("scan options")
+    scan.add_argument("--private", action="store_true",
+                      help="keep the report private (needs a plan that includes it)")
+    scan.add_argument("--internet", action="store_true",
+                      help="detonate with internet access (paid plans only)")
+    scan.add_argument("--os", default=None, metavar="KEY", dest="os_key",
+                      help="force a sandbox image; by default the platform picks "
+                           "Windows or Linux from the file itself")
+    scan.add_argument("--timeout-run", type=int, default=None, metavar="SECONDS",
+                      dest="run_timeout",
+                      help="how long to let the sample run inside the sandbox")
+    scan.add_argument("--no-dynamic", action="store_true",
+                      help="static analysis only, no detonation")
+    scan.add_argument("--no-ai", action="store_true",
+                      help="skip the AI narrative layer")
+
+    wait = parser.add_argument_group("waiting")
+    wait.add_argument("--no-wait", action="store_true",
+                      help="submit and exit immediately with the scan id")
+    wait.add_argument("--wait-timeout", type=int, default=_DEFAULT_DEADLINE,
+                      metavar="SECONDS",
+                      help="give up waiting after this long (default %d)"
+                           % _DEFAULT_DEADLINE)
+
+    out = parser.add_argument_group("output")
+    out.add_argument("--json", action="store_true", dest="as_json",
+                     help="print one JSON object and nothing else")
+    out.add_argument("--quiet", "-q", action="store_true",
+                     help="suppress progress; the result still prints")
+    out.add_argument("--no-color", action="store_true",
+                     help="never emit colour (NO_COLOR is also honoured)")
+
+    safety = parser.add_argument_group("safety")
+    safety.add_argument("--force", action="store_true",
+                        help="upload even if the path looks like a credential file")
+    safety.add_argument("--follow-symlinks", action="store_true",
+                        help="upload the target of a symlink rather than refusing")
+    return parser
+
+
+def _resolve_api_url(args):
+    return normalise_url(args.api_url or os.environ.get(config.ENV_URL)
+                         or DEFAULT_API_URL)
+
+
+def _error_message(status, body):
+    """The server's own words, sanitised, or a sentence about the status."""
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, dict) and error.get("message"):
+            return render.safe(error["message"], limit=300)
+    return {
+        400: "the platform rejected the request",
+        401: "the API key was not accepted",
+        402: "no scan credits left on this account",
+        403: "this key is not allowed to do that",
+        404: "not found",
+        413: "the file is too large for this platform",
+        429: "rate limited",
+    }.get(status, "the platform answered HTTP %d" % status)
+
+
+def _fail_from_response(status, body, headers=None):
+    message = _error_message(status, body)
+    hint = ""
+    if status == 401:
+        hint = ("mint a key in the console under Settings, API tokens, then "
+                "store it with 'malwagon login'")
+    elif status == 403 and "submit" in message:
+        hint = "the key needs the submit permission, not just read"
+    elif status == 429 and headers is not None:
+        retry = headers.get("Retry-After")
+        if retry:
+            hint = "try again in %s seconds" % render.safe(retry, limit=12)
+    return MalwagonError(message, hint=hint)
+
+
+def _plan_notes(report):
+    """What this account did NOT get, said plainly.
+
+    A Community scan runs network isolated and without the intelligence and AI
+    layers, and a report that simply omits those sections reads as "the sample
+    did nothing" rather than "we did not look". Saying which layers were absent
+    is the difference between a result and a misleading result.
+    """
+    notes = []
+    if not isinstance(report, dict):
+        return notes
+    intel = report.get("intel")
+    ai = report.get("ai")
+    empty_intel = not intel or (isinstance(intel, dict) and not intel.get("items")
+                                and not intel.get("sources"))
+    if empty_intel:
+        notes.append("threat intelligence lookups did not run")
+    if not ai:
+        notes.append("the AI narrative did not run")
+    return notes
+
+
+def cmd_login(args, printer):
+    api_url = _resolve_api_url(args)
+    host = host_of(api_url)
+    key, source = config.resolve_key(args, host, prompt=True)
+    client = Client(api_url, key, timeout=args.timeout, ca_bundle=args.ca_bundle,
+                    proxy=args.proxy)
+    # Proved before it is stored. Writing a key that does not work, and finding
+    # out at the next scan, is the failure this round trip exists to prevent.
+    status, body, _ = client.scan_status(0)
+    if status in (401, 403):
+        raise _fail_from_response(status, body)
+    if status >= 500:
+        raise MalwagonError("the platform is not answering (HTTP %d)" % status)
+    path = config.save_key(host, key, api_url)
+    printer.note("key accepted (read from the %s) and saved to %s" % (source, path))
+    if os.name == "posix":
+        printer.note("the file is readable only by you")
+    return EXIT_OK
+
+
+def cmd_logout(args, printer):
+    host = host_of(_resolve_api_url(args))
+    if config.forget_key(host):
+        printer.note("removed the stored key for %s" % host)
+    else:
+        printer.note("no key was stored for %s" % host)
+    return EXIT_OK
+
+
+def _submit(client, args, printer):
+    handle, name, size = localfile.open_sample(
+        args.target, allow_sensitive=args.force,
+        allow_symlink=args.follow_symlinks)
+    with handle:
+        printer.note("uploading %s (%s) to %s"
+                     % (name, localfile.human_size(size), client.host))
+        fields = {
+            "private": "true" if args.private else None,
+            "internet": "true" if args.internet else None,
+            "os": args.os_key,
+            "timeout": str(args.run_timeout) if args.run_timeout else None,
+            "dynamic": "false" if args.no_dynamic else None,
+            "ai": "false" if args.no_ai else None,
+        }
+        status, body, headers = client.submit_file(handle, name, fields)
+    if status != 202:
+        raise _fail_from_response(status, body, headers)
+    scan = (body or {}).get("scan")
+    if not isinstance(scan, dict) or not isinstance(scan.get("scan_id"), int):
+        raise MalwagonError("the platform accepted the upload but did not "
+                            "return a scan id")
+    return scan
+
+
+def _wait(client, scan_id, args, printer):
+    """Poll until the scan is terminal, saying so while it happens."""
+    deadline = time.monotonic() + max(30, args.wait_timeout)
+    started = time.monotonic()
+    interval = _POLL_START
+    last_status = ""
+    printer.note("waiting for the sandbox, usually %d to %d seconds"
+                 % (_ESTIMATE_LOW, _ESTIMATE_HIGH))
+    scan = None
+    while True:
+        status, body, headers = client.scan_status(scan_id)
+        if status == 429:
+            retry = 0
+            try:
+                retry = int(headers.get("Retry-After") or 0)
+            except (TypeError, ValueError):
+                retry = 0
+            # A hostile or misconfigured server can send an enormous
+            # Retry-After; honour it up to a ceiling and no further.
+            interval = max(interval, min(retry or interval, 60))
+        elif status != 200:
+            raise _fail_from_response(status, body, headers)
+        else:
+            scan = (body or {}).get("scan")
+            if not isinstance(scan, dict):
+                raise MalwagonError("the platform returned an unreadable status")
+            state = render.safe(scan.get("status"), limit=24)
+            if state not in render.STATUSES:
+                state = "running"
+            if state != last_status:
+                last_status = state
+                printer.note("  %-12s %s elapsed"
+                             % (state, _duration(time.monotonic() - started)))
+            if scan.get("terminal"):
+                return scan
+        if time.monotonic() > deadline:
+            raise MalwagonError(
+                "the scan did not finish within %s" % _duration(args.wait_timeout),
+                hint="it may still be running: %s" % client.report_url(scan_id))
+        time.sleep(interval)
+        interval = min(_POLL_MAX, interval * 1.5)
+
+
+def _print_result(scan, report, url, printer, args, notes):
+    verdict, raw = render.verdict_word(scan.get("verdict"))
+    score = scan.get("score")
+    score = score if isinstance(score, int) and 0 <= score <= 100 else None
+
+    if args.as_json:
+        printer.out(json.dumps({
+            "scan_id": scan.get("scan_id"),
+            "verdict": verdict,
+            "verdict_raw": raw or None,
+            "score": score,
+            "status": render.safe(scan.get("status"), limit=24),
+            "sha256": render.safe(scan.get("sha256"), limit=64),
+            "size": scan.get("size") if isinstance(scan.get("size"), int) else None,
+            "report_url": url,
+            "limitations": notes,
+        }, indent=2, sort_keys=True))
+        return
+
+    printer.out("")
+    label = verdict.upper()
+    if raw:
+        label += " (server said %r)" % raw
+    line = printer.paint(label, verdict)
+    if score is not None:
+        line += "  score %d/100" % score
+    printer.out("  " + line)
+    digest = render.safe(scan.get("sha256"), limit=64)
+    if digest:
+        printer.out("  sha256 " + printer.paint(digest, "dim"))
+    printer.out("  report " + url)
+    if notes:
+        printer.out("")
+        for note in notes:
+            printer.out("  " + printer.paint("- " + note, "dim"))
+        printer.out("  " + printer.paint(
+            "  a paid plan adds internet egress, threat intelligence and the",
+            "dim"))
+        printer.out("  " + printer.paint(
+            "  AI narrative to this report", "dim"))
+    printer.out("")
+
+
+def run(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    printer = render.Printer(colour=False if args.no_color else None,
+                             quiet=args.quiet)
+
+    if not args.target:
+        parser.print_help(sys.stderr)
+        return EXIT_ERROR
+    if args.target == "login":
+        return cmd_login(args, printer)
+    if args.target == "logout":
+        return cmd_logout(args, printer)
+
+    api_url = _resolve_api_url(args)
+    host = host_of(api_url)
+    key, _source = config.resolve_key(args, host)
+    client = Client(api_url, key, timeout=args.timeout,
+                    ca_bundle=args.ca_bundle, proxy=args.proxy)
+
+    scan = _submit(client, args, printer)
+    scan_id = scan["scan_id"]
+    url = client.report_url(scan_id)
+    printer.note("scan %d queued" % scan_id)
+
+    if args.no_wait:
+        if args.as_json:
+            printer.out(json.dumps({"scan_id": scan_id, "status": "queued",
+                                    "report_url": url}, indent=2, sort_keys=True))
+        else:
+            printer.out(url)
+        return EXIT_OK
+
+    scan = _wait(client, scan_id, args, printer)
+    state = render.safe(scan.get("status"), limit=24)
+    if state != "completed":
+        raise MalwagonError("the scan ended as %s" % (state or "unknown"),
+                            hint=url)
+
+    notes = []
+    if scan.get("report_available"):
+        status, body, _ = client.scan_report(scan_id)
+        if status == 200 and isinstance(body, dict):
+            notes = _plan_notes(body.get("report"))
+
+    _print_result(scan, None, url, printer, args, notes)
+    verdict, _ = render.verdict_word(scan.get("verdict"))
+    if verdict == "malicious":
+        return EXIT_MALICIOUS
+    if verdict == "suspicious":
+        return EXIT_SUSPICIOUS
+    return EXIT_OK
+
+
+def main(argv=None):
+    try:
+        return run(argv)
+    except MalwagonError as exc:
+        print("malwagon: %s" % config.redact(exc.message), file=sys.stderr)
+        if exc.hint:
+            print("          %s" % config.redact(exc.hint), file=sys.stderr)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        print("\nmalwagon: interrupted", file=sys.stderr)
+        return 130
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

malwagon/client.py

@@ -0,0 +1,237 @@
+"""The HTTP half: one host, one bearer token, bounded answers.
+
+Standard library only. `urllib.request` is more awkward than `requests`, and it
+is four fewer maintainer keys in the trust path of a tool that handles malware
+samples and an API credential.
+
+The rules this module exists to keep:
+
+  - HTTPS, verified, always. There is no --insecure and there will not be one.
+    A flag that turns off certificate checking is used far more often to make an
+    error go away than to solve the problem the error was reporting.
+  - No redirects, ever followed. A redirect is the standard way to walk a bearer
+    token onto a host that was not the one it was stored for, and this client
+    reports the Location instead of chasing it.
+  - No ambient configuration. `urllib` reads no netrc and no proxy environment
+    here unless the user asks for a proxy explicitly, so a `machine ...` line in
+    ~/.netrc cannot attach a second credential to our request.
+  - Every response is bounded before it is parsed. `Content-Length` is a claim,
+    not a fact, so the read is capped by count, and the cap applies to the
+    DECOMPRESSED stream - a 2 MB gzip body can be 20 GB of JSON.
+"""
+
+import gzip
+import io
+import json
+import socket
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+from . import __version__
+from .config import redact
+from .errors import MalwagonError
+
+DEFAULT_API_URL = "https://malwagon.com"
+
+#: Generous for the objects this API returns (a report is a few tens of KB) and
+#: far below anything that would trouble a laptop.
+MAX_RESPONSE = 4 * 1024 * 1024
+
+USER_AGENT = "malwagon-cli/%s" % __version__
+
+
+def normalise_url(raw):
+    """Validate a base URL and return it without a trailing slash.
+
+    Refusals, each because it is a way to move a credential somewhere it was not
+    meant to go: a non-https scheme off the loopback, a URL carrying userinfo
+    (`https://user:pass@host` - a second credential, and one that shows up in
+    logs), and a URL with a query or fragment, which a base URL has no use for
+    and which would be silently dropped when a path is appended.
+    """
+    raw = (raw or "").strip()
+    if not raw:
+        raise MalwagonError("the API URL is empty")
+    parts = urllib.parse.urlsplit(raw)
+    if not parts.scheme or not parts.netloc:
+        raise MalwagonError("%r is not a full URL (try https://malwagon.com)" % raw)
+    if parts.username or parts.password:
+        raise MalwagonError("the API URL must not contain a username or password")
+    if parts.query or parts.fragment:
+        raise MalwagonError("the API URL must not contain a query or a fragment")
+    host = (parts.hostname or "").lower()
+    if parts.scheme != "https":
+        if not (parts.scheme == "http"
+                and host in ("localhost", "127.0.0.1", "::1")):
+            raise MalwagonError(
+                "the API URL must be https (%r is not)" % raw,
+                hint="plain http is accepted only for localhost")
+    return urllib.parse.urlunsplit(
+        (parts.scheme, parts.netloc, parts.path.rstrip("/"), "", ""))
+
+
+def host_of(url):
+    return (urllib.parse.urlsplit(url).hostname or "").lower()
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """A redirect is reported, never followed.
+
+    Following one is how a bearer token reaches a host it was not stored for,
+    and following it "just once, to the same host" still hands an in-path
+    attacker an https-to-http downgrade.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        raise MalwagonError(
+            "the server answered %s and redirected to %s"
+            % (code, redact(newurl)),
+            hint="this client does not follow redirects; check --api-url")
+
+
+def _ssl_context():
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = True
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    # Belt and braces: an environment that disabled verification globally would
+    # otherwise be honoured silently, which is the one failure a security tool
+    # must not have.
+    if ctx.verify_mode is not ssl.CERT_REQUIRED or not ctx.check_hostname:
+        raise MalwagonError("this Python's TLS defaults have been weakened; "
+                            "refusing to send a credential over it")
+    return ctx
+
+
+class Client:
+    def __init__(self, api_url, api_key, *, timeout=60, ca_bundle=None,
+                 proxy=None):
+        self.api_url = normalise_url(api_url)
+        self.host = host_of(self.api_url)
+        self.api_key = api_key
+        self.timeout = timeout
+        ctx = _ssl_context()
+        if ca_bundle:
+            try:
+                ctx.load_verify_locations(cafile=ca_bundle)
+            except (OSError, ssl.SSLError) as exc:
+                raise MalwagonError("could not load %s: %s" % (ca_bundle, exc)) from exc
+        handlers = [urllib.request.HTTPSHandler(context=ctx), _NoRedirect()]
+        # `ProxyHandler({})` with an EMPTY mapping is what disables proxy
+        # discovery; omitting the handler would let urllib read the environment.
+        handlers.append(urllib.request.ProxyHandler({"https": proxy, "http": proxy}
+                                                    if proxy else {}))
+        self._opener = urllib.request.build_opener(*handlers)
+
+    # -- transport -------------------------------------------------------
+    def _request(self, method, path, *, body=None, content_type=None):
+        url = self.api_url + path
+        request = urllib.request.Request(url, data=body, method=method)
+        request.add_header("Authorization", "Bearer " + self.api_key)
+        request.add_header("Accept", "application/json")
+        request.add_header("User-Agent", USER_AGENT)
+        # Asked for explicitly so the response cap below is the only thing that
+        # decides how much is decompressed.
+        request.add_header("Accept-Encoding", "identity")
+        if content_type:
+            request.add_header("Content-Type", content_type)
+        try:
+            response = self._opener.open(request, timeout=self.timeout)
+        except urllib.error.HTTPError as exc:
+            return self._decode(exc.code, exc.headers, exc)
+        except urllib.error.URLError as exc:
+            reason = getattr(exc, "reason", exc)
+            if isinstance(reason, ssl.SSLCertVerificationError):
+                raise MalwagonError(
+                    "the TLS certificate for %s could not be verified: %s"
+                    % (self.host, reason.verify_message or reason),
+                    hint="if this is a private deployment, pass --ca-bundle") from exc
+            if isinstance(reason, socket.timeout):
+                raise MalwagonError("%s did not answer within %ds"
+                                    % (self.host, self.timeout)) from exc
+            raise MalwagonError("could not reach %s: %s"
+                                % (self.host, redact(reason))) from exc
+        except socket.timeout as exc:
+            raise MalwagonError("%s did not answer within %ds"
+                                % (self.host, self.timeout)) from exc
+        with response:
+            return self._decode(response.status, response.headers, response)
+
+    def _decode(self, status, headers, stream):
+        """(status, parsed-body-or-None, headers), with every bound applied."""
+        try:
+            declared = int(headers.get("Content-Length") or 0)
+        except (TypeError, ValueError):
+            declared = 0
+        if declared > MAX_RESPONSE:
+            raise MalwagonError("%s declared a %d byte response, which is over "
+                                "this client's %d byte ceiling"
+                                % (self.host, declared, MAX_RESPONSE))
+        raw = stream.read(MAX_RESPONSE + 1)
+        if len(raw) > MAX_RESPONSE:
+            raise MalwagonError("the response from %s exceeded %d bytes"
+                                % (self.host, MAX_RESPONSE))
+        if (headers.get("Content-Encoding") or "").lower() == "gzip":
+            try:
+                with gzip.GzipFile(fileobj=io.BytesIO(raw)) as gz:
+                    raw = gz.read(MAX_RESPONSE + 1)
+            except OSError as exc:
+                raise MalwagonError("the response from %s was not valid gzip"
+                                    % self.host) from exc
+            if len(raw) > MAX_RESPONSE:
+                raise MalwagonError("the response from %s expanded past %d bytes"
+                                    % (self.host, MAX_RESPONSE))
+        body = None
+        kind = (headers.get("Content-Type") or "").split(";")[0].strip().lower()
+        if kind == "application/json" and raw:
+            try:
+                body = json.loads(raw.decode("utf-8"))
+            except (ValueError, UnicodeDecodeError, RecursionError):
+                body = None
+        if body is not None and not isinstance(body, dict):
+            body = None
+        return status, body, headers
+
+    # -- endpoints -------------------------------------------------------
+    def submit_file(self, handle, name, fields):
+        """POST /api/v1/scans/file as multipart, built by hand.
+
+        Built rather than borrowed because the whole file is already open and
+        bounded; encoding it into a string first would double the memory for a
+        128 MB sample.
+        """
+        boundary = "----malwagon" + uuid.uuid4().hex
+        parts = []
+        for key, value in sorted(fields.items()):
+            if value is None:
+                continue
+            parts.append(
+                ("--%s\r\nContent-Disposition: form-data; name=\"%s\"\r\n\r\n%s\r\n"
+                 % (boundary, key, value)).encode("utf-8"))
+        head = ("--%s\r\nContent-Disposition: form-data; name=\"file\"; "
+                "filename=\"%s\"\r\nContent-Type: application/octet-stream\r\n\r\n"
+                % (boundary, name.replace('"', "_"))).encode("utf-8")
+        tail = ("\r\n--%s--\r\n" % boundary).encode("utf-8")
+        body = b"".join(parts) + head + handle.read() + tail
+        return self._request(
+            "POST", "/api/v1/scans/file", body=body,
+            content_type="multipart/form-data; boundary=%s" % boundary)
+
+    def scan_status(self, scan_id):
+        return self._request("GET", "/api/v1/scans/%d" % int(scan_id))
+
+    def scan_report(self, scan_id):
+        return self._request("GET", "/api/v1/scans/%d/report" % int(scan_id))
+
+    def report_url(self, scan_id):
+        """The human page for a scan.
+
+        Built here rather than read from the response, because the API returns
+        no URL - deliberately, since it emits no field nobody named. `/s/<id>`
+        is the platform's own short link: it resolves for the owner and
+        redirects a public scan onto its indexable page.
+        """
+        return "%s/s/%d" % (self.api_url, int(scan_id))