skill-scanner 0.1.0__tar.gz

skill_scanner-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  trusted-publishing-config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Validate trusted publishing workflows
+        run: |
+          set -euo pipefail
+          test -f .github/workflows/publish-testpypi.yml
+          test -f .github/workflows/release.yml
+          grep -Fq 'name: test' .github/workflows/publish-testpypi.yml
+          grep -Fq 'name: release' .github/workflows/release.yml
+          grep -Fq 'id-token: write' .github/workflows/publish-testpypi.yml
+          grep -Fq 'id-token: write' .github/workflows/release.yml
+          grep -Fq 'gh-action-pypi-publish@' .github/workflows/publish-testpypi.yml
+          grep -Fq 'gh-action-pypi-publish@' .github/workflows/release.yml
+          grep -Fq 'repository-url: https://test.pypi.org/legacy/' .github/workflows/publish-testpypi.yml
+
+  test:
+    needs: trusted-publishing-config
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --extra all --group dev
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest --cov=src --cov-report=xml

skill_scanner-0.1.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,49 @@
+name: Publish TestPyPI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "README.md"
+      - ".github/workflows/publish-testpypi.yml"
+      - ".github/workflows/release.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test-pypi-publish:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: test
+      url: https://test.pypi.org/p/skill-scanner
+    permissions:
+      id-token: write
+      attestations: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          python-version: "3.12"
+          enable-cache: false
+      - run: uv sync --locked --group dev
+      - run: uv build --no-sources
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3
+        with:
+          subject-path: "dist/*"
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          repository-url: https://test.pypi.org/legacy/

skill_scanner-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Publish PyPI
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/skill-scanner
+    permissions:
+      id-token: write
+      attestations: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          python-version: "3.12"
+          enable-cache: false
+      - run: uv sync --locked --group dev
+      - run: uv build --no-sources
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3
+        with:
+          subject-path: "dist/*"
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

skill_scanner-0.1.0/.github/workflows/zizmor.yml

@@ -0,0 +1,28 @@
+name: GitHub Actions Security Analysis with zizmor
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Run zizmor
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor
+        uses: zizmorcore/zizmor-action@135698455da5c3b3e55f73f4419e481ab68cdd95 # v0.4.1

skill_scanner-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.cache/
+reports/
+.env
+
+SKILL.md

skill_scanner-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

skill_scanner-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: skill-scanner
+Version: 0.1.0
+Summary: Security scanner for AI agent skills and instruction artifacts
+Author: skill-scanner
+Requires-Python: >=3.11
+Requires-Dist: httpx==0.28.1
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: rich==14.3.2
+Requires-Dist: typer==0.24.0
+Provides-Extra: all
+Requires-Dist: openai==2.21.0; extra == 'all'
+Requires-Dist: vt-py==0.22.0; extra == 'all'
+Provides-Extra: openai
+Requires-Dist: openai==2.21.0; extra == 'openai'
+Provides-Extra: virustotal
+Requires-Dist: vt-py==0.22.0; extra == 'virustotal'
+Description-Content-Type: text/markdown
+
+# skill-scanner
+
+`skill-scanner` reviews AI skill and instruction artifacts for security risk using:
+- OpenAI analysis
+- VirusTotal analysis
+
+## Requirements
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/)
+- OpenAI and/or VirusTotal API key (at least one)
+
+## Install (from source)
+
+```bash
+uv sync --all-extras --group dev
+```
+
+Run with:
+
+```bash
+uv run skill-scanner --help
+```
+
+Alias:
+
+```bash
+uv run skillscan --help
+```
+
+## What gets scanned
+
+By default, `discover` and `scan` detect common skill/instruction files (for example `SKILL.md`, `AGENTS.md`, `*.instructions.md`, `*.prompt.md`, `.mdc`, and related artifacts).
+
+Use `--path` to target a specific file or folder.
+
+## Quick start
+
+```bash
+# See targets
+uv run skill-scanner discover --format json
+
+# Verify key/model configuration
+uv run skill-scanner doctor
+
+# Run a combined scan (if both keys are configured)
+uv run skill-scanner scan --format summary
+```
+
+## Key configuration and analyzer selection
+
+`scan` requires at least one analyzer enabled.
+
+- If only `OPENAI_API_KEY` is available, AI runs and VT is disabled.
+- If only `VT_API_KEY` is available, VT runs and AI is disabled.
+- If both keys are available, VT findings are included and VT context is passed into AI analysis.
+- You can disable either analyzer with `--no-ai` or `--no-vt`.
+
+## API key safety
+
+Never commit API keys. This repository ignores `.env` by default.
+
+### Option 1: Shell environment variables
+
+```bash
+export OPENAI_API_KEY="..."
+export VT_API_KEY="..."
+uv run skill-scanner scan --format summary
+```
+
+### Option 2: Local `.env` file
+
+```bash
+OPENAI_API_KEY=...
+VT_API_KEY=...
+```
+
+Then run:
+
+```bash
+uv run skill-scanner doctor
+uv run skill-scanner scan --format summary
+```
+
+### Option 3: 1Password secret references (recommended)
+
+Use 1Password secret references instead of plaintext secrets in `.env`:
+
+```bash
+OPENAI_API_KEY=op://Engineering/OpenAI/api_key
+VT_API_KEY=op://Engineering/VirusTotal/api_key
+```
+
+Run the scanner through 1Password CLI so references are resolved at runtime:
+
+```bash
+op run --env-file=.env -- uv run skill-scanner scan --format summary
+```
+
+Security best practice:
+- Prefer a 1Password Service Account scoped to only the vault/items required for scanning (least privilege).
+
+Reference:
+- https://developer.1password.com/docs/cli/secret-references/
+
+## Output formats
+
+`scan --format` supports:
+- `table` (default)
+- `summary`
+- `json`
+- `sarif`
+
+You can write output to a file with `--output <path>`.
+
+## Useful commands
+
+```bash
+# List providers
+uv run skill-scanner providers
+
+# Scan one path only
+uv run skill-scanner scan --path ./some/skill/folder --format summary
+
+# Filter to medium+
+uv run skill-scanner scan --min-severity medium --format summary
+
+# Non-zero exit if high+ findings exist
+uv run skill-scanner scan --fail-on high --format summary
+```
+
+## Exit behavior
+
+- `0`: scan completed and fail threshold not hit
+- `1`: `--fail-on` threshold matched
+- `2`: no analyzers enabled (for example missing keys combined with flags)

