python-skills 1.0.0__py3-none-any.whl

skills/security/input_validation.md

@@ -0,0 +1,190 @@
+---
+name: security_input_validation
+purpose: Validate all external input at system boundaries
+category: security
+triggers:
+  - validation
+  - input
+  - pydantic
+  - boundary
+  - sanitize
+  - allowlist
+dependencies:
+  - security/sql_injection.md
+  - security/command_injection.md
+  - security/path_traversal.md
+  - security/unsafe_deserialization.md
+  - generation/error_handling.md
+priority: supporting
+estimated_tokens: 1700
+---
+# Security: Input Validation
+
+**Purpose**: Validate all external input at system boundaries.
+
+**When to use**: All code handling user input, API requests, file uploads, config.
+
+---
+
+## Core Rules
+
+### Validate at Boundaries
+```python
+# API boundary
+@app.post("/users")
+def create_user(request: CreateUserRequest) -> UserResponse:
+    # Request validated by Pydantic/FastAPI automatically
+    return user_service.create(request)
+
+# CLI boundary
+def main(args: list[str]) -> int:
+    parsed = parse_args(args)  # argparse validates
+    config = load_config(parsed.config_file)  # Validates file
+    ...
+
+# Config boundary
+def load_config(path: Path) -> Config:
+    raw = tomllib.load(path)
+    return Config.model_validate(raw)  # Pydantic validates
+```
+
+### Validation Libraries
+| Use Case | Library |
+|----------|---------|
+| API/Config/Data | `pydantic` (v2) |
+| Simple CLI | `argparse` + custom types |
+| JSON Schema | `jsonschema` |
+| Form data | `wtforms` |
+
+### Pydantic Patterns
+```python
+from pydantic import BaseModel, Field, field_validator, EmailStr
+from typing import Annotated
+
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    name: Annotated[str, Field(min_length=2, max_length=100)]
+    age: Annotated[int, Field(ge=13, le=120)]
+    tags: list[str] = Field(default_factory=list)
+    
+    @field_validator("name")
+    @classmethod
+    def name_no_special_chars(cls, v: str) -> str:
+        if not v.replace(" ", "").isalnum():
+            raise ValueError("Name must be alphanumeric")
+        return v.strip()
+
+# Usage
+def create_user(data: CreateUserRequest) -> User:
+    # data is guaranteed valid here
+    ...
+```
+
+### Allowlist Over Blocklist
+```python
+# GOOD — allowlist
+ALLOWED_EXTENSIONS = {".jpg", ".png", ".pdf"}
+def validate_extension(filename: str) -> None:
+    ext = Path(filename).suffix.lower()
+    if ext not in ALLOWED_EXTENSIONS:
+        raise ValidationError("file", f"Extension not allowed: {ext}")
+
+# BAD — blocklist (incomplete)
+def validate_extension(filename: str) -> None:
+    if filename.endswith(".exe"):
+        raise ValidationError("file", "Executable not allowed")
+    # Misses .bat, .sh, .php, .jar, etc.
+```
+
+### Size Limits
+```python
+# Request body
+app = FastAPI()
+app.add_middleware(MaxBodySizeMiddleware, max_size=10_000_000)  # 10MB
+
+# File upload
+def upload(file: UploadFile) -> None:
+    if file.size > MAX_FILE_SIZE:
+        raise ValidationError("file", "File too large")
+    
+    # Stream, don't load entirely
+    while chunk := file.read(8192):
+        process(chunk)
+```
+
+### Sanitization
+```python
+# HTML output
+from markupsafe import escape
+safe_html = escape(user_input)
+
+# SQL — use parameterized queries (see sql_injection.md)
+# Path — use pathlib.resolve() + is_relative_to() (see path_traversal.md)
+# Shell — never use shell=True (see command_injection.md)
+```
+
+---
+
+## Decision Rules
+
+| Input Type | Validation |
+|------------|------------|
+| API request | Pydantic model |
+| Config file | Pydantic model |
+| CLI args | argparse + custom types |
+| File upload | Size + type + content validation |
+| Database input | ORM/parameterized queries |
+| User content (display) | Escape on output |
+
+---
+
+## Preferred Patterns
+
+```python
+# Centralized validation
+class ValidationError(Exception):
+    def __init__(self, field: str, message: str):
+        self.field = field
+        self.message = message
+        super().__init__(f"{field}: {message}")
+
+def validate_and_load[T](
+    model: type[BaseModel],
+    data: dict,
+    context: dict | None = None,
+) -> T:
+    try:
+        return model.model_validate(data, context=context)
+    except ValidationError as e:
+        # Convert to domain exceptions
+        errors = e.errors()
+        raise ValidationError(errors[0]["loc"][0], errors[0]["msg"]) from e
+```
+
+---
+
+## Avoid
+
+- Trusting any external input
+- Validation only in UI (client-side only)
+- Blocklist-based validation
+- No size limits on uploads/requests
+- Manual string parsing for structured data
+
+---
+
+## Validation Considerations
+
+- Test with malicious inputs (injection, oversized, malformed)
+- Fuzz testing for parsers
+- Validate error messages don't leak info
+
+---
+
+## Related Skills
+
+- `security/sql_injection.md`
+- `security/command_injection.md`
+- `security/path_traversal.md`
+- `security/unsafe_deserialization.md`
+- `generation/error_handling.md`

