Skip to main content

honeyrun

Run an untrusted repo or MCP server and see what it truly reaches for.

ci license: MIT python 3.11+ macOS · Linux · Windows sandbox: gVisor or VM dependencies: 0 works with

Try it What it looks for Benchmark GitHub Action

honeyrun catching an MCP server that reads ~/.cursor/mcp.json and posts it out

Your coding agent installs packages, clones repos and adds MCP servers for you now. One postinstall script or one poisoned tool description can read ~/.ssh, ~/.aws and your agent's API keys before you notice. Reading the code first doesn't help much when the payload is base64, waits a month, or only wakes up inside CI.

honeyrun runs it for you first, in a throwaway sandbox whose home folder is full of fake keys: SSH, AWS, GitHub, npm, and the configs of Claude, Codex, Cursor and Gemini. Each key is made up for that run. If one turns up in a web request, a DNS lookup or a log line, you know exactly what took it and where it went.

pipx install honeyrun==0.1.1      # signed build on PyPI; see "Verify what you install"
honeyrun npm:some-package        # or owner/repo, pypi:name, a folder, an MCP server

Before running anything it reads the code for hooks and hidden instructions. While it runs, it watches every process, file and connection. Then it runs the code again with the clock 45 days ahead, for code that waits. You get one line at the end: LOOKS SAFE, UNCLEAR or NOT SAFE, and what to do next.

  • One command, no account, no server. Runs on your laptop or in a GitHub Action. Zero Python dependencies.
  • Catches what reading misses. On 100 real malicious packages, 33 were marked NOT SAFE, and 32 of those looked clean or only suspicious when the same code was just read. They gave themselves away when they ran.
  • Built for the agent era. It calls every MCP tool, spots instructions hidden for your AI, notices when a tool quietly changes after you approved it, and gives your agent a short answer it can act on.

Try it

Point it at whatever you're about to trust:

honeyrun owner/repo                  # any git host: GitHub, GitLab, Codeberg, your own server
honeyrun npm:some-package            # npm:@scope/name@1.2.3 works too
honeyrun pypi:some-package==1.0.0
honeyrun ./downloads/tool.tgz        # .tgz .zip .whl .vsix .crate
honeyrun ./my-app --installed        # already installed it? checks node_modules and .venv, runs nothing
honeyrun --agent-configs             # the MCP servers and hooks your agents start on this machine
honeyrun owner/repo --static-only    # read only, a few seconds, no sandbox needed
honeyrun owner/repo --deep           # extra passes: as if inside CI, and three runs in a row

The end of a run looks like this:

NOT SAFE  Do not install or run this.
          2 critical, 4 high, 1 medium

What to do now:
  1. It ran only inside the sandbox: your real files and keys were not exposed by this check.
  2. Don't install it. If you already did, run `honeyrun <that project dir> --installed` and follow the steps it gives.
  3. Report it so others are protected: rerun with --abuse-report report.txt and paste it into the form it names.

When the problem is on your own machine (--installed, --agent-configs), the steps say what to remove, which keys to rotate and where to look for leftovers.

Sandboxes, with or without Docker

--engine auto picks the strongest one you have:

Engine Boundary Notes
Apple container (macOS 26+) a small VM per sandbox no always-on daemon, light on RAM. Experimental, from apple/container
Docker or Podman + gVisor (Linux) a user-space kernel between the code and yours scripts/install-gvisor.sh, see below
Podman + krun (Linux) a microVM per sandbox --engine podman --runtime krun with crun-krun
Docker Desktop (macOS, Windows) Docker's Linux VM works out of the box
Rootless Podman (Linux) user namespaces, no daemon lightest; weaker than gVisor, still no root on your machine

No engine at all? --static-only, --installed and --agent-configs don't need one.

To install gVisor, take the script from a release tag, check it, then run it. It only trusts gVisor's apt key if its fingerprint matches 6F1DF85E3A71C24918E727D56FC6D554E32BD943, the key published in the gVisor source:

curl -fsSLO https://raw.githubusercontent.com/m4xkushnir/honeyrun/v0.1.1/scripts/install-gvisor.sh
echo "499613d33d17c1516a171f60559f0faecef935a6a87b24660b72504d640dad89  install-gvisor.sh" | sha256sum -c -
bash install-gvisor.sh

What it looks for

