Metadata-Version: 2.5
Name: andymal
Version: 0.2.0
Summary: Andy Mal client - antimalware for agents. Scan files, packages and instructions with a real-time AI virus analyst before your agent acts on them.
Project-URL: Homepage, https://andymal.com
Project-URL: Documentation, https://api.andymal.com/docs
Project-URL: Source, https://github.com/andymal-com/andymal
Author-email: Andy Mal <hello@andymal.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude-code,malware,mcp,prompt-injection,security,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: mcp<2,>=1.2
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# Andy Mal

**Antimalware for agents. Your AI virus analyst, on call 24/7.**

Coding agents install packages, clone repos, open attachments and follow README instructions hundreds of
times a day. Signature-based antivirus is written by human analysts days after a sample appears, and
AI-written malware never had a signature. Andy reverse-engineers every file, package and instruction your
agent is about to act on, in real time, before it runs.

Every scan returns two verdicts:

- **payload**: what the file does when opened, installed or executed (credential theft, exfiltration,
  download-and-execute, persistence, obfuscation, install-time decryption)
- **delivery**: whether the agent was socially engineered or prompt-injected into opening it (hidden
  instructions, forged system messages, tool poisoning in MCP servers and skills, "ignore previous instructions")

This repository is the open-source client, the integrations, and the benchmark. The analysis engine runs
at `api.andymal.com` and is not part of this repo. Website: https://andymal.com

## Install

```bash
pip install andymal
curl -X POST https://api.andymal.com/v1/register -F email=you@example.com -F agent=claude-code   # free key
export ANDY_API_KEY=andy_...
```

Free tier: 50 scans a day, 30 a minute, unlimited hash lookups.

## Use

```bash
andy scan invoice.pdf --context-file email.txt   # a file, plus what the agent was told
andy scan pypi:requets                           # a package, before installing it
andy scan npm:lodahs@latest
andy scan ./cloned-repo                          # a directory (zipped and scanned as one sample)
cat README.md | andy scan -                      # any text that asks the agent to do something
andy scan --json ...                             # machine-readable
```

Exit codes: `0` clean, `1` suspicious, `2` malicious, `3` unknown or error. Hash first: the client sends a
SHA-256 before uploading; anything Andy has seen returns in milliseconds.

### MCP server (Claude Code, Claude Desktop, Cursor, Hermes, OpenCode, any MCP client)

```json
{"mcpServers": {"andy": {"command": "andy-mcp", "env": {"ANDY_API_KEY": "andy_..."}}}}
```

Tools: `andy_scan_file(path, context)`, `andy_scan_package("npm:name@ver" | "pypi:name==ver")`,
`andy_check_text(text, source)`, `andy_report(scan_id)`. See [integrations/mcp](integrations/mcp).

### Claude Code hook

Automatically checks `pip install`, `npm install`, `npx` and `curl | bash` before they run, and blocks on
malicious. See [integrations/claude-code](integrations/claude-code).

## Verdict shape

```json
{"verdict": "malicious", "action": "block", "confidence": 0.95,
 "summary": "Postinstall decrypts an embedded blob, compiles it with bytenode and deletes the source ...",
 "payload": {"verdict": "malicious", "score": 0.95, "findings": [...]},
 "delivery": {"verdict": "clean", "score": 0.0, "findings": []},
 "iocs": {"urls": [], "domains": [], "ips": [], "paths": []},
 "report_url": "https://api.andymal.com/report/<id>"}
```

`action` is what your agent should do: `allow`, `isolate` (run only in a throwaway sandbox without
credentials), or `block`. A result with `extra.degraded: true` was produced by heuristics only because the
analyst model was unavailable; treat it as advisory.

## Benchmark

`bench/` is a labelled, reproducible benchmark you can run against the public API with your own key:

```bash
python bench/run.py                                   # synthetic samples in bench/samples
python bench/fetch_real.py --npm 12 --pypi 12 --skills 6 --benign 16 --inject 20
python bench/run.py bench/real/manifest.json          # real samples (see below)
```

`fetch_real.py` pulls malicious npm/PyPI packages and malicious agent skills from
[DataDog/malicious-software-packages-dataset](https://github.com/DataDog/malicious-software-packages-dataset),
benign top packages from the registries, and prompt-injection texts from `deepset/prompt-injections`.
Samples are never executed anywhere; Andy's analysis is static plus an AI analyst. Downloaded samples stay
in the gitignored `bench/real/`.

Current numbers on that set (2026-09-04): 55/64, zero false positives, 24/24 malicious packages, 5/6
malicious skills; the misses are deepset entries that are not attacks on an agent ("write c++ code").
Send a PR with cases Andy gets wrong: that is the most useful contribution.

## Contributing

Client code, integrations for other agents, and benchmark cases are welcome. Issues about detection
quality should include the scan id or report URL. MIT licensed.
