SkillTotal README

SkillTotal

Scan packages before Claude Code installs them. SkillTotal is a static security scanner for what coding agents install: npm and PyPI packages, MCP servers, agent skills and git repositories. It runs on your machine, never executes the code it reads and never calls an LLM. Every finding cites the file and line it came from.

Quick start

pipx install skilltotal

Then, inside Claude Code:

/plugin marketplace add pezhik/skilltotal
/plugin install skilltotal@skilltotal
/reload-plugins

From then on, when the agent runs npx, npm install, pip install, uvx or claude mcp add, the plugin first scans the package the command names. If the package has malicious indicators, the command is denied and the agent is told what was found and where:

SkillTotal blocked this install: it found malicious indicators. npm:some-pkg@1.0.3:
Decode-and-execute (obfuscated execution) at `scripts/setup.js:4`. Run
`skilltotal scan npm:some-pkg@1.0.3` to see every finding with its file:line evidence.

Without the plugin, scan anything from a terminal:

skilltotal scan npm:some-package         # or pypi:name, a git URL, a local folder or an archive
skilltotal guard npm:some-mcp-server     # exit code 2 if it should not be installed

Try it online (no install, no account): www.skilltotal.ai runs the same engine.

SkillTotal analyzes only the component itself, not the user, company, environment, deployment or runtime context around it. Every score and finding comes from the files inside the component.

Core principle: every confirmed finding carries evidence (file, line range, code snippet). Anything that cannot be tied to evidence goes to needs_review instead of findings and never affects the score.

Why SkillTotal

• Checks packages before your agent installs them. The Claude Code plugin reads each npx, npm install, pip install or claude mcp add command the agent is about to run. It blocks packages with malicious indicators, and asks you first about high- or critical-risk packages and any it could not check. Set it up.
• Runs on your machine. It needs no account or API token, uploads nothing and sends no telemetry. A local folder, archive or file is scanned offline. The network is used only to fetch what you asked for: see Network access.
• Safe to point at untrusted components. The engine reads them and never runs them.
• Zero runtime dependencies. It uses only the Python standard library, so it is easy to audit, vendor or run air-gapped.
• Deterministic. Detection is regex and AST matching with no LLM, so the same input on the same Python version always yields the same findings and score. The AST parser comes from the Python interpreter that runs the scan, and a file written in newer syntax than it understands falls back to regex and is listed for review, so run the scan on the newest Python you can.
• Evidence-anchored, with few false positives. 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. Three of the traits record how the component authenticates its tool calls (an embedded static credential, delegated OAuth/OIDC or a least-privilege scoped identity), which shows the blast radius of a compromise, not only whether 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 and for scan --staged.

For the CLI, pipx is recommended. It installs into an isolated environment and also works on Debian/Ubuntu and Homebrew Python, where PEP 668 blocks a bare pip install:

pipx install skilltotal

If skilltotal is not found afterwards, run pipx ensurepath and open a new terminal. On a fresh Linux machine, pipx's folder is not on PATH yet.

To install into a virtual environment, or to use it as a library:

pip install skilltotal

You can also run it with npx. The npm package only starts this engine, so it needs uv, pipx, or Python 3.11+ with skilltotal installed. With uv or pipx it runs the PyPI release that matches the npm version; when it falls back to an installed Python skilltotal of another release, it says so on stderr. Name the release with --package: a plain npx skilltotal run inside a repository first runs any skilltotal program in that repository's node_modules/.bin, and a repository you are about to scan can ship one (with --package, npx runs only that exact release; uvx does not look in the folder at all).

npx -y --package=skilltotal@0.73.0 -- skilltotal scan https://github.com/owner/repo

From source (development):

pip install -e ".[dev]"

Running it inside a directory you don't trust (a checkout you are about to scan): use the skilltotal console script or python -P -m skilltotal ... (Python 3.11+). Plain python -m puts the current directory first on the import path, so a json.py or skilltotal/ planted there would run instead of the standard library or the engine.

Usage

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

# Scan a remote repository (shallow git clone), or one folder of it at a ref
skilltotal scan https://github.com/owner/repo
skilltotal scan https://github.com/owner/repo/tree/main/src/server