Before it runs. Install hooks and anything that runs on its own: VS Code tasks that start when you open the folder, devcontainer commands that run on your host, .envrc, .pth files, git hooks, conftest.py, Rust build.rs. Hooks, permissions and MCP servers the repo sets up for Claude Code, Codex, Gemini CLI and Cursor. Hidden orders for AI models in AGENTS.md, CLAUDE.md, rules files and tool descriptions. Commands that shadow git or ssh, typosquatted names, obfuscated JavaScript, payloads tucked inside images, archives and binaries. Encoded payloads are decoded as text and shown to you. They are never run.

While it runs. Which fake keys it opens and whether they leave, even when hex or base64 encoded, split across DNS lookups, or sent over HTTPS (honeyrun intercepts TLS with a per-run CA). Cloud metadata endpoints, your SSH agent, keyboard and clipboard access, browser and chat-app sessions, crypto wallets. Persistence in shell files, cron, systemd, PATH and other agents' configs. Dropped binaries, wipers, miners, reverse shells, paste sites and webhooks, processes dressed up as kworker. MCP servers get their tools listed and every tool called, so payloads that wait for a tool call still go off.

Later, and under other conditions. A second pass with the clock 45 days ahead. With --deep, also a pass that looks like CI and three runs in a row. Behaviour that only shows up there is reported as a time bomb or a CI-only payload.

What others already know. Known malware and vulnerabilities from OSV, the repo's published advisories, and open issues about leaks or code execution that aren't fixed yet.

What changed. honeyrun remembers a fingerprint of each check on your machine. Next time it tells you about new hosts, changed install hooks, and MCP tools whose description changed after you approved them (a "rug pull").

The full list with severities is in docs/RULES.md.

How it works

flowchart LR
  T["repo, package or MCP server"] --> R["read: hooks, configs,<br/>instructions, binaries"]
  R --> H["honeyrun"]
  H -->|"code goes in as a tar,<br/>nothing of yours is mounted"| S
  subgraph S["sandbox: gVisor or a VM, read-only root, no capabilities, no network"]
    B[("20 fake credentials<br/>in home and env")]
    W["install, run, call MCP tools<br/>as an unprivileged user"]
    W -->|"every exec, open, connect"| X[("trace, root-only")]
    W -->|"DNS, HTTP, HTTPS"| K["fake internet<br/>answers and records"]
    W -->|"clock +45 days"| L["second pass"]
  end
  S --> V["LOOKS SAFE / UNCLEAR / NOT SAFE<br/>+ what to do now"]

The code runs as an unprivileged user under strace, inside gVisor or a VM, with a read-only root and no Linux capabilities. Offline (the default), every hostname resolves to the sandbox itself, so exfiltration code "succeeds" and leaves its evidence behind. A root-only agent keeps the trace where the code can't touch it, compares the filesystem before and after, and hands everything back as a tar. Your files, keys and environment never go in.

With your coding agent

--agent prints a dozen short lines ending in a next: instruction, so an agent spends a few hundred tokens rather than reading a trace.

  • Claude Code: copy integrations/claude-code/honeyrun into ~/.claude/skills/.
  • Codex, Cursor, Gemini CLI, Copilot, Windsurf: paste integrations/AGENTS.md into your AGENTS.md, GEMINI.md or rules file.
  • Agents that can start subagents are told to hand the check to one and keep only the verdict lines.

A second opinion from your own AI, only when it helps. --review "claude -p" (or "codex exec -", or "gemini -p {prompt_file}") asks the AI you already use to explain an UNCLEAR or NOT SAFE result in plain words, including what any decoded payload does, and to draft the abuse report. LOOKS SAFE runs never call it. It gets about 6 KB of masked, pre-filtered evidence and is told to explain only, never to rewrite or improve the code. Its answer never changes the exit code.

Keeping your AI safe while it checks

The code being checked may try to talk to the AI that reads the results. honeyrun assumes it will:

  • In --agent output, every string from the code under test is quoted as evidence:. Text written for a model (hidden tool instructions, decoded payloads, a fake "LOOKS SAFE" line) is withheld and left in --json for humans.
  • The verdict line and the next: line end with the same per-run tag, so a forged verdict can't pass for honeyrun's.
  • The --review AI runs in an empty folder, without your GitHub, npm, cloud or SSH-agent credentials, and gets its evidence fenced with a random nonce. It has to end its answer with a second secret marker. If that marker is missing, if it calls hard evidence benign, or if it tells you to run something, honeyrun labels the answer unreliable. Either way the verdict comes from the evidence, never from the AI.
  • The skill and AGENTS.md snippet tell agents not to open the target before it's checked, never to act on quoted evidence, and to give a checking subagent nothing but shell access to honeyrun.

