skillpool 4.3.0__py3-none-any.whl

skillpool/hooks/security_scanner.py

@@ -0,0 +1,288 @@
+"""Hook-layer security checks for SkillPool skill materialization.
+
+Runs before any skill is materialized to ensure safety:
+1. YAML syntax safety — no unsafe tags or constructors
+2. Dangerous pattern scanning — exec/os.system/eval/subprocess
+3. Signature verification — sigstore placeholder (production needs cosign)
+
+Part of SkillPool — independent infrastructure, shared by all agents.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class ThreatLevel(Enum):
+    """Threat severity classification."""
+
+    SAFE = "safe"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+@dataclass
+class SecurityCheckResult:
+    """Result of a security check on skill content."""
+
+    threat_level: ThreatLevel
+    checks_passed: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    blockers: list[str] = field(default_factory=list)
+
+    @property
+    def is_safe(self) -> bool:
+        return self.threat_level != ThreatLevel.CRITICAL
+
+
+# Dangerous patterns to detect in skill content (NOT executed — regex strings for scanning only)
+# These patterns are used to flag unsafe code in skill YAML/MD content before materialization.
+_DANGEROUS_PATTERNS: list[tuple[str, str]] = [
+    (r"\bexec\s*\(", "exec() call — arbitrary code execution"),  # NOSONAR: regex for detection, not a call
+    (r"\beval\s*\(", "eval() call — arbitrary code execution"),  # NOSONAR: regex for detection, not a call
+    (r"\bos\.system\s*\(", "os.system() call — shell injection risk"),  # NOSONAR: regex for detection, not a call
+    (r"\bos\.popen\s*\(", "os.popen() call — shell injection risk"),  # NOSONAR: regex for detection, not a call
+    (r"\bsubprocess\.\w+\s*\(", "subprocess call — external process execution"),
+    (r"\b__import__\s*\(", "__import__() call — dynamic import risk"),
+    (r"\bcompile\s*\(", "compile() call — dynamic code compilation"),
+    (r"\bopen\s*\(.*['\"]w", "file write — potential data modification"),
+    (r"\bshutil\.rmtree\s*\(", "shutil.rmtree() — directory deletion"),
+    (r"\bos\.remove\s*\(", "os.remove() — file deletion"),
+    (r"\bos\.unlink\s*\(", "os.unlink() — file deletion"),
+]
+
+# Safe contexts that should be excluded from dangerous matches
+_SAFE_CONTEXTS = [
+    r"#\s*",  # commented out code
+    r'"""',  # inside docstring
+    r"'''",  # inside docstring
+    r"re\.compile",  # re.compile() is safe (not builtins.compile)
+]
+
+
+def _extract_code_blocks(content: str) -> str:
+    """Extract code blocks from Markdown content for scanning.
+
+    Handles:
+    - Triple-backtick fences (```...```)
+    - Tilde fences (~~~...~~~)
+    - Unclosed code blocks (fallback: scan entire content)
+    - CRLF line endings
+    - Multiple consecutive code blocks
+    """
+    # Normalize CRLF to LF
+    normalized = content.replace("\r\n", "\n")
+
+    # Line-by-line parser: correctly handles multiple blocks
+    blocks: list[str] = []
+    in_block = False
+    fence_char: str | None = None
+    fence_len = 0
+    current_lines: list[str] = []
+
+    for line in normalized.split("\n"):
+        stripped = line.strip()
+        is_fence = False
+        detected_char: str | None = None
+        detected_len = 0
+
+        if stripped.startswith("```"):
+            detected_char = "`"
+            for ch in stripped:
+                if ch == "`":
+                    detected_len += 1
+                else:
+                    break
+            is_fence = detected_len >= 3
+        elif stripped.startswith("~~~"):
+            detected_char = "~"
+            for ch in stripped:
+                if ch == "~":
+                    detected_len += 1
+                else:
+                    break
+            is_fence = detected_len >= 3
+
+        if is_fence:
+            if not in_block:
+                # Opening fence
+                in_block = True
+                fence_char = detected_char
+                fence_len = detected_len
+                current_lines = []
+            elif detected_char == fence_char and detected_len >= fence_len:
+                # Closing fence matching opening
+                blocks.append("\n".join(current_lines))
+                in_block = False
+                current_lines = []
+            else:
+                # Different fence inside a block — treat as content
+                current_lines.append(line)
+        elif in_block:
+            current_lines.append(line)
+
+    # Handle unclosed fence
+    if in_block and current_lines:
+        blocks.append("\n".join(current_lines))
+
+    # If no fenced blocks found, try inline code
+    if not blocks:
+        inline_blocks = re.findall(r"`([^`]+)`", normalized)
+        if inline_blocks:
+            return "\n".join(inline_blocks)
+        # No code blocks at all — scan the entire content
+        return normalized
+
+    return "\n".join(blocks)
+
+
+class SecurityScanner:
+    """Scans skill content for security threats before materialization.
+
+    Part of SkillPool — independent infrastructure, shared by all agents.
+    """
+
+    def __init__(
+        self,
+        custom_patterns: list[tuple[str, str]] | None = None,
+        evidence_tier: str | None = None,
+    ):
+        self._patterns = _DANGEROUS_PATTERNS.copy()
+        if custom_patterns:
+            self._patterns.extend(custom_patterns)
+        self._evidence_tier = evidence_tier
+
+    def check_yaml_safety(self, content: str) -> SecurityCheckResult:
+        """Check YAML content for unsafe constructs.
+
+        Blocks:
+        - YAML tags that invoke Python constructors (!!python/object, etc.)
+        - Custom YAML constructors that aren't in the safe list
+        """
+        result = SecurityCheckResult(threat_level=ThreatLevel.SAFE)
+        result.checks_passed.append("yaml_syntax")
+
+        # Check for dangerous YAML tags
+        dangerous_tags = [
+            "!!python/object",
+            "!!python/object/apply",
+            "!!python/object/new",
+            "!!python/module",
+            "!!python/name",
+            "!!python/object/subclass",
+        ]
+        for tag in dangerous_tags:
+            if tag in content:
+                result.blockers.append(f"Dangerous YAML tag: {tag}")
+                result.threat_level = ThreatLevel.CRITICAL
+
+        return result
+
+    def scan_dangerous_patterns(self, content: str) -> SecurityCheckResult:
+        """Scan for dangerous code patterns in skill content.
+
+        Scans code blocks and inline code for patterns that could indicate
+        security risks. Uses _extract_code_blocks for robust code block
+        extraction (handles unclosed fences, tildes, CRLF).
+        Applies _SAFE_CONTEXTS to exclude commented-out code and
+        re.compile() calls.
+        """
+        result = SecurityCheckResult(threat_level=ThreatLevel.SAFE)
+        result.checks_passed.append("pattern_scan")
+
+        # Extract code blocks for scanning
+        scan_text = _extract_code_blocks(content)
+
+        for pattern, description in self._patterns:
+            matches = list(re.finditer(pattern, scan_text))
+            for match in matches:
+                # Get the line containing the match
+                line_start = scan_text.rfind("\n", 0, match.start()) + 1
+                line_end = scan_text.find("\n", match.end())
+                if line_end == -1:
+                    line_end = len(scan_text)
+                line = scan_text[line_start:line_end].strip()
+
+                # Skip if in a safe context (commented out, re.compile, etc.)
+                is_safe_context = False
+                for safe_pattern in _SAFE_CONTEXTS:
+                    if re.search(safe_pattern, line):
+                        is_safe_context = True
+                        break
+                if is_safe_context:
+                    continue
+
+                result.warnings.append(f"{description} at position {match.start()}: {match.group()}")
+                # Patterns that are always critical
+                critical_patterns = {r"\bexec\s*\(", r"\beval\s*\(", r"\bos\.system\s*\("}
+                if pattern in critical_patterns:
+                    result.blockers.append(f"Critical: {description}")
+                    result.threat_level = ThreatLevel.CRITICAL
+                elif result.threat_level == ThreatLevel.SAFE:
+                    result.threat_level = ThreatLevel.WARNING
+
+        return result
+
+    def verify_signature(self, skill_path: Path) -> SecurityCheckResult:
+        """Verify skill signature.
+
+        Tier-dependent behavior:
+        - dev: placeholder passes with informational note
+        - prod: BLOCKS materialization — requires cosign/sigstore signature
+        - ci: WARNING (strict mode, signature required but may use test key)
+        """
+        import os
+
+        tier = getattr(self, "_evidence_tier", None) or os.environ.get("SKILLPOOL_EVIDENCE_TIER", "dev")
+        result = SecurityCheckResult(threat_level=ThreatLevel.SAFE)
+        result.checks_passed.append("signature_check")
+
+        if tier == "prod":
+            # Production: signature is REQUIRED — block if not verified
+            result.blockers.append(
+                "Signature verification REQUIRED in prod tier — configure cosign/sigstore before deployment"
+            )
+            result.threat_level = ThreatLevel.CRITICAL
+        elif tier == "ci":
+            result.warnings.append(
+                "Signature verification is a placeholder in CI — production deployment requires cosign/sigstore"
+            )
+            result.threat_level = ThreatLevel.WARNING
+        else:
+            result.warnings.append(
+                "Signature verification skipped (dev tier) — set SKILLPOOL_EVIDENCE_TIER=prod for strict checking"
+            )
+        return result
+
+    def full_check(self, content: str, skill_path: Path | None = None) -> SecurityCheckResult:
+        """Run all security checks and return aggregated result.
+
+        Args:
+            content: The SKILL.md or CSDF YAML content to check.
+            skill_path: Optional path to the skill directory for signature verification.
+
+        Returns:
+            Aggregated SecurityCheckResult with the highest threat level found.
+        """
+        results = [
+            self.check_yaml_safety(content),
+            self.scan_dangerous_patterns(content),
+        ]
+        if skill_path:
+            results.append(self.verify_signature(skill_path))
+
+        # Aggregate: take the highest threat level
+        aggregated = SecurityCheckResult(threat_level=ThreatLevel.SAFE)
+        for r in results:
+            if r.threat_level == ThreatLevel.CRITICAL:
+                aggregated.threat_level = ThreatLevel.CRITICAL
+            elif r.threat_level == ThreatLevel.WARNING and aggregated.threat_level == ThreatLevel.SAFE:
+                aggregated.threat_level = ThreatLevel.WARNING
+            aggregated.checks_passed.extend(r.checks_passed)
+            aggregated.warnings.extend(r.warnings)
+            aggregated.blockers.extend(r.blockers)
+
+        return aggregated