# 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) to a file; the console gets a short summary
skilltotal scan ./component --sarif --output report.sarif

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

# SARIF for a subfolder: repository-root paths and a Code Scanning category of its own
skilltotal scan ./services/agent --sarif --output agent.sarif --sarif-uri-prefix services/agent --sarif-category skilltotal/agent

# CI gate: exit code 2 by finding severity (low, medium, high, critical) 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
# ...or when part of the component could not be analyzed: unreadable, too large or unparseable
# files, or code in a language SkillTotal does not analyze (binaries and dependency folders don't count)
skilltotal scan ./component --fail-on-unanalyzed
# Report only: no gate at all, also none from the config
skilltotal scan ./component --fail-on none
# Use the config's gate when it sets one, else this level (for wrappers)
skilltotal scan ./component --fail-on-default high

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

# Scan what the next commit will contain (git's index), as the pre-commit hook does
skilltotal scan . --staged --fail-on-high

# Use a config file from another place, or ignore any .skilltotal.toml in the current directory
skilltotal scan ./component --config ci/skilltotal.toml
skilltotal scan ./component --no-config

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

# Baseline: snapshot current findings (exits 0), 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 npm:x --block-on malicious   # block only on malicious indicators
skilltotal guard --installed                  # check the MCP servers, plugins and skills your agents use
skilltotal guard --installed --allow-unchecked  # exit 0 even if some could not be checked

# Inventory: list the MCP servers, plugins and skills your agents are configured with, and scan them
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

scan on its own exits 0 whatever it finds, even for a malicious verdict. In a script, use skilltotal guard or a gate (--fail-on) and check the exit code. With --output FILE, the full report goes to the file and the console gets a short summary: the verdict, the risk, the finding counts, any gate lines and Full report: FILE. Options must be spelled out in full: --out is an error, not --output.

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. Writing a baseline is how you adopt the tool on existing code: --write-baseline writes the file and exits 0, whatever it found, and warns on stderr when the baseline accepts a malicious indicator. A scan with a baseline says how many occurrences it suppressed on a Baseline : line.

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, counted like scan --fail-on (a malicious indicator at any severity, never a capability on its own). 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 --fail-on, it weighs the aggregate risk level rather than single findings. It also does not block a package for a secret it ships: that puts the publisher at risk, not the person installing the package.

