ipman-cli 0.1.73__py3-none-any.whl

ipman/core/package.py

@@ -0,0 +1,188 @@
+"""IP package data models, parsing, and serialization."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class ValidationError(Exception):
+    """Raised when an IP file fails validation."""
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SkillRef:
+    """Reference to a skill in an IP package."""
+
+    name: str
+    source: dict[str, Any] | None = None
+    description: str | None = None
+
+    @property
+    def is_direct_source(self) -> bool:
+        return self.source is not None
+
+
+@dataclass
+class DependencyRef:
+    """Reference to a dependency IP package."""
+
+    name: str
+    version: str | None = None
+    source: str | None = None
+
+    @property
+    def is_direct_source(self) -> bool:
+        return self.source is not None
+
+
+@dataclass
+class IPPackage:
+    """Parsed representation of an .ip.yaml file."""
+
+    name: str
+    version: str
+    description: str
+    skills: list[SkillRef]
+    dependencies: list[DependencyRef] = field(default_factory=list)
+    author: dict[str, str] | None = None
+    license: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Name validation
+# ---------------------------------------------------------------------------
+
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9\-]{1,48}[a-z0-9]$")
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+def parse_ip_file(
+    path: Path | None = None,
+    *,
+    content: str | None = None,
+) -> IPPackage:
+    """Parse an .ip.yaml file into an IPPackage.
+
+    Provide either *path* (reads from disk) or *content* (raw YAML string).
+    """
+    if content is None:
+        if path is None:
+            msg = "Either path or content must be provided"
+            raise ValueError(msg)
+        content = path.read_text(encoding="utf-8")
+
+    data = yaml.safe_load(content)
+    if not isinstance(data, dict):
+        msg = "IP file must be a YAML mapping"
+        raise ValidationError(msg)
+
+    # --- required fields ---
+    if "name" not in data:
+        msg = "Missing required field: name"
+        raise ValidationError(msg)
+    if "version" not in data:
+        msg = "Missing required field: version"
+        raise ValidationError(msg)
+    if "skills" not in data:
+        msg = "Missing required field: skills"
+        raise ValidationError(msg)
+
+    # --- skills ---
+    raw_skills: list[dict[str, Any]] = data.get("skills") or []
+    skills = [
+        SkillRef(
+            name=s["name"],
+            source=s.get("source"),
+            description=s.get("description"),
+        )
+        for s in raw_skills
+    ]
+
+    # --- dependencies ---
+    raw_deps: list[dict[str, Any]] = data.get("dependencies") or []
+    dependencies = [
+        DependencyRef(
+            name=d["name"],
+            version=d.get("version"),
+            source=d.get("source"),
+        )
+        for d in raw_deps
+    ]
+
+    return IPPackage(
+        name=data["name"],
+        version=str(data["version"]),
+        description=data.get("description", ""),
+        skills=skills,
+        dependencies=dependencies,
+        author=data.get("author"),
+        license=data.get("license"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Serialization
+# ---------------------------------------------------------------------------
+
+_HEADER = """\
+# IpMan Intelligence Package — https://github.com/twisker/ipman
+# Install: ipman install {filename}
+"""
+
+
+def dump_ip_file(pkg: IPPackage, path: Path) -> None:
+    """Serialize an IPPackage to an .ip.yaml file with header comment."""
+    data: dict[str, Any] = {
+        "name": pkg.name,
+        "version": pkg.version,
+        "description": pkg.description,
+    }
+
+    if pkg.author:
+        data["author"] = pkg.author
+    if pkg.license:
+        data["license"] = pkg.license
+
+    # Skills
+    skills_out: list[dict[str, Any]] = []
+    for s in pkg.skills:
+        entry: dict[str, Any] = {"name": s.name}
+        if s.description:
+            entry["description"] = s.description
+        if s.source:
+            entry["source"] = s.source
+        skills_out.append(entry)
+    data["skills"] = skills_out
+
+    # Dependencies
+    if pkg.dependencies:
+        deps_out: list[dict[str, Any]] = []
+        for d in pkg.dependencies:
+            dep_entry: dict[str, Any] = {"name": d.name}
+            if d.version:
+                dep_entry["version"] = d.version
+            if d.source:
+                dep_entry["source"] = d.source
+            deps_out.append(dep_entry)
+        data["dependencies"] = deps_out
+
+    header = _HEADER.format(filename=path.name)
+    body = yaml.dump(
+        data, default_flow_style=False, allow_unicode=True, sort_keys=False,
+    )
+    path.write_text(header + "\n" + body, encoding="utf-8")

ipman/core/resolver.py

@@ -0,0 +1,160 @@
+"""Dependency resolver — version matching, recursive resolution."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class CyclicDependencyError(Exception):
+    """Raised when a cyclic dependency is detected."""
+
+
+# ---------------------------------------------------------------------------
+# Version constraint
+# ---------------------------------------------------------------------------
+
+_CONSTRAINT_RE = re.compile(
+    r"^(?P<op>>=|\^|~)?(?P<major>\d+)\.(?P<minor>\d+)(?:\.(?P<patch>\d+))?$"
+)
+
+
+@dataclass(frozen=True)
+class VersionConstraint:
+    """Parsed version constraint."""
+
+    op: str  # "==", ">=", "^", "~"
+    major: int
+    minor: int
+    patch: int
+
+
+def parse_constraint(spec: str) -> VersionConstraint:
+    """Parse a version constraint string like '>=1.2.0', '^1.3.0', '~1.3.0', '1.2.0'."""
+    m = _CONSTRAINT_RE.match(spec.strip())
+    if not m:
+        msg = f"Invalid version constraint: '{spec}'"
+        raise ValueError(msg)
+    op = m.group("op") or "=="
+    return VersionConstraint(
+        op=op,
+        major=int(m.group("major")),
+        minor=int(m.group("minor")),
+        patch=int(m.group("patch") or 0),
+    )
+
+
+def _parse_version(version: str) -> tuple[int, int, int]:
+    """Parse a plain version string into (major, minor, patch)."""
+    parts = version.strip().split(".")
+    major = int(parts[0])
+    minor = int(parts[1]) if len(parts) > 1 else 0
+    patch = int(parts[2]) if len(parts) > 2 else 0
+    return major, minor, patch
+
+
+def version_matches(candidate: str, constraint: str | None) -> bool:
+    """Check if *candidate* version satisfies *constraint*.
+
+    Returns True if constraint is None (no restriction).
+    """
+    if constraint is None:
+        return True
+
+    c = parse_constraint(constraint)
+    v_major, v_minor, v_patch = _parse_version(candidate)
+    v = (v_major, v_minor, v_patch)
+    base = (c.major, c.minor, c.patch)
+
+    if c.op == "==":
+        return v == base
+
+    if c.op == ">=":
+        return v >= base
+
+    if c.op == "^":
+        # ^M.N.P  =>  >=M.N.P, <(M+1).0.0   (when M>0)
+        #             >=0.N.P, <0.(N+1).0     (when M==0)
+        if v < base:
+            return False
+        if c.major == 0:
+            return v_major == 0 and v_minor == c.minor
+        return v_major == c.major
+
+    if c.op == "~":
+        # ~M.N.P  =>  >=M.N.P, <M.(N+1).0
+        if v < base:
+            return False
+        return v_major == c.major and v_minor == c.minor
+
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Dependency resolution
+# ---------------------------------------------------------------------------
+
+# Type alias for the fetcher callback:
+#   fetcher(name, version_constraint) -> dict with keys: version, skills, dependencies
+PackageFetcher = Callable[[str, str | None], dict[str, Any]]
+
+
+def resolve_dependencies(
+    name: str,
+    version: str | None,
+    fetcher: PackageFetcher,
+) -> list[dict[str, Any]]:
+    """Recursively resolve all skills from a package and its dependencies.
+
+    Args:
+        name: Root package name.
+        version: Version constraint for the root (or None).
+        fetcher: Callback that returns package data given (name, version).
+                 Must return dict with 'skills' and 'dependencies' keys.
+
+    Returns:
+        Deduplicated list of skill dicts (order: root-first DFS).
+
+    Raises:
+        CyclicDependencyError: If a dependency cycle is detected.
+    """
+    seen_skills: set[str] = set()
+    result: list[dict[str, Any]] = []
+    visiting: set[str] = set()  # cycle detection (DFS stack)
+    visited: set[str] = set()   # already fully resolved
+
+    def _visit(pkg_name: str, pkg_version: str | None) -> None:
+        if pkg_name in visiting:
+            raise CyclicDependencyError(
+                f"Cyclic dependency detected: {pkg_name}"
+            )
+        if pkg_name in visited:
+            return
+
+        visiting.add(pkg_name)
+
+        data = fetcher(pkg_name, pkg_version)
+
+        # Collect skills (deduplicate by name)
+        for skill in data.get("skills", []):
+            sname = skill["name"]
+            if sname not in seen_skills:
+                seen_skills.add(sname)
+                result.append(skill)
+
+        # Recurse into dependencies
+        for dep in data.get("dependencies", []):
+            dep_name = dep.get("name") or dep
+            dep_version = dep.get("version") if isinstance(dep, dict) else None
+            _visit(dep_name, dep_version)
+
+        visiting.discard(pkg_name)
+        visited.add(pkg_name)
+
+    _visit(name, version)
+    return result

