skill-security-scan

# 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
```bash
# Install dependencies
pip install -r requirements.txt

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

### Running the Scanner
```bash
# 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
```bash
# 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
```bash
# 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

4. **Scan Engine Layer**
   - `SkillParser` (`src/scanner/parser.py`): Collects files, extracts metadata, filters directories
   - `SkillAnalyzer` (`src/scanner/analyzer.py`): Analyzes files against rules, generates findings
   - `Finding` class: Represents individual security issues

5. **Rule Detection Layer** (`src/rules/`)
   - `base.py`: Abstract `SecurityRule` base class with regex matching logic
   - Specialized rule implementations: `network.py`, `fileops.py`, `injection.py`, `command.py`, `dependencies.py`
   - Each rule defines patterns, severity, and match logic

6. **Reporting Layer** (`src/reporters/`)
   - `ConsoleReporter`: Colored terminal output with emojis
   - `JSONReporter`: Machine-readable JSON format

### Data Flow

```
User Command → ConfigLoader → RulesFactory → SecurityDetector
    ↓
SkillParser (collect files, extract metadata)
    ↓
SkillAnalyzer (apply rules to each file)
    ↓
Findings collected → Risk score calculated
    ↓
Reporter formats output → Display/Save report
```

### Risk Score Calculation

Located in `src/scanner/analyzer.py:_calculate_risk_score`:
- Weighted by severity: CRITICAL=10, HIGH=7, WARNING=4, INFO=1
- Multiplies severity weight by finding confidence (0-1)
- Normalizes to 0-10 scale (max assumes 20 issues at highest weight/confidence)
- Risk levels: 8-10 CRITICAL, 6-7 HIGH, 4-5 MEDIUM, 2-3 LOW, 0-1 SAFE

### Rule Matching

All rules inherit from `SecurityRule` in `src/rules/base.py`:
- Patterns are compiled as case-insensitive regex on initialization
- `_find_matches()` scans content line-by-line
- Confidence calculated based on context (comments reduce confidence, suspicious keywords increase it)
- Specialized rules can override `match()` for custom logic

### File Filtering

`SkillParser._collect_files()` defines:
- **Scanned extensions**: `.md`, `.txt`, `.py`, `.js`, `.ts`, `.sh`, `.bash`, `.yml`, `.yaml`, `.json`, `.toml`
- **Excluded directories**: `.git`, `__pycache__`, `node_modules`, `.venv`, `venv`, `dist`, `build`, `.pytest_cache`
- Always scans `SKILL.md` if present

### Configuration Files

- `config/config.yaml`: Scanner settings (max file size, exclude patterns, scan extensions)
- `config/rules.yaml`: Detection rules organized by category (network, file, command, injection, dependency, obfuscation)
- `config/whitelist.yaml`: Rule IDs to skip during scanning

## Important Implementation Details

### Rule Categories and IDs

Rule IDs follow prefix pattern indicating category:
- `NET*`: Network operations (external requests, data exfiltration)
- `FILE*`: File operations (sensitive file access, dangerous modifications)
- `CMD*`: Command execution (dangerous commands, system calls)
- `INJ*`: Code injection (injection patterns, dynamic execution, backdoors)
- `DEP*`: Dependency operations (global installs, version conflicts)
- `OBF*`: Code obfuscation (base64 encoding, indirect calls)

### Error Handling

The scanner uses defensive error handling:
- File read errors print warnings and continue scanning other files
- Missing config files use defaults
- Invalid rules are skipped with warnings
- Only critical errors (invalid path, CLI syntax) cause exit with code 1

### Confidence Calculation

Located in `src/rules/base.py:_calculate_confidence`:
- Base confidence: 0.7
- -0.2 if line contains `#` or `//` (likely commented)
- +0.2 if contains suspicious keywords (password, secret, eval, curl, etc.)
- Clamped to 0.0-1.0 range

### Extending Rules

To add a new rule:
1. Add rule config to `config/rules.yaml` with appropriate category
2. If custom logic needed, create new class inheriting `SecurityRule` in appropriate `src/rules/` file
3. Register rule class in `RulesFactory.RULE_CLASSES` mapping

## Testing Strategy

Test files in `tests/skills/` provide real Skill examples:
- `valid_skills/log-analyzer`: Safe Skill with minimal risks
- `malicious_skills/data-optimizer`: Contains intentional security issues for testing

Tests verify:
- Specific rule detection (NET002, FILE001, INJ003, DEP001)
- Risk score differentiation between safe/malicious Skills
- File scanning coverage and metadata extraction