sentro 0.1.0__py3-none-any.whl

sentro/__init__.py

@@ -0,0 +1,3 @@
+"""sentro: a security-conscious pip wrapper."""
+
+__version__ = "0.1.0"

sentro/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

sentro/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sentro/cli.py

@@ -0,0 +1,195 @@
+"""CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.console import Console
+
+from ._version import __version__
+from .config import load_config
+from .installer import InstallerType, detect_installer
+from .models import RiskLevel
+from .orchestrator import ScanOrchestrator
+from .reporting.reporter import render_report
+
+_console = Console(stderr=True)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="sentro")
+def cli() -> None:
+    """sentro: pip with a security conscience.
+
+    Scans Python packages for malicious code before installing them.
+    Detects typosquatting, obfuscated payloads, malicious install hooks,
+    dependency confusion, and more.
+    """
+
+
+@cli.command(
+    name="install",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("packages", nargs=-1, required=True)
+@click.option(
+    "--strict",
+    is_flag=True,
+    envvar="SENTRO_STRICT",
+    help="Block installation if any package scores DANGER.",
+)
+@click.option(
+    "--no-install",
+    is_flag=True,
+    help="Scan only — do not invoke the package installer.",
+)
+@click.option(
+    "--skip-scan",
+    is_flag=True,
+    help="Skip all scanning and forward directly to the installer.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(["text", "json"]),
+    default=None,
+    envvar="SENTRO_OUTPUT_FORMAT",
+    help="Output format for the scan report.",
+)
+@click.option(
+    "--installer",
+    type=click.Choice(["pip", "uv", "conda", "mamba", "poetry", "pipenv", "pdm", "auto"]),
+    default="auto",
+    envvar="SENTRO_INSTALLER",
+    help="Package installer to use after scanning. Defaults to auto-detect.",
+    show_default=True,
+)
+@click.option(
+    "--config",
+    "config_file",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Path to a TOML config file.",
+)
+@click.pass_context
+def install_cmd(
+    ctx: click.Context,
+    packages: tuple[str, ...],
+    strict: bool,
+    no_install: bool,
+    skip_scan: bool,
+    output_format: Optional[str],
+    installer: str,
+    config_file: Optional[Path],
+) -> None:
+    """Install PACKAGES after scanning them for malicious code.
+
+    Unknown options (e.g. --index-url, --constraint) are forwarded to the
+    package installer verbatim.
+
+    Examples:
+
+      sentro install requests
+
+      sentro install requests==2.28.0 --strict
+
+      sentro install numpy --no-install --output-format json
+
+      sentro install mypackage --installer uv
+    """
+    cli_overrides = {}
+    if strict:
+        cli_overrides["strict"] = True
+    if output_format:
+        cli_overrides["output_format"] = output_format
+
+    config = load_config(cli_overrides=cli_overrides, config_file=config_file)
+
+    # Resolve installer
+    if skip_scan:
+        resolved_installer = _resolve_installer(installer)
+        rc = _forward_to_installer(resolved_installer, list(packages), ctx.args)
+        sys.exit(rc)
+
+    orchestrator = ScanOrchestrator(config=config)
+    out_console = Console()
+
+    blocked = False
+    scanned_packages: list[str] = []
+
+    for package_spec in packages:
+        name, _, version = package_spec.partition("==")
+        name = name.strip()
+        version = version.strip() or None
+
+        _console.print(f"[dim]Scanning[/dim] [bold]{package_spec}[/bold]...", highlight=False)
+
+        try:
+            report = orchestrator.scan_package(name, version)
+        except Exception as exc:
+            _console.print(f"[red]Error scanning {package_spec}: {exc}[/red]")
+            if config.strict:
+                sys.exit(2)
+            continue
+
+        if config.output_format == "json":
+            from .reporting.json_reporter import render_json_report
+            click.echo(render_json_report(report, config.thresholds))
+        else:
+            from .reporting.text_reporter import render_text_report
+            render_text_report(report, config.thresholds, console=out_console)
+
+        level = report.risk_level(config.thresholds)
+        if level == RiskLevel.DANGER and config.strict:
+            blocked = True
+        else:
+            scanned_packages.append(package_spec)
+
+    if blocked:
+        _console.print(
+            "[bold red]Installation BLOCKED[/bold red] — one or more packages scored DANGER "
+            "and --strict mode is enabled."
+        )
+        sys.exit(1)
+
+    if no_install:
+        sys.exit(0)
+
+    # Determine which installer to use
+    resolved_installer = _resolve_installer(installer)
+    _console.print(
+        f"[dim]Installing via[/dim] [bold]{resolved_installer.value}[/bold]..."
+    )
+
+    packages_to_install = list(packages)  # install all, including warned ones
+    rc = _forward_to_installer(resolved_installer, packages_to_install, ctx.args)
+    sys.exit(rc)
+
+
+@cli.command(name="detect-installer")
+def detect_installer_cmd() -> None:
+    """Show which package installer would be used automatically."""
+    inst = detect_installer()
+    click.echo(f"Detected installer: {inst.value}")
+
+
+def _resolve_installer(installer_str: str) -> InstallerType:
+    if installer_str == "auto":
+        return detect_installer()
+    for inst in InstallerType:
+        if inst.value == installer_str:
+            return inst
+    return InstallerType.PIP
+
+
+def _forward_to_installer(
+    installer: InstallerType,
+    packages: list[str],
+    extra_args: list[str],
+) -> int:
+    from .installer import build_install_command
+    import subprocess
+    cmd = build_install_command(installer, packages, extra_args)
+    return subprocess.run(cmd).returncode

sentro/config.py

@@ -0,0 +1,133 @@
+"""Configuration loading with multi-source merge chain."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+
+@dataclass
+class Config:
+    strict: bool = False
+    thresholds: dict = field(default_factory=lambda: {"warning": 30, "danger": 70})
+    whitelist_packages: list[str] = field(default_factory=list)
+    scanners_enabled: list[str] = field(default_factory=list)   # empty = all enabled
+    scanners_disabled: list[str] = field(default_factory=list)
+    pypi_timeout: int = 10
+    prefer_wheel: bool = True
+    output_format: str = "text"
+
+
+def load_config(
+    cli_overrides: Optional[dict[str, Any]] = None,
+    config_file: Optional[Path] = None,
+) -> Config:
+    """
+    Merge chain (lowest → highest priority):
+      1. Built-in defaults
+      2. ~/.config/sentro/config.toml
+      3. pyproject.toml [tool.sentro] in cwd
+      4. .sentro.toml in cwd
+      5. Explicit --config path
+      6. SENTRO_* environment variables
+      7. CLI flags
+    """
+    merged: dict[str, Any] = {}
+
+    # 2. User-level config
+    user_cfg = Path.home() / ".config" / "sentro" / "config.toml"
+    if user_cfg.exists():
+        merged.update(_load_toml_section(user_cfg))
+
+    # 3. pyproject.toml in cwd
+    cwd_pyproject = Path.cwd() / "pyproject.toml"
+    if cwd_pyproject.exists():
+        merged.update(_load_toml_section(cwd_pyproject, "sentro"))
+
+    # 4. .sentro.toml in cwd
+    cwd_sentro = Path.cwd() / ".sentro.toml"
+    if cwd_sentro.exists():
+        merged.update(_load_toml_section(cwd_sentro))
+
+    # 5. Explicit config file
+    if config_file is not None:
+        merged.update(_load_toml_section(Path(config_file)))
+
+    # 6. Environment variables
+    merged.update(_apply_env_overrides())
+
+    # 7. CLI flags (only non-None values)
+    if cli_overrides:
+        for k, v in cli_overrides.items():
+            if v is not None:
+                merged[k] = v
+
+    return _build_config(merged)
+
+
+def _load_toml_section(path: Path, section: str = "sentro") -> dict[str, Any]:
+    try:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+        # Support [tool.sentro] and [sentro]
+        tool_section = data.get("tool", {}).get(section, {})
+        top_section = data.get(section, {})
+        result = {}
+        result.update(top_section)
+        result.update(tool_section)
+        return result
+    except Exception:
+        return {}
+
+
+def _apply_env_overrides() -> dict[str, Any]:
+    overrides: dict[str, Any] = {}
+    if os.environ.get("SENTRO_STRICT", "").lower() in ("1", "true", "yes"):
+        overrides["strict"] = True
+    if val := os.environ.get("SENTRO_DANGER_THRESHOLD"):
+        try:
+            overrides.setdefault("thresholds", {})["danger"] = int(val)
+        except ValueError:
+            pass
+    if val := os.environ.get("SENTRO_WARNING_THRESHOLD"):
+        try:
+            overrides.setdefault("thresholds", {})["warning"] = int(val)
+        except ValueError:
+            pass
+    if val := os.environ.get("SENTRO_WHITELIST"):
+        overrides["whitelist_packages"] = [p.strip() for p in val.split(",") if p.strip()]
+    if val := os.environ.get("SENTRO_OUTPUT_FORMAT"):
+        overrides["output_format"] = val
+    return overrides
+
+
+def _build_config(data: dict[str, Any]) -> Config:
+    cfg = Config()
+    if "strict" in data:
+        cfg.strict = bool(data["strict"])
+    if "thresholds" in data:
+        cfg.thresholds.update(data["thresholds"])
+    if "whitelist_packages" in data:
+        cfg.whitelist_packages = list(data["whitelist_packages"])
+    if "scanners_enabled" in data:
+        cfg.scanners_enabled = list(data["scanners_enabled"])
+    if "scanners_disabled" in data:
+        cfg.scanners_disabled = list(data["scanners_disabled"])
+    if "pypi_timeout" in data:
+        cfg.pypi_timeout = int(data["pypi_timeout"])
+    if "prefer_wheel" in data:
+        cfg.prefer_wheel = bool(data["prefer_wheel"])
+    if "output_format" in data:
+        cfg.output_format = str(data["output_format"])
+    return cfg

