# nvidia/skillspector architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia/skillspector
- Repository: https://github.com/nvidia/skillspector

## Overview

SkillSpector scans AI-agent skills for security risks. The principal workflow accepts a local, archive, repository, or URL input; prepares skill and artifact context; runs static checks and optionally semantic LLM analysis; then produces risk-scored reports. Major branches include vulnerability and MCP checks, live OSV lookups, suppression, and parallel batch scanning. The README documents these capabilities; sampled source confirms input safeguards and analyzer/provider support, but the CLI orchestration itself was not sampled, so some links are documented rather than code-traced.

Main entry points: [`src/skillspector/cli.py`](https://github.com/nvidia/skillspector/blob/main/src/skillspector/cli.py) (Scan CLI), [`src/skillspector/llm_analyzer_base.py`](https://github.com/nvidia/skillspector/blob/main/src/skillspector/llm_analyzer_base.py) (Semantic analyzer), [`contrib/batch_scan/batch_scan.py`](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/batch_scan.py) (Batch coordinator), [`src/skillspector/nodes/analyzers`](https://github.com/nvidia/skillspector/tree/main/src/skillspector/nodes/analyzers) (Static analyzers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan workflow"]
  node_cli["Scan CLI<br/>[cli.py]"]
  node_ingest["Input resolution<br/>[input_handler.py]"]
  node_context["Skill context<br/>[build_context.py]"]
  node_artifacts["Artifact handling<br/>[artifacts.py]"]
end

subgraph group_analysis["Security analysis"]
  node_static["Static analyzers"]
  node_ast["Python AST checks<br/>[python_ast.py]"]
  node_mcp["MCP security checks"]
  node_osv["OSV vulnerability lookup<br/>[osv_client.py]"]
  node_ledger["Inspection ledger"]
end

subgraph group_llm["LLM analysis"]
  node_semantic["Semantic analyzer"]
  node_providers["Provider selection<br/>[__init__.py]"]
  node_provider_impl["Provider adapters"]
  node_usage["Inference usage<br/>[inference_usage.py]"]
end

subgraph group_outputs["Findings and reports"]
  node_suppression["Finding suppression<br/>[suppression.py]"]
  node_report["Report generation<br/>[report.py]"]
  node_formats["SARIF models<br/>[sarif_models.py]"]
end

subgraph group_batch["Batch scanning"]
  node_batch["Batch coordinator<br/>[batch_scan.py]"]
  node_discovery["Skill discovery<br/>[discovery.py]"]
  node_batch_runner["Batch scan runner<br/>[runner.py]"]
  node_api_pool["API key pool<br/>[api_pool.py]"]
  node_batch_reports["Batch reports<br/>[reports.py]"]
end

node_user(("Skill publisher or auditor"))
node_osv_service["OSV.dev"]
node_llm_service["LLM provider service"]

node_user -->|"requests scan"| node_cli
node_cli -->|"accepts inputs"| node_ingest
node_ingest -.->|"prepares skill"| node_context
node_context -->|"inspects artifacts"| node_artifacts
node_cli -->|"runs static checks"| node_static
node_cli -->|"optionally evaluates"| node_semantic
node_static -->|"includes AST checks"| node_ast
node_static -->|"includes MCP checks"| node_mcp
node_cli -->|"performs lookups"| node_osv
node_osv -->|"queries CVEs"| node_osv_service
node_semantic -->|"resolves model"| node_providers
node_providers -->|"selects adapter"| node_provider_impl
node_semantic -->|"records usage"| node_usage
node_semantic -.->|"requests analysis"| node_llm_service
node_cli -->|"applies baseline"| node_suppression
node_cli -->|"creates report"| node_report
node_report -->|"emits SARIF"| node_formats
node_user -->|"requests batch scan"| node_batch
node_batch -->|"discovers skills"| node_discovery
node_batch -->|"dispatches scans"| node_batch_runner
node_batch_runner -->|"uses key pool"| node_api_pool
node_batch -->|"writes reports"| node_batch_reports

click node_cli "https://github.com/nvidia/skillspector/blob/main/src/skillspector/cli.py"
click node_ingest "https://github.com/nvidia/skillspector/blob/main/src/skillspector/input_handler.py"
click node_context "https://github.com/nvidia/skillspector/blob/main/src/skillspector/nodes/build_context.py"
click node_artifacts "https://github.com/nvidia/skillspector/blob/main/src/skillspector/artifacts.py"
click node_static "https://github.com/nvidia/skillspector/tree/main/src/skillspector/nodes/analyzers"
click node_ast "https://github.com/nvidia/skillspector/blob/main/src/skillspector/python_ast.py"
click node_mcp "https://github.com/nvidia/skillspector/tree/main/src/skillspector/nodes/analyzers"
click node_osv "https://github.com/nvidia/skillspector/blob/main/src/skillspector/nodes/analyzers/osv_client.py"
click node_semantic "https://github.com/nvidia/skillspector/blob/main/src/skillspector/llm_analyzer_base.py"
click node_providers "https://github.com/nvidia/skillspector/blob/main/src/skillspector/providers/__init__.py"
click node_provider_impl "https://github.com/nvidia/skillspector/tree/main/src/skillspector/providers"
click node_usage "https://github.com/nvidia/skillspector/blob/main/src/skillspector/inference_usage.py"
click node_ledger "https://github.com/nvidia/skillspector/blob/main/src/skillspector/inspection_ledger.py"
click node_suppression "https://github.com/nvidia/skillspector/blob/main/src/skillspector/suppression.py"
click node_report "https://github.com/nvidia/skillspector/blob/main/src/skillspector/nodes/report.py"
click node_formats "https://github.com/nvidia/skillspector/blob/main/src/skillspector/sarif_models.py"
click node_batch "https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/batch_scan.py"
click node_discovery "https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/discovery.py"
click node_batch_runner "https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/runner.py"
click node_api_pool "https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/api_pool.py"
click node_batch_reports "https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/reports.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_cli,node_ingest,node_context,node_artifacts toneBlue
class node_static,node_ast,node_mcp,node_osv,node_ledger toneAmber
class node_semantic,node_providers,node_provider_impl,node_usage toneMint
class node_suppression,node_report,node_formats toneRose
class node_batch,node_discovery,node_batch_runner,node_api_pool,node_batch_reports,node_user,node_osv_service,node_llm_service toneIndigo
```

## Components

### Scan workflow

- [Scan CLI](https://github.com/nvidia/skillspector/blob/main/src/skillspector/cli.py): `src/skillspector/cli.py`
- [Input resolution](https://github.com/nvidia/skillspector/blob/main/src/skillspector/input_handler.py): `src/skillspector/input_handler.py`
- [Skill context](https://github.com/nvidia/skillspector/blob/main/src/skillspector/nodes/build_context.py): `src/skillspector/nodes/build_context.py`
- [Artifact handling](https://github.com/nvidia/skillspector/blob/main/src/skillspector/artifacts.py): `src/skillspector/artifacts.py`

### Security analysis

- [Static analyzers](https://github.com/nvidia/skillspector/tree/main/src/skillspector/nodes/analyzers): `src/skillspector/nodes/analyzers`
- [Python AST checks](https://github.com/nvidia/skillspector/blob/main/src/skillspector/python_ast.py): `src/skillspector/python_ast.py`
- [MCP security checks](https://github.com/nvidia/skillspector/tree/main/src/skillspector/nodes/analyzers): `src/skillspector/nodes/analyzers`
- [OSV vulnerability lookup](https://github.com/nvidia/skillspector/blob/main/src/skillspector/nodes/analyzers/osv_client.py): `src/skillspector/nodes/analyzers/osv_client.py`
- [Inspection ledger](https://github.com/nvidia/skillspector/blob/main/src/skillspector/inspection_ledger.py): `src/skillspector/inspection_ledger.py`

### LLM analysis

- [Semantic analyzer](https://github.com/nvidia/skillspector/blob/main/src/skillspector/llm_analyzer_base.py): `src/skillspector/llm_analyzer_base.py`
- [Provider selection](https://github.com/nvidia/skillspector/blob/main/src/skillspector/providers/__init__.py): `src/skillspector/providers/__init__.py`
- [Provider adapters](https://github.com/nvidia/skillspector/tree/main/src/skillspector/providers): `src/skillspector/providers`
- [Inference usage](https://github.com/nvidia/skillspector/blob/main/src/skillspector/inference_usage.py): `src/skillspector/inference_usage.py`

### Findings and reports

- [Finding suppression](https://github.com/nvidia/skillspector/blob/main/src/skillspector/suppression.py): `src/skillspector/suppression.py`
- [Report generation](https://github.com/nvidia/skillspector/blob/main/src/skillspector/nodes/report.py): `src/skillspector/nodes/report.py`
- [SARIF models](https://github.com/nvidia/skillspector/blob/main/src/skillspector/sarif_models.py): `src/skillspector/sarif_models.py`

### Batch scanning

- [Batch coordinator](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/batch_scan.py): `contrib/batch_scan/batch_scan.py`
- [Skill discovery](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/discovery.py): `contrib/batch_scan/discovery.py`
- [Batch scan runner](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/runner.py): `contrib/batch_scan/runner.py`
- [API key pool](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/api_pool.py): `contrib/batch_scan/api_pool.py`
- [Batch reports](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/reports.py): `contrib/batch_scan/reports.py`

### Other components

- **Skill publisher or auditor**
- **OSV.dev**
- **LLM provider service**

## Connections

- Skill publisher or auditor → Scan CLI: requests scan
- Scan CLI → Input resolution: accepts inputs
- Input resolution → Skill context: prepares skill (evidence: `src/skillspector/nodes/build_context.py`)
- Skill context → Artifact handling: inspects artifacts (evidence: `src/skillspector/nodes/build_context.py`)
- Scan CLI → Static analyzers: runs static checks
- Scan CLI → Semantic analyzer: optionally evaluates
- Static analyzers → Python AST checks: includes AST checks
- Static analyzers → MCP security checks: includes MCP checks
- Scan CLI → OSV vulnerability lookup: performs lookups
- OSV vulnerability lookup → OSV.dev: queries CVEs
- Semantic analyzer → Provider selection: resolves model (evidence: `src/skillspector/llm_analyzer_base.py`)
- Provider selection → Provider adapters: selects adapter (evidence: `src/skillspector/providers/__init__.py`)
- Semantic analyzer → Inference usage: records usage (evidence: `src/skillspector/llm_analyzer_base.py`)
- Semantic analyzer → LLM provider service: requests analysis
- Scan CLI → Finding suppression: applies baseline
- Scan CLI → Report generation: creates report
- Report generation → SARIF models: emits SARIF (evidence: `src/skillspector/nodes/report.py`)
- Skill publisher or auditor → Batch coordinator: requests batch scan
- Batch coordinator → Skill discovery: discovers skills (evidence: `contrib/batch_scan/batch_scan.py`)
- Batch coordinator → Batch scan runner: dispatches scans (evidence: `contrib/batch_scan/batch_scan.py`)
- Batch scan runner → API key pool: uses key pool (evidence: `contrib/batch_scan/runner.py`)
- Batch coordinator → Batch reports: writes reports (evidence: `contrib/batch_scan/batch_scan.py`)