skillpool/lifecycle.py

@@ -0,0 +1,150 @@
+"""
+Skill Lifecycle State Machine — 9-state enumeration with transition validation.
+
+States: DRAFT → PROPOSED → UNDER_REVIEW → APPROVED → ACTIVE → DEPRECATED → ARCHIVED → REMOVED
+                                                                          ↗              ↘
+        REJECTED ←───────────────────────────────────────────────────────────────────────
+            ↓
+        DRAFT (rework cycle)
+
+Terminal state: REMOVED (no outgoing transitions)
+"""
+
+from enum import IntEnum
+from typing import Optional
+
+
+class SkillLifecycleState(IntEnum):
+    """9-state lifecycle for skills in the pool."""
+
+    DRAFT = 0
+    PROPOSED = 1
+    UNDER_REVIEW = 2
+    APPROVED = 3
+    REJECTED = 4
+    ACTIVE = 5
+    DEPRECATED = 6
+    ARCHIVED = 7
+    REMOVED = 8
+
+
+# Transition table: from_state → set of valid to_states
+_TRANSITIONS: dict[SkillLifecycleState, list[SkillLifecycleState]] = {
+    SkillLifecycleState.DRAFT: [
+        SkillLifecycleState.PROPOSED,
+        SkillLifecycleState.REMOVED,
+    ],
+    SkillLifecycleState.PROPOSED: [
+        SkillLifecycleState.UNDER_REVIEW,
+        SkillLifecycleState.DRAFT,
+        SkillLifecycleState.REMOVED,
+    ],
+    SkillLifecycleState.UNDER_REVIEW: [
+        SkillLifecycleState.APPROVED,
+        SkillLifecycleState.REJECTED,
+        SkillLifecycleState.PROPOSED,
+    ],
+    SkillLifecycleState.APPROVED: [
+        SkillLifecycleState.ACTIVE,
+        SkillLifecycleState.REJECTED,
+    ],
+    SkillLifecycleState.REJECTED: [
+        SkillLifecycleState.DRAFT,
+        SkillLifecycleState.REMOVED,
+    ],
+    SkillLifecycleState.ACTIVE: [
+        SkillLifecycleState.DEPRECATED,
+        SkillLifecycleState.ARCHIVED,
+    ],
+    SkillLifecycleState.DEPRECATED: [
+        SkillLifecycleState.ARCHIVED,
+        SkillLifecycleState.ACTIVE,
+        SkillLifecycleState.REMOVED,
+    ],
+    SkillLifecycleState.ARCHIVED: [
+        SkillLifecycleState.ACTIVE,
+        SkillLifecycleState.REMOVED,
+    ],
+    SkillLifecycleState.REMOVED: [],
+}
+
+
+def validate_transition(
+    from_state: SkillLifecycleState,
+    to_state: SkillLifecycleState,
+) -> bool:
+    """Check if a transition from from_state to to_state is valid."""
+    if from_state == to_state:
+        return False
+    return to_state in _TRANSITIONS.get(from_state, [])
+
+
+def get_valid_transitions(
+    from_state: SkillLifecycleState,
+) -> list[SkillLifecycleState]:
+    """Return sorted list of valid target states from from_state."""
+    return sorted(_TRANSITIONS.get(from_state, []), key=lambda s: s.value)
+
+
+def is_terminal(state: SkillLifecycleState) -> bool:
+    """Check if a state is terminal (no outgoing transitions)."""
+    return len(_TRANSITIONS.get(state, [])) == 0
+
+
+def get_state_name(state: SkillLifecycleState) -> str:
+    """Return lowercase snake_case name of a state."""
+    return state.name.lower()
+
+
+def parse_state(name: str) -> Optional[SkillLifecycleState]:
+    """Parse a state name (case-insensitive) into SkillLifecycleState.
+    Returns None if the name is not a valid state.
+    """
+    if not name:
+        return None
+    upper = name.strip().upper()
+    try:
+        return SkillLifecycleState[upper]
+    except KeyError:
+        return None
+
+
+def check_auto_deprecation(skill_id: str) -> bool:
+    """Check if an ACTIVE skill should auto-transition to DEPRECATED.
+
+    Based on execution feedback data from GainTracker:
+      - avg_effectiveness < 3.0 with >= 5 executions → deprecate
+
+    Also cascades: skill deprecated → all its PROMOTED combinations deprecated.
+
+    Returns True if auto-deprecated, False otherwise.
+    """
+    try:
+        from skillpool.gain import GainTracker
+        from skillpool.combiner import CombinationLifecycleManager
+
+        tracker = GainTracker()
+        report = tracker.report(skill_id, last_n=50)
+
+        # No executions — not enough data to deprecate
+        if report.execution_count == 0:
+            return False
+
+        # Low effectiveness with sufficient data → deprecate
+        if report.avg_effectiveness < 3.0 and report.execution_count >= 5:
+            # Cascade: deprecate all PROMOTED combinations involving this skill
+            lifecycle_mgr = CombinationLifecycleManager()
+            combos = lifecycle_mgr.get_combinations_for_skill(skill_id)
+            for combo in combos:
+                if combo.state.value == 2:  # PROMOTED
+                    lifecycle_mgr.transition(
+                        combo.combination_id,
+                        4,  # DEPRECATED
+                        reason=f"Skill {skill_id} auto-deprecated (effectiveness={report.avg_effectiveness:.1f})",
+                    )
+            return True
+
+    except (ImportError, Exception):
+        pass
+
+    return False

