@paulduvall/claude-dev-toolkit 0.0.1-alpha.2 → 0.0.1-alpha.21

package/hooks/prevent-credential-exposure.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Claude Code Hook: Prevent Credential Exposure
+# 
+# Purpose: Scan for exposed credentials before any file write/edit operations
+# Trigger: PreToolUse for Edit, Write, MultiEdit tools
+# Blocking: Yes - prevents credential exposure
+#
+# This hook implements enterprise-grade security by detecting and preventing
+# accidental credential exposure in AI-generated or AI-modified code.
+
+##################################
+# Configuration
+##################################
+HOOK_NAME="prevent-credential-exposure"
+LOG_FILE="$HOME/.claude/logs/security-hooks.log"
+VIOLATION_LOG="$HOME/.claude/logs/credential-violations.log"
+NOTIFICATION_WEBHOOK="${SECURITY_WEBHOOK_URL:-}"
+
+# Ensure log directory exists with secure permissions
+mkdir -p "$(dirname "$LOG_FILE")"
+chmod 700 "$(dirname "$LOG_FILE")"
+
+# Create log files with restrictive permissions if they don't exist
+touch "$LOG_FILE" "$VIOLATION_LOG"
+chmod 600 "$LOG_FILE" "$VIOLATION_LOG"
+
+##################################
+# Logging Functions
+##################################
+log() {
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] [$HOOK_NAME] $*" | tee -a "$LOG_FILE"
+}
+
+log_violation() {
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] VIOLATION: $*" | tee -a "$VIOLATION_LOG"
+}
+
+##################################
+# JSON Utilities
+##################################
+json_escape() {
+    local input="$1"
+    input="${input//\\/\\\\}"
+    input="${input//\"/\\\"}"
+    input="${input//$'\n'/\\n}"
+    input="${input//$'\r'/\\r}"
+    input="${input//$'\t'/\\t}"
+    printf '%s' "$input"
+}
+
+##################################
+# Notification Functions
+##################################
+notify_security_team() {
+    local violation_type="$1"
+    local file_path="$2"
+    local pattern="$3"
+
+    if [[ -n "$NOTIFICATION_WEBHOOK" ]]; then
+        local safe_type safe_path safe_pattern safe_user safe_ts
+        safe_type=$(json_escape "$violation_type")
+        safe_path=$(json_escape "$file_path")
+        safe_pattern=$(json_escape "$pattern")
+        safe_user=$(json_escape "$USER")
+        safe_ts=$(json_escape "$(date)")
+
+        curl -s -X POST "$NOTIFICATION_WEBHOOK" \
+            -H "Content-Type: application/json" \
+            -d "{
+                \"text\": \"SECURITY ALERT: Credential exposure prevented\",
+                \"attachments\": [{
+                    \"color\": \"danger\",
+                    \"fields\": [
+                        {\"title\": \"Violation Type\", \"value\": \"$safe_type\", \"short\": true},
+                        {\"title\": \"File\", \"value\": \"$safe_path\", \"short\": true},
+                        {\"title\": \"Pattern\", \"value\": \"$safe_pattern\", \"short\": false},
+                        {\"title\": \"User\", \"value\": \"$safe_user\", \"short\": true},
+                        {\"title\": \"Timestamp\", \"value\": \"$safe_ts\", \"short\": true}
+                    ]
+                }]
+            }" 2>/dev/null || log "Failed to send security notification"
+    fi
+}
+
+##################################
+# Credential Detection Patterns
+##################################
+# High-confidence patterns for common credential types
+declare -A CREDENTIAL_PATTERNS
+
+# API Keys
+CREDENTIAL_PATTERNS["anthropic_api_key"]='sk-ant-[a-zA-Z0-9]{95}'
+CREDENTIAL_PATTERNS["openai_api_key"]='sk-[a-zA-Z0-9]{32,}'
+CREDENTIAL_PATTERNS["github_token"]='gh[po]_[a-zA-Z0-9]{36}'
+CREDENTIAL_PATTERNS["aws_access_key"]='AKIA[0-9A-Z]{16}'
+CREDENTIAL_PATTERNS["azure_key"]='[a-zA-Z0-9/+]{86}=='
+
+# Database URLs with credentials
+CREDENTIAL_PATTERNS["database_url_with_password"]='(mysql|postgresql|mongodb)://[^:]+:[^@]+@'
+
+# Generic high-entropy patterns
+CREDENTIAL_PATTERNS["generic_api_key"]='["'"'"']?[a-zA-Z0-9_-]*[aA][pP][iI][_-]?[kK][eE][yY]["'"'"']?\s*[:=]\s*["'"'"'][a-zA-Z0-9+/=]{20,}["'"'"']'
+CREDENTIAL_PATTERNS["generic_secret"]='["'"'"']?[a-zA-Z0-9_-]*[sS][eE][cC][rR][eE][tT]["'"'"']?\s*[:=]\s*["'"'"'][a-zA-Z0-9+/=]{20,}["'"'"']'
+CREDENTIAL_PATTERNS["generic_password"]='["'"'"']?[a-zA-Z0-9_-]*[pP][aA][sS][sS][wW][oO][rR][dD]["'"'"']?\s*[:=]\s*["'"'"'][^"'"'"']{8,}["'"'"']'
+
+# JWT Tokens
+CREDENTIAL_PATTERNS["jwt_token"]='eyJ[a-zA-Z0-9+/=]{20,}\.[a-zA-Z0-9+/=]{20,}\.[a-zA-Z0-9+/=_-]{20,}'
+
+# Private Keys
+CREDENTIAL_PATTERNS["private_key"]='-----BEGIN [A-Z ]*PRIVATE KEY-----'
+CREDENTIAL_PATTERNS["ssh_private_key"]='-----BEGIN OPENSSH PRIVATE KEY-----'
+
+# Cloud Provider Specific
+CREDENTIAL_PATTERNS["gcp_service_account_key"]='"type":\s*"service_account"'
+CREDENTIAL_PATTERNS["slack_webhook"]='hooks\.slack\.com/services/[A-Z0-9]{9}/[A-Z0-9]{11}/[a-zA-Z0-9]{24}'
+
+##################################
+# Content Analysis Functions
+##################################
+scan_file_content() {
+    local file_path="$1"
+    local content="$2"
+    local violations=()
+    
+    # Skip if file doesn't exist or is binary
+    if [[ ! -f "$file_path" ]]; then
+        return 0
+    fi
+    
+    # Check if file is binary (avoid scanning binary files)
+    if file "$file_path" 2>/dev/null | grep -q "binary"; then
+        return 0
+    fi
+    
+    # Redirect log output to stderr so it doesn't pollute stdout
+    # (callers capture stdout via command substitution for the violation count)
+    log "Scanning file: $file_path" >&2
+
+    # Check each credential pattern
+    for pattern_name in "${!CREDENTIAL_PATTERNS[@]}"; do
+        local pattern="${CREDENTIAL_PATTERNS[$pattern_name]}"
+
+        if echo "$content" | grep -qiP -e "$pattern"; then
+            log_violation "$pattern_name detected in $file_path" >&2
+            violations+=("$pattern_name")
+
+            # Extract the matched content for logging (but redact it)
+            local matched_line
+            matched_line=$(echo "$content" | grep -iP -e "$pattern" | head -1)
+            local redacted_line
+            redacted_line=$(echo "$matched_line" | sed 's/[a-zA-Z0-9+/=]\{10,\}/[REDACTED]/g')
+
+            log_violation "Pattern: $pattern_name, Line: $redacted_line" >&2
+
+            # Notify security team
+            notify_security_team "$pattern_name" "$file_path" "$redacted_line"
+        fi
+    done
+
+    # Return violation count
+    echo "${#violations[@]}"
+}
+
+check_environment_leakage() {
+    local content="$1"
+    local violations=0
+    
+    # Check for environment variable exposure patterns
+    if echo "$content" | grep -qiP 'process\.env\.[A-Z_]*(?:KEY|SECRET|PASSWORD|TOKEN)'; then
+        log_violation "Environment variable credential exposure detected" >&2
+        ((violations++))
+    fi
+
+    # Check for hardcoded production URLs with credentials
+    if echo "$content" | grep -qiP 'https?://[^:]+:[^@]+@[^/]+'; then
+        log_violation "URL with embedded credentials detected" >&2
+        ((violations++))
+    fi
+    
+    echo "$violations"
+}
+
+##################################
+# Dependency Validation
+##################################
+validate_hook_dependencies() {
+    local deps=("grep" "file" "sed" "head")
+    local missing=()
+    
+    for dep in "${deps[@]}"; do
+        if ! command -v "$dep" &> /dev/null; then
+            missing+=("$dep")
+        fi
+    done
+    
+    if [[ ${#missing[@]} -gt 0 ]]; then
+        log "ERROR: Missing required dependencies: ${missing[*]}"
+        echo "Install missing tools and retry"
+        exit 1
+    fi
+}
+
+##################################
+# Main Hook Logic
+##################################
+main() {
+    # Validate dependencies first
+    validate_hook_dependencies
+    local tool_name="${CLAUDE_TOOL:-unknown}"
+    local file_path="${CLAUDE_FILE:-}"
+    local content=""
+    
+    log "Hook triggered for tool: $tool_name"
+    
+    # Only process file modification tools
+    case "$tool_name" in
+        "Edit"|"Write"|"MultiEdit")
+            ;;
+        *)
+            log "Skipping non-file tool: $tool_name"
+            exit 0
+            ;;
+    esac
+    
+    # Get file content to analyze
+    if [[ -n "$file_path" ]] && [[ -f "$file_path" ]]; then
+        content=$(cat "$file_path" 2>/dev/null || echo "")
+    elif [[ -n "$CLAUDE_CONTENT" ]]; then
+        content="$CLAUDE_CONTENT"
+        file_path="${file_path:-stdin}"
+    else
+        log "No content to analyze"
+        exit 0
+    fi
+    
+    # Perform security scans
+    local credential_violations
+    local env_violations
+    
+    credential_violations=$(scan_file_content "$file_path" "$content")
+    env_violations=$(check_environment_leakage "$content")
+    
+    local total_violations=$((credential_violations + env_violations))
+    
+    # Block if violations found
+    if [[ $total_violations -gt 0 ]]; then
+        echo "🚨 SECURITY VIOLATION: Credential exposure detected!"
+        echo "File: $file_path"
+        echo "Violations: $total_violations"
+        echo ""
+        echo "The operation has been BLOCKED to prevent credential exposure."
+        echo "Please review the file and remove any exposed credentials before proceeding."
+        echo ""
+        echo "Common fixes:"
+        echo "- Move credentials to environment variables"
+        echo "- Use a secrets management system"
+        echo "- Add files to .gitignore if they contain test data"
+        echo "- Use placeholder values in examples"
+        echo ""
+        log_violation "BLOCKED: $total_violations violations in $file_path"
+
+        exit 1
+    fi
+    
+    log "Security scan passed for $file_path"
+    exit 0
+}
+
+##################################
+# Error Handling
+##################################
+trap 'log "Hook failed with error on line $LINENO"' ERR
+
+##################################
+# Execute Main Function
+##################################
+main "$@"

package/hooks/security_bandit.py

@@ -0,0 +1,177 @@
+"""Python AST-based security checks inspired by Bandit.
+
+Detects common security anti-patterns without external dependencies:
+B101 (assert), B102 (exec/eval), B105/B106 (hardcoded passwords),
+B110 (try-except-pass), B301 (pickle), B602 (subprocess shell=True).
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+
+from smell_types import FIXES, Smell
+
+# ---------------------------------------------------------------------------
+# Individual check functions
+# ---------------------------------------------------------------------------
+
+_PASSWORD_NAMES = frozenset((
+    "password", "passwd", "pwd", "secret", "token", "api_key",
+))
+
+
+def _is_test_file(file_path: str) -> bool:
+    """Return True if file looks like a test file."""
+    base = os.path.basename(file_path)
+    return base.startswith("test_") or base.endswith("_test.py")
+
+
+def _check_assert(node: ast.Assert, file_path: str) -> Smell | None:
+    """B101: assert used outside test files."""
+    if _is_test_file(file_path):
+        return None
+    return Smell(
+        "B101", "assert", node.lineno,
+        "assert used in non-test code",
+        FIXES["B101"],
+    )
+
+
+def _check_exec_eval(node: ast.Call) -> Smell | None:
+    """B102: exec() or eval() call detected."""
+    func = node.func
+    if isinstance(func, ast.Name) and func.id in ("exec", "eval"):
+        return Smell(
+            "B102", func.id, node.lineno,
+            f"{func.id}() call detected",
+            FIXES["B102"],
+        )
+    return None
+
+
+def _check_hardcoded_password(node: ast.Assign) -> Smell | None:
+    """B105/B106: hardcoded string assigned to password-like variable."""
+    if not isinstance(node.value, ast.Constant):
+        return None
+    if not isinstance(node.value.value, str):
+        return None
+    if not node.value.value or len(node.value.value) < 2:
+        return None
+    for target in node.targets:
+        name = _extract_name(target)
+        if name and name.lower() in _PASSWORD_NAMES:
+            return Smell(
+                "B105", name, node.lineno,
+                f"hardcoded value assigned to '{name}'",
+                FIXES["B105"],
+            )
+    return None
+
+
+def _extract_name(node: ast.AST) -> str | None:
+    """Extract variable name from an assignment target."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _check_except_pass(node: ast.ExceptHandler) -> Smell | None:
+    """B110: except block that only contains pass."""
+    if len(node.body) == 1 and isinstance(node.body[0], ast.Pass):
+        return Smell(
+            "B110", "except-pass", node.lineno,
+            "except block silently passes",
+            FIXES["B110"],
+        )
+    return None
+
+
+def _check_pickle(node: ast.Call) -> Smell | None:
+    """B301: pickle.loads/load call detected."""
+    func = node.func
+    if not isinstance(func, ast.Attribute):
+        return None
+    if func.attr not in ("load", "loads"):
+        return None
+    if isinstance(func.value, ast.Name) and func.value.id == "pickle":
+        return Smell(
+            "B301", "pickle", node.lineno,
+            f"pickle.{func.attr}() used on potentially untrusted data",
+            FIXES["B301"],
+        )
+    return None
+
+
+def _check_subprocess_shell(node: ast.Call) -> Smell | None:
+    """B602: subprocess call with shell=True."""
+    func = node.func
+    if not isinstance(func, ast.Attribute):
+        return None
+    if func.attr not in ("call", "run", "Popen", "check_output"):
+        return None
+    if not (isinstance(func.value, ast.Name) and func.value.id == "subprocess"):
+        return None
+    for kw in node.keywords:
+        if kw.arg == "shell" and _is_true_constant(kw.value):
+            return Smell(
+                "B602", f"subprocess.{func.attr}", node.lineno,
+                "subprocess call with shell=True",
+                FIXES["B602"],
+            )
+    return None
+
+
+def _is_true_constant(node: ast.AST) -> bool:
+    """Return True if the node is the constant True."""
+    return isinstance(node, ast.Constant) and node.value is True
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def check_bandit(file_path: str, source: str) -> list[Smell]:
+    """Run AST-based security checks on Python source.
+
+    Args:
+        file_path: Path for context (test file detection).
+        source: Python source code string.
+
+    Returns:
+        List of detected security violations.
+    """
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return []
+    smells: list[Smell] = []
+    for node in ast.walk(tree):
+        smell = _dispatch_check(node, file_path)
+        if smell is not None:
+            smells.append(smell)
+    return smells
+
+
+def _dispatch_check(node: ast.AST, file_path: str) -> Smell | None:
+    """Route an AST node to the appropriate security check."""
+    if isinstance(node, ast.Assert):
+        return _check_assert(node, file_path)
+    if isinstance(node, ast.Call):
+        return _check_call(node)
+    if isinstance(node, ast.Assign):
+        return _check_hardcoded_password(node)
+    if isinstance(node, ast.ExceptHandler):
+        return _check_except_pass(node)
+    return None
+
+
+def _check_call(node: ast.Call) -> Smell | None:
+    """Run all Call-node security checks, return first match."""
+    for checker in (_check_exec_eval, _check_pickle, _check_subprocess_shell):
+        result = checker(node)
+        if result is not None:
+            return result
+    return None

package/hooks/security_checks.py

@@ -0,0 +1,97 @@
+"""Security check orchestrator -- runs secrets, bandit, and trojan checks.
+
+Reads a source file, runs applicable security checks, and returns
+Smell objects for any violations. Respects per-project config.
+"""
+
+from __future__ import annotations
+
+import os
+
+from config import Config, load_config, is_file_suppressed
+from security_bandit import check_bandit
+from security_secrets import check_secrets
+from security_trojan import check_trojan
+from smell_types import Smell
+from suppression import filter_suppressed
+
+PYTHON_EXTS = frozenset((".py",))
+ALL_EXTS = frozenset((
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".java", ".go",
+    ".rs", ".c", ".cpp", ".cs", ".rb", ".sh", ".yaml", ".yml",
+    ".json", ".toml", ".env", ".cfg", ".ini", ".conf",
+))
+SKIP_DIRS = frozenset((
+    "node_modules", "__pycache__", ".git", "dist", "build", ".next",
+))
+
+
+def _should_skip(file_path: str) -> bool:
+    """Return True for paths in ignored directories."""
+    parts = set(file_path.replace("\\", "/").split("/"))
+    return bool(SKIP_DIRS & parts)
+
+
+def _read_source(file_path: str) -> str | None:
+    """Read file contents, returning None on failure."""
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
+def _run_checks(file_path: str, source: str, config: Config) -> list[Smell]:
+    """Run applicable security checks on file contents."""
+    lines = source.splitlines()
+    smells = _collect_violations(file_path, source, lines, config)
+    return filter_suppressed(smells, lines, "security")
+
+
+def _collect_violations(
+    file_path: str, source: str, lines: list[str], config: Config,
+) -> list[Smell]:
+    """Gather raw violations before suppression filtering."""
+    smells: list[Smell] = []
+    if config.security_enabled:
+        smells.extend(check_secrets(lines))
+    ext = os.path.splitext(file_path)[1]
+    if ext in PYTHON_EXTS and config.security_enabled:
+        smells.extend(check_bandit(file_path, source))
+    if config.trojan_enabled:
+        smells.extend(check_trojan(lines))
+    return smells
+
+
+def _is_excluded(file_path: str, ext: str, config: Config) -> bool:
+    """Return True if file should be excluded from security checks."""
+    if ext not in ALL_EXTS or _should_skip(file_path):
+        return True
+    return is_file_suppressed(file_path, config)
+
+
+def check_security(file_path: str, config: Config | None = None) -> list[Smell]:
+    """Run all security checks on a single file."""
+    if config is None:
+        config = load_config(file_path)
+    ext = os.path.splitext(file_path)[1]
+    if _is_excluded(file_path, ext, config):
+        return []
+    source = _read_source(file_path)
+    if source is None:
+        return []
+    return _run_checks(file_path, source, config)
+
+
+def format_security_violations(file_path: str, smells: list[Smell]) -> str:
+    """Build the feedback message for security violations."""
+    header = f"\nSECURITY VIOLATIONS in {file_path}:"
+    details = []
+    for s in smells:
+        tag = s.kind.upper().replace("_", " ")
+        details.append(f"  [{tag}] {s.name} line {s.line}: {s.detail}")
+    fixes = ["\nFix these security issues before moving on:"]
+    for fix in dict.fromkeys(s.fix for s in smells):
+        fixes.append(f"  - {fix}")
+    fixes.append("Then notify the user what you fixed and why.")
+    return "\n".join([header, *details, *fixes])

package/hooks/security_secrets.py

@@ -0,0 +1,81 @@
+"""Hardcoded secrets detection via regex patterns.
+
+Scans source lines for common secret patterns: API keys, tokens,
+private key headers, and credential URLs. Skips known false positives.
+"""
+
+from __future__ import annotations
+
+import re
+
+from smell_types import FIXES, Smell
+
+# ---------------------------------------------------------------------------
+# Secret patterns -- each is (compiled_regex, description)
+# ---------------------------------------------------------------------------
+
+_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"AKIA[0-9A-Z]{16}"), "AWS access key"),
+    (re.compile(r"ghp_[0-9a-zA-Z]{36}"), "GitHub personal access token"),
+    (re.compile(r"gho_[0-9a-zA-Z]{36}"), "GitHub OAuth token"),
+    (re.compile(r"xoxb-[0-9]{10,13}-[0-9a-zA-Z-]+"), "Slack bot token"),
+    (re.compile(r"xoxp-[0-9]{10,13}-[0-9a-zA-Z-]+"), "Slack user token"),
+    (re.compile(r"sk_live_[0-9a-zA-Z]{24,}"), "Stripe secret key"),
+    (re.compile(r"rk_live_[0-9a-zA-Z]{24,}"), "Stripe restricted key"),
+    (re.compile(r"AIza[0-9A-Za-z_-]{35}"), "Google API key"),
+    (re.compile(r"sk-[0-9a-zA-Z]{20,}T3BlbkFJ[0-9a-zA-Z]+"), "OpenAI API key"),
+    (re.compile(r"-----BEGIN\s+(RSA |EC |DSA )?PRIVATE KEY-----"), "private key"),
+    (re.compile(r"[a-zA-Z+]+://[^:]+:[^@]+@[^\s]+"), "credentials in URL"),
+]
+
+# ---------------------------------------------------------------------------
+# False-positive skip heuristics
+# ---------------------------------------------------------------------------
+
+_FP_WORDS = re.compile(
+    r"(example|fake|test|dummy|placeholder|xxxx|TODO|CHANGEME)",
+    re.IGNORECASE,
+)
+
+
+def _is_false_positive(line: str) -> bool:
+    """Return True if the line looks like a placeholder or example."""
+    stripped = line.strip()
+    if stripped.startswith(("#", "//", "/*", "*")):
+        return True
+    return bool(_FP_WORDS.search(stripped))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def _match_line(line: str, lineno: int) -> Smell | None:
+    """Check a single line against all secret patterns."""
+    if _is_false_positive(line):
+        return None
+    for pattern, desc in _PATTERNS:
+        if pattern.search(line):
+            return Smell(
+                "secrets", desc, lineno,
+                f"possible {desc} detected",
+                FIXES["secrets"],
+            )
+    return None
+
+
+def check_secrets(lines: list[str]) -> list[Smell]:
+    """Scan lines for hardcoded secret patterns.
+
+    Args:
+        lines: Source file lines to scan.
+
+    Returns:
+        List of Smell objects for detected secrets.
+    """
+    smells: list[Smell] = []
+    for lineno, line in enumerate(lines, start=1):
+        smell = _match_line(line, lineno)
+        if smell is not None:
+            smells.append(smell)
+    return smells

