Metadata-Version: 2.4
Name: t2i-skillguard
Version: 0.1.0
Summary: Security scanner for AI skill files (SKILL.md)
License: MIT
License-File: LICENSE
Keywords: security,scanner,ai,skills,cli
Author: T2I Team
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: rich (>=13.9.4,<14.0.0)
Project-URL: Homepage, https://github.com/Tech2Insights/t2i-skillguard
Project-URL: Repository, https://github.com/Tech2Insights/t2i-skillguard
Description-Content-Type: text/markdown

# t2i-skillguard

Security scanner for AI skill files (`SKILL.md`) and bundled code (`scripts/`, `tools/`).

It helps you catch high-risk patterns before publishing or running a skill.

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![Output](https://img.shields.io/badge/output-terminal%20%7C%20json-brightgreen)
![License](https://img.shields.io/badge/license-MIT-black)

## TL;DR

```bash
# 1) Install
pip install t2i-skillguard

# 2) Scan default locations
t2i-skillguard scan -v

# 3) JSON report with CVSS + payment aggregation
t2i-skillguard scan --format json --aggregate-payment --output report.json
```

Example execution output:

![t2i-skillguard scan example](docs/assets/example.png)

## Why this project

- Focused on real AI-skill risks (prompt injection, third-party content abuse, unsafe code execution).
- Scans both skill metadata and executable code paths.
- Clear terminal output + machine-readable JSON for CI.
- Opinionated severity model to support go/no-go decisions.

## Features

- 13 built-in security rules for AI skill ecosystems.
- Scans both `SKILL.md` and bundled code in `scripts/` + `tools/`.
- CVSS metadata per vulnerability in JSON output.
- Optional aggregation of repetitive payment findings (`--aggregate-payment`).
- Severity/category filters for focused triage.
- CI-friendly exit codes (`0` clean, `1` findings).

## What it detects

t2i-skillguard currently ships with **13 security rules** across CRITICAL/HIGH/MEDIUM/LOW.

| Severity | Rule | Category | Typical risk |
|---|---|---|---|
| CRITICAL | `prompt_injection` | Injection | Override safety instructions / exfiltrate context |
| CRITICAL | `command_injection` | Injection | Arbitrary command execution |
| HIGH | `secret_exposure` | Exposure | Hardcoded keys, tokens, passwords, private keys |
| HIGH | `malicious_patterns` | Dangerous Patterns | `eval`/`exec`/unsafe deserialization paths |
| HIGH | `supply_chain` | Supply Chain | Downloading/executing untrusted code |
| HIGH / MEDIUM | `third_party_exposure` | Dangerous Patterns | External content driving AI behavior |
| MEDIUM | `insecure_flags` | Configuration | TLS/cert bypass, unsafe runtime flags |
| MEDIUM | `path_traversal` | Configuration | Access outside allowed file roots |
| MEDIUM | `credential_exposure` | Exposure | Secrets leaked in logs, errors, output |
| MEDIUM | `external_content` | Exposure | Unsafe processing of untrusted web/user content |
| LOW | `payment_capability` | Supply Chain | Financial capability signal for extra review |
| MEDIUM | `system_alteration` | Configuration | Service/firewall/startup/system modifications |
| LOW | `frontmatter` | Metadata | Missing/invalid skill metadata |

Full rule docs: [`docs/rules/README.md`](docs/rules/README.md)

## Installation

### Option A: install from PyPI (recommended for usage)

```bash
pip install t2i-skillguard
```

### Option B: local development (recommended for contributors)

```bash
poetry install
```

## Quick start

Scan default skill locations:

```bash
t2i-skillguard scan
```

Scan one skill:

```bash
t2i-skillguard scan-skill /path/to/skill
```

Scan custom paths:

```bash
t2i-skillguard scan /path/to/skills-a /path/to/skills-b
```

## CLI usage

### Output modes

```bash
# Terminal (default)
t2i-skillguard scan --format terminal

# JSON
t2i-skillguard scan --format json

# Terminal + JSON
t2i-skillguard scan --format both

# Compact JSON (single line)
t2i-skillguard scan --format compact
```

### Common filters

```bash
# Only HIGH and CRITICAL findings
t2i-skillguard scan --min-severity HIGH

# Only one rule category
t2i-skillguard scan --category prompt_injection

# Ignore a whole category
t2i-skillguard scan --ignore-rule prompt_injection

# Ignore a specific pattern in a category
t2i-skillguard scan --ignore-rule prompt_injection.role_confusion

# Repeat or use comma-separated values
t2i-skillguard scan --ignore-rule insecure_flags.http_url --ignore-rule path_traversal
t2i-skillguard scan --ignore-rule insecure_flags.http_url,path_traversal

# Load scoped ignores from YAML file
t2i-skillguard scan --ignore-file .t2i-skillguard-ignore.yml

# Disable warnings for unmatched ignore entries
t2i-skillguard scan --no-warn-unused-ignores

# Skip scripts/tools analysis
t2i-skillguard scan --no-scripts
```

### Ignore rules

Use `--ignore-rule` when you need to suppress known/accepted findings for a specific run.

- Accepted format: `category` or `category.pattern`
- Repeatable: `--ignore-rule a --ignore-rule b.c`
- Comma-separated supported: `--ignore-rule a,b.c`
- Works with both `scan` and `scan-skill`
- You can combine with `--ignore-file` for file/line-scoped suppression

Examples:

```bash
# Ignore all prompt injection findings
t2i-skillguard scan --ignore-rule prompt_injection

# Keep only prompt_injection category, then ignore one noisy pattern
t2i-skillguard scan --category prompt_injection --ignore-rule prompt_injection.role_confusion

# Single-skill scan with ignores
t2i-skillguard scan-skill /path/to/skill --ignore-rule insecure_flags.http_url
```

### Ignore file (YAML)

The scanner will auto-load `./.t2i-skillguard-ignore.yml` if it exists. You can also set a custom path with `--ignore-file`.

Supported schema (`version: 1`):

```yaml
version: 1
ignores:
  - category: prompt_injection
  - category: insecure_flags
    pattern: http_url
  - category: credential_exposure
    file: skills/skill-creator/scripts/aggregate_benchmark.py
  - category: prompt_injection
    pattern: concealment_instruction
    file: skills/skill-creator/SKILL.md
    line: 327
    reason: "Known accepted case"
```

Fields:

- `category` (required)
- `pattern` (optional)
- `file` (optional)
- `line` or `lines` (optional, requires `file`)
- `reason` (optional)

Note: ignore rules (CLI and YAML) affect the final report and exit code for that run. They do not modify detector logic.

### Unused ignore warnings

By default, the CLI warns when an ignore entry does not match any finding in the current run.

- Default: `--warn-unused-ignores`
- Disable warnings: `--no-warn-unused-ignores`

Example warning output:

```text
Ignored findings: 3

Warning: 2 ignore entries did not match any finding.
  - prompt_injection.role_confusion @ /repo/skills/skill-a/SKILL.md:120
  - external_content
```

### Reporting

```bash
# Verbose terminal output
t2i-skillguard scan -v

# Save JSON report
t2i-skillguard scan --output report.json

# Aggregate repetitive payment capability findings in terminal and JSON output
t2i-skillguard scan --format both --aggregate-payment

# Aggregate for a single skill scan
t2i-skillguard scan-skill /path/to/skill --format json --aggregate-payment

# Show default locations that will be scanned
t2i-skillguard list-paths
```

## Exit codes (CI-friendly)

- `0` -> no vulnerabilities found
- `1` -> one or more vulnerabilities found

This makes it easy to fail CI pipelines when findings are detected.

## CI integration (GitHub Actions)

```yaml
name: Skill Security Scan

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Poetry
        run: pipx install poetry

      - name: Install dependencies
        run: poetry install

      - name: Run scanner
        run: poetry run t2i-skillguard scan --format json --aggregate-payment --output skillguard-report.json
```

## Release and PyPI publish

When a GitHub Release is published, `.github/workflows/publish-pypi.yml` runs and publishes the package to PyPI.

Important:

- Release tag must match `tool.poetry.version` in `pyproject.toml`.
- Both `1.0.0` and `v1.0.0` tag formats are accepted.
- Publish job runs lint (`poetry run ruff check .`) and tests (`poetry run pytest`) before build/upload.
- Trusted Publisher must be configured in PyPI for this repository/workflow.

## Scoring model

Each skill gets a score on a `0-10` scale:

```text
raw_score = min(10, max_severity + vulnerability_count * 0.5)
score = min(raw_score, severity_cap[max_severity])

severity_cap = {
  CRITICAL: 10,
  HIGH: 9,
  MEDIUM: 7,
  LOW: 4,
  INFO: 0,
}
```

This cap keeps score bands coherent with max-severity verdicts (for example, many LOW findings cannot become CRITICAL by count alone).

Verdict bands:

- `0` -> OK
- `1-4` -> LOW
- `5-7` -> MEDIUM
- `8-9` -> HIGH
- `10` -> CRITICAL

## Default scan locations

If no path is provided, scanner checks existing directories in this order.

Project scope:

- `./.opencode/skills/`
- `./.claude/skills/`
- `./.agents/skills/`

Global scope:

- `~/.config/opencode/skills/`
- `~/.claude/skills/`
- `~/.agents/skills/`

Compatibility (when present):

- `${XDG_CONFIG_HOME}/opencode/skills/`
- `${XDG_CONFIG_HOME}/claude/skills/`
- `${XDG_CONFIG_HOME}/agents/skills/`
- `${APPDATA}/opencode/skills/` (Windows)
- `${APPDATA}/claude/skills/` (Windows)
- `${APPDATA}/agents/skills/` (Windows)
- `~/.config/claude/skills/` (legacy)
- `~/.config/anthropic/skills/` (legacy)

Tip: run `t2i-skillguard list-paths` to see exactly which paths were found on your machine.

## Supported environments

- **OS**: Linux, macOS, Windows (including `APPDATA` path discovery support).
- **Python**: 3.10+ recommended.
- **Execution modes**:
  - local development via Poetry,
  - CI pipelines (GitHub Actions example included above).
- **Input layout**:
  - project-local skill folders (`.opencode`, `.claude`, `.agents`),
  - global skill folders (`~/.config/opencode`, `~/.claude`, `~/.agents`),
  - compatibility paths (`XDG_CONFIG_HOME`, legacy config paths).

## CVSS in JSON output

Each vulnerability in JSON output includes CVSS metadata:

- `cvss_vector`
- `cvss_score`
- `cvss_severity`

CVSS is resolved per `category.pattern` (with category fallback coverage).

When using `--aggregate-payment`, output also includes grouped-vs-raw counters:

- report level: `raw_total_vulnerabilities`
- skill level: `raw_vulnerability_count`, `raw_payment_vulnerability_count`

Aggregation is presentation-only; detection logic, score, and verdict are unchanged.

Example:

```json
{
  "id": "CMDI-001",
  "severity": "CRITICAL",
  "category": "command_injection",
  "pattern": "subprocess_shell_true",
  "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
  "cvss_score": 10.0,
  "cvss_severity": "CRITICAL"
}
```

## Development

```bash
# Install dependencies
poetry install

# Run lint
poetry run ruff check .

# Run tests
poetry run pytest

# Run scanner locally
poetry run t2i-skillguard scan -v
```

## Contributing

Contributions are welcome.

- Open an issue for bugs, false positives, or rule improvements.
- Submit focused PRs with tests for behavior changes.
- Keep rule docs in `docs/rules/` aligned with detector changes.
- Pull requests run CI checks (`.github/workflows/tests.yml`) that execute lint + tests and fail the PR check if either command fails.
- Run the same checks locally before opening PR:

```bash
poetry run ruff check .
poetry run pytest
```

Recommended contribution scope:

- one detector fix/improvement per PR,
- documentation updates in the same PR,
- include before/after examples when tuning detection patterns.

## Security policy

See [`SECURITY.md`](SECURITY.md) for supported versions, private reporting instructions, and disclosure policy.

## Documentation

- Rules index: [`docs/rules/README.md`](docs/rules/README.md)
- Rule deep-dives: [`docs/rules/`](docs/rules)

## License

MIT