skill_scanner-0.1.0/README.md

@@ -0,0 +1,136 @@
+# skill-scanner
+
+`skill-scanner` reviews AI skill and instruction artifacts for security risk using:
+- OpenAI analysis
+- VirusTotal analysis
+
+## Requirements
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/)
+- OpenAI and/or VirusTotal API key (at least one)
+
+## Install (from source)
+
+```bash
+uv sync --all-extras --group dev
+```
+
+Run with:
+
+```bash
+uv run skill-scanner --help
+```
+
+Alias:
+
+```bash
+uv run skillscan --help
+```
+
+## What gets scanned
+
+By default, `discover` and `scan` detect common skill/instruction files (for example `SKILL.md`, `AGENTS.md`, `*.instructions.md`, `*.prompt.md`, `.mdc`, and related artifacts).
+
+Use `--path` to target a specific file or folder.
+
+## Quick start
+
+```bash
+# See targets
+uv run skill-scanner discover --format json
+
+# Verify key/model configuration
+uv run skill-scanner doctor
+
+# Run a combined scan (if both keys are configured)
+uv run skill-scanner scan --format summary
+```
+
+## Key configuration and analyzer selection
+
+`scan` requires at least one analyzer enabled.
+
+- If only `OPENAI_API_KEY` is available, AI runs and VT is disabled.
+- If only `VT_API_KEY` is available, VT runs and AI is disabled.
+- If both keys are available, VT findings are included and VT context is passed into AI analysis.
+- You can disable either analyzer with `--no-ai` or `--no-vt`.
+
+## API key safety
+
+Never commit API keys. This repository ignores `.env` by default.
+
+### Option 1: Shell environment variables
+
+```bash
+export OPENAI_API_KEY="..."
+export VT_API_KEY="..."
+uv run skill-scanner scan --format summary
+```
+
+### Option 2: Local `.env` file
+
+```bash
+OPENAI_API_KEY=...
+VT_API_KEY=...
+```
+
+Then run:
+
+```bash
+uv run skill-scanner doctor
+uv run skill-scanner scan --format summary
+```
+
+### Option 3: 1Password secret references (recommended)
+
+Use 1Password secret references instead of plaintext secrets in `.env`:
+
+```bash
+OPENAI_API_KEY=op://Engineering/OpenAI/api_key
+VT_API_KEY=op://Engineering/VirusTotal/api_key
+```
+
+Run the scanner through 1Password CLI so references are resolved at runtime:
+
+```bash
+op run --env-file=.env -- uv run skill-scanner scan --format summary
+```
+
+Security best practice:
+- Prefer a 1Password Service Account scoped to only the vault/items required for scanning (least privilege).
+
+Reference:
+- https://developer.1password.com/docs/cli/secret-references/
+
+## Output formats
+
+`scan --format` supports:
+- `table` (default)
+- `summary`
+- `json`
+- `sarif`
+
+You can write output to a file with `--output <path>`.
+
+## Useful commands
+
+```bash
+# List providers
+uv run skill-scanner providers
+
+# Scan one path only
+uv run skill-scanner scan --path ./some/skill/folder --format summary
+
+# Filter to medium+
+uv run skill-scanner scan --min-severity medium --format summary
+
+# Non-zero exit if high+ findings exist
+uv run skill-scanner scan --fail-on high --format summary
+```
+
+## Exit behavior
+
+- `0`: scan completed and fail threshold not hit
+- `1`: `--fail-on` threshold matched
+- `2`: no analyzers enabled (for example missing keys combined with flags)

