Scanything

Scan any file for malware, with an AI that explains false positives.

Scanything dissects a .zip, .exe, .dll or a GitHub repository without ever running it, tells you whether it looks malicious, explains whether an antivirus alert is probably a false positive, and lets you chat about the result. It works inside Claude Code and Codex as an MCP server, or on its own with your API key.

🇮🇩 Bahasa Indonesia: docs/README.id.md

Quick start

pip install "scanything[pe] @ git+https://github.com/arielfikru/scanything"

Then pick one:

scanything setup                 # use it from Claude Code / Codex (agent mode)

export NETRA_API_KEY=...         # or OPENROUTER_API_KEY / OPENAI_API_KEY
scanything ~/Downloads/file.zip  # standalone AI analyst (orchestrator mode)

No key and no agent? scanything file.zip --no-llm still gives the full static report.

Checking a repository before you clone it? scanything https://github.com/OWNER/REPO downloads the archive pinned to one commit and scans it in memory. Nothing is cloned, built or run.

Related MCP server: Malware-Sandbox-mcp

Two modes, one engine

Both modes use the same tools: scan_file, scan_github, get_report_section, search_strings, list_files, vt_lookup.

🤖 Agent mode: Claude Code & Codex

scanything setup              # both agents
scanything setup claude       # only Claude Code
scanything setup --dry-run    # show what would happen

No codex CLI on PATH? Add this to ~/.codex/config.toml:

[mcp_servers.scanything]
command = "/path/to/python"
args = ["-m", "scanything", "mcp"]

Restart the agent and ask:

> is ~/Downloads/Game_Setup.zip a virus? Defender says Wacatac

The agent calls scan_file, digs with search_strings and get_report_section, and answers with a verdict, the false-positive reasoning, the scan_id, and a next step.

🧠 Orchestrator mode: your own API key

Put one key in ~/.config/scanything/.env (template: .env.example) or export it, then:

$ scanything Game_Setup.zip --vt

== scanything: Game_Setup.zip ==
scan_id scn_9f2c41d0b7e3a8c5d1e6f402  ·  file_id (sha256) 5d41…c2a9  ·  ruleset rs_ace23f4945c8
Heuristic verdict: SUSPICIOUS  (score 11, 3 file(s), static only)

  #  type         size  score  name
  0  zip        4.1 MB      4  Game_Setup.zip
  1  pe         9.8 MB      7    └ Setup.exe
  2  text        312 B      0    └ readme.txt

[*] Asking deepseek/deepseek-v4-flash-0731 via netra for a verdict...
   ↳ get_report_section(files[1].pe.suspicious_imports)
   ↳ search_strings({"file_index": 1, "pattern": "webhook|telegram"})

## Verdict: LIKELY FALSE POSITIVE (confidence 75%)
...
verdict_id vrd_3b8e…  ·  scan_id scn_9f2c41d0b7e3a8c5d1e6f402
you> why does Defender call it Wacatac?

Providers

• Without --provider, Scanything uses LLM_PROVIDER, else the first key it finds (Netra → OpenRouter → OpenAI).

• --model or LLM_MODEL picks any other model. scanything models lists what your provider serves right now.

• Models without tool calling still work: Scanything falls back to plain chat, or pass --no-tools.

Options

scanything setup.exe --vt                   # VirusTotal hash lookup (never uploads)
scanything locked.zip --password infected   # encrypted archives
scanything file.exe --no-llm --json-out file.report.json   # offline, no AI
scanything file.exe --no-chat --md-out verdict.md          # CI / batch
scanything file.exe --provider openrouter --model anthropic/claude-sonnet-5.5 --lang en
scanything https://github.com/OWNER/REPO --no-llm             # a repository, pinned to its latest commit
scanything github:OWNER/REPO@v1.2.0                          # a branch, tag or commit

GITHUB_TOKEN (optional) raises GitHub's rate limit and gives access to private repositories you can read.