Inventory and guard --installed read agent configuration files and never start a server: ~/.claude.json (Claude Code's user-scope servers and its local-scope servers per project), the Claude Code plugins you installed, an organization's Claude Code managed-mcp.json (in /etc/claude-code, /Library/Application Support/ClaudeCode or C:\Program Files\ClaudeCode), Claude Desktop, Cursor (~/.cursor/mcp.json), Windsurf, VS Code (the user mcp.json and settings.json mcp.servers) and Gemini CLI configs, and the skills in ~/.claude/skills. With --project DIR they also read that project's .mcp.json, .cursor/mcp.json, .vscode/mcp.json and .claude/skills. Claude Code's ~/.claude/settings.json is not read: it holds permissions and hooks, not server definitions. Each server's launch command is read by the same parser as the plugin hook, which derives the npm:, pypi:, git or local source to scan. A launcher that pipes a download into a shell is marked risky, a remote (URL) server cannot be scanned, and an inline secret in a config entry (an env value, an Authorization header, a key in a URL) is reported redacted. guard --installed exits 2 when a component blocks, else 1 when any component could not be checked (a scan error, a remote or unsupported server, a risky launcher) or none was found; --allow-unchecked turns that 1 into 0.

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 component-only.

Project config

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
fail_on_unanalyzed = true  # or when part of the component could not be analyzed (true/false)
exclude = ["vendor/*", "*.min.js"]
ignore = ["ST-NET-PY"]     # rule ids to drop
baseline = ".skilltotal-baseline.json"   # relative to this file

# 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-DESERIALIZE-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`)

The config is read from the directory you run skilltotal in (not from the scanned folder), or from the file --config names; --no-config ignores it. A config it cannot honor stops the scan with exit code 1, so a typo can't turn a gate off: invalid TOML, an unknown key, a value of the wrong kind, an unknown policy action, a rule id in ignore or [policy] that no rule has (the error suggests the closest id), or a --config path that does not exist. A relative baseline path is resolved against the config file's folder.

An applied config is always named: on a Config : line in the text report, as a config applied: ... line on stderr with --json or --sarif, and in the report's metadata.config_applied. A baseline set in the config is named there too.

Protect the config in CI. The GitHub Action and the pre-commit hook run from the root of the repository they scan, so that repository's own .skilltotal.toml is applied, and a pull request can change it: lower fail_on, ignore a rule, point baseline at a file that suppresses everything. Inline skilltotal:ignore markers come with the code too. Put .skilltotal.toml and the baseline file under CODEOWNERS with branch protection, and review new ignore markers like any other code. When you scan code you don't control from its own root, pass --no-config (Action: config: none).

Inline suppression

To accept a single finding, add a skilltotal:ignore[ST-ID] comment (any comment syntax: #, //, <!-- -->) on the finding's line or on the line just above it. Several ids are separated by commas; a bare skilltotal:ignore accepts every rule on that line. Inline markers count only when you scan a local directory (your own code, as in CI). In a package, repository, archive or file that SkillTotal fetches or unpacks they are ignored, so a component cannot silence its own findings. Suppressed occurrences are counted in the report (metadata.suppressed_count).

A marker never hides a malicious indicator, in any source. The finding stays, and a needs_review note says so. To accept one after review, record it in a baseline or set its rule to warn under [policy]. A marker that names a rule id no rule has suppresses nothing and gets a needs_review note suggesting the closest id.

Environment variables

Settings (environment variables, for the CLI, the plugin and the action):

A source over a limit is refused with its size and the variable to raise. A value that is not a positive whole number is an error. The plugin's own settings are listed in docs/plugin.md.

Exit codes

When a gate trips, stderr gets one gate: line per gate, naming the gate, the finding that tripped it and why it counts, for example gate: --fail-on high tripped by ST-COMBO-EXFIL (index.js:7), severity critical and 1 more or gate: fail_on = "critical" in .skilltotal.toml tripped by ST-INSTALL-NPM-REMOTE-EXEC (package.json:1), a malicious indicator.

Gate semantics: --fail-on/--fail-on-high trip on the severity of a single finding, not the aggregate risk_score. They count risk findings: a malicious indicator at any severity, and a risky construct or a shipped secret at or above the level you set. A capability, such as shell or network access, is what a component can do. It is reported but never trips the gate on its own; to forbid one, give its rule a block policy. The gate also fails closed on what the scan could not read: an install script it could not analyze, or a component with nothing it could read. A component can therefore report risk_level: low and still fail the gate on one high-severity risky construct. 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). --fail-on none turns off every gate the config sets (fail_on, fail_on_score, fail_on_unanalyzed, block policies); gate flags given on the same command line still apply.

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
  actions: read            # required for the SARIF upload in a private repository
  pull-requests: write     # required only for comment-on-pr (optional)
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: pezhik/skilltotal@v0.73.0
        id: skilltotal
        with:
          source: .             # a path, a git URL, or an npm:/pypi:<name> spec
          fail-on: high         # fail on a high/critical risk finding (or 'none')
          fail-on-unanalyzed: 'false' # 'true': also fail when part of it could not be analyzed
          comment-on-pr: 'true' # post a sticky summary comment on pull requests (optional)
          # upload-sarif: 'false'     # a private repository without GitHub Advanced Security
      # Runners are discarded after the job: keep the report as an artifact, also after a tripped gate
      - if: always()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: skilltotal-report
          path: skilltotal.sarif
      - if: always()
        run: echo "verdict=$VERDICT score=$SCORE"
        env:
          VERDICT: ${{ steps.skilltotal.outputs.verdict }}
          SCORE: ${{ steps.skilltotal.outputs.risk-score }}

on: [push, pull_request] runs the scan twice for a branch with an open pull request, once for each event. To scan once, limit push to your default branch (push: { branches: [main] }).

The action runs the engine that ships with the tag you pin, so nothing is downloaded from PyPI and the tag pins the scanner too. Pin it to a released tag (see Releases), or to that release's commit SHA (pezhik/skilltotal@<commit> # vX.Y.Z), which, unlike a tag, cannot be moved. Without the action, the same scan is skilltotal scan . --sarif --output skilltotal.sarif --fail-on-high.

Outputs: risk-level, risk-score, sarif-file and verdict, which is malicious whenever a malicious indicator was found, whatever the score. Read them as steps.<id>.outputs.<name> after giving the step an id. A tripped gate fails the step, so a later step that should still run needs if: always().

How it behaves:

• The gate decides the job. The semantics above apply: a malicious indicator fails the job at any severity, and a capability on its own, such as a shell call or network access, never does. The Scan step's log says which gate tripped, and each gate line is also an error annotation. With fail-on empty and no gate in .skilltotal.toml, the log names the gate fail-on high (action default).
• Errors are not verdicts. A usage, config or fetch error fails the job as "SkillTotal could not run the scan (exit 1): ...", not as a tripped gate.
• Job summary. Each run writes one: the applied .skilltotal.toml and what it sets, the verdict, the risk score and the gate result, the gate lines that tripped, a table of risk findings (severity, rule, file:line and title; up to 20, then a count), the capabilities, and how many findings a baseline or inline marker suppressed. The pull request comment says the same in short. A pull request that changes the applied config gets a warning when the base branch is fetched (fetch-depth: 0).
• The log lists the findings. It prints a count of risk findings and, separately, capability findings (not scored, never gated), then every location of each risk finding: up to 10 per rule, then "and N more" (the SARIF and JSON reports have them all). When Code Scanning is off, this is where you read why the gate failed. Text from the scanned files cannot issue workflow commands in the log.
• SARIF paths. For a source in a subfolder, SARIF locations are made relative to the repository root, so alerts point at real files. SARIF for an npm:, pypi: or git-URL source is written to sarif-file but not uploaded: its alerts would point at files the repository does not have. For an npm: or pypi: source it describes the same release the gate scanned. If the SARIF report cannot be written, the action warns and skips the upload; the gate still decides the job.
• Without Code Scanning. A private repository has Code Scanning only with GitHub Advanced Security. Without it, GitHub's upload action shows an error annotation of its own, the next step prints a warning explaining why, and the job result is still decided by the gate. Set upload-sarif: 'false' to skip the upload, and keep the report with actions/upload-artifact as in the example above: the runner and its files are gone after the job.
• PR comment. With comment-on-pr: 'true', the action keeps one comment on the pull request up to date: the verdict, the risk and the gate result, the gate lines, the top five risk findings with file:line, the capabilities, the suppressed count and a link to the workflow run. On a pull request from a fork the token is read-only: the comment is skipped with a warning, and the job is not failed for it.

To re-check a third-party package you depend on, on a schedule:

on:
  schedule: [{ cron: '0 6 * * 1' }]   # runs only from the default branch
jobs:
  mcp-server:
    runs-on: ubuntu-latest
    permissions: { contents: read }
    steps:
      - uses: pezhik/skilltotal@v0.73.0
        with:
          source: npm:some-mcp-server@1.4.2
          config: none         # this repository's .skilltotal.toml is not about that package

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.73.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). It scans what the commit will contain (skilltotal scan --staged): every file in git's index across the whole repository, not only the changed files, so the verdict matches what CI sees. Untracked and ignored files are left out. The repository's .skilltotal.toml applies here too.