package/hooks/security_trojan.py

@@ -0,0 +1,61 @@
+"""Unicode trojan source detection.
+
+Detects bidirectional override characters and zero-width characters
+that can be used to disguise malicious code. BOM at file start is allowed.
+"""
+
+from __future__ import annotations
+
+import re
+
+from smell_types import FIXES, Smell
+
+# Bidi overrides: U+202A-U+202E
+_BIDI_OVERRIDES = re.compile(r"[\u202A-\u202E]")
+# Bidi isolates: U+2066-U+2069
+_BIDI_ISOLATES = re.compile(r"[\u2066-\u2069]")
+# Zero-width chars: U+200B-U+200F, U+FEFF (BOM)
+_ZERO_WIDTH = re.compile(r"[\u200B-\u200F\uFEFF]")
+
+
+def _check_bidi(line: str, lineno: int) -> Smell | None:
+    """Check a single line for bidi override/isolate characters."""
+    if _BIDI_OVERRIDES.search(line) or _BIDI_ISOLATES.search(line):
+        return Smell(
+            "trojan_bidi", "bidi-override", lineno,
+            "Unicode bidi override character detected",
+            FIXES["trojan_bidi"],
+        )
+    return None
+
+
+def _check_zero_width(line: str, lineno: int) -> Smell | None:
+    """Check a single line for zero-width characters."""
+    match = _ZERO_WIDTH.search(line)
+    if not match:
+        return None
+    if lineno == 1 and match.start() == 0 and match.group() == "\uFEFF":
+        return None
+    return Smell(
+        "trojan_zero_width", "zero-width-char", lineno,
+        "zero-width Unicode character detected",
+        FIXES["trojan_zero_width"],
+    )
+
+
+def check_trojan(lines: list[str]) -> list[Smell]:
+    """Scan lines for trojan source Unicode characters.
+
+    Args:
+        lines: Source file lines to scan.
+
+    Returns:
+        List of Smell objects for detected trojan characters.
+    """
+    smells: list[Smell] = []
+    for lineno, line in enumerate(lines, start=1):
+        for checker in (_check_bidi, _check_zero_width):
+            result = checker(line, lineno)
+            if result is not None:
+                smells.append(result)
+    return smells