sentro/data/popular_packages.txt

@@ -0,0 +1,259 @@
+# Top PyPI packages used for typosquatting detection
+# Source: https://hugovk.github.io/top-pypi-packages/
+numpy
+pandas
+requests
+scipy
+matplotlib
+scikit-learn
+tensorflow
+torch
+flask
+django
+fastapi
+sqlalchemy
+boto3
+pytest
+click
+rich
+pydantic
+httpx
+aiohttp
+pillow
+cryptography
+paramiko
+celery
+redis
+pymongo
+setuptools
+wheel
+twine
+black
+mypy
+flake8
+urllib3
+charset-normalizer
+certifi
+idna
+six
+attrs
+packaging
+typing-extensions
+colorama
+tqdm
+pyyaml
+python-dotenv
+jinja2
+werkzeug
+itsdangerous
+markupsafe
+psutil
+lxml
+beautifulsoup4
+pyarrow
+grpcio
+protobuf
+google-cloud-storage
+azure-storage-blob
+cffi
+pyopenssl
+bcrypt
+passlib
+pyjwt
+oauthlib
+stripe
+twilio
+sendgrid
+boto
+botocore
+s3transfer
+awscli
+azure-core
+google-auth
+google-api-python-client
+kubernetes
+docker
+ansible
+fabric
+invoke
+poetry
+pipenv
+virtualenv
+tox
+coverage
+pytest-cov
+mock
+responses
+factory-boy
+hypothesis
+locust
+gunicorn
+uvicorn
+starlette
+aiofiles
+asyncpg
+databases
+alembic
+psycopg2
+pymysql
+motor
+elasticsearch
+opensearch-py
+kafka-python
+pika
+kombu
+dramatiq
+rq
+apscheduler
+arrow
+pendulum
+python-dateutil
+pytz
+tzdata
+humanize
+babel
+babel
+simplejson
+ujson
+orjson
+msgpack
+protobuf
+avro-python3
+pyzmq
+websockets
+socketio
+python-socketio
+channels
+daphne
+twisted
+scrapy
+selenium
+playwright
+httpcore
+h11
+h2
+trio
+anyio
+tenacity
+retry
+backoff
+loguru
+structlog
+sentry-sdk
+prometheus-client
+opentelemetry-sdk
+datadog
+newrelic
+nltk
+spacy
+gensim
+transformers
+huggingface-hub
+datasets
+tokenizers
+accelerate
+diffusers
+langchain
+openai
+anthropic
+cohere
+tiktoken
+faiss-cpu
+pinecone-client
+chromadb
+weaviate-client
+qdrant-client
+Pillow
+opencv-python
+imageio
+scikit-image
+albumentations
+torchvision
+tensorflow-datasets
+keras
+xgboost
+lightgbm
+catboost
+statsmodels
+sympy
+networkx
+igraph
+graph-tool
+dask
+ray
+joblib
+multiprocess
+concurrent-futures
+cloudpickle
+pyzmq
+zarr
+h5py
+netcdf4
+xarray
+geopandas
+shapely
+fiona
+pyproj
+folium
+plotly
+bokeh
+altair
+seaborn
+dash
+streamlit
+gradio
+panel
+hvplot
+pydeck
+kepler.gl
+pyvis
+wordcloud
+reportlab
+fpdf2
+weasyprint
+openpyxl
+xlrd
+xlwt
+xlsxwriter
+python-docx
+python-pptx
+pdfminer.six
+pypdf
+tabula-py
+camelot-py
+pytesseract
+pdf2image
+docx2txt
+chardet
+ftfy
+unidecode
+regex
+parse
+pyparsing
+lark
+antlr4-python3-runtime
+pygments
+mistune
+markdown
+sphinx
+mkdocs
+pdoc
+numpydoc
+rsa
+ecdsa
+pynacl
+paramiko
+fabric
+invoke
+plumbum
+sh
+cmd2
+prompt-toolkit
+blessed
+curtsies
+urwid
+textual
+blessed
+rich
+typer
+argparse