skillpool/materializer/__init__.py

@@ -0,0 +1,124 @@
+"""
+Materializer — CSDF→SKILL.md 实体化引擎
+
+将 CSDF (Canonical Skill Definition Format) YAML 定义转化为
+SKILL.md 运行时格式，供 Agent 在协作中消费。
+
+核心流程:
+  CSDF YAML → Mapper(14条规则) → Lifecycle Filter → Budget Cropper → SKILL.md
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from skillpool.materializer.models import (
+    MaterializationResult,
+    MaterializedSkill,
+    CSDFDocument as CSDFDocument,
+)
+from skillpool.materializer.mapper import CSDFMapper
+from skillpool.materializer.lifecycle_filter import LifecycleFilter
+from skillpool.materializer.budget_cropper import BudgetCropper
+from skillpool.profile import AgentCapabilityProfile
+
+
+class Materializer:
+    """CSDF → SKILL.md 实体化引擎主类。
+
+    Usage:
+        mat = Materializer(profile=CLAUDE_CODE_PROFILE)
+        result = mat.materialize(csdf_path=Path("S05a-security-transport.yaml"))
+        print(result.skill.markdown)
+    """
+
+    def __init__(
+        self,
+        profile: AgentCapabilityProfile,
+        context_budget: int = 4096,
+        strict_lifecycle: bool = True,
+    ):
+        self.profile = profile
+        self.context_budget = context_budget
+        self.mapper = CSDFMapper()
+        self.lifecycle_filter = LifecycleFilter(strict=strict_lifecycle)
+        self.budget_cropper = BudgetCropper(max_tokens=context_budget)
+
+    def materialize(
+        self,
+        csdf_path: Optional[Path] = None,
+        csdf_dict: Optional[dict] = None,
+    ) -> MaterializationResult:
+        """执行 CSDF → SKILL.md 实体化。
+
+        Args:
+            csdf_path: CSDF YAML 文件路径
+            csdf_dict: CSDF 字典（与 csdf_path 二选一）
+
+        Returns:
+            MaterializationResult 包含结果状态和实体化后的 SKILL.md
+        """
+        # 1. 加载 CSDF
+        csdf = self._load_csdf(csdf_path, csdf_dict)
+
+        # 2. 能力匹配检查
+        can_exec, reason = self.profile.can_execute(
+            {
+                "required_capabilities": csdf.get("required_agent_capabilities", set()),
+                "min_trust_level": csdf.get("min_trust_level", 0),
+                "paradigm": csdf.get("paradigm"),
+            }
+        )
+        if not can_exec:
+            return MaterializationResult(
+                status="rejected",
+                skill=None,
+                errors=[f"capability mismatch: {reason}"],
+            )
+
+        # 3. 映射规则 (14 条)
+        skill_md = self.mapper.map(csdf)
+
+        # 4. Lifecycle 过滤
+        skill_md = self.lifecycle_filter.filter(skill_md, csdf)
+
+        # 5. Budget 裁剪
+        skill_md = self.budget_cropper.crop(skill_md)
+
+        # 6. 组装结果
+        skill = MaterializedSkill(
+            id=csdf.get("id", "unknown"),
+            name=csdf.get("name", "unknown"),
+            version=csdf.get("version", "0.0.0"),
+            dimension=csdf.get("dimension", ""),
+            markdown=skill_md,
+            token_count=self.budget_cropper.estimate_tokens(skill_md),
+        )
+
+        return MaterializationResult(
+            status="success",
+            skill=skill,
+            errors=[],
+        )
+
+    def materialize_batch(
+        self,
+        csdf_paths: list[Path],
+    ) -> list[MaterializationResult]:
+        """批量实体化多个 CSDF 文件。"""
+        return [self.materialize(csdf_path=p) for p in csdf_paths]
+
+    def _load_csdf(
+        self,
+        csdf_path: Optional[Path],
+        csdf_dict: Optional[dict],
+    ) -> dict:
+        """加载 CSDF 文档，优先用 dict，否则从文件读取。"""
+        if csdf_dict is not None:
+            return csdf_dict
+        if csdf_path is not None:
+            import yaml
+
+            return yaml.safe_load(csdf_path.read_text())
+        raise ValueError("必须提供 csdf_path 或 csdf_dict")