Other CI systems

Anywhere Python 3.10+ runs, install a pinned release and gate on the exit code: 0 passed, 2 a gate tripped, 1 the scan could not run. SkillTotal writes SARIF 2.1.0 (--sarif) and its own JSON report; it does not write GitLab's security report format, so publish the files as job artifacts. Write reports outside the scanned folder, or into a folder you --exclude (SkillTotal also recognises its own SARIF, JSON and baseline files by content and skips them). --output does not create folders, so create the report folder first.

A shell step (a virtual environment outside the checkout, so it is not scanned):

python3 -m venv "$HOME/.skilltotal-venv"
"$HOME/.skilltotal-venv/bin/pip" install skilltotal==0.73.0
OUT="$(mktemp -d)"
"$HOME/.skilltotal-venv/bin/skilltotal" scan . --sarif --output "$OUT/skilltotal.sarif" --fail-on high

Where pipx is on PATH, pipx run --spec skilltotal==0.73.0 skilltotal followed by the same arguments runs the pinned CLI without a virtual environment. The python:*-slim images do not include pipx.

GitLab CI (allow_failure: exit_codes: [2] would turn the gate into a warning):

skilltotal:
  image: python:3.12-slim
  script:
    - pip install skilltotal==0.73.0
    - mkdir -p skilltotal-reports
    - skilltotal scan . --exclude "skilltotal-reports/*" --sarif --output skilltotal-reports/skilltotal.sarif --fail-on high
  artifacts:
    when: always
    paths: [skilltotal-reports/]