In CI or in the cloud

- uses: m4xkushnir/honeyrun@d4b3d7939b20c6b10fe04b0396e7ad58a570f5f8 # v0.1.1
  with:
    target: .              # or owner/repo, npm:name, pypi:name
    network: open          # offline | open
    fail-on: high          # medium | high | critical

The step installs gVisor on the runner, fails on findings and writes the report to the job summary. It's also the easiest way to keep untrusted code off your laptop entirely: it runs on GitHub's machines. To use a server of your own, point Docker at it: DOCKER_HOST=ssh://you@server honeyrun owner/repo.

Other tools can read the results too: --sarif for GitHub code scanning and other SARIF readers, --json for scripts, --markdown for PR comments, and exit codes 0 clean, 1 findings, 3 couldn't run. It sits well next to static scanners such as Socket, GuardDog, Semgrep or OSV-Scanner. They read code and advisories; honeyrun watches behaviour.

Verify what you install

honeyrun asks you to distrust code you haven't checked, so it shouldn't ask for blind trust either:

  • Releases are signed and attested. Each release's wheel and sdist are built in GitHub Actions, published to PyPI with Trusted Publishing (no stored tokens) and carry a Sigstore build-provenance attestation. PyPI shows it on the file page (PEP 740), and gh attestation verify honeyrun-0.1.1-py3-none-any.whl --repo m4xkushnir/honeyrun checks a downloaded file.
  • Tags and commits are signed. Run git tag -v v0.1.1 after cloning.
  • Pin the Action to a commit SHA, not a branch: uses: m4xkushnir/honeyrun@d4b3d7939b20c6b10fe04b0396e7ad58a570f5f8 # v0.1.1. honeyrun's own workflows pin every action the same way.
  • Zero runtime dependencies. Nothing else gets pulled in when you install it.

Benchmark

Real malware

100 real malicious packages (50 npm, 50 PyPI), picked at random with a fixed seed from Datadog's public dataset of malware found in the wild. Each one ran in CI under gVisor, fully offline, with OSV lookups turned off so honeyrun couldn't simply recognise the names. Workflow · script.

npm PyPI Total
NOT SAFE 20 13 33
UNCLEAR 15 20 35
LOOKS SAFE (missed) 15 17 32
NOT SAFE from reading the code alone 1 0 1

One of them, sap-cd (npm), reads as harmless. When installed, it runs whoami, hostname and env and sends the AWS, GitHub, OpenAI and Anthropic keys from the environment to an out-of-band collaborator server. honeyrun sees the four planted keys leave and names the server.

Why the misses are missed, from the logs of the run:

  • Windows-only payloads. Some samples call ctypes.windll or other Windows APIs. The sandbox is Linux, so they crash before doing anything.
  • Broken packages. Missing files (Cannot find module './postinstall.js'), corrupted tarballs, tools like bun that aren't installed, Python version pins.
  • Payloads that wait for something specific: a function call, a particular argument, a missing credential (Missing Airtable credentials), or a live server that answers with a second stage.

"UNCLEAR" usually means honeyrun saw an unexpected host, obfuscated code or an install that couldn't finish, without hard proof of theft. That's a reason to look before installing, not a pass. This benchmark also drove fixes: the first run caught 14 of the 100; adding common build tools and libraries to the sandbox, out-of-band hosts and machine-fingerprinting detection brought it to 33.

Fixtures and real projects

Every number below comes from CI, under gVisor on ubuntu-latest, on every push.

Detection on 32 fixtures written to cover techniques one by one. 25 imitate real malware: install hooks that steal SSH and AWS keys, curl | sh, tokens tunnelled out over DNS or HTTPS, an MCP server that poisons its tool description and steals other agents' configs, a time bomb that waits 30 days, a CI-only payload, cloud metadata theft, SSH agent hijack, a fake git in PATH, droppers, wipers, miners, disguised processes, webhook exfiltration and hooks hidden in editor and agent configs. 7 are ordinary projects that build, read their own config, serve MCP and ship images, archives and analytics.

Malicious flagged Benign flagged Exact rule match Median time per check
25 / 25 0 / 7 32 / 32 2.4 s

False positives on well-known projects, with real network and the time-shifted pass:

