Trojaino v0.3.1

Trojaino: Local Trust Scanner

Your first line of defense.

Scan AI-built and downloaded software locally before you run it. Trojaino is a local deterministic trust scanner for Node/TypeScript and Python projects, MCP/tooling repos, Docker configs, and agent instruction files.

It is intentionally not a generic "ask an LLM to review this repo" wrapper. Trojaino runs repeatable rule packs and produces evidence-first findings with a conservative verdict:

• DO NOT RUN
• CAUTION
• NO CRITICAL RISKS FOUND

It never says software is "safe" or "certified secure."

Claude Code install gate

The Trojaino plugin for Claude Code checks software before Claude installs it. When Claude runs npx, npm install, pip install, uvx, git clone, claude mcp add or claude plugin install, Trojaino fetches that exact package, scans it without running it, and binds clean installs to what it scanned: npm installs to the exact version, pip install to the scanned file URL and SHA-256, and uv add, uvx and pipx to the exact version when that version can only install the scanned file. Installs that cannot be bound require approval. CAUTION results and anything it cannot scan go to you to decide; DO NOT RUN results are blocked. Everything else Claude does is untouched.

Install it inside Claude Code 2.1.274 or newer (Python 3.11+ is required as python3 or python; Git is required, including Git Bash on Windows):

/plugin marketplace add BlockhouseSoftware/claude-marketplace
/plugin install trojaino@blockhouse-software

Restart Claude Code and run /trojaino:doctor. Look for Ready. See prerequisites, updating and migration. The plugin needs no separate pip installation.

New to the terminal on Windows? Follow the Windows quick start.

Repository scope

This repository contains only the product source, public documentation, tests, and synthetic fixtures needed to verify detections. Company strategy, private requirements, decks, raw scan reports, screenshots, and generated evidence live outside this repository.

Generated reports should be written to a local-only workspace. A report belongs in this repository only when it is deliberately selected as a public example, sanitized, and manually reviewed.

Install

Clone the repo, then run the CLI directly from the checkout:

git clone https://github.com/BlockhouseSoftware/trojaino.git
cd trojaino
python3 -m trojaino scan ./tests/fixtures/clean-project

For local development, install it in editable mode inside a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
tjscan scan ./tests/fixtures/clean-project

Distribution

Trojaino is published to PyPI as trojaino, starting with v0.3.0, and verified through PyPI Trusted Publishing on every release:

pip install trojaino

It is also distributed as source through this repository and its GitHub Releases page. trojaino on PyPI is the only official package for this tool - do not install a similarly named package.

For the verified Windows installer, SHA-256 and publisher-signature checks, SmartScreen guidance, command usage, and uninstall behavior, see Install and verify Trojaino on Windows.

For a reproducible source checkout, select a published release tag:

git checkout <published-release-tag>

Run locally

tjscan scan ./some-project          # terminal summary, top 5 findings
tjscan scan ./some-project --all    # terminal summary, all findings
tjscan scan ./some-project --json   # full machine-readable report
tjscan scan ./some-project --html report.html
tjscan scan . --profile release     # shipped-source view; excludes tests/examples/reference artifacts

When stderr is an interactive terminal, Trojaino shows a compact progress bar while it reads eligible files. Progress is written only to stderr, so reports, JSON, exit codes, redirected output, and CI remain stable and quiet. Use --no-progress to hide it in an interactive terminal.

Exit codes are stable for scripts and demos:

• 0 — NO CRITICAL RISKS FOUND
• 1 — CAUTION
• 2 — DO NOT RUN

Bad demo fixtures are expected to exit 2; do not continue with install/run/deploy commands until findings are reviewed.

Release-profile self-scan

Use --profile release when scanning a development checkout as the artifact you intend to ship. It deliberately excludes development-only tests/, reference/, docs/, and example directories, while retaining package metadata, shipped source, agent instructions, and CI/deployment files. This avoids treating intentionally unsafe fixtures and rendered scan reports as runtime application code.

It is not a blanket suppression mechanism: a committed .env, dangerous package lifecycle hook, or other supported risk in the shipped source still produces a finding. Before cutting a release, run both the unit suite and release-profile scan:

python3 -m unittest discover -s tests -v
tjscan scan . --profile release --json

Demo fixtures

Use the included fixtures to see the alpha behavior without scanning an unrelated project:

tjscan scan tests/fixtures/bad-node-app
tjscan scan tests/fixtures/poisoned-agent-file
tjscan scan tests/fixtures/risky-mcp-server
tjscan scan tests/fixtures/unsafe-docker-config
tjscan scan tests/fixtures/clean-project

The intentionally bad fixtures should produce Verdict: DO NOT RUN and exit 2. That is expected: they demonstrate catches such as remote package install scripts, committed env files, client-exposed key names, poisoned agent instructions, risky MCP access, and unsafe Docker settings.

The clean-project fixture is only "clean-ish": it should produce NO CRITICAL RISKS FOUND for Trojaino's deterministic rules, not a guarantee that the project is safe.

Current deterministic checks

• Dangerous package lifecycle scripts (postinstall, preinstall, curl | bash, remote script execution)
• Python packaging metadata: malformed pyproject.toml, direct build/runtime dependency sources, extra package indexes, and module-level setup.py network access
• Suspicious package script access to home/credential paths
• Committed .env files and client-exposed key patterns (VITE_*KEY, NEXT_PUBLIC_*SECRET, etc.)
• Docker host escape/overexposure risks (privileged: true, Docker socket mounts, home-directory mounts, exposed admin/database ports)
• Agent instruction risks in AGENTS.md, CLAUDE.md, Cursor/Windsurf rules, and prompt-like markdown files
• MCP/tool risk patterns: filesystem/shell/environment access, credential paths, undeclared outbound endpoints
• Node route heuristics for unauthenticated destructive endpoints and dangerous shell/eval/file operations
• Python app heuristics for dangerous execution, unsafe deserialization, debug/CORS exposure, destructive routes, and user-input-to-sensitive-sink review signals

Limitations

Trojaino v0.3.1 is an alpha deterministic scanner:

• It does not prove a project is safe, complete a full security audit, or replace human review.
• Rules are intentionally incomplete and may miss logic bugs, auth design flaws, dependency vulnerabilities, obfuscated payloads, generated code, or runtime-only behavior.
• It is strongest today on Node/TypeScript and Python apps, package scripts, MCP/tooling code, Docker/self-hosted config, and agent instruction files.
• Python support is heuristic and stdlib-only. It catches common AI-generated Flask/FastAPI/script risks and narrow pre-run packaging signals, but it is not comprehensive Python SAST.
• Findings are evidence-first heuristics. Treat DO NOT RUN as a stop-and-review signal, not as an automated fix plan.

Test

python3 -m unittest discover -s tests -v

License

Copyright © 2026 Blockhouse Software.

Trojaino is licensed under the GNU Affero General Public License version 3 only (AGPL-3.0-only).