SkillTotal

SkillTotal

Verifique pacotes antes que o Claude Code os instale. SkillTotal é um scanner de segurança estático para o que agentes de codificação instalam: pacotes npm e PyPI, servidores MCP, habilidades de agente e repositórios git. Ele roda na sua máquina, nunca executa o código que lê e nunca chama um LLM. Cada achado cita o arquivo e a linha de onde veio.

Início rápido

pipx install skilltotal

Depois, dentro do Claude Code:

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

A partir daí, quando o agente executar npx, npm install, pip install, uvx ou claude mcp add, o plugin primeiro verifica o pacote que o comando nomeia. Se o pacote tiver indicadores maliciosos, o comando é negado e o agente é informado sobre o que foi encontrado e onde:

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.

Sem o plugin, verifique qualquer coisa a partir de um 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

Experimente online (sem instalação, sem conta): www.skilltotal.ai executa o mesmo mecanismo.

SkillTotal analisa apenas o componente em si, não o usuário, empresa, ambiente, implantação ou contexto de execução ao redor dele. Cada pontuação e achado vem dos arquivos dentro do componente.

Princípio central: todo achado confirmado carrega evidência (arquivo, intervalo de linhas, trecho de código). Qualquer coisa que não possa ser vinculada a evidência vai para needs_review em vez de findings e nunca afeta a pontuação.

Por que SkillTotal

• Verifica pacotes antes que seu agente os instale. O plugin do Claude Code lê cada comando npx, npm install, pip install ou claude mcp add que o agente está prestes a executar. Ele bloqueia pacotes com indicadores maliciosos e pergunta a você primeiro sobre pacotes de risco alto ou crítico e qualquer coisa que não conseguiu verificar. Configure-o.
• Roda na sua máquina. Não precisa de conta ou token de API e não envia nada. Ele usa a rede apenas para buscar o pacote ou repositório que você pediu para verificar.
• Seguro para apontar para componentes não confiáveis. O mecanismo os lê e nunca os executa. (Análise dinâmica em um sandbox isolado está planejada como um serviço pago separado.)
• Zero dependências em tempo de execução. Usa apenas a biblioteca padrão do Python, então é fácil de auditar, incorporar ou executar sem conexão com a internet.
• Determinístico. A detecção é baseada em regex e correspondência de AST sem LLM, então a mesma entrada sempre produz os mesmos achados e pontuação.
• Ancorado em evidências, com poucos falsos positivos. Cada achado aponta para um arquivo:linha exato.
• Alinhado a padrões. Cada componente recebe uma impressão digital de traço comportamental mapeada para o modelo de ameaça agêntico da Cloud Security Alliance (CSA), camadas do modelo de ameaça MAESTRO e táticas do MITRE ATLAS. Três dos traços registram como o componente autentica suas chamadas de ferramenta (uma credencial estática incorporada, OAuth/OIDC delegado ou uma identidade com escopo de privilégio mínimo), o que mostra o raio de explosão de um comprometimento, não apenas se existe um segredo.
• Gratuito e de código aberto (Apache-2.0). O relatório estático completo é gratuito, para sempre.

Medido, não afirmado

Alegações de detecção são baratas, então os números por trás delas são publicados com os dados e o código que os produziram.

• O registro MCP, verificado: 15.341 dos 17.535 componentes distintos no registro oficial (87,5%), verificados com conjuntos de regras 56 a 59 e concluídos com o mecanismo 0.49.0 em 2026-09-19. A maioria do restante não estava mais acessível ou excedeu um limite de tempo ou tamanho, e cada exclusão é contabilizada. Dos componentes verificados, 88,2% expõem ferramentas a um agente, 64,8% podem alcançar a rede e 21,1% podem executar comandos de shell, ainda assim 99,3% deles pontuam risco baixo, porque uma capacidade por si só pontua zero. JSON bruto · o harness.
• Eficácia de detecção: recall e precisão em um corpus rotulado que construímos e publicamos (64 amostras maliciosas e 46 benignas), regenerado a cada lançamento e imposto por CI como um piso. Uma pontuação perfeita em nosso próprio corpus protege contra regressões; não é uma afirmação sobre todos os ataques no mundo real.