Repo Install Run MCP tools called Verdict
chalk/chalk ok LOOKS SAFE
sindresorhus/slugify ok ok LOOKS SAFE
expressjs/express ok ok LOOKS SAFE
pallets/itsdangerous ok LOOKS SAFE
pallets/markupsafe ok LOOKS SAFE
psf/requests ok LOOKS SAFE
modelcontextprotocol/servers src/fetch ok ok 1 LOOKS SAFE
modelcontextprotocol/servers src/time ok ok 2 LOOKS SAFE
modelcontextprotocol/servers src/git ok ok 12 LOOKS SAFE

0 of 9 flagged, and every install succeeded. CI fails if one doesn't, so a clean result can't hide a broken run. The same fixtures also run under rootless Podman, with no Docker at all, and the unit tests run on Linux, macOS and Windows.

Reproduce: python bench/run.py, python bench/run.py --real, and the real-malware workflow (it refuses to run outside a disposable CI runner).

Compared with

As described in each project's own README (November 2026):

honeyrun ossf/package-analysis decon mcp-sentinel
One command on your own machine yes needs privileged nested containers yes no, sandbox runs on Daytona
Repos, npm, PyPI, archives, local dirs yes registry packages repos MCP servers
Watches behaviour at run time yes yes no, static pre-flight yes
Fake credentials as tripwires 20 per run no no yes
Calls MCP tools, tracks tool changes yes no no yes
Fake internet incl. HTTPS yes no no not stated
Time-shifted and CI-like passes yes no no no

Where to stay careful

honeyrun shows you what a piece of code does when it runs. A few things deserve your judgement on top:

  • Patient code. A payload that waits months, or for one particular company's hostname, can stay quiet through every pass. The time-shifted and --deep passes catch the common triggers. Your own sense of whether a project is what it claims still matters.
  • Pinned TLS. Code that ships its own certificate store shows where it connects but not what it sends. Plain HTTP, DNS and normal HTTPS are read in full.
  • Container awareness. A determined sample can tell it's in a sandbox. When it checks, honeyrun reports the check itself (sandbox-detection).
  • Isolation strength depends on the engine. gVisor and the VM engines are the strong options. On Linux without them, honeyrun falls back only to rootless Podman, or to plain containers if you pass --allow-runc.

Privacy and responsible use

honeyrun has no telemetry and no server. It goes online only to fetch what you asked it to check, to look the target up in OSV and GitHub (--no-intel turns that off; local folders are never looked up unless you ask), and to call your own AI if you pass --review. Reports mask tokens and URL passwords and write ~ for your home folder. Your history of checks stays on your machine.

Check code you're allowed to run, and send reports through official channels. honeyrun is provided as is, without warranty. Read DISCLAIMER.md for the full terms and SECURITY.md to report a problem in honeyrun itself.

Contributing

Found malware it missed, or a false alarm on a real project? Open an issue with the package name, or better, a small fixture in bench/fixtures/: every fixture becomes a test that runs on each push. Security problems in honeyrun itself go through SECURITY.md. AI agents working on this repo: read AGENTS.md first.

If honeyrun caught something for you, a star helps the next person find it.

License

MIT

Metadata

Release files for honeyrun 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for honeyrun 0.1.2
File Size Uploaded Provenance Actions
honeyrun-0.1.2.tar.gz 153.4 kB With provenance Details for honeyrun-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for honeyrun 0.1.2
File Interpreter ABI Platform Actions
honeyrun-0.1.2-py3-none-any.whl Python 3 none any Details for honeyrun-0.1.2-py3-none-any.whl

Total release size: 267.1 kB

Release files / honeyrun-0.1.2.tar.gz

Download URL honeyrun-0.1.2.tar.gz
Size 153.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ee67db7e46309598d3dddf9d31f038a509e73672daae709ccb4de73e26913e55
BLAKE2b-256 checksum
How to use checksums
96e46e69e457f6dd573bb950e20ca031c1f0c9d5e07b5d3c8a293328a21fbd68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / honeyrun-0.1.2-py3-none-any.whl

Download URL honeyrun-0.1.2-py3-none-any.whl
Size 113.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df9feed8cac57a0899c71a20916f70d7a17a43ad7840c8597caeea569ab4d366
BLAKE2b-256 checksum
How to use checksums
c62d0fbd2b9977ab8970cf115c2a3c51867c0350cbb9df5832a7ee7f8a996504
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for honeyrun 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for honeyrun-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page