# pezhik/skilltotal architecture

> Architecture diagram of the GitHub repository pezhik/skilltotal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pezhik/skilltotal
- Repository: https://github.com/pezhik/skilltotal

## Overview

SkillTotal is a local, static security-analysis engine for AI components and software packages. Its main workflow collects a component from a path, archive, git URL, or package registry; indexes its files; runs specialized scanners; then synthesizes evidence-backed findings, capabilities, and a risk score into a report. The CLI also exposes distinct review workflows—diff, baseline suppression, pre-install guard, and installed-component inventory—plus SARIF and AI-BOM output. Scanner details and some subsystem wiring are only partially sampled, so unsourced links are omitted.

Main entry points: [`skilltotal/cli.py`](https://github.com/pezhik/skilltotal/blob/main/skilltotal/cli.py) (CLI commands), [`skilltotal/engine.py`](https://github.com/pezhik/skilltotal/blob/main/skilltotal/engine.py) (Analysis engine), [`skilltotal/scanners/__init__.py`](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/__init__.py) (Scanner registry), [`skilltotal/file_index.py`](https://github.com/pezhik/skilltotal/blob/main/skilltotal/file_index.py) (File index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Source intake"]
  node_collector["Source collector<br/>[collector.py]"]
end

subgraph group_analysis["Static analysis"]
  node_file_index["File index<br/>[file_index.py]"]
  node_scanner_registry["Scanner registry<br/>[__init__.py]"]
  node_scanner_base["Scanner framework<br/>[base.py]"]
  node_python_scanner["Python AST scan<br/>[python_ast.py]"]
  node_mcp_scanner["MCP scan<br/>[mcp.py]"]
  node_sensitive_scanner["Sensitive paths<br/>[sensitive_paths.py]"]
  node_other_scanners["Other risk scanners"]
  node_normalization["Text normalization<br/>[text_normalize.py]"]
end

subgraph group_assessment["Risk assessment"]
  node_engine["Analysis engine<br/>[engine.py]"]
  node_skill_analysis["Skill analysis<br/>[agent_skill.py]"]
  node_traits["Trait fingerprint<br/>[traits.py]"]
  node_typosquatting["Typosquatting check<br/>[typosquatting.py]"]
  node_scoring["Risk scoring<br/>[scoring.py]"]
  node_models["Report models<br/>[models.py]"]
  node_owasp["Threat mappings<br/>[owasp.py]"]
  node_rules["Rules catalog<br/>[rules.py]"]
end

subgraph group_workflows["Review workflows"]
  node_baseline["Baseline suppression<br/>[baseline.py]"]
  node_diff["Version diff<br/>[diff.py]"]
  node_guard["Install guard<br/>[guard.py]"]
  node_inventory["Component inventory<br/>[inventory.py]"]
  node_provenance["Registry provenance<br/>[provenance.py]"]
  node_sbom["AI-BOM output<br/>[sbom.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_mcp_api["MCP server<br/>[mcp_server.py]"]
  node_report["Report rendering<br/>[report.py]"]
  node_sarif["SARIF output<br/>[sarif.py]"]
end

node_user(("Engineer"))
node_registry["Package registries"]
node_git["Git remote"]

node_user -->|"runs scan"| node_cli
node_cli -->|"collects source"| node_collector
node_collector -->|"downloads packages"| node_registry
node_collector -->|"clones remote"| node_git
node_engine -->|"collects source"| node_collector
node_engine -->|"indexes files"| node_file_index
node_engine -->|"runs scanners"| node_scanner_registry
node_scanner_registry -->|"registers"| node_python_scanner
node_scanner_registry -->|"registers"| node_mcp_scanner
node_scanner_registry -->|"registers"| node_sensitive_scanner
node_scanner_registry -->|"registers"| node_other_scanners
node_python_scanner -->|"reads indexed files"| node_file_index
node_mcp_scanner -->|"reads indexed files"| node_file_index
node_sensitive_scanner -->|"reads indexed files"| node_file_index
node_scanner_base -->|"uses index"| node_file_index
node_scanner_base -->|"normalizes text"| node_normalization
node_engine -->|"analyzes skills"| node_skill_analysis
node_engine -->|"fingerprints traits"| node_traits
node_engine -->|"checks package names"| node_typosquatting
node_engine -->|"scores findings"| node_scoring
node_scoring -->|"builds findings"| node_models
node_engine -->|"returns report"| node_models
node_engine -->|"maps findings"| node_owasp
node_cli -->|"lists rules"| node_rules
node_scanner_registry -->|"provides scanner rules"| node_rules
node_cli -->|"analyzes component"| node_engine
node_mcp_api -->|"analyzes component"| node_engine
node_cli -->|"renders report"| node_report
node_cli -->|"writes SARIF"| node_sarif
node_cli -->|"applies baseline"| node_baseline
node_cli -->|"compares reports"| node_diff
node_cli -->|"checks install risk"| node_guard
node_cli -->|"discovers components"| node_inventory
node_inventory -.->|"scans components"| node_engine
node_cli -->|"adds provenance"| node_provenance
node_cli -->|"writes AI-BOM"| node_sbom

click node_cli "https://github.com/pezhik/skilltotal/blob/main/skilltotal/cli.py"
click node_mcp_api "https://github.com/pezhik/skilltotal/blob/main/skilltotal/mcp_server.py"
click node_collector "https://github.com/pezhik/skilltotal/blob/main/skilltotal/collector.py"
click node_file_index "https://github.com/pezhik/skilltotal/blob/main/skilltotal/file_index.py"
click node_scanner_registry "https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/__init__.py"
click node_scanner_base "https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/base.py"
click node_python_scanner "https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/python_ast.py"
click node_mcp_scanner "https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/mcp.py"
click node_sensitive_scanner "https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/sensitive_paths.py"
click node_other_scanners "https://github.com/pezhik/skilltotal/tree/main/skilltotal/scanners"
click node_normalization "https://github.com/pezhik/skilltotal/blob/main/skilltotal/text_normalize.py"
click node_engine "https://github.com/pezhik/skilltotal/blob/main/skilltotal/engine.py"
click node_skill_analysis "https://github.com/pezhik/skilltotal/blob/main/skilltotal/agent_skill.py"
click node_traits "https://github.com/pezhik/skilltotal/blob/main/skilltotal/traits.py"
click node_typosquatting "https://github.com/pezhik/skilltotal/blob/main/skilltotal/typosquatting.py"
click node_scoring "https://github.com/pezhik/skilltotal/blob/main/skilltotal/scoring.py"
click node_models "https://github.com/pezhik/skilltotal/blob/main/skilltotal/models.py"
click node_owasp "https://github.com/pezhik/skilltotal/blob/main/skilltotal/owasp.py"
click node_rules "https://github.com/pezhik/skilltotal/blob/main/skilltotal/rules.py"
click node_report "https://github.com/pezhik/skilltotal/blob/main/skilltotal/report.py"
click node_sarif "https://github.com/pezhik/skilltotal/blob/main/skilltotal/sarif.py"
click node_baseline "https://github.com/pezhik/skilltotal/blob/main/skilltotal/baseline.py"
click node_diff "https://github.com/pezhik/skilltotal/blob/main/skilltotal/diff.py"
click node_guard "https://github.com/pezhik/skilltotal/blob/main/skilltotal/guard.py"
click node_inventory "https://github.com/pezhik/skilltotal/blob/main/skilltotal/inventory.py"
click node_provenance "https://github.com/pezhik/skilltotal/blob/main/skilltotal/provenance.py"
click node_sbom "https://github.com/pezhik/skilltotal/blob/main/skilltotal/sbom.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collector toneBlue
class node_file_index,node_scanner_registry,node_scanner_base,node_python_scanner,node_mcp_scanner,node_sensitive_scanner,node_other_scanners,node_normalization toneAmber
class node_engine,node_skill_analysis,node_traits,node_typosquatting,node_scoring,node_models,node_owasp,node_rules toneMint
class node_baseline,node_diff,node_guard,node_inventory,node_provenance,node_sbom toneRose
class node_cli,node_mcp_api,node_report,node_sarif,node_user,node_registry,node_git toneIndigo
```

## Components

### Source intake

- [Source collector](https://github.com/pezhik/skilltotal/blob/main/skilltotal/collector.py): `skilltotal/collector.py`

### Static analysis

- [File index](https://github.com/pezhik/skilltotal/blob/main/skilltotal/file_index.py): `skilltotal/file_index.py`
- [Scanner registry](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/__init__.py): `skilltotal/scanners/__init__.py`
- [Scanner framework](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/base.py): `skilltotal/scanners/base.py`
- [Python AST scan](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/python_ast.py): `skilltotal/scanners/python_ast.py`
- [MCP scan](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/mcp.py): `skilltotal/scanners/mcp.py`
- [Sensitive paths](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scanners/sensitive_paths.py): `skilltotal/scanners/sensitive_paths.py`
- [Other risk scanners](https://github.com/pezhik/skilltotal/tree/main/skilltotal/scanners): `skilltotal/scanners`
- [Text normalization](https://github.com/pezhik/skilltotal/blob/main/skilltotal/text_normalize.py): `skilltotal/text_normalize.py`

### Risk assessment

- [Analysis engine](https://github.com/pezhik/skilltotal/blob/main/skilltotal/engine.py): `skilltotal/engine.py`
- [Skill analysis](https://github.com/pezhik/skilltotal/blob/main/skilltotal/agent_skill.py): `skilltotal/agent_skill.py`
- [Trait fingerprint](https://github.com/pezhik/skilltotal/blob/main/skilltotal/traits.py): `skilltotal/traits.py`
- [Typosquatting check](https://github.com/pezhik/skilltotal/blob/main/skilltotal/typosquatting.py): `skilltotal/typosquatting.py`
- [Risk scoring](https://github.com/pezhik/skilltotal/blob/main/skilltotal/scoring.py): `skilltotal/scoring.py`
- [Report models](https://github.com/pezhik/skilltotal/blob/main/skilltotal/models.py): `skilltotal/models.py`
- [Threat mappings](https://github.com/pezhik/skilltotal/blob/main/skilltotal/owasp.py): `skilltotal/owasp.py`
- [Rules catalog](https://github.com/pezhik/skilltotal/blob/main/skilltotal/rules.py): `skilltotal/rules.py`

### Review workflows

- [Baseline suppression](https://github.com/pezhik/skilltotal/blob/main/skilltotal/baseline.py): `skilltotal/baseline.py`
- [Version diff](https://github.com/pezhik/skilltotal/blob/main/skilltotal/diff.py): `skilltotal/diff.py`
- [Install guard](https://github.com/pezhik/skilltotal/blob/main/skilltotal/guard.py): `skilltotal/guard.py`
- [Component inventory](https://github.com/pezhik/skilltotal/blob/main/skilltotal/inventory.py): `skilltotal/inventory.py`
- [Registry provenance](https://github.com/pezhik/skilltotal/blob/main/skilltotal/provenance.py): `skilltotal/provenance.py`
- [AI-BOM output](https://github.com/pezhik/skilltotal/blob/main/skilltotal/sbom.py): `skilltotal/sbom.py`

### User interfaces

- [CLI commands](https://github.com/pezhik/skilltotal/blob/main/skilltotal/cli.py): `skilltotal/cli.py`
- [MCP server](https://github.com/pezhik/skilltotal/blob/main/skilltotal/mcp_server.py): `skilltotal/mcp_server.py`
- [Report rendering](https://github.com/pezhik/skilltotal/blob/main/skilltotal/report.py): `skilltotal/report.py`
- [SARIF output](https://github.com/pezhik/skilltotal/blob/main/skilltotal/sarif.py): `skilltotal/sarif.py`

### Other components

- **Engineer**
- **Package registries**
- **Git remote**

## Connections

- Engineer → CLI commands: runs scan (evidence: `README.md`)
- CLI commands → Source collector: collects source (evidence: `skilltotal/cli.py`)
- Source collector → Package registries: downloads packages (evidence: `skilltotal/collector.py`)
- Source collector → Git remote: clones remote (evidence: `skilltotal/collector.py`)
- Analysis engine → Source collector: collects source (evidence: `skilltotal/engine.py`)
- Analysis engine → File index: indexes files (evidence: `skilltotal/engine.py`)
- Analysis engine → Scanner registry: runs scanners (evidence: `skilltotal/engine.py`)
- Scanner registry → Python AST scan: registers (evidence: `skilltotal/scanners/__init__.py`)
- Scanner registry → MCP scan: registers (evidence: `skilltotal/scanners/__init__.py`)
- Scanner registry → Sensitive paths: registers (evidence: `skilltotal/scanners/__init__.py`)
- Scanner registry → Other risk scanners: registers (evidence: `skilltotal/scanners/__init__.py`)
- Python AST scan → File index: reads indexed files (evidence: `skilltotal/scanners/python_ast.py`)
- MCP scan → File index: reads indexed files (evidence: `skilltotal/scanners/mcp.py`)
- Sensitive paths → File index: reads indexed files (evidence: `skilltotal/scanners/sensitive_paths.py`)
- Scanner framework → File index: uses index (evidence: `skilltotal/scanners/base.py`)
- Scanner framework → Text normalization: normalizes text (evidence: `skilltotal/scanners/base.py`)
- Analysis engine → Skill analysis: analyzes skills (evidence: `skilltotal/engine.py`)
- Analysis engine → Trait fingerprint: fingerprints traits (evidence: `skilltotal/engine.py`)
- Analysis engine → Typosquatting check: checks package names (evidence: `skilltotal/engine.py`)
- Analysis engine → Risk scoring: scores findings (evidence: `skilltotal/engine.py`)
- Risk scoring → Report models: builds findings (evidence: `skilltotal/scoring.py`)
- Analysis engine → Report models: returns report (evidence: `skilltotal/engine.py`)
- Analysis engine → Threat mappings: maps findings (evidence: `skilltotal/engine.py`)
- CLI commands → Rules catalog: lists rules (evidence: `skilltotal/cli.py`)
- Scanner registry → Rules catalog: provides scanner rules (evidence: `skilltotal/rules.py`)
- CLI commands → Analysis engine: analyzes component (evidence: `skilltotal/cli.py`)
- MCP server → Analysis engine: analyzes component (evidence: `skilltotal/mcp_server.py`)
- CLI commands → Report rendering: renders report (evidence: `skilltotal/cli.py`)
- CLI commands → SARIF output: writes SARIF (evidence: `skilltotal/cli.py`)
- CLI commands → Baseline suppression: applies baseline (evidence: `skilltotal/cli.py`)
- CLI commands → Version diff: compares reports (evidence: `skilltotal/cli.py`)
- CLI commands → Install guard: checks install risk (evidence: `skilltotal/cli.py`)
- CLI commands → Component inventory: discovers components (evidence: `skilltotal/cli.py`)
- Component inventory → Analysis engine: scans components (evidence: `README.md`)
- CLI commands → Registry provenance: adds provenance (evidence: `skilltotal/cli.py`)
- CLI commands → AI-BOM output: writes AI-BOM (evidence: `skilltotal/cli.py`)