skill_scanner-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "skill-scanner"
+version = "0.1.0"
+description = "Security scanner for AI agent skills and instruction artifacts"
+readme = "README.md"
+authors = [{ name = "skill-scanner" }]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx==0.28.1",
+    "pydantic==2.12.5",
+    "pyyaml==6.0.3",
+    "rich==14.3.2",
+    "typer==0.24.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai==2.21.0"]
+virustotal = ["vt-py==0.22.0"]
+all = ["openai==2.21.0", "vt-py==0.22.0"]
+
+[dependency-groups]
+dev = [
+    "mypy==1.19.1",
+    "pytest==9.0.2",
+    "pytest-cov==7.0.0",
+    "ruff==0.15.1",
+    "types-PyYAML==6.0.12.20250915",
+]
+
+[project.scripts]
+skill-scanner = "skill_scanner.cli:app"
+skillscan = "skill_scanner.cli:app"
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skill_scanner"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["B008", "E501", "SIM108", "SIM115"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

skill_scanner-0.1.0/renovate.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:best-practices",
+    "helpers:pinGitHubActionDigests",
+    "helpers:pinGitHubActionDigestsToSemver",
+    "schedule:weekly"
+  ],
+  "dependencyDashboard": true,
+  "minimumReleaseAge": "7 days",
+  "rangeStrategy": "pin",
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": [
+      "before 5am on monday"
+    ]
+  },
+  "packageRules": [
+    {
+      "groupName": "github-actions",
+      "matchManagers": [
+        "github-actions"
+      ]
+    },
+    {
+      "groupName": "Testing Framework",
+      "matchDatasources": [
+        "pypi"
+      ],
+      "matchPackageNames": [
+        "pytest",
+        "/^pytest-/"
+      ]
+    },
+    {
+      "groupName": "Type Checking & Validation",
+      "matchDatasources": [
+        "pypi"
+      ],
+      "matchPackageNames": [
+        "mypy",
+        "types-PyYAML",
+        "pydantic",
+        "pydantic-core"
+      ]
+    },
+    {
+      "groupName": "Dev Tools",
+      "matchDatasources": [
+        "pypi"
+      ],
+      "matchPackageNames": [
+        "ruff"
+      ]
+    },
+    {
+      "groupName": "Runtime Dependencies",
+      "matchDatasources": [
+        "pypi"
+      ],
+      "matchPackageNames": [
+        "httpx",
+        "openai",
+        "typer",
+        "vt-py"
+      ]
+    },
+    {
+      "matchUpdateTypes": [
+        "major"
+      ],
+      "dependencyDashboardApproval": true
+    }
+  ]
+}

skill_scanner-0.1.0/src/skill_scanner/__init__.py

@@ -0,0 +1,4 @@
+"""skill_scanner package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

skill_scanner-0.1.0/src/skill_scanner/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for python -m skill_scanner."""
+
+from skill_scanner.cli import app
+
+if __name__ == "__main__":
+    app()

skill_scanner-0.1.0/src/skill_scanner/analyzers/__init__.py

@@ -0,0 +1,5 @@
+"""Analyzers package."""
+
+from skill_scanner.analyzers.pipeline import run_scan
+
+__all__ = ["run_scan"]

skill_scanner-0.1.0/src/skill_scanner/analyzers/ai_analyzer.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from skill_scanner.models.reports import AIReport, VTReport
+from skill_scanner.models.targets import ScanTarget
+from skill_scanner.providers.base import LLMProvider
+
+
+def build_payload(target: ScanTarget, max_chars: int = 400_000) -> str:
+    chunks: list[str] = []
+    total = 0
+    for meta in target.files:
+        path = Path(meta.path)
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            continue
+        chunk = f"\n## FILE: {meta.relative_path}\n{text}\n"
+        if total + len(chunk) > max_chars:
+            continue
+        chunks.append(chunk)
+        total += len(chunk)
+    return "".join(chunks)
+
+
+def _append_vt_context(payload: str, vt_report: VTReport | None) -> str:
+    if vt_report is None:
+        return payload
+    vt_context = (
+        "\n## VIRUSTOTAL_CONTEXT\n"
+        f"sha256: {vt_report.sha256}\n"
+        f"malicious: {vt_report.malicious}\n"
+        f"suspicious: {vt_report.suspicious}\n"
+        f"harmless: {vt_report.harmless}\n"
+        f"undetected: {vt_report.undetected}\n"
+        f"permalink: {vt_report.permalink or 'n/a'}\n"
+    )
+    return f"{payload}{vt_context}"
+
+
+def analyze_with_ai(target: ScanTarget, provider: LLMProvider, vt_report: VTReport | None = None) -> AIReport:
+    payload = build_payload(target)
+    if not payload.strip():
+        return AIReport(provider=provider.name, model=provider.model, findings=[])
+    return provider.analyze(target, _append_vt_context(payload, vt_report))