skills/security/path_traversal.md

@@ -0,0 +1,172 @@
+# Security: Path Traversal Prevention
+
+**Purpose**: Prevent directory traversal attacks when handling file paths.
+
+**When to use**: File uploads, path parameters, file serving, archive extraction.
+
+---
+
+## Core Rules
+
+### Always Resolve and Validate
+```python
+from pathlib import Path
+
+def safe_path(user_input: str, base_dir: Path) -> Path:
+    """Resolve path and ensure it's within base directory."""
+    base = base_dir.resolve()
+    requested = (base / user_input).resolve()
+    
+    # Critical: check AFTER resolve (handles symlinks)
+    if not requested.is_relative_to(base):
+        raise ValueError(f"Path traversal attempt: {user_input}")
+    
+    return requested
+
+# Usage
+@app.get("/files/{path:path}")
+def serve_file(path: str):
+    safe = safe_path(path, FILES_ROOT)
+    return FileResponse(safe)
+```
+
+### Common Attack Vectors
+```python
+# These all attempt to escape:
+"../../etc/passwd"
+"..\\..\\windows\\system32"
+"%2e%2e%2f"  # URL encoded
+"....//"     # Double dots
+"subdir/../../etc/passwd"
+"symlink_to_root/target"
+```
+
+### Archive Extraction (Critical)
+```python
+import tarfile
+import zipfile
+
+def safe_extract_tar(tar_path: Path, dest: Path) -> None:
+    dest = dest.resolve()
+    with tarfile.open(tar_path) as tar:
+        for member in tar.getmembers():
+            member_path = (dest / member.name).resolve()
+            if not member_path.is_relative_to(dest):
+                raise ValueError(f"Path traversal in archive: {member.name}")
+        tar.extractall(dest)  # Safe after validation
+
+def safe_extract_zip(zip_path: Path, dest: Path) -> None:
+    dest = dest.resolve()
+    with zipfile.ZipFile(zip_path) as zf:
+        for name in zf.namelist():
+            member_path = (dest / name).resolve()
+            if not member_path.is_relative_to(dest):
+                raise ValueError(f"Path traversal in archive: {name}")
+        zf.extractall(dest)
+```
+
+### File Upload
+```python
+def save_upload(file: UploadFile, upload_dir: Path) -> Path:
+    # Validate filename
+    filename = Path(file.filename).name  # Strip directory components
+    if not filename:
+        raise ValueError("Invalid filename")
+    
+    # Allowlist extension
+    allowed = {".jpg", ".png", ".pdf", ".txt"}
+    if filename.suffix.lower() not in allowed:
+        raise ValueError("File type not allowed")
+    
+    # Generate safe name (UUID + extension)
+    safe_name = f"{uuid4()}{filename.suffix.lower()}"
+    dest = safe_path(safe_name, upload_dir)
+    
+    # Stream write (memory efficient)
+    with dest.open("wb") as f:
+        while chunk := file.file.read(8192):
+            f.write(chunk)
+    
+    return dest
+```
+
+### Symlink Safety
+```python
+def read_file_safe(path: Path, base: Path) -> bytes:
+    """Read file, following symlinks but validating final target."""
+    resolved = path.resolve()
+    base_resolved = base.resolve()
+    
+    if not resolved.is_relative_to(base_resolved):
+        raise ValueError("Path traversal via symlink")
+    
+    # Optional: reject symlinks entirely
+    if path.is_symlink():
+        raise ValueError("Symlinks not allowed")
+    
+    return resolved.read_bytes()
+```
+
+---
+
+## Decision Rules
+
+| Operation | Protection |
+|-----------|------------|
+| Serve static file | `safe_path` + `is_relative_to` |
+| User upload | Strip path, allowlist ext, UUID name |
+| Archive extract | Validate each member before extract |
+| Config file read | Fixed known paths only |
+| Temp file | `tempfile.mkstemp` (secure) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Centralized path validator
+class PathValidator:
+    def __init__(self, base: Path):
+        self.base = base.resolve()
+    
+    def validate(self, user_path: str | Path) -> Path:
+        requested = (self.base / user_path).resolve()
+        if not requested.is_relative_to(self.base):
+            raise SecurityError("Path traversal attempt")
+        return requested
+    
+    def validate_exists(self, user_path: str | Path) -> Path:
+        path = self.validate(user_path)
+        if not path.exists():
+            raise FileNotFoundError(path)
+        return path
+```
+
+---
+
+## Avoid
+
+- `os.path.join` without validation
+- `Path(user_input)` directly
+- `../` in user-controlled paths
+- Extracting archives without member validation
+- Serving files from user input without validation
+
+---
+
+## Validation Considerations
+
+- Test with traversal payloads
+- Test with symlinks
+- Test with URL encoding
+- Test with null bytes (`\0`)
+- `bandit` B108, B306 checks
+
+---
+
+## Related Skills
+
+- `security/command_injection.md`
+- `security/input_validation.md`
+- `stdlib/pathlib.md`
+- `stdlib/subprocess.md`

skills/security/secrets.md

@@ -0,0 +1,171 @@
+# Security: Secrets Management
+
+**Purpose**: Handle secrets (API keys, passwords, tokens) securely.
+
+**When to use**: Any code dealing with credentials or sensitive data.
+
+---
+
+## Core Rules
+
+### Never Hardcode Secrets
+```python
+# NEVER
+API_KEY = "sk_live_abc123"
+DB_PASSWORD = "supersecret"
+
+# NEVER in config files committed to git
+# config.yaml
+# database:
+#   password: "supersecret"
+```
+
+### Environment Variables
+```python
+import os
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    database_url: str
+    api_key: str
+    jwt_secret: str
+    
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+settings = Settings()  # Loads from env vars + .env
+```
+
+### .env File Pattern
+```bash
+# .env.example (COMMITTED)
+DATABASE_URL=postgresql://user:pass@localhost/db
+API_KEY=
+JWT_SECRET=
+
+# .env (GITIGNORED - local only)
+DATABASE_URL=postgresql://prod:realpass@db/prod
+API_KEY=sk_live_realkey
+JWT_SECRET=supersecretkey
+```
+
+### Secret Managers (Production)
+```python
+# AWS Secrets Manager
+import boto3
+
+def get_secret(name: str) -> str:
+    client = boto3.client("secretsmanager")
+    response = client.get_secret_value(SecretId=name)
+    return response["SecretString"]
+
+# HashiCorp Vault
+import hvac
+
+client = hvac.Client(url="https://vault.example.com")
+secret = client.secrets.kv.v2.read_secret_version(path="app/config")
+```
+
+### In Memory Only
+```python
+# Don't log secrets
+logger.info("Connecting to database", extra={"url": sanitize_url(db_url)})
+
+def sanitize_url(url: str) -> str:
+    # postgresql://user:pass@host/db -> postgresql://user:***@host/db
+    from urllib.parse import urlparse, urlunparse
+    parsed = urlparse(url)
+    if parsed.password:
+        netloc = f"{parsed.username}:***@{parsed.hostname}"
+        if parsed.port:
+            netloc += f":{parsed.port}"
+        return urlunparse(parsed._replace(netloc=netloc))
+    return url
+```
+
+### Key Rotation
+```python
+# Support multiple keys for rotation
+class Settings(BaseSettings):
+    jwt_secrets: list[str] = Field(default_factory=list)  # Current + previous
+    current_jwt_secret_index: int = 0
+    
+    @property
+    def jwt_secret(self) -> str:
+        return self.jwt_secrets[self.current_jwt_secret_index]
+    
+    def verify_token(self, token: str) -> dict:
+        # Try all secrets for backward compatibility
+        for secret in self.jwt_secrets:
+            try:
+                return jwt.decode(token, secret, algorithms=["HS256"])
+            except jwt.InvalidTokenError:
+                continue
+        raise InvalidTokenError()
+```
+
+---
+
+## Decision Rules
+
+| Environment | Approach |
+|-------------|----------|
+| Local dev | `.env` file (gitignored) |
+| CI/CD | Platform secrets (GitHub Actions, GitLab CI) |
+| Kubernetes | Secrets + External Secrets Operator |
+| Cloud | AWS Secrets Manager, GCP Secret Manager, Azure Key Vault |
+| Serverless | Platform env vars + secret manager |
+
+---
+
+## Preferred Patterns
+
+```python
+# Single settings instance
+_settings: Settings | None = None
+
+def get_settings() -> Settings:
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+
+# Dependency injection for testing
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or get_settings()
+    app = FastAPI()
+    app.state.settings = settings
+    return app
+```
+
+---
+
+## Avoid
+
+- Committing `.env` with real secrets
+- Printing/logging secrets
+- Passing secrets in URLs (query params, paths)
+- Storing secrets in code (even encoded)
+- Single key without rotation plan
+- Secrets in Docker images
+
+---
+
+## Validation Considerations
+
+- `git-secrets` / `truffleHog` / `gitleaks` in CI
+- No secrets in logs (test with log capture)
+- Secret rotation tested
+- Least privilege for secret access
+
+---
+
+## Related Skills
+
+- `security/input_validation.md`
+- `engineering/configuration.md`
+- `engineering/logging.md`
+- `engineering/virtual_environments.md`

skills/security/sql_injection.md

@@ -0,0 +1,188 @@
+# Security: SQL Injection Prevention
+
+**Purpose**: Prevent SQL injection through proper query parameterization.
+
+**When to use**: All database interactions.
+
+---
+
+## Core Rules
+
+### Always Use Parameterized Queries
+```python
+# CORRECT — asyncpg
+async with pool.acquire() as conn:
+    await conn.execute(
+        "INSERT INTO users (email, name) VALUES ($1, $2)",
+        email, name
+    )
+
+# CORRECT — psycopg
+with conn.cursor() as cur:
+    cur.execute(
+        "INSERT INTO users (email, name) VALUES (%s, %s)",
+        (email, name)
+    )
+
+# CORRECT — SQLAlchemy
+session.execute(
+    text("SELECT * FROM users WHERE email = :email"),
+    {"email": email}
+)
+
+# CORRECT — ORM
+User.query.filter_by(email=email).first()
+```
+
+### Never Use String Interpolation
+```python
+# WRONG — SQL INJECTION!
+cursor.execute(f"SELECT * FROM users WHERE email = '{email}'")
+cursor.execute("SELECT * FROM users WHERE email = '" + email + "'")
+cursor.execute("SELECT * FROM users WHERE id = " + str(user_id))
+
+# WRONG — .format()
+cursor.execute("SELECT * FROM users WHERE email = '{}'".format(email))
+```
+
+### Dynamic Queries (Safe Patterns)
+```python
+# WHERE IN with variable length
+ids = [1, 2, 3]
+placeholders = ", ".join(["%s"] * len(ids))
+query = f"SELECT * FROM users WHERE id IN ({placeholders})"
+cursor.execute(query, ids)  # Parameters still parameterized!
+
+# Optional filters
+conditions = []
+params = []
+if name:
+    conditions.append("name ILIKE %s")
+    params.append(f"%{name}%")
+if email:
+    conditions.append("email = %s")
+    params.append(email)
+
+query = "SELECT * FROM users"
+if conditions:
+    query += " WHERE " + " AND ".join(conditions)
+cursor.execute(query, params)
+```
+
+### ORM Safety
+```python
+# SQLAlchemy — safe
+User.query.filter(User.email == email).all()
+session.query(User).filter_by(email=email).first()
+
+# Django — safe
+User.objects.filter(email=email)
+
+# Unsafe in ORM — raw()
+User.objects.raw("SELECT * FROM users WHERE email = '%s'" % email)  # BAD!
+User.objects.raw("SELECT * FROM users WHERE email = %s", [email])   # GOOD
+```
+
+### Identifier Quoting (Table/Column Names)
+```python
+# Can't parameterize identifiers — validate against allowlist
+ALLOWED_TABLES = {"users", "orders", "products"}
+ALLOWED_COLUMNS = {"id", "email", "name", "created_at"}
+
+def query_table(table: str, column: str, value: str):
+    if table not in ALLOWED_TABLES:
+        raise ValueError("Invalid table")
+    if column not in ALLOWED_COLUMNS:
+        raise ValueError("Invalid column")
+    
+    # Safe: validated identifiers
+    query = f"SELECT * FROM {table} WHERE {column} = %s"
+    cursor.execute(query, (value,))
+```
+
+---
+
+## Decision Rules
+
+| Query Type | Safe Pattern |
+|------------|--------------|
+| Static query | Parameterized |
+| Dynamic WHERE | Build conditions, parameterize values |
+| IN clause | Generate placeholders, parameterize values |
+| Table/column names | Allowlist validation |
+| Complex reporting | Views / stored procedures / CTEs |
+
+---
+
+## Preferred Patterns
+
+```python
+# Repository pattern encapsulates safety
+class UserRepository:
+    def __init__(self, pool: asyncpg.Pool):
+        self.pool = pool
+    
+    async def find_by_email(self, email: str) -> User | None:
+        async with self.pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT * FROM users WHERE email = $1",
+                email
+            )
+            return User(**row) if row else None
+    
+    async def search(
+        self,
+        name: str | None = None,
+        email: str | None = None,
+        limit: int = 100,
+    ) -> list[User]:
+        conditions = []
+        params = []
+        param_num = 1
+        
+        if name:
+            conditions.append(f"name ILIKE ${param_num}")
+            params.append(f"%{name}%")
+            param_num += 1
+        if email:
+            conditions.append(f"email = ${param_num}")
+            params.append(email)
+            param_num += 1
+        
+        query = "SELECT * FROM users"
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+        query += f" LIMIT ${param_num}"
+        params.append(limit)
+        
+        async with self.pool.acquire() as conn:
+            rows = await conn.fetch(query, *params)
+            return [User(**row) for row in rows]
+```
+
+---
+
+## Avoid
+
+- Any string concatenation in SQL
+- `f-strings` in SQL
+- `.format()` in SQL
+- `%` formatting in SQL (except parameterized drivers)
+- Dynamic ORDER BY without validation
+
+---
+
+## Validation Considerations
+
+- Code review: grep for `f"SELECT` `f"INSERT` `f"UPDATE` `f"DELETE`
+- `bandit` SQL injection checks
+- SQLMap testing
+- ORM raw query audit
+
+---
+
+## Related Skills
+
+- `security/input_validation.md`
+- `engineering/database.md`
+- `generation/error_handling.md`