skill-security-scan: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

skill-security-scan is a command-line security scanner for Claude Skills. It performs static analysis to detect security risks like data exfiltration, sensitive file access, code injection, and dangerous command execution in third-party Skills before installation.

Development Commands

Installation & Setup

# Install dependencies
pip install -r requirements.txt

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running the Scanner

# Basic scan
python -m src.cli scan /path/to/skill

# Scan with JSON output
python -m src.cli scan /path/to/skill --format json --output report.json

# Scan with custom rules
python -m src.cli scan /path/to/skill --rules custom-rules.yaml

# Scan with severity filter
python -m src.cli scan /path/to/skill --severity CRITICAL

Testing

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_skills_scanner.py

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test
pytest tests/test_skills_scanner.py::TestSkillsScanner::test_detect_network_exfiltration -v

Code Quality

# Format code with Black
black src/ tests/

# Lint with Ruff
ruff check src/ tests/

# Type check with MyPy
mypy src/

Architecture

Core Components

The scanner follows a layered architecture:

1. CLI Layer (src/cli.py)

   • Entry point using Click framework
   • Command parsing and user interaction
   • Coordinates config loading, rule creation, scanning, and reporting

2. Configuration Layer (src/config_loader.py)

   • Loads YAML configs from config/ directory
   • Supports multiple config paths with fallback
   • Loads rules and whitelist

3. Business Logic Layer

   • RulesFactory (src/rules_factory.py): Instantiates rule objects from config
   • SecurityDetector (src/scanner/detector.py): Main controller coordinating scan workflow