sentro/extraction/extractor.py

@@ -0,0 +1,27 @@
+"""Dispatcher: detect archive type and delegate to the correct extractor."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import PackageFiles
+from .sdist_extractor import SDistExtractor
+from .wheel_extractor import WheelExtractor
+
+
+def extract_package(archive_path: Path, dest_dir: Path) -> PackageFiles:
+    """
+    Detect whether archive_path is a wheel or sdist and extract accordingly.
+    Returns a populated PackageFiles.
+    """
+    name = archive_path.name
+    if name.endswith(".whl"):
+        return WheelExtractor().extract(archive_path, dest_dir)
+    elif name.endswith((".tar.gz", ".tgz", ".zip")):
+        return SDistExtractor().extract(archive_path, dest_dir)
+    else:
+        # Best-effort: try tarball first, then zip
+        try:
+            return SDistExtractor().extract(archive_path, dest_dir)
+        except Exception:
+            return WheelExtractor().extract(archive_path, dest_dir)

sentro/extraction/sdist_extractor.py

@@ -0,0 +1,91 @@
+"""Extract .tar.gz / .zip sdist files into a temp directory."""
+
+from __future__ import annotations
+
+import sys
+import tarfile
+import zipfile
+from pathlib import Path
+
+from ..models import PackageFiles
+
+
+class PathTraversalError(Exception):
+    """Raised when an archive entry attempts path traversal."""
+
+
+class SDistExtractor:
+    def extract(self, sdist_path: Path, dest_dir: Path) -> PackageFiles:
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        name_str = sdist_path.name
+
+        if name_str.endswith(".tar.gz") or name_str.endswith(".tgz"):
+            name, version = _parse_sdist_name(name_str)
+            _extract_tarball(sdist_path, dest_dir)
+        elif name_str.endswith(".zip"):
+            name, version = _parse_sdist_name(name_str)
+            _extract_zip(sdist_path, dest_dir)
+        else:
+            name, version = _parse_sdist_name(name_str)
+            _extract_tarball(sdist_path, dest_dir)
+
+        return _build_package_files(name, version, dest_dir)
+
+
+def _parse_sdist_name(filename: str) -> tuple[str, str]:
+    for suffix in (".tar.gz", ".tgz", ".zip"):
+        if filename.endswith(suffix):
+            stem = filename[: -len(suffix)]
+            break
+    else:
+        stem = filename
+    parts = stem.rsplit("-", 1)
+    if len(parts) == 2:
+        return parts[0], parts[1]
+    return stem, "unknown"
+
+
+def _guard_tar_member(member: tarfile.TarInfo) -> bool:
+    """Return True if safe, False to skip."""
+    name = member.name
+    if name.startswith("/") or name.startswith("\\"):
+        return False
+    normalized = Path(name)
+    if ".." in normalized.parts:
+        return False
+    return True
+
+
+def _extract_tarball(path: Path, dest: Path) -> None:
+    if sys.version_info >= (3, 12):
+        with tarfile.open(path, "r:gz") as tf:
+            tf.extractall(dest, filter="data")
+    else:
+        with tarfile.open(path, "r:gz") as tf:
+            safe_members = [m for m in tf.getmembers() if _guard_tar_member(m)]
+            tf.extractall(dest, members=safe_members)
+
+
+def _extract_zip(path: Path, dest: Path) -> None:
+    with zipfile.ZipFile(path, "r") as zf:
+        for member in zf.infolist():
+            parts = Path(member.filename).parts
+            if any(p in ("..", "") for p in parts) or Path(member.filename).is_absolute():
+                raise PathTraversalError(f"Unsafe path in zip: {member.filename!r}")
+        zf.extractall(dest)
+
+
+def _build_package_files(name: str, version: str, root: Path) -> PackageFiles:
+    python_files = [p for p in root.rglob("*.py") if p.name != "setup.py"]
+    setup_py_candidates = list(root.rglob("setup.py"))
+    setup_py = setup_py_candidates[0] if setup_py_candidates else None
+    pyproject_candidates = list(root.rglob("pyproject.toml"))
+    pyproject_toml = pyproject_candidates[0] if pyproject_candidates else None
+    return PackageFiles(
+        name=name,
+        version=version,
+        source_dir=root,
+        python_files=python_files,
+        setup_py=setup_py,
+        pyproject_toml=pyproject_toml,
+    )