Skilltotal

SkillTotal

[](https://pypi.org/project/skilltotal/) [](https://pypi.org/project/skilltotal/) [](LICENSE) [](https://github.com/pezhik/skilltotal/actions/workflows/ci.yml) [](https://github.com/marketplace/actions/skilltotal-ai-component-security-scan) [](https://scorecard.dev/viewer/?uri=github.com/pezhik/skilltotal)

AI Component Security Platform — open-source CLI engine.

SkillTotal statically analyzes AI-related components — agent skills/plugins, MCP servers, npm / Python packages, repositories, and AI-generated projects you upload as an archive or file — to surface supply-chain risks, dangerous capabilities, prompt-injection surfaces, and data-exfiltration paths before the component is installed or trusted. Point it at a path, a git URL, an npm: / pypi: package, or a project archive (.zip / .tar.gz) / single file.

Try it online (no install, no account): www.skilltotal.ai — the website runs this same engine. Prefer the CLI? pipx install skilltotal (below).

It analyzes only the component itself — never your user, company, environment, deployment, or runtime context. Every score and finding is derived exclusively from the files inside the component.

> Core principle: every confirmed finding carries evidence (file, line range, code > snippet). Anything that cannot be evidenced is placed in needs_review, never in > findings, and never affects the score.

Why SkillTotal

• 100% local & offline — the component's code never leaves your machine. No account,

no API token, no cloud upload (unlike cloud scanners that send your components to a backend).

• Safe to point at untrusted components — the engine analyzes without ever running them on

your machine. (Optional dynamic analysis is a separate paid service that runs only in our isolated sandbox, with your consent.)

• Zero runtime dependencies, pure Python stdlib — auditable and easy to vendor/air-gap.
• Deterministic — regex + AST, no LLM in the static engine; the same input always yields

the same report.

• Evidence-anchored & low false-positive — every finding points at an exact file:line.
• Standards-aligned — every component gets a behavioral trait fingerprint mapped to the

Cloud Security Alliance (CSA) agentic threat model, MAESTRO threat-model layers, and MITRE ATLAS tactics — including a three-way execution-context read (embedded static credential → delegated OAuth/OIDC → least-privilege scoped identity) that shows the blast radius of a compromise, not just that a secret exists.

• Free and open source (Apache-2.0) — the full static report is free, forever.

Install

Requires Python 3.10+. Zero runtime dependencies. git is required only for scanning remote URLs.

Recommended for the CLI — pipx (isolated install; also works on Debian/Ubuntu where bare pip install is blocked by PEP 668):

pipx install skilltotal

Or into a virtual environment / as a library:

pip install skilltotal

From source (development):

pip install -e ".[dev]"

Usage

# Human-readable report
skilltotal scan ./path/to/component

# Scan a remote repository (shallow git clone)
skilltotal scan https://github.com/owner/repo

# Scan a project archive or a single file (e.g. an AI-generated project downloaded as a ZIP)
skilltotal scan ./my-project.zip
skilltotal scan ./app.tar.gz
skilltotal scan ./suspicious.py

# Scan a package from a registry (latest, or a pinned version)
skilltotal scan npm:left-pad
skilltotal scan npm:left-pad@1.3.0
skilltotal scan pypi:requests
skilltotal scan pypi:requests==2.31.0

# JSON to stdout
skilltotal scan ./component --json

# SARIF 2.1.0 (GitHub Code Scanning / IDE)
skilltotal scan ./component --sarif --output report.sarif

# Write the report to a file (SARIF if --sarif, else JSON)
skilltotal scan ./component --output report.json

# CI gate: exit code 2 by severity level or by risk score
skilltotal scan ./component --fail-on-high             # alias for --fail-on high
skilltotal scan ./component --fail-on medium
skilltotal scan ./component --fail-on-score 50

# Skip paths (repeatable; combined with the config file's `exclude`)
skilltotal scan ./component --exclude "vendor/*" --exclude "*.min.js"

# Opt-in provenance for npm:/pypi: sources (registry metadata -> needs_review, never scored)
skilltotal scan npm:some-lib --provenance

# Baseline: snapshot current findings, then suppress them on later scans
skilltotal scan ./component --write-baseline .skilltotal-baseline.json
skilltotal scan ./component --baseline .skilltotal-baseline.json --fail-on-high

# Diff two versions of a component: what changed between them?
# Each side is any scannable source (path/archive/git/npm:/pypi:) or a saved --json report.
skilltotal diff npm:some-lib@1.2.3 npm:some-lib@1.2.4
skilltotal diff ./old-checkout ./new-checkout --json
skilltotal diff old-report.json new-report.json
# CI gate: fail (exit 2) if the new version INTRODUCES a high/critical finding
skilltotal diff npm:some-lib@1.2.3 npm:some-lib@1.2.4 --fail-on-new high

# Pre-install guard: allow/block decision (exit 2 on block) you can chain before installing
skilltotal guard npm:some-mcp-server && claude mcp add some-mcp-server -- npx some-mcp-server
skilltotal guard --installed            # check every AI component already on this machine
skilltotal guard npm:x --block-on malicious   # block only on malicious indicators

# Inventory: discover AI components already installed on this machine and scan them
# (reads agent configs for Claude Desktop/Code, Cursor, Windsurf, VS Code, Gemini, and
#  local skills; derives an npm:/pypi:/local source per MCP server and runs the engine)
skilltotal inventory
skilltotal inventory --json
skilltotal inventory --no-scan          # list only, do not scan
skilltotal inventory --project .        # also include this project's agent configs
skilltotal inventory --sbom             # AI-BOM: CycloneDX 1.6 JSON of your agent stack,
                                        # scan verdicts attached as component properties

# List every detection rule
skilltotal rules list
skilltotal rules list --json

Baseline suppresses findings by a stable fingerprint of (rule id, file, code snippet) — independent of line numbers, so it survives edits. Suppressed findings are removed before scoring and do not affect the risk score.

Diff reports new / resolved / changed findings, evidence-level additions and removals (matched by the same line-independent fingerprint as the baseline, so pure line shifts are not noise), capability changes, and the risk-score delta. --fail-on-new LEVEL gates only on risk the new version introduces — existing accepted findings never trip it, so it fits upgrade reviews ("is 1.2.4 riskier than the 1.2.3 we already vetted?") without a baseline file.

Guard is the install-time answer to "should I trust this component right now?". Malicious indicators always block; scored risk at/above --block-on blocks; capabilities alone never block — a legitimate MCP server with shell/network access passes, so the guard stays quiet enough to leave enabled everywhere (unlike a raw --fail-on high gate, which would trip on most of the ecosystem's honest capability findings).

Provenance (--provenance, opt-in) adds registry-metadata signals for npm: / pypi: sources: recently published, deprecated / yanked, no recent releases, no repository link. Metadata is context about a component, not component content — so these signals go to needs_review and never affect the score or verdict, and the default scan stays 100% component-only and offline.

Project config (optional) — commit a .skilltotal.toml instead of repeating flags (CLI flags override it):

fail_on = "high"           # low | medium | high | critical
fail_on_score = 50         # or gate on the 0-100 risk score
exclude = ["vendor/*", "*.min.js"]
ignore = ["ST-NET-PY"]     # rule ids to drop
baseline = ".skilltotal-baseline.json"

# Per-rule policy: reviewable gate decisions that live in the repo, not in a dashboard.
[policy]
"ST-SHELL-PIPE-EXEC" = "block"   # gate trips (exit 2) whenever this rule fires,
                                 # even with no fail_on configured
"ST-DYN-PY" = "warn"             # explicit accept-but-show: reported, still counts toward
                                 # the risk score, but exempt from the fail_on severity gate
"ST-SENS-WORD" = "ignore"        # suppressed entirely (same effect as `ignore`)

Suppress a single finding inline with a # skilltotal:ignore (or # skilltotal:ignore[ST-ID]) comment on its line.

python -m skilltotal ... works identically to the skilltotal console script.

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Usage / collection error (e.g. path missing, clone failed) | | 2 | A configured gate tripped (--fail-on/--fail-on-high severity, --fail-on-score, or diff --fail-on-new) |

> Gate semantics: --fail-on/--fail-on-high trip on the severity of any single finding, > not the aggregate risk_score. A component can report risk_level: low (score 0) and still fail > the gate if it has a high-severity finding — including a powerful capability (e.g. shell or > network access), which is reported but never scored as malicious. To gate on the score instead, > use --fail-on-score; to accept known findings, use a baseline, an inline > # skilltotal:ignore[ST-ID], or a per-rule [policy] action (block / warn / ignore).

CI / GitHub Action

Run SkillTotal in CI and surface findings in your repository's Security → Code scanning tab.

# .github/workflows/skilltotal.yml
name: SkillTotal
on: [push, pull_request]
permissions:
  contents: read
  security-events: write   # required to upload SARIF to Code Scanning
  pull-requests: write     # required only for comment-on-pr (optional)
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pezhik/skilltotal@v0.38.0
        with:
          source: .             # a path, a git URL, or an npm:/pypi: spec
          fail-on: high         # fail the build on a high/critical finding (or 'none')
          comment-on-pr: 'true' # post a sticky summary comment on pull requests (optional)

The action installs the CLI, scans source, uploads SARIF (so findings appear inline on pull requests and in Code Scanning), and fails the job on a high/critical finding unless fail-on: none. On pull requests, comment-on-pr: 'true' posts a single summary comment (risk level, score, findings, capabilities) and updates it in place on later runs — it needs pull-requests: write and is off by default. Pin the action to a released tag (see Releases) and, optionally, pin the engine version with the version: input. Prefer plain CLI? It is the same thing: skilltotal scan . --sarif --output skilltotal.sarif --fail-on-high.

Use as a pre-commit hook

Run SkillTotal on every commit via pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pezhik/skilltotal
    rev: v0.38.0
    hooks:
      - id: skilltotal
        args: [".", "--fail-on-high"]   # scan the repo; block the commit on a high/critical finding

Then pre-commit install. The hook installs the CLI in its own environment and scans the repo on commit; tune the scan with the same flags as the CLI (e.g. --exclude, --fail-on).

Use as an MCP server

Let your agent check a component before installing it. skilltotal mcp runs the engine as a stdio MCP server (stdlib-only, still zero dependencies) — register it in Claude Code/Desktop, Cursor, Windsurf, or any MCP client:

{ "mcpServers": { "skilltotal": { "command": "skilltotal", "args": ["mcp"] } } }

Tools exposed: scan_component (full report for a path / git URL / npm: / pypi: source), diff_components (upgrade review: what changed between two versions), and list_rules. Scans run locally with the same never-execute static engine — the component's code is not uploaded anywhere.

Add a status badge

Scan a component on skilltotal.ai and each report offers an "Add this badge" snippet — a small SVG that always reflects the component's latest scan and links back to the full report. Drop it in your README so visitors see the risk at a glance:

[](https://www.skilltotal.ai)

Copy the exact, ready-to-paste markdown from the report page — it fills in the badge URL for you.

Methodology

SkillTotal performs static security analysis of AI components — MCP servers, agent skills/plugins, npm and PyPI packages, and AI-generated projects/repositories. The engine combines capability analysis, dangerous-pattern detection, privilege analysis, supply-chain (install-time) analysis, prompt-surface analysis, and data-flow correlation (e.g. secret access combined with network egress). Findings are mapped to risk categories and contribute to a 0–100 risk score; capabilities are reported but never inflate the score — capability ≠ risk. Nothing is executed and no LLM is called, so results are deterministic and reproducible.

What it detects

| Category | Examples | |----------|----------| | Shell execution | subprocess.*, os.system, child_process.exec | | Filesystem access | open, read_text/write_text, fs.readFile/writeFile | | Sensitive paths | ~/.ssh, ~/.aws, .env, id_rsa, credentials, secrets | | Network egress | requests, urllib, aiohttp, fetch, axios | | Install-time execution | npm preinstall/postinstall/prepare, setup.py hooks | | Dynamic code execution | eval, exec, compile, new Function, vm.runInNewContext | | Obfuscation | decode-and-execute chains, base64 blobs, hex escaping, minification | | MCP risks | manifests, dangerous tools (shell/fs/network/credential), server commands | | Prompt surface | "ignore previous instructions", "reveal system prompt", exfiltration phrasing |

Coverage by component type

Legend: ✅ analyzed by default for this component type · ⚠️ the engine detects this, but that surface is uncommon for this type — so it is flagged only when the component actually contains it (e.g. prompt-injection text inside an npm/PyPI package) · ❌ not applicable to this type · 🚧 planned (SkillTotal Cloud).

Columns are the component types SkillTotal scans. AI project = a scanned repository or folder — an agent skill/plugin, an AI-generated codebase, or a set of prompts/configs — that is not a published npm/PyPI package.

| Category | MCP | npm | PyPI | AI project | |---|---|---|---|---| | Prompt injection / instruction override | ✅ | ⚠️ | ⚠️ | ✅ | | Tool poisoning (MCP tool metadata) | ✅ | ❌ | ❌ | ⚠️ | | Dangerous capabilities (shell / fs / network) | ✅ | ✅ | ✅ | ⚠️ | | Data exfiltration (secret access + egress) | ✅ | ✅ | ✅ | ⚠️ | | Secret theft / sensitive-path access | ✅ | ✅ | ✅ | ⚠️ | | Dynamic code execution | ✅ | ✅ | ✅ | ⚠️ | | Obfuscation (decode-and-execute) | ✅ | ✅ | ✅ | ✅ | | Hidden-Unicode smuggling | ✅ | ✅ | ✅ | ✅ | | Embedded secrets (hardcoded keys/tokens) | ✅ | ✅ | ✅ | ✅ | | Install-time / supply-chain hooks | ⚠️ | ✅ | ✅ | ❌ | | Overprivileged / auto-approved tools | ✅ | ❌ | ❌ | ⚠️ | | Runtime behavior analysis | 🚧 | 🚧 | 🚧 | 🚧 | | Sandbox analysis | 🚧 | 🚧 | 🚧 | 🚧 |

Typical findings

• An MCP tool can execute arbitrary shell commands
• A package downloads and runs code from an external URL
• Access to credential locations (~/.aws, ~/.ssh, .env) detected
• Dynamic code execution (eval / exec) detected
• Prompt-injection / instruction-override phrasing in a tool description or skill
• Sensitive-data access combined with outbound network egress

-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pezhik
• Source: pezhik/skilltotal
• License: Apache-2.0
• Homepage: https://www.skilltotal.ai

Install and usage instructions live in the source repository linked above.