sentro 0.1.0

A security-conscious pip wrapper that scans packages for malicious code before installation

sentro

Built by Solvyx.dev — a pip wrapper that scans Python packages for malicious code before installing them.

sentro install requests

╭──────────────────────── sentro scan ─────────────────────────╮
│   Package : requests 2.31.0                                     │
│   PyPI    : verified                                            │
│   Risk    : SAFE  (score 0/100)                                 │
╰─────────────────────────────────────────────────────────────────╯
  No issues found.

---

Why

Supply-chain attacks on PyPI are getting more frequent. Attackers publish packages with names one typo away from requests or numpy, or shadow internal package names to trigger dependency confusion. The malicious code runs at install time inside setup.py, or silently on first import.

sentro downloads and scans a package before pip ever touches it.

---

What it detects

Check	Examples
Malicious code	eval() / exec() at module level, os.system(), subprocess(shell=True), socket connections to hardcoded IPs
Install hooks	Dangerous calls in setup.py that run unconditionally at install time, cmdclass overrides, dynamic install_requires
Obfuscation	exec(base64.b64decode(...)) chains, high-entropy string constants, marshal.loads payloads
Typosquatting	Names similar to popular packages (reqeusts, numpy-dev), Unicode homoglyphs
Dependency confusion	Package names that shadow Python stdlib modules (json, os, urllib)
Metadata signals	Package age under 7 days, very low download count, missing author/homepage

Each finding contributes to a risk score (0–100). The overall verdict is SAFE, WARNING, or DANGER.

---

Install

pip install sentro

Requires Python 3.11+.

---

Usage

# Scan and install
sentro install requests

# Scan only — don't install
sentro install requests --no-install

# Block installation if anything scores DANGER
sentro install requests --strict

# Pin a version
sentro install "requests==2.28.0"

# Multiple packages
sentro install requests flask sqlalchemy

# JSON output (for CI pipelines)
sentro install requests --no-install --output-format json

# See which installer was detected
sentro detect-installer

---

Flags

Flag	Description
--strict	Exit 1 and block install if any package scores DANGER
--no-install	Scan only, don't install
--skip-scan	Skip scanning, forward directly to the installer
--output-format text|json	Output format (default: text)
--installer pip|uv|conda|mamba|poetry|pipenv|pdm|auto	Installer to use (default: auto)
--config PATH	Path to a TOML config file

---

Installer detection

sentro auto-detects your package manager so the install step uses the right tool.

Installer	Detected when
uv	uv is on PATH and a virtual env is active
conda / mamba	CONDA_DEFAULT_ENV or CONDA_PREFIX is set
poetry	pyproject.toml has [tool.poetry] and poetry is on PATH
pipenv	Pipfile exists and pipenv is on PATH
pdm	pyproject.toml has [tool.pdm] and pdm is on PATH
pip	Fallback

Override with --installer pip or set SENTRO_INSTALLER=pip.

---

Configuration

Create a .sentro.toml in your project root (or add [tool.sentro] to pyproject.toml):

[sentro]
strict = true

[sentro.thresholds]
warning = 30
danger  = 70

whitelist_packages  = ["requests", "numpy"]
scanners_disabled   = ["metadata"]

Config is merged from multiple sources in this order (last wins):

1. ~/.config/sentro/config.toml — user-level defaults
2. pyproject.toml [tool.sentro] in the current directory
3. .sentro.toml in the current directory
4. --config PATH flag
5. SENTRO_* environment variables
6. CLI flags

Environment variables

Variable	Effect
SENTRO_STRICT=true	Enable strict mode
SENTRO_INSTALLER=pip	Force a specific installer
SENTRO_OUTPUT_FORMAT=json	JSON output
SENTRO_DANGER_THRESHOLD=50	Override the DANGER score threshold
SENTRO_WARNING_THRESHOLD=20	Override the WARNING score threshold
SENTRO_WHITELIST=requests,numpy	Comma-separated whitelist

---

CI usage

# GitHub Actions example
- name: Scan dependencies
  run: |
    pip install sentro
    sentro install -r requirements.txt --strict --output-format json > scan.json

The --strict flag makes the step fail if any package scores DANGER. The JSON output can be parsed or stored as an artifact.

---

False positives

Some legitimate packages use dynamic imports or eval() inside functions (template engines, plugin loaders, REPLs). sentro tries to distinguish:

• eval() / exec() at module level → DANGER (runs unconditionally on import)
• eval() / exec() inside a function → WARNING (may be legitimate)
• __import__() inside a function → not flagged (standard plugin-loader pattern)

If a package you trust keeps triggering warnings, add it to whitelist_packages in your config.

---

Development

git clone https://github.com/solvyx-dev/sentro
cd sentro
pip install -e ".[dev]"

# Run tests (no network required)
pytest -m "not integration"

# Run with coverage
pytest --cov=sentro --cov-report=term-missing

# Run integration tests (requires internet)
pytest -m integration

---

Roadmap

• requirements.txt file scanning (sentro install -r requirements.txt)
• Support for other languages (npm, cargo, gem)
• GitHub Action
• Cache scan results to avoid re-scanning unchanged packages

---

License

MIT — built and maintained by Solvyx.dev