skilltotal CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

SkillTotal is an AI Component Security Platform — a CLI engine that statically analyzes AI-related components (skills, plugins, MCP servers, npm/Python packages, repos) for supply-chain risks, dangerous capabilities, prompt-injection surfaces, and exfiltration paths. This phase is CLI-only, but the core is built to be reused by future web/SaaS products.

Commands

# Install (editable) + dev deps
pip install -e ".[dev]"

# Run the full test suite (pytest config lives in pyproject.toml; addopts = -q)
pytest

# Run one test file / one test
pytest tests/test_scoring.py
pytest tests/test_scoring.py::test_combo_rule_fires_when_fs_and_network_present

# Security checks (required on every change — see memory + SECURITY.md)
bandit -r skilltotal          # static security scan (clean = exit 0)
pre-commit install            # once: enables gitleaks/detect-secrets/ruff/bandit on commit

# Run the CLI (console script or module form — identical)
skilltotal scan <path-or-url> [--json | --sarif] [--output FILE] [--fail-on-high]
skilltotal scan <path-or-url> [--baseline FILE | --write-baseline FILE]
skilltotal rules list [--json]
python -m skilltotal scan <path-or-url>

Zero runtime dependencies (Python stdlib only); dev deps (pip install -e ".[dev]") cover testing/lint/security/build. Requires Python 3.10+. git is required only for scanning remote URLs. Secret-leak defense is layered: pre-commit (gitleaks/detect-secrets) → CI secrets job (gitleaks) → GitHub push protection → OIDC publishing (no stored tokens); see SECURITY.md.

On Windows PowerShell, do not pipe between two python processes (encoding corruption); use a script file or one process.

Non-negotiable invariants

These define the product and are enforced in code — preserve them in any change:

1. Every confirmed Finding carries evidence. Finding.__post_init__ (models.py) raises if evidence is empty. Signals that cannot be anchored to a file/line/snippet must be emitted as NeedsReview, never as Finding, and NeedsReview never affects the score.
2. Component-only analysis. Derive everything from files inside the component — never from user/company/environment/deployment/runtime context.
3. Never execute analyzed code, never call an LLM. Detection is deterministic regex + targeted JSON/markdown parsing. (Security hooks may flag eval/os.system in scanner regexes — those are detection string literals, not calls.)
4. Interpret evidence only. Descriptions may explain what a matched API does ("child_process.exec enables shell execution"); they must not assert unproven intent ("this steals secrets").