jonaslejon/scanmalware-cli repository overview

⁠🧪 ScanMalware CLI

Rust command-line client for the ScanMalware API.

API docs:

• https://scanmalware.com/api-docs⁠
• https://scanmalware.com/openapi.json⁠

⁠✨ Features

• Submit URL scans, poll for completion, and fetch results/summary/progress.
• Batch mode for URLs or scan IDs (file or stdin).
• Search coverage across all search endpoints exposed by the API.
• Output formats: json, text, csv, raw.
• Quiet and silent modes; ANSI color control for text output.
• Health and module ping checks.
• Cross-compile friendly (Rust + rustls, build script included).

⁠📦 Install

⁠Quick install (macOS/Linux)

curl -fsSL https://scanmalware.com/install.sh | bash

⁠Windows (PowerShell)

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; irm https://scanmalware.com/install.ps1 | iex

⁠Homebrew

brew tap scanmalware/tap && brew install scanmalware/tap/scanmalware-cli

Supported targets: macOS (x86_64, arm64), Linux (x86_64, arm64, armv7), and Windows (x86_64, arm64).

Install a specific version or custom location (macOS/Linux):

SCANMALWARE_VERSION=0.1.8 \
SCANMALWARE_INSTALL_DIR="$HOME/.local/bin" \
curl -fsSL https://scanmalware.com/install.sh | bash

⁠Build from source

cargo install --path .

Or build a local binary:

cargo build --release

⁠🐳 Docker

Run the CLI directly from Docker Hub (multi-arch linux/amd64, linux/arm64, linux/arm/v7):

docker run --rm jonaslejon/scanmalware-cli:latest --help
docker run --rm jonaslejon/scanmalware-cli:latest scan https://example.com --wait
docker run --rm jonaslejon/scanmalware-cli:latest search screenshot-hash phash bc3c3cc1c3c3c3c3 --limit 5

If you want to pass environment variables:

docker run --rm \
  -e SCANMALWARE_BASE_URL=https://scanmalware.com \
  -e SCANMALWARE_TIMEOUT=60 \
  jonaslejon/scanmalware-cli:latest health

⁠⚙️ Configuration

• SCANMALWARE_BASE_URL (default: https://scanmalware.com)
• SCANMALWARE_TIMEOUT (request timeout in seconds)

Command-line flags override environment variables. No authentication is required.

⁠🚀 Usage

If scanmalware alone feels too minimal, use the built-in help:

scanmalware --help
scanmalware scan --help
scanmalware search --help
scanmalware technologies --help

scanmalware scan https://example.com
scanmalware scan https://example.com --wait --wait-interval 5 --wait-timeout 600
scanmalware scan https://example.com --unlisted
scanmalware result <scan_id>
scanmalware summary <scan_id>
scanmalware progress <scan_id>
scanmalware recent --page 1 --limit 20
scanmalware health
scanmalware ping

Global flags can be placed before or after the subcommand:

scanmalware --format text --color always stats
scanmalware stats --format text --color always

Global options:

--base-url <URL>        Override API base URL (or SCANMALWARE_BASE_URL)
--timeout-secs <SECS>   Request timeout in seconds (or SCANMALWARE_TIMEOUT)
--format <FORMAT>       text | json | csv | raw
--color <MODE>          auto | always | never
--quiet                Suppress batch headers
--silent               Suppress all output

⁠🧪 Examples

# Scan and wait for completion (text output)
scanmalware scan https://example.com --wait

# JSON output for a result
scanmalware result <scan_id> --format json

# Scan then fetch summary
scanmalware scan https://example.com --wait --format json
scanmalware summary <scan_id>

# OCR text for a scan
scanmalware ocr text <scan_id>

# Search OCR text
scanmalware search ocr "login" --limit 5

# CSV output for a search
scanmalware search scans "example" --limit 10 --format csv

# Search technologies (top-level command)
scanmalware technologies search --query cloudflare --limit 5

# Batch scan (NDJSON output)
scanmalware scan --batch urls.txt --format json > scans.ndjson

# Search by screenshot hash (hex values)
scanmalware search screenshot-hash phash bc3c3cc1c3c3c3c3 --limit 5
scanmalware search screenshot-hash dhash 2026000000000000 --limit 5
scanmalware search screenshot-hash color_hash "#87b3c5" --limit 5

# Search similar screenshots (integer hash values)
scanmalware search screenshot-similar 13563782980643832771 --hash-type phash --max-distance 5 --limit 5
scanmalware search screenshot-similar 2316539058328698880 --hash-type dhash --max-distance 5 --limit 5

# TLSH search (JS segments)
scanmalware search js-segments tlsh <tlsh_hash> --max-distance 30 --limit 50 --include-known-libraries true

Notes:

• Use screenshot_hashes.*_hex for search screenshot-hash.
• Use screenshot_hashes.*_int for search screenshot-similar.
• Quote # in color hashes to avoid shell comments.

⁠🧰 Batch mode

Batch mode accepts a file path or - for stdin. Batch JSON output is NDJSON.

scanmalware scan --batch urls.txt
scanmalware result --batch scan_ids.txt
cat urls.txt | scanmalware scan --batch -

⁠🧾 Output formats

• text (default): human-readable tree output with optional ANSI color.
• json: pretty-printed JSON for a single response.
• csv: two-column CSV with JSON values encoded as strings.
• raw: raw response body (useful for binary endpoints).

Use --quiet to suppress batch headers and --silent to suppress all output. Use --color auto|always|never for text output.

⁠🔍 Search

Search commands are organized under scanmalware search. Use scanmalware search --help to see the full list.

Core search:

• search scans
• search asn
• search ip
• search ip-stats
• search jarm
• search favicon
• search favicon-mmh3
• search fuzzy
• search clipboard-suspicious
• search ocr
• search ocr-pattern
• search screenshot-hash
• search screenshot-similar
• search semantic
• search similar
• search cpe
• search registrar
• search technologies

AI and analyzer search:

• search ai classification
• search ai high-risk
• search ai scam-type
• search analyzers high-risk

JavaScript search:

• search js-fingerprinter2 code-hash
• search js-fingerprinter2 composite-hash
• search js-fingerprinter2 coverage
• search js-fingerprinter2 health
• search js-fingerprinter2 js-obfuscation
• search js-fingerprinter2 malware-families
• search js-fingerprinter2 signature
• search js-fingerprinter2 similar
• search js-segments hash
• search js-segments normalized
• search js-segments tlsh
• search js-fingerprints bundler
• search js-fingerprints fuzzy
• search js-fingerprints library
• search js-fingerprints library-version
• search js-fingerprints md5
• search js-fingerprints normalized
• search js-fingerprints sha1
• search js-fingerprints sha256

⁠🧩 Generic request and download

Use request for arbitrary JSON endpoints and download for binary payloads.

scanmalware request --method GET --path /api/v1/search --query q=example --query page=1
scanmalware download --path /api/v1/pcap/<scan_id> --output scan.pcap.gz

⁠🧱 Cross-compiling

This project uses reqwest with rustls to reduce OS-specific dependencies. The scripts/build-release.sh script builds Linux, Windows, and macOS targets.

cargo install cargo-zigbuild
# Install Zig from https://ziglang.org/download/
./scripts/build-release.sh

Notes:

• Building macOS targets on non-macOS hosts requires a macOS SDK (for example via osxcross).
• You can also build native binaries on each OS with cargo build --release.

⁠🛠️ Troubleshooting

• Negative mmh3 hashes are positional arguments; use -- to avoid flag parsing: scanmalware search favicon --limit 1 -- -1670507450
• Increase --timeout-secs if requests time out on long-running endpoints.