Jenkins (declarative pipeline, Docker agent):

stage('SkillTotal') {
  agent { docker { image 'python:3.12-slim' } }
  steps {
    sh '''
      python -m venv .skilltotal-venv    # a virtual environment is not scanned
      .skilltotal-venv/bin/pip install skilltotal==0.73.0
      mkdir -p skilltotal-reports
      .skilltotal-venv/bin/skilltotal scan . --exclude "skilltotal-reports/*" --sarif --output skilltotal-reports/skilltotal.sarif --fail-on high
    '''
  }
  post { always { archiveArtifacts artifacts: 'skilltotal-reports/*', allowEmptyArchive: true } }
}

For a JSON report, drop --sarif (--output then writes JSON). To publish both, run the scan twice: once with --fail-on none for the report, once with the gate.

Rolling out on an existing repository

1. Record what is there today. skilltotal scan . --write-baseline .skilltotal-baseline.json writes a baseline of the current findings and exits 0. Read the report first: a baseline accepts everything in it, malicious indicators included.
2. Gate only new findings. Commit the baseline and a .skilltotal.toml with baseline = ".skilltotal-baseline.json" and fail_on = "high" (or pass the action's baseline input). Findings already in the baseline no longer trip the gate; new ones do.
3. Protect the gate. Put .skilltotal.toml and the baseline under CODEOWNERS with branch protection, so loosening them needs a review.
4. Accept a false positive. For one occurrence, prefer an inline # skilltotal:ignore[ST-ID] on its line or the line above: it sits next to the code and is reviewed with it. A malicious indicator needs the baseline or a [policy] warn instead. Re-writing the baseline accepts every current finding at once, which is convenient after a review but easy to misuse. A [policy] warn or ignore applies to a rule everywhere. Report false positives too: they are fixed in the open.
5. Decide on --fail-on-unanalyzed. It is off by default, so the gate passes code it could not read (files over 2 MiB, minified bundles, code in languages whose behavior is not analyzed). Turned on, it fails closed on that code, which also fails a repository that commits bundles or Go code. Exclude such paths if you trust them, or turn the flag on for the third-party components you scan rather than for your own repository.

Claude Code plugin

The plugin checks each package the agent is about to install, on your machine and with the same engine as the CLI, before the install command runs. It reads npm, pnpm, yarn, bun, npx, pip, uv, uvx, pipx, poetry and similar installs, claude mcp add (and the Codex and Gemini equivalents) and npx skills add, also when they are wrapped in sudo, bash -c, $(...) or PowerShell.

Install the CLI first (skilltotal --version must work in the terminal you start Claude Code from), then:

/plugin marketplace add pezhik/skilltotal
/plugin install skilltotal@skilltotal
/reload-plugins

What happens to an install:

• Malicious indicators: denied, and the agent is told the finding and its file:line.
• High or critical risk, a look-alike package name, or anything it could not check (a custom registry, a name built at run time, a command hidden behind a decoder, a check that failed or ran out of time): Claude Code asks you.
• Clean: it installs, and the agent gets a one-line note with the version checked and its score.
• Never silent: every install command gets a line in the console saying what was checked, or what was not and why.
• CI is fail-closed: in CI (CI, GITLAB_CI, JENKINS_URL and similar, or SKILLTOTAL_STRICT=1) nobody can answer a question, so everything it would ask about is denied, and so are installs it could not check (from a lockfile, a local path, a downloaded script, a company registry, or an MCP server at a URL or in a container) unless SKILLTOTAL_ALLOW_UNCHECKED lists their kind.

What it does not check:

• dependencies of the package a command names
• installs that name no package (npm ci, pip install -r, uv sync); the console says so
• scripts on disk and shell-profile aliases or functions; downloaded scripts (curl ... | bash) are reported as not checked
• repositories fetched with git clone
• code already running on your account (it can rewrite the verdict cache or the CLI)

The plugin also adds a /skilltotal:scan <target> command and registers the SkillTotal MCP server. It is a static guardrail, not a sandbox: for code you don't trust, run the agent in a container. The full reference is in docs/plugin.md: every recognized command, the settings, cache and timing, rolling it out to a team and troubleshooting.

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). The Claude Code plugin already registers it, so don't add it a second time there. In Claude Code without the plugin:

claude mcp add skilltotal -- skilltotal mcp

For Claude Desktop, Cursor, Windsurf or any client that reads mcpServers:

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

For VS Code (.vscode/mcp.json or the user mcp.json):

{ "servers": { "skilltotal": { "type": "stdio", "command": "skilltotal", "args": ["mcp"] } } }

A desktop app started from the Dock, Start menu or Finder does not see the PATH that pipx set up in your shell. If it cannot start skilltotal, give the full path that which skilltotal (where skilltotal on Windows) prints as command.

If you have not installed it locally, use "command": "uvx", "args": ["skilltotal@0.73.0", "mcp"] (pinned) or "command": "npx", "args": ["-y", "--package=skilltotal@0.73.0", "--", "skilltotal", "mcp"] (with --package, npx does not run whatever skilltotal program the node_modules/.bin of the client's folder holds). The npx form needs uv, pipx, or Python 3.11+ with skilltotal; if it falls back to an installed Python skilltotal of another release, it warns on stderr (stdout stays the MCP session).

Tools exposed, all annotated read-only:

• scan_component scans a local path, git URL, npm: or pypi: source. By default it answers with a summary of a few kilobytes: the verdict, the risk, why (each finding with up to three locations), the capabilities, notes to check by hand and what the scan does not cover. Pass detail: "full" for the complete report.
• diff_components reviews an upgrade: what changed between two versions. It takes the same detail.
• list_rules lists the detection rules. Narrow it with ids or query; pass verbose: true for each rule's description and recommendation.

A local path must be absolute, because the server's working directory is not the client's. The home folder (under any name for it, a link included), any folder above it and a filesystem root are refused, and ~ is not expanded. So are network shares and device paths (\\host\share, \\?\...) and NTFS streams. The server runs two requests at a time and answers ping at once; a cancelled request gets no answer. Scans run locally with the same never-execute static engine; the component's code is not uploaded anywhere. To raise a size limit for the server, set the variable in the env of its entry in the client's config.

Status badge

Scan a component on skilltotal.ai and each report offers an "Add this badge" snippet: a small SVG that reflects the website's latest public scan of that component and links back to the full report.

[![SkillTotal](https://www.skilltotal.ai/badge?source=npm:your-package)](https://www.skilltotal.ai)

The badge comes from the website's scan, not from your CI, so it works only for components the website can fetch: published npm/PyPI packages and public repositories. Copy the exact markdown from the report page; it fills in the badge URL for you.

What it detects

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.

skilltotal rules list prints every rule. Which rules catch which malware archetype is in docs/detection-coverage.md.

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.

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.

Each row names what the engine checks today. The code-behavior rows (dangerous capabilities, data exfiltration, dynamic code execution, decode-and-execute) cover Python and JavaScript/TypeScript; shell, PowerShell and batch scripts are checked for download-and-run, decode-and-run and evasion idioms. Code in other languages gets only the secret, sensitive-path and hidden-text checks (see Limitations). Bidi controls and lone zero-width characters are listed for review and left out of the score, because locale and CJK files use them legitimately.

Typical findings

• An MCP tool can execute arbitrary shell commands
• A package downloads and runs code from an external URL, for example in an npm install script
• 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
• Hardcoded API keys or tokens
• An MCP server with auto-approved or overprivileged tools
• Untrusted input (environment, sys.argv, a request/response body) flowing into exec or a shell: a traced path, not just a dangerous API in isolation
• An agent skill whose bundled code does more than its declared allowed-tools cover. The field pre-approves tools and does not limit the skill's code, so a narrow list can make a skill look safer than it is.

Verdict

Every report has a one-line verdict next to the score: Malicious indicators found whenever a malicious indicator fired, whatever the score; High risk - review before installing or Critical risk - review before installing for a high or critical score without one; Some risk - review before installing for a medium score; and, for a low score, wording that says what was found ("No significant risks found", "No malicious indicators - review capabilities before installing", ...). A low verdict never sounds clean over code that was not read: it reads Partially analyzed - ... when the component ships code in a language whose behavior is not analyzed, or code files that were not read (Partially analyzed - 2 code files not read (2 minified)), and Not analyzed - nothing in this component could be read when nothing could be read. That wording does not change the score.

Limitations

• Files over 2 MiB are not read, and minified JavaScript/TypeScript bundles are listed but not analyzed. The scripts npm runs at install are the exception: they are read even when minified or filed in a skipped folder. A low verdict then reads "Partially analyzed", and the report counts them in verdict.unanalyzed_files.
• Dependency and environment folders are skipped: node_modules/, vendor/ (and vendored-*), Python virtual environments and installed site-packages, and in a repository (not a published package) the build output in dist/ and build/. Code the component loads from those folders by a literal path (a relative require/import, a Python import, a package.json or pyproject.toml entry point) is read anyway.
• Dependencies are not scanned. A scan covers the component's own files, not what it installs.
• Public registries only. npm: and pypi: sources come from the public npm registry and PyPI; a company registry or mirror is not supported yet (see Network access).
• Code that is not in the files is not analyzed: code fetched or generated at run time, and binaries or compiled artifacts (counted in metadata.files_skipped_binary).
• Languages. Shell execution, network access, file access and dynamic code are analyzed in Python and JavaScript/TypeScript. Shell, PowerShell and batch scripts are checked for download-and-run, decode-and-run and evasion idioms. Go, Rust, Java, Ruby, PHP, C/C++, C#, Swift, Kotlin, Scala, Dart, Lua, Perl, Elixir, Groovy, Haskell, Clojure, Erlang, R and Zig files get only the secret, sensitive-path and hidden-Unicode checks; the report adds a needs_review note, and a low verdict reads "Partially analyzed". See docs/language-scope.md.
• Symbolic links and junctions in a scanned folder are not followed, and links inside an archive are not extracted.
• The default gate does not count unread code. --fail-on (and the action's fail-on) pass a component whose code was partly not analyzed, unless you add --fail-on-unanalyzed (action: fail-on-unanalyzed: 'true').
• Detection is at the call/import level. A capability used through an higher-level library (a git library that writes files internally, a browser library) may not be flagged as a raw filesystem/shell call. Capabilities indicate , not proven misuse.

Out of scope

SkillTotal statically analyzes a single component's own files. It does not execute code, observe runtime behavior, or assess your environment, deployment, or infrastructure. It is not a substitute for:

• a penetration test
• an application-security (app-sec) review
• an architecture / design review
• a cloud-security or infrastructure assessment
• a Kubernetes / container runtime audit
• a business-logic review
• a manual code review

Accuracy notes

• Python is analyzed via an AST (resolves import aliases, tells open(p,'w') from a read, ignores API names that only appear in strings/comments). Node.js/config use regex.
• Test code (__tests__/, *.test.*, tests/, conftest.py, …) is demoted to needs_review: it is not executed by consumers, so it does not affect the score.
• Ambiguous signals (bare secrets/credentials words, lone base64 blobs, "before answering" phrasing, minified files) go to needs_review, never to findings.
• Hidden Unicode (ASCII-smuggling tag characters, variation selectors and invisible math operators used as bytes, zero-width characters threaded through words, Hangul filler identifiers) is detected; where it encodes text, that text is decoded into the evidence. Trojan-Source bidi overrides and lone zero-width characters go to needs_review. Attackers use hidden text to smuggle instructions past human review. See tests/manual_eval/ for calibration against real-world attacks.
• Shell execution covers subprocess/os.system, asyncio.create_subprocess_*, Node child_process, and common process-spawning libraries (Python sh/plumbum/pexpect/ invoke/fabric; Node zx/execa/cross-spawn/shelljs/tinyexec/node-pty).
• MCP dangerous tools are classified by name/description both in JSON manifests and when defined in code (server.tool("run_command", …), @mcp.tool over def read_file).
• SARIF, JSON and baseline files that SkillTotal wrote into the scanned folder are recognised by their content, listed in needs_review and not scanned (their rule descriptions quote detection patterns).

Network access

A scan of a local folder, archive or file makes no network request. SkillTotal goes online only for:

• git URLs: git clone --depth 1 of the repository; for github.com, GitHub REST API calls (api.github.com) first, to check the size of what would be cloned
• npm: / pypi: sources: package metadata and the package archive from the npm registry (registry.npmjs.org) or PyPI (pypi.org and its file host)
• --provenance: the package's registry metadata
• inventory, guard --installed and the Claude Code plugin: the same registries and git hosts, for the packages they check

There is no telemetry, no account and no LLM call. The MCP server makes the same requests for the sources an agent asks it to scan.

npm: and pypi: sources are always fetched from the public npm registry and PyPI. Scanning through a company registry or mirror is not supported yet: download the package archive yourself and scan the file.

Measured, not asserted

Detection claims are cheap, so the numbers behind them are published with the data and the code that produced them.

• Detection efficacy: recall and precision on a labeled corpus we built and publish (125 malicious and 89 benign samples), regenerated every release and enforced by CI as a floor. A perfect score on our own corpus guards against regressions; it is not a claim about every attack in the wild.
• The MCP registry, scanned (September 2026, engine 0.49.0, rulesets 56 to 59; later rule changes are not reflected): 15,341 of the 17,535 distinct components in the official registry (87.5%), finished on 2026-09-19. Most of the rest were no longer reachable or exceeded a time or size bound, and every exclusion is counted. Of the components scanned, 88.2% expose tools to an agent, 64.8% can reach the network and 21.1% can execute shell commands, yet all but 116 of them score low risk, because a capability on its own scores zero. The rules were tuned on this population: we read every malicious-indicator hit from an earlier run by hand and fixed the false positives before this run. Aggregates (JSON) · the harness.

The same code scanned by the same engine on the same Python version gives the same findings. Nothing is executed and no LLM is involved. The survey read each component's latest release or default branch when it ran, so a re-run today reads newer code.

Output

A normalized report containing the component identity, a risk score (0–100) and risk level (low / medium / high / critical), a plain-language verdict, detected capabilities (each evidence-backed), a behavioral trait fingerprint (with a CSA / MAESTRO / MITRE ATLAS crosswalk), findings, needs_review, and metadata. See docs/report-schema.md and docs/scoring.md.

Every finding also carries its OWASP Agentic Skills Top 10 category ids (owasp), emitted in both the JSON report and SARIF (native taxonomies/relationships); docs/owasp-agentic-skills-mapping.md explains the coverage (AST01–AST05) and the honest gaps. For MCP servers, docs/mcp-owasp-mapping.md maps SkillTotal's checks to the OWASP MCP Security Cheat Sheet (and names the runtime controls a static engine can't cover).

The report's traits array is a behavioral fingerprint: a higher-level projection over the findings (e.g. execution_authority, embedded_credential, untrusted_perception, and the emergent exfil_correlation combination), each mapped to the Cloud Security Alliance trait-based model, a MAESTRO threat-model layer, and a MITRE ATLAS tactic where there is an honest fit. It is descriptive and never affects the score; see docs/trait-crosswalk.md.

Architecture

The package under skilltotal/ (except cli.py) is a pure, side-effect-free library so the same engine powers the web app at www.skilltotal.ai. See docs/architecture.md.

Development

pip install -e ".[dev]"
pytest

Open source vs SkillTotal Cloud

SkillTotal is open core. This engine (the analysis, all detection rules and the CLI) is open source and complete on its own: you can run it locally or in CI, for free, with zero runtime dependencies. It tells you what a component does, with evidence.

Paid features are planned for SkillTotal Cloud (the website) and will explain why it matters: LLM interpretation and prioritization of findings, dynamic sandbox execution, scan history and monitoring. They will run as server-side services on top of this engine, and their code is not part of this repository. See docs/open-core.md.

License

Apache-2.0. See also NOTICE.