In chat: /save [file.md], /exit. Config is read from ./.env, then ~/.config/scanything/.env.

What it checks

MITRE ATT&CK

Signals map to the ATT&CK technique they are typical of, like capa does, and the summary lists every technique with its evidence (T1490 Inhibit System Recovery <- #1 shadow_copy_delete). A mapping means "this evidence is typical of the technique", not proof that the file performs it.

How false positives are judged

Every signal carries an fp_note saying when it is harmless, and the AI weighs those against the evidence.

Scan IDs

Every result gets IDs, like the hash-based IDs of malware scanning platforms.

scan_id ignores volatile data (timestamps, local path, VirusTotal/ClamAV results), so anyone scanning the same file with the same version gets the same id. It also seals the report:

from scanything.ids import scan_id_of
assert scan_id_of(report) == report["ids"]["scan_id"]   # fails if the JSON was edited

With --json-out, the report also holds verdict = {verdict_id, scan_id, label, confidence, provider, model, created}.

Try it safely

python scripts/make-test-samples.py   # harmless samples in ./samples (gitignored)
scanything samples/eicar.zip          # EICAR: every AV flags it, it does nothing
scanything samples/stealer_lookalike.exe

The samples are one-instruction PE stubs with malware-like strings, plus the standard EICAR test file. None of them does anything when run.

Highly recommended: Netra Runtime

We highly recommend Netra Runtime for orchestrator mode: fast inference, an OpenAI-compatible API, and DeepSeek V4 Flash 0731 handles the tool calling the analyst relies on. It is the first provider Scanything looks for, so NETRA_API_KEY is all you need. Save a key from your clipboard with scripts/save-netra-key (macOS).

The recommendation appears in this README, as a CLI hint when no key is set, as a one-line footer when Netra produced the verdict, and in the agent instructions only if you ask which provider to use. It never appears inside a verdict or affects how files are judged. SCANYTHING_NO_RECOMMEND=1 hides it.

How it works

file or GitHub repo ──► scanner (recursive, in memory, never executed)
           ├─ static: type, hashes, entropy, strings/IOCs, PE, toolchain DB, decoded strings, code rules
           ├─ archive: entries, passwords, bombs, nested files
           └─ engines (optional): VirusTotal, ClamAV, YARA, osslsigncode
        ──► report: signals + fp_notes + heuristic score + file_id / scan_id
        ──► tools: scan_file · scan_github · get_report_section · search_strings · list_files · vt_lookup
              ├─ MCP server ──► Claude Code / Codex / any MCP client     (agent mode)
              └─ built-in analyst ──► Netra / OpenRouter / OpenAI       (orchestrator mode)

Content from a scanned file is untrusted: both the MCP instructions and the analyst prompt say so, and text that tries to steer an AI is flagged as a prompt_injection signal.

Limits

• Static analysis can never prove a file is safe. When in doubt, use a sandbox (ANY.RUN, Hybrid Analysis, Tria.ge) or the vendor's published hash.

• No machine-learning score: there is no trained, openly licensed model small enough for a stdlib-only core, and an unexplained number would undercut the false-positive reasoning. VirusTotal results already include vendors' ML engines.

• Hidden-string recovery is pattern based, not emulation: multi-byte XOR, RC4 and runtime-built strings are not recovered.

• Repositories: up to 10,000 archive entries and 3,000 analyzed files, 512 MiB archive. Only what is in the repository is scanned, not the dependencies it pulls at install time.

• 7z, RAR and ISO are detected but not unpacked yet: extract them without running anything, then scan the contents.

• Authenticode is only verified when osslsigncode is installed; otherwise Scanything reports its presence and certificate names.

• The AI can be wrong. Treat its verdict as a second opinion with cited evidence.

Development

git clone https://github.com/arielfikru/scanything && cd scanything
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pyflakes scanything tests && .venv/bin/pytest -q

See CONTRIBUTING.md, AGENTS.md and SECURITY.md. Never commit live malware.

License

MIT, see LICENSE.