ipman/core/security.py

@@ -0,0 +1,84 @@
+"""Security enforcement — decision matrix and logging."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+
+from ipman.core.config import SecurityMode
+from ipman.core.vetter import RiskLevel
+
+
+class Action(Enum):
+    """Install-time action determined by risk level x security mode."""
+
+    INSTALL = "INSTALL"
+    WARN_INSTALL = "WARN_INSTALL"
+    WARN_CONFIRM = "WARN_CONFIRM"
+    BLOCK = "BLOCK"
+
+
+# Decision matrix: _MATRIX[security_mode][risk_level] -> Action
+_MATRIX: dict[SecurityMode, dict[RiskLevel, Action]] = {
+    SecurityMode.PERMISSIVE: {
+        RiskLevel.LOW: Action.INSTALL,
+        RiskLevel.MEDIUM: Action.INSTALL,
+        RiskLevel.HIGH: Action.INSTALL,
+        RiskLevel.EXTREME: Action.WARN_INSTALL,
+    },
+    SecurityMode.DEFAULT: {
+        RiskLevel.LOW: Action.INSTALL,
+        RiskLevel.MEDIUM: Action.INSTALL,
+        RiskLevel.HIGH: Action.WARN_INSTALL,
+        RiskLevel.EXTREME: Action.BLOCK,
+    },
+    SecurityMode.CAUTIOUS: {
+        RiskLevel.LOW: Action.INSTALL,
+        RiskLevel.MEDIUM: Action.WARN_INSTALL,
+        RiskLevel.HIGH: Action.BLOCK,
+        RiskLevel.EXTREME: Action.BLOCK,
+    },
+    SecurityMode.STRICT: {
+        RiskLevel.LOW: Action.INSTALL,
+        RiskLevel.MEDIUM: Action.WARN_CONFIRM,
+        RiskLevel.HIGH: Action.BLOCK,
+        RiskLevel.EXTREME: Action.BLOCK,
+    },
+}
+
+
+def decide_action(
+    risk_level: RiskLevel,
+    security_mode: SecurityMode,
+) -> Action:
+    """Determine the install action for a given risk + mode."""
+    return _MATRIX[security_mode][risk_level]
+
+
+def log_security_event(
+    *,
+    log_path: Path,
+    skill_name: str,
+    source: str,
+    risk_level: RiskLevel,
+    action: Action,
+    details: str = "",
+) -> None:
+    """Append a security event to the log file."""
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    parts = [
+        ts,
+        action.value,
+        skill_name,
+        f"source={source}",
+        f"risk={risk_level.name}",
+    ]
+    if details:
+        parts.append(f"reason={details}")
+
+    line = " ".join(parts)
+    with log_path.open("a", encoding="utf-8") as f:
+        f.write(line + "\n")

ipman/core/vetter.py

@@ -0,0 +1,193 @@
+"""Skill risk assessment engine — red flag detection + risk classification."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class RiskLevel(IntEnum):
+    """Risk severity levels (ordered for comparison)."""
+
+    LOW = 0
+    MEDIUM = 1
+    HIGH = 2
+    EXTREME = 3
+
+
+@dataclass
+class RiskFlag:
+    """A single detected risk indicator."""
+
+    id: str
+    description: str
+    severity: RiskLevel
+
+
+@dataclass
+class VetReport:
+    """Complete risk assessment report."""
+
+    skill_name: str
+    risk_level: RiskLevel
+    verdict: str
+    flags: list[RiskFlag] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Content scanning patterns
+# ---------------------------------------------------------------------------
+
+_PATTERNS: list[tuple[str, re.Pattern[str], RiskLevel]] = [
+    # Network exfiltration
+    (
+        "network-exfil",
+        re.compile(r"\b(curl|wget)\b", re.IGNORECASE),
+        RiskLevel.HIGH,
+    ),
+    # Raw IP address in URLs
+    (
+        "raw-ip",
+        re.compile(
+            r"https?://\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}",
+        ),
+        RiskLevel.HIGH,
+    ),
+    # Credential / sensitive path access
+    (
+        "credential-access",
+        re.compile(
+            r"~/?\.(ssh|aws|config|gnupg|kube)/",
+            re.IGNORECASE,
+        ),
+        RiskLevel.HIGH,
+    ),
+    # Obfuscated code (base64 decode)
+    (
+        "obfuscated-code",
+        re.compile(
+            r"\bbase64\b.*\b(decode|--decode|-d)\b",
+            re.IGNORECASE,
+        ),
+        RiskLevel.HIGH,
+    ),
+    # Dynamic code evaluation
+    (
+        "obfuscated-code",
+        re.compile(r"\beval\s*\(", re.IGNORECASE),
+        RiskLevel.HIGH,
+    ),
+    # Privilege escalation
+    (
+        "privilege-escalation",
+        re.compile(r"\bsudo\b", re.IGNORECASE),
+        RiskLevel.HIGH,
+    ),
+    # Agent memory file access
+    (
+        "memory-access",
+        re.compile(
+            r"\b(MEMORY\.md|SOUL\.md|IDENTITY\.md|USER\.md)\b",
+        ),
+        RiskLevel.EXTREME,
+    ),
+]
+
+
+def vet_skill_content(content: str) -> list[RiskFlag]:
+    """Scan skill content for red flags.
+
+    Analyzes text (SKILL.md, code files, etc.) for suspicious
+    patterns that indicate potential security threats.
+    """
+    flags: list[RiskFlag] = []
+    seen_ids: set[str] = set()
+
+    for flag_id, pattern, severity in _PATTERNS:
+        if pattern.search(content):
+            # Deduplicate by flag_id (same id can come from
+            # multiple pattern variants like eval + base64)
+            if flag_id not in seen_ids:
+                seen_ids.add(flag_id)
+                match = pattern.search(content)
+                snippet = match.group(0) if match else ""
+                flags.append(RiskFlag(
+                    id=flag_id,
+                    description=f"Detected: {snippet}",
+                    severity=severity,
+                ))
+
+    return flags
+
+
+# ---------------------------------------------------------------------------
+# Metadata-based checks
+# ---------------------------------------------------------------------------
+
+_REPORTS_THRESHOLD = 3
+_LOW_INSTALLS_THRESHOLD = 10
+
+
+def vet_skill_metadata(
+    *,
+    author: str,
+    installs: int,
+    reports: int,
+) -> list[RiskFlag]:
+    """Check metadata-based risk signals."""
+    flags: list[RiskFlag] = []
+
+    if reports >= _REPORTS_THRESHOLD:
+        flags.append(RiskFlag(
+            id="high-reports",
+            description=f"{reports} community reports",
+            severity=RiskLevel.HIGH,
+        ))
+
+    if installs < _LOW_INSTALLS_THRESHOLD:
+        flags.append(RiskFlag(
+            id="low-reputation",
+            description=(
+                f"Low install count ({installs}) "
+                f"by {author}"
+            ),
+            severity=RiskLevel.MEDIUM,
+        ))
+
+    return flags
+
+
+# ---------------------------------------------------------------------------
+# Risk assessment
+# ---------------------------------------------------------------------------
+
+_VERDICTS = {
+    RiskLevel.LOW: "SAFE TO INSTALL",
+    RiskLevel.MEDIUM: "INSTALL WITH CAUTION",
+    RiskLevel.HIGH: "DO NOT INSTALL",
+    RiskLevel.EXTREME: "DO NOT INSTALL",
+}
+
+
+def assess_risk(
+    flags: list[RiskFlag],
+    *,
+    skill_name: str,
+) -> VetReport:
+    """Compute overall risk level from collected flags."""
+    if not flags:
+        return VetReport(
+            skill_name=skill_name,
+            risk_level=RiskLevel.LOW,
+            verdict=_VERDICTS[RiskLevel.LOW],
+            flags=[],
+        )
+
+    highest = max(f.severity for f in flags)
+    return VetReport(
+        skill_name=skill_name,
+        risk_level=RiskLevel(highest),
+        verdict=_VERDICTS[RiskLevel(highest)],
+        flags=flags,
+    )