Metadata-Version: 2.4
Name: trojaino
Version: 0.1.6
Summary: Local trust scanner for AI-built and downloaded software.
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/BlockhouseSoftware/trojaino
Project-URL: Source, https://github.com/BlockhouseSoftware/trojaino
Project-URL: Issues, https://github.com/BlockhouseSoftware/trojaino/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Trojaino v0.1.6

**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. v0.1 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."

## 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:

```bash
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:

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

### Distribution

Trojaino is distributed as source through this repository and its GitHub Releases page. No Trojaino package has been published to PyPI yet. Until an official release links to a verified PyPI project, do not install similarly named packages from PyPI or with `pipx`.

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](docs/windows-installation.md).

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

```bash
git checkout <published-release-tag>
```

## Run locally

```bash
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:

```bash
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:

```bash
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.1.6 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

```bash
python3 -m unittest discover -s tests -v
```

## License

Copyright © 2026 Blockhouse Software.

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