Ambos são reproduzíveis: mesma entrada, mesmo mecanismo, mesma saída. Nada é executado e nenhum LLM está envolvido.

Instalação

Requer Python 3.10+. Zero dependências em tempo de execução. git é necessário apenas para verificar URLs remotas.

Para a CLI, pipx é recomendado. Ele instala em um ambiente isolado e também funciona em Debian/Ubuntu e Homebrew Python, onde PEP 668 bloqueia um pip install simples:

pipx install skilltotal

Para instalar em um ambiente virtual, ou para usar como biblioteca:

pip install skilltotal

Você também pode executá-lo com npx. O pacote npm apenas inicia este mecanismo, então precisa de uv, pipx ou Python 3.11+ com skilltotal instalado:

npx -y skilltotal scan https://github.com/owner/repo

A partir do código-fonte (desenvolvimento):

pip install -e ".[dev]"

Plugin do Claude Code

Agentes de codificação instalam pacotes no meio de uma tarefa, e o prompt de permissão, se houver, mostra apenas o comando. O plugin verifica cada pacote na sua máquina, com o mesmo mecanismo da CLI, antes que o comando de instalação seja executado. Seu hook reconhece npx, bunx, pnpm dlx, npm/pnpm/yarn/bun adicionar ou instalar, pip, uv, uvx, pipx, claude mcp add e claude mcp add-json. Ele lê um comando da mesma forma que o shell faria, então também encontra instalações atrás de sudo, env, bash -c '...', cmd /c e $(...), em grupos como (npm i y) e em cadeias como cd x && npm i y. No Windows, o Claude Code executa a maioria dos comandos através da sua ferramenta PowerShell, e o hook também segue & { ... }, iex '...', Start-Process npm -ArgumentList ... e powershell -EncodedCommand.

O que acontece com a instalação:

• Indicadores maliciosos: o comando é negado, e o agente é informado sobre o achado e seu arquivo:linha.
• Risco alto ou crítico: o Claude Code pede que você aprove a instalação e mostra o principal achado.
• Qualquer coisa que o SkillTotal não conseguiu verificar: o Claude Code pergunta a você. Isso cobre um pacote de um registro ou índice personalizado (--registry, --index-url, --extra-index-url), uma URL de arquivo direta, uma referência git que a verificação não consegue reproduzir exatamente, uma verificação que falhou ou não terminou dentro dos 20 segundos que todas as verificações de um comando compartilham, o sexto e pacotes posteriores em um comando, um nome a uma ou duas letras de um pacote popular e um script de instalação que o SkillTotal não conseguiu ler. O SkillTotal nunca nega uma instalação por causa de sua própria falha.
• Limpo: o pacote instala normalmente, e o agente recebe uma nota de uma linha com a versão que foi verificada e sua pontuação.

Pacotes do GitHub (github:owner/repo#v1.2.0, git+https://github.com/...@ref) são verificados na referência que será instalada. Um veredito é reutilizado para o mesmo artefato (um lançamento npm exato ou arquivo PyPI por uma semana, um repositório git por uma hora), então chamadas repetidas de npx tsc ou npx prettier não disparam uma nova verificação. Quando a versão do mecanismo muda, tudo é verificado novamente. Para pacotes grandes, defina SKILLTOTAL_HOOK_BUDGET (em segundos, até 100) para esperar mais que 20 segundos. Em uma execução sem supervisão (claude -p), o Claude Code transforma uma pergunta que ninguém pode responder em uma negação, então um pacote que o hook não conseguiu verificar não é instalado lá; dê mais tempo a pacotes grandes com a mesma variável. O plugin também adiciona um comando /skilltotal:scan <target> e registra o servidor MCP descrito abaixo.

O plugin chama a CLI, então instale a CLI onde o Claude Code possa encontrá-la: skilltotal --version deve funcionar no terminal a partir do qual você inicia o Claude Code. Se a CLI estiver ausente ou falhar ao iniciar, os comandos de instalação são executados sem verificação e nada é bloqueado. O Claude Code então mostra um aviso em cada um, para que você possa distinguir uma configuração quebrada de uma verificação limpa.

O hook carrega junto com os plugins, então execute /reload-plugins (ou reinicie o Claude Code) após /plugin install. Para vê-lo funcionar sem tocar em um pacote real, peça ao agente para executar npm install --registry https://registry.example.invalid left-pad. O Claude Code deve parar e perguntar a você, com o motivo do SkillTotal. Nada é instalado a menos que você aprove.

O que o plugin não verifica

• Dependências. Ele verifica o pacote que um comando nomeia, não os pacotes que ele puxa.
• Instalações que não nomeiam pacote. npm install, npm ci, pip install -r requirements.txt e uv sync instalam a partir de um arquivo de bloqueio ou arquivo de requisitos, que o hook não lê.
• Comandos que constroem o nome do pacote em tempo de execução, e scripts que o agente baixa e executa. O hook vê apenas o que o comando especifica.
• Bundles minificados. Eles são listados no relatório, mas não analisados. Os scripts que o npm executa na instalação são a exceção: eles são analisados mesmo quando minificados.
• Wheels específicos de plataforma. Para um lançamento PyPI que os inclui, o SkillTotal verifica a distribuição de código-fonte; o wheel que o pip escolhe para sua máquina pode diferir dela. Um lançamento cujo único wheel é Python puro é verificado como esse wheel.
• Comportamento em código Go, Rust, Java, Ruby e PHP. Segredos, caminhos sensíveis e Unicode oculto são ainda verificados lá.

É uma proteção estática, não um sandbox. Para código em que você não confia, execute o agente em um contêiner.

Uso

# 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 suprime achados por uma impressão digital estável de (rule id, file, code snippet) — independente de números de linha, então sobrevive a edições. Achados suprimidos são removidos antes da pontuação e não afetam a pontuação de risco.

Diff relata achados novos / resolvidos / alterados, adições e remoções de nível de evidência (correspondidos pela mesma impressão digital independente de linha que a baseline, então mudanças puras de linha não são ruído), mudanças de capacidade e o delta de pontuação de risco. --fail-on-new LEVEL limita apenas no risco que a nova versão introduz — achados aceitos existentes nunca o disparam, então se encaixa em revisões de atualização ("1.2.4 é mais arriscado que o 1.2.3 que já validamos?") sem um arquivo de baseline.

Guard é a resposta no momento da instalação para "devo confiar neste componente agora?". Indicadores maliciosos sempre bloqueiam; risco pontuado em/ acima de --block-on bloqueia; capacidades sozinhas nunca bloqueiam — um servidor MCP legítimo com acesso a shell/rede passa, então o guard permanece silencioso o suficiente para ficar habilitado em todos os lugares (diferente de um gate --fail-on high bruto, que dispararia na maioria dos achados honestos de capacidade do ecossistema).

Provenance (--provenance, opt-in) adiciona sinais de metadados de registro para fontes npm: / pypi:: publicado recentemente, descontinuado / removido, sem lançamentos recentes, sem link de repositório. Metadados são contexto sobre um componente, não conteúdo do componente — então esses sinais vão para needs_review e nunca afetam a pontuação ou veredito, e a verificação padrão permanece apenas no componente.

Configuração de projeto (opcional) — envie um .skilltotal.toml em vez de repetir flags (flags da CLI têm precedência sobre ele):

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

Para suprimir um único achado, coloque um comentário # skilltotal:ignore (ou # skilltotal:ignore[ST-ID]) na sua linha. Marcadores inline contam apenas quando você verifica um diretório local (seu próprio código, como em CI). Em um pacote ou repositório que o SkillTotal baixa, eles são ignorados, então um pacote não pode silenciar seus próprios achados.

python -m skilltotal ... funciona de forma idêntica ao script de console skilltotal.

Códigos de saída

Código	Significado
0	Sucesso
1	Erro de uso ou coleta (por exemplo, um valor de flag desconhecido, um caminho ausente ou um clone falho)
2	Um gate configurado disparou (severidade --fail-on/--fail-on-high, --fail-on-score ou diff --fail-on-new), ou guard bloqueou o componente

Semântica do gate: --fail-on/--fail-on-high são acionados com base na gravidade de qualquer achado individual, não no risk_score agregado. Um componente pode reportar risk_level: low (pontuação 0) e ainda assim falhar no gate se tiver um achado de alta gravidade, incluindo uma capacidade como acesso a shell ou rede, que é reportada mas nunca pontuada como maliciosa. Para usar o gate com base na pontuação, use --fail-on-score; para aceitar achados conhecidos, use uma linha de base, um # skilltotal:ignore[ST-ID] inline ou uma ação [policy] por regra (block / warn / ignore).

CI / GitHub Action

Execute o SkillTotal no CI e exiba os achados na aba Security → Code scanning do seu repositório.

# .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.62.0
        with:
          source: .             # a path, a git URL, or an npm:/pypi:<name> 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)

A action executa o mecanismo que acompanha a tag que você fixa, então nada é baixado do PyPI. Ela escaneia source, envia SARIF (para que os achados apareçam inline em pull requests e no Code Scanning) e falha o job em um achado alto/crítico, a menos que fail-on: none. Com comment-on-pr: 'true', ela publica um único comentário resumido no pull request (nível de risco, pontuação, achados, capacidades) e o atualiza no lugar em execuções posteriores. O comentário fica desativado por padrão e precisa de pull-requests: write. Fixe a action a uma tag de release (veja Releases), e defina a entrada version: apenas para executar uma versão diferente do mecanismo a partir do PyPI. Sem a action, a mesma varredura é skilltotal scan . --sarif --output skilltotal.sarif --fail-on-high.

Uso como hook de pre-commit

Execute o SkillTotal em cada commit via pre-commit:

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

Em seguida, pre-commit install. O hook instala a CLI no próprio ambiente e escaneia o repositório no commit; ajuste a varredura com os mesmos flags da CLI (ex.: --exclude, --fail-on).

Uso como servidor MCP

Deixe seu agente verificar um componente antes de instalá-lo. skilltotal mcp executa o mecanismo como um servidor MCP stdio (somente stdlib, ainda com zero dependências) — registre-o no Claude Code/Desktop, Cursor, Windsurf ou em qualquer cliente MCP:

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

Se você não o instalou localmente, use "command": "npx", "args": ["-y", "skilltotal", "mcp"] em vez disso. Isso requer uv, pipx ou Python 3.11+ com skilltotal.

Ferramentas expostas: scan_component (relatório completo para um caminho / URL git / fonte npm: / pypi:), diff_components (revisão de upgrade: o que mudou entre duas versões) e list_rules. As varreduras são executadas localmente com o mesmo mecanismo estático que nunca executa código — o código do componente não é enviado a lugar nenhum.

Adicionar um selo de status

Escaneie um componente em skilltotal.ai e cada relatório oferece um trecho "Add this badge" — um pequeno SVG que sempre reflete a varredura mais recente do componente e linka de volta ao relatório completo. Coloque-o no seu README para que os visitantes vejam o risco de relance:

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

Copie o markdown exato e pronto para colar da página do relatório — ele preenche a URL do selo para você.

Metodologia

O SkillTotal realiza análise de segurança estática de componentes de IA — servidores MCP, skills/plugins de agentes, pacotes npm e PyPI e projetos/repositórios gerados por IA. O mecanismo combina análise de capacidades, detecção de padrões perigosos, análise de privilégios, análise de cadeia de suprimentos (em tempo de instalação), análise de superfície de prompt e correlação de fluxo de dados (ex.: acesso a segredos combinado com egresso de rede). Os achados são mapeados para categorias de risco e contribuem para uma pontuação de risco de 0–100; as capacidades são reportadas, mas nunca inflam a pontuação — capacidade ≠ risco. Nada é executado e nenhum LLM é chamado, então os resultados são determinísticos e reproduzíveis.

O que ele detecta

Categoria	Exemplos
Execução de shell	subprocess.*, os.system, child_process.exec
Acesso ao sistema de arquivos	open, read_text/write_text, fs.readFile/writeFile
Caminhos sensíveis	~/.ssh, ~/.aws, .env, id_rsa, credentials, secrets
Egresso de rede	requests, urllib, aiohttp, fetch, axios
Execução em tempo de instalação	npm preinstall/postinstall/prepare, hooks setup.py
Execução dinâmica de código	eval, exec, compile, new Function, vm.runInNewContext
Ofuscação	cadeias de decodificar-e-executar, blocos base64, escape hexadecimal, minificação
Riscos de MCP	manifestos, ferramentas perigosas (shell/fs/rede/credenciais), comandos de servidor
Superfície de prompt	"ignore instruções anteriores", "revele o prompt do sistema", redação de exfiltração

Cobertura por tipo de componente

Legenda: ✅ analisado por padrão para este tipo de componente · ⚠️ o mecanismo detecta isso, mas essa superfície é incomum para este tipo — então é sinalizado apenas quando o componente realmente o contém (ex.: texto de injeção de prompt dentro de um pacote npm/PyPI) · ❌ não aplicável a este tipo · 🚧 planejado (SkillTotal Cloud).

As colunas são os tipos de componente que o SkillTotal escaneia. Projeto de IA = um repositório ou pasta escaneado — uma skill/plugin de agente, uma base de código gerada por IA ou um conjunto de prompts/configurações — que não é um pacote npm/PyPI publicado.

Categoria	MCP	npm	PyPI	Projeto de IA
Injeção de prompt / substituição de instrução	✅	⚠️	⚠️	✅
Envenenamento de ferramenta (metadados de ferramenta MCP)	✅	❌	❌	⚠️
Capacidades perigosas (shell / fs / rede)	✅	✅	✅	⚠️
Exfiltração de dados (acesso a segredos + egresso)	✅	✅	✅	⚠️
Roubo de segredos / acesso a caminhos sensíveis	✅	✅	✅	⚠️
Execução dinâmica de código	✅	✅	✅	⚠️
Ofuscação (decodificar-e-executar)	✅	✅	✅	✅
Contrabando de Unicode oculto	✅	✅	✅	✅
Segredos embutidos (chaves/tokens codificados)	✅	✅	✅	✅
Hooks de instalação / cadeia de suprimentos	⚠️	✅	✅	❌
Ferramentas superprivilegiadas / aprovadas automaticamente	✅	❌	❌	⚠️
Análise de comportamento em tempo de execução	🚧	🚧	🚧	🚧
Análise em sandbox	🚧	🚧	🚧	🚧

Achados típicos

• Uma ferramenta MCP pode executar comandos de shell arbitrários
• Um pacote baixa e executa código de uma URL externa
• Acesso a locais de credenciais (~/.aws, ~/.ssh, .env) detectado
• Execução dinâmica de código (eval / exec) detectada
• Redação de injeção de prompt / substituição de instrução em uma descrição de ferramenta ou skill
• Acesso a dados sensíveis combinado com egresso de rede de saída
• Chaves de API ou tokens codificados
• Um servidor MCP com ferramentas aprovadas automaticamente ou superprivilegiadas
• Entrada não confiável (ambiente, sys.argv, corpo de requisição/resposta) fluindo para exec ou um shell — um caminho de injeção comprovado, não apenas uma API perigosa isolada
• Uma skill de agente faz mais do que suas allowed-tools declaradas permitem (capacidade não declarada / violação de privilégio mínimo)

Fora do escopo

O SkillTotal analisa estaticamente os arquivos próprios de um único componente. Ele não executa código, observa comportamento em tempo de execução ou avalia seu ambiente, implantação ou infraestrutura. Ele não é um substituto para:

• um teste de penetração
• uma revisão de segurança de aplicação (app-sec)
• uma revisão de arquitetura / design
• uma avaliação de segurança em nuvem ou infraestrutura
• uma auditoria de runtime de Kubernetes / contêineres
• uma revisão de lógica de negócios
• uma revisão manual de código

Análise de comportamento em tempo de execução e sandbox estão planejadas para o SkillTotal Cloud (pago).

Saída

Um relatório normalizado contendo a identidade do componente, uma pontuação de risco (0–100) e nível de risco (baixo / médio / alto / crítico), capacidades detectadas (cada uma com evidência), uma impressão digital de traços comportamental (com um mapeamento CSA / MAESTRO / MITRE ATLAS), achados, needs_review e metadados. Veja docs/report-schema.md e docs/scoring.md.

Cada achado também carrega seus ids de categoria do OWASP Agentic Skills Top 10 (owasp), emitidos tanto no relatório JSON quanto no SARIF (nativo taxonomies/relationships); docs/owasp-agentic-skills-mapping.md explica a cobertura (AST01–AST05) e as lacunas honestas. Para servidores MCP, docs/mcp-owasp-mapping.md mapeia as verificações do SkillTotal para o OWASP MCP Security Cheat Sheet (e nomeia os controles de runtime que um mecanismo estático não pode cobrir).

O array traits do relatório é uma impressão digital comportamental — uma projeção de nível mais alto sobre os achados (ex.: execution_authority, embedded_credential, untrusted_perception e a combinação emergente exfil_correlation) — cada um mapeado para o modelo baseado em traços da Cloud Security Alliance, uma camada de modelo de ameaça MAESTRO e uma tática MITRE ATLAS onde há um ajuste honesto. É descritivo e nunca afeta a pontuação; veja docs/trait-crosswalk.md.

Arquitetura

O pacote sob skilltotal/ (exceto cli.py) é uma biblioteca pura, sem efeitos colaterais, para que o mesmo mecanismo alimente o aplicativo web em www.skilltotal.ai. Veja docs/architecture.md.

Desenvolvimento

pip install -e ".[dev]"
pytest

Notas de precisão

• Python é analisado via um AST (resolve aliases de importação, distingue open(p,'w') de uma leitura, ignora nomes de API que aparecem apenas em strings/comentários). Node.js/config usam regex.
• Idiomas: execução de shell, acesso de rede, acesso a arquivos e código dinâmico são detectados em Python e JavaScript/TypeScript. Arquivos Go, Rust, Java, Ruby e PHP ainda recebem as verificações de segredos, caminhos sensíveis e Unicode oculto, mas seu comportamento ainda não é analisado. Se um componente incluir código nesses idiomas, o relatório adiciona uma nota needs_review, e um veredito baixo lê "Parcialmente analisado" em vez de "Nenhum risco significativo encontrado".
• Código de teste (__tests__/, *.test.*, tests/, conftest.py, …) é rebaixado para needs_review — ele não é executado por consumidores, então não afeta a pontuação.
• Sinais ambíguos (palavras secrets/credentials isoladas, blocos base64 soltos, redação "antes de responder", arquivos minificados) vão para needs_review, nunca para findings.
• Unicode oculto (caracteres de tag de contrabando ASCII, overrides bidi Trojan-Source, caracteres de largura zero) é detectado e decodificado — uma evasão real usada para contrabandear instruções além da revisão humana. Veja tests/manual_eval/ para calibração contra ataques do mundo real.
• A execução de shell cobre subprocess/os.system, asyncio.create_subprocess_*, Node child_process e bibliotecas comuns de spawn de processos (Python sh/plumbum/pexpect/ invoke/fabric; Node zx/execa/cross-spawn/shelljs/tinyexec/node-pty).
• Ferramentas MCP perigosas são classificadas por nome/descrição tanto em manifestos JSON quanto quando definidas em código (server.tool("run_command", …), @mcp.tool sobre def read_file).
• Limitações: a detecção está no nível de chamada/importação. Capacidade via uma biblioteca de nível superior não reconhecida (ex.: uma biblioteca git que grava arquivos internamente, uma biblioteca de navegador) pode não ser sinalizada como uma chamada bruta de filesystem/shell. As capacidades indicam presença, não uso indevido comprovado.

Open source vs SkillTotal Cloud

O SkillTotal é open core. Este mecanismo (a análise, todas as regras de detecção e a CLI) é open source e completo por si só: você pode executá-lo localmente ou no CI, gratuitamente, com zero dependências de runtime. Ele informa o que um componente faz, com evidências.

Recursos pagos estão planejados para o SkillTotal Cloud (o site) e explicarão por que isso importa: interpretação e priorização de achados por LLM, execução dinâmica em sandbox, histórico de varredura e monitoramento. Eles serão executados como serviços do lado do servidor sobre este mecanismo, e seu código não faz parte deste repositório. Veja docs/open-core.md.

Licença

Apache-2.0. Veja também NOTICE.