vouch-agent 0.3.0__py3-none-any.whl

vouch/__init__.py

@@ -0,0 +1,36 @@
+"""vouch: vet agent Skills and agents, and vouch for the safe ones.
+
+Public API
+----------
+    from vouch import validate_skill, validate_path, validate_text
+    from vouch import build_cv, build_agent_cv
+
+Each validator returns a :class:`~vouch.models.Report` with a ``verdict`` of
+``"valid"``, ``"suspicious"`` or ``"malicious"``.
+"""
+
+from .agent import AgentCV, build_agent_cv, discover_skills
+from .cv import SkillCV, build_cv, render_markdown, render_text
+from .engine import Engine, validate_path, validate_skill, validate_text
+from .models import Finding, Report, Severity, SkillInput, Verdict
+
+__all__ = [
+    "AgentCV",
+    "Engine",
+    "Finding",
+    "Report",
+    "Severity",
+    "SkillCV",
+    "SkillInput",
+    "Verdict",
+    "build_agent_cv",
+    "build_cv",
+    "discover_skills",
+    "render_markdown",
+    "render_text",
+    "validate_path",
+    "validate_skill",
+    "validate_text",
+]
+
+__version__ = "0.3.0"

vouch/agent.py

@@ -0,0 +1,278 @@
+"""Agent CV: a trust profile for a whole agent (all of its skills).
+
+Where a :class:`~vouch.cv.SkillCV` profiles a single skill, an
+:class:`AgentCV` aggregates *every* skill an agent has loaded into one report:
+the overall verdict, the union of capabilities across skills, and a per-skill
+breakdown. Think of it as "would you hire this agent?".
+
+An "agent" here is simply a directory that contains one or more skills (each a
+folder with a ``SKILL.md``). Discovery walks the tree and treats every folder
+containing a ``SKILL.md`` as a distinct skill.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import loader
+from .cv import SkillCV, build_cv
+from .models import Severity, Verdict
+
+# Ordering used to pick the "worst" verdict across skills.
+_VERDICT_RANK = {Verdict.VALID: 0, Verdict.SUSPICIOUS: 1, Verdict.MALICIOUS: 2}
+
+
+def discover_skills(root: str | os.PathLike[str]) -> list[Path]:
+    """Return the directory of every skill (folder with a SKILL.md) under root.
+
+    If ``root`` itself is a single skill (or a file), it is returned as-is.
+    """
+    p = Path(root)
+    if p.is_file():
+        return [p]
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(p):
+        dirnames[:] = [d for d in dirnames if d not in loader._SKIP_DIRS]
+        if any(f.lower() == "skill.md" for f in filenames):
+            found.append(Path(dirpath))
+            # Don't descend further into a skill's own subdirectories.
+            dirnames[:] = []
+    if not found:
+        # No SKILL.md anywhere; treat the root itself as one skill.
+        return [p]
+    return sorted(found)
+
+
+@dataclass
+class SkillSummary:
+    name: str
+    path: str
+    verdict: Verdict
+    risk_score: int
+    finding_count: int
+    top_capabilities: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": self.path,
+            "verdict": self.verdict.value,
+            "risk_score": self.risk_score,
+            "finding_count": self.finding_count,
+            "top_capabilities": self.top_capabilities,
+        }
+
+
+@dataclass
+class AgentCV:
+    name: str
+    verdict: Verdict
+    risk_score: int  # max across skills
+    recommendation: str
+    skill_count: int
+    skills: list[SkillSummary]
+    capabilities: dict[str, int]  # capability label -> how many skills use it
+    findings_by_severity: dict[str, int]
+    skill_cvs: list[SkillCV] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "verdict": self.verdict.value,
+            "risk_score": self.risk_score,
+            "recommendation": self.recommendation,
+            "skill_count": self.skill_count,
+            "capabilities": self.capabilities,
+            "findings_by_severity": self.findings_by_severity,
+            "skills": [s.to_dict() for s in self.skills],
+        }
+
+
+_RECOMMENDATION = {
+    Verdict.VALID: "TRUSTED — all skills passed. Safe to run this agent.",
+    Verdict.SUSPICIOUS: "REVIEW — one or more skills need a look before trusting this agent.",
+    Verdict.MALICIOUS: "QUARANTINE — this agent has a malicious skill. Do not run.",
+}
+
+
+def build_agent_cv(
+    root: str | os.PathLike[str],
+    *,
+    name: str | None = None,
+    use_llm: bool | None = None,
+    model: str | None = None,
+    api_key: str | None = None,
+    human_signoff: bool = False,
+) -> AgentCV:
+    """Build an Agent CV by profiling every skill discovered under ``root``."""
+    skill_dirs = discover_skills(root)
+
+    skill_cvs: list[SkillCV] = []
+    for sd in skill_dirs:
+        skill = loader.load(str(sd))
+        skill_cvs.append(
+            build_cv(
+                skill,
+                use_llm=use_llm,
+                model=model,
+                api_key=api_key,
+                human_signoff=human_signoff,
+            )
+        )
+
+    worst = Verdict.VALID
+    max_risk = 0
+    cap_counts: dict[str, int] = {}
+    sev_totals: dict[str, int] = {s.value: 0 for s in Severity}
+    summaries: list[SkillSummary] = []
+
+    for cv in skill_cvs:
+        if _VERDICT_RANK[cv.verdict] > _VERDICT_RANK[worst]:
+            worst = cv.verdict
+        max_risk = max(max_risk, cv.risk_score)
+        present = [c.label for c in cv.capabilities if c.present]
+        for label in present:
+            cap_counts[label] = cap_counts.get(label, 0) + 1
+        for sev, n in cv.findings_by_severity.items():
+            sev_totals[sev] += n
+        summaries.append(
+            SkillSummary(
+                name=cv.name,
+                path=cv.report.skill_name,
+                verdict=cv.verdict,
+                risk_score=cv.risk_score,
+                finding_count=len(cv.report.findings),
+                top_capabilities=present[:4],
+            )
+        )
+
+    # Worst skills first, then by risk.
+    summaries.sort(key=lambda s: (_VERDICT_RANK[s.verdict], s.risk_score), reverse=True)
+
+    agent_name = name or Path(root).name or "agent"
+    return AgentCV(
+        name=agent_name,
+        verdict=worst,
+        risk_score=max_risk,
+        recommendation=_RECOMMENDATION[worst],
+        skill_count=len(skill_cvs),
+        skills=summaries,
+        capabilities=dict(sorted(cap_counts.items(), key=lambda kv: -kv[1])),
+        findings_by_severity=sev_totals,
+        skill_cvs=skill_cvs,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Renderers
+# ---------------------------------------------------------------------------
+
+_VERDICT_BADGE = {
+    Verdict.VALID: "🟢 TRUSTED",
+    Verdict.SUSPICIOUS: "🟡 REVIEW",
+    Verdict.MALICIOUS: "🔴 QUARANTINE",
+}
+
+
+def render_markdown(cv: AgentCV) -> str:
+    lines: list[str] = []
+    lines.append(f"# Agent CV — {cv.name}")
+    lines.append("")
+    lines.append(
+        f"**Status:** {_VERDICT_BADGE[cv.verdict]}  ·  "
+        f"**Max risk:** {cv.risk_score}/100  ·  "
+        f"**Skills:** {cv.skill_count}"
+    )
+    lines.append("")
+    lines.append(f"**Recommendation:** {cv.recommendation}")
+    lines.append("")
+
+    lines.append("## Skills")
+    lines.append("")
+    lines.append("| Skill | Verdict | Risk | Findings | Capabilities |")
+    lines.append("|---|---|---:|---:|---|")
+    for s in cv.skills:
+        caps = ", ".join(s.top_capabilities) or "—"
+        lines.append(
+            f"| {s.name} | {s.verdict.value} | {s.risk_score} | "
+            f"{s.finding_count} | {caps} |"
+        )
+    lines.append("")
+
+    lines.append("## Capabilities across the agent")
+    if not cv.capabilities:
+        lines.append("_None detected._")
+    else:
+        for label, count in cv.capabilities.items():
+            lines.append(f"- **{label}** — used by {count} skill(s)")
+    lines.append("")
+
+    total = sum(cv.findings_by_severity.values())
+    lines.append(f"## Security ({total} finding(s) total)")
+    order = ["critical", "high", "medium", "low", "info"]
+    badge = ", ".join(
+        f"{cv.findings_by_severity[s]} {s}"
+        for s in order
+        if cv.findings_by_severity.get(s)
+    )
+    lines.append(badge or "_No findings._")
+    lines.append("")
+    return "\n".join(lines)
+
+
+_C = {
+    Verdict.VALID: "\033[32m",
+    Verdict.SUSPICIOUS: "\033[33m",
+    Verdict.MALICIOUS: "\033[31m",
+}
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+
+
+def render_text(cv: AgentCV, color: bool = False) -> str:
+    def c(text: str, code: str) -> str:
+        return f"{code}{text}{_RESET}" if color else text
+
+    width = 62
+    lines: list[str] = []
+    lines.append("╔" + "═" * width + "╗")
+    lines.append("║" + f" AGENT CV — {cv.name}".ljust(width)[:width] + "║")
+    lines.append("╚" + "═" * width + "╝")
+    badge = _VERDICT_BADGE[cv.verdict].split(" ", 1)[1]
+    lines.append(
+        c(f"Status: {badge}", _BOLD + _C[cv.verdict])
+        + f"   Max risk: {cv.risk_score}/100   Skills: {cv.skill_count}"
+    )
+    lines.append(c(f"Recommendation: {cv.recommendation}", _C[cv.verdict]))
+    lines.append("")
+
+    lines.append(c("SKILLS", _BOLD))
+    for s in cv.skills:
+        mark = c(s.verdict.value.upper().ljust(10), _C[s.verdict])
+        lines.append(
+            f"  {mark} risk {s.risk_score:>3}  {s.finding_count:>2} finding(s)  {s.name}"
+        )
+        if s.top_capabilities:
+            lines.append(f"             caps: {', '.join(s.top_capabilities)}")
+    lines.append("")
+
+    lines.append(c("CAPABILITIES (agent-wide)", _BOLD))
+    if not cv.capabilities:
+        lines.append("  (none detected)")
+    for label, count in cv.capabilities.items():
+        lines.append(f"  • {label} — {count} skill(s)")
+    lines.append("")
+
+    total = sum(cv.findings_by_severity.values())
+    lines.append(c(f"SECURITY ({total} total)", _BOLD))
+    order = ["critical", "high", "medium", "low", "info"]
+    summary = "  ".join(
+        f"{cv.findings_by_severity[s]} {s}"
+        for s in order
+        if cv.findings_by_severity.get(s)
+    )
+    lines.append("  " + (summary or "(none)"))
+    return "\n".join(lines)

vouch/api.py

@@ -0,0 +1,113 @@
+"""HTTP API for skill validation (FastAPI).
+
+Run with::
+
+    vouch-api                           # uvicorn on 0.0.0.0:8000
+    # or
+    uvicorn vouch.api:app --reload
+
+Requires the ``api`` extra::
+
+    pip install "vouch[api]"
+
+Endpoints
+---------
+- ``GET  /health``           -> liveness probe
+- ``POST /validate/text``    -> body: {content, name?, use_llm?}
+- ``POST /validate/path``    -> body: {path, use_llm?}  (local FS access)
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def create_app():
+    try:
+        from fastapi import FastAPI, HTTPException
+        from pydantic import BaseModel, Field
+    except Exception as e:  # pragma: no cover - import guard
+        raise SystemExit(
+            "FastAPI is required. Install with: pip install "
+            '"vouch[api]"'
+        ) from e
+
+    from . import loader
+    from .engine import validate_skill
+
+    app = FastAPI(
+        title="Vouch",
+        version="0.3.0",
+        description="Vet agent Skills; classify as valid, suspicious, or malicious.",
+    )
+
+    class TextRequest(BaseModel):
+        content: str = Field(..., description="Raw skill content (e.g. SKILL.md body).")
+        name: str = Field("inline-skill", description="Optional skill name.")
+        use_llm: bool | None = Field(
+            None, description="Enable LLM auditor. Default: auto (if API key set)."
+        )
+        model: str | None = Field(None, description="Optional LLM model id override.")
+
+    class PathRequest(BaseModel):
+        path: str = Field(..., description="Local path to a skill dir or file.")
+        use_llm: bool | None = Field(None, description="Enable LLM auditor.")
+        model: str | None = Field(None, description="Optional LLM model id override.")
+
+    @app.get("/health")
+    def health() -> dict:
+        return {"status": "ok"}
+
+    @app.post("/validate/text")
+    def validate_text_endpoint(req: TextRequest) -> dict:
+        skill = loader.load_text(req.content, name=req.name)
+        report = validate_skill(skill, use_llm=req.use_llm, model=req.model)
+        return report.to_dict()
+
+    @app.post("/cv/text")
+    def cv_text_endpoint(req: TextRequest) -> dict:
+        from . import cv as cv_mod
+
+        skill = loader.load_text(req.content, name=req.name)
+        skill_cv = cv_mod.build_cv(skill, use_llm=req.use_llm, model=req.model)
+        payload = skill_cv.to_dict()
+        payload["markdown"] = cv_mod.render_markdown(skill_cv)
+        return payload
+
+    @app.post("/validate/path")
+    def validate_path_endpoint(req: PathRequest) -> dict:
+        # Guard: local-path validation is disabled unless explicitly allowed,
+        # since it exposes the host filesystem to callers.
+        if os.environ.get("VOUCH_ALLOW_PATH") != "1":
+            raise HTTPException(
+                status_code=403,
+                detail="Path validation disabled. Set VOUCH_ALLOW_PATH=1 "
+                "to enable local filesystem access.",
+            )
+        try:
+            skill = loader.load(req.path)
+        except FileNotFoundError as e:
+            raise HTTPException(status_code=404, detail=str(e)) from e
+        report = validate_skill(skill, use_llm=req.use_llm, model=req.model)
+        return report.to_dict()
+
+    return app
+
+
+# Module-level app for `uvicorn vouch.api:app`.
+try:  # pragma: no cover - only succeeds when FastAPI is installed
+    app = create_app()
+except SystemExit:
+    app = None  # type: ignore[assignment]
+
+
+def run() -> None:  # pragma: no cover - thin runner
+    import uvicorn
+
+    host = os.environ.get("VOUCH_HOST", "0.0.0.0")
+    port = int(os.environ.get("VOUCH_PORT", "8000"))
+    uvicorn.run("vouch.api:app", host=host, port=port)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

vouch/capabilities.py

@@ -0,0 +1,148 @@
+"""Capability inference for skills.
+
+Separate from :mod:`vouch.cv` (which imports the engine) so the engine can also
+use capability data without a circular import.
+
+A *capability* describes what a skill *can do* (benign-or-not): network access,
+shell execution, dynamic code execution, filesystem read/write, credential
+access, persistence, environment access. The engine uses the **combination** of
+capabilities — not just rule findings — to gate verdicts, because the dangerous
+minority of skills are multi-stage chains whose individual steps look benign.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .models import SkillInput
+
+
+@dataclass
+class Evidence:
+    file: str
+    line: int
+    excerpt: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Capability:
+    key: str
+    label: str
+    present: bool = False
+    evidence: list[Evidence] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "label": self.label,
+            "present": self.present,
+            "evidence": [e.to_dict() for e in self.evidence],
+        }
+
+
+# key, label, pattern
+_CAP_PATTERNS: list[tuple[str, str, re.Pattern[str]]] = [
+    (
+        "network",
+        "Network access",
+        re.compile(
+            r"\b(curl|wget|fetch\(|requests\.(get|post|put|delete)|urllib|"
+            r"http\.client|axios|http[sx]?://)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "shell",
+        "Shell execution",
+        re.compile(
+            r"\b(subprocess\.|os\.system|os\.popen|shell=True|/bin/(ba)?sh|"
+            r"\bsh\s+-c|\bbash\b|child_process|execSync|spawn\()\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "code_exec",
+        "Dynamic code execution",
+        re.compile(r"\b(eval\(|exec\(|Function\(|compile\(|importlib)\b"),
+    ),
+    (
+        "fs_write",
+        "Filesystem writes",
+        re.compile(
+            r"(open\([^)]*['\"][wax]\+?['\"]|write_text|\.write\(|>>?\s*[~/.\w]|"
+            r"\b(rm|mv|cp|mkdir|rmdir|touch|chmod|chown)\b)",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "fs_read",
+        "Filesystem reads",
+        re.compile(
+            r"(open\([^)]*['\"]r['\"]?|read_text|\.read\(|\b(cat|less|more|head|tail)\b)",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "credentials",
+        "Credential / secret access",
+        re.compile(
+            r"(\.ssh/|\.aws/|\.kube/|token|secret|api[_-]?key|password|passwd|"
+            r"credential|\.env\b)",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "persistence",
+        "Persistence mechanisms",
+        re.compile(
+            r"\b(crontab|launchctl|systemd|\.bashrc|\.zshrc|\.profile|LaunchAgents|"
+            r"LaunchDaemons)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "env",
+        "Environment variable access",
+        re.compile(r"(os\.environ|process\.env|getenv|printenv|\benv\b)", re.IGNORECASE),
+    ),
+]
+
+_MAX_EVIDENCE = 3
+
+
+def scan_capabilities(skill: SkillInput) -> list[Capability]:
+    """Return one Capability per class, marked present with up to 3 evidence hits."""
+    caps = {key: Capability(key, label) for key, label, _ in _CAP_PATTERNS}
+    seen: dict[str, set[tuple[str, int]]] = {key: set() for key, _, _ in _CAP_PATTERNS}
+    for sf in skill.files:
+        content_lines = sf.content.splitlines()
+        for key, _label, pat in _CAP_PATTERNS:
+            cap = caps[key]
+            for m in pat.finditer(sf.content):
+                cap.present = True
+                line = sf.content.count("\n", 0, m.start()) + 1
+                loc = (sf.path, line)
+                if loc in seen[key]:
+                    continue
+                seen[key].add(loc)
+                if len(cap.evidence) < _MAX_EVIDENCE:
+                    snippet = (
+                        content_lines[line - 1].strip()
+                        if line <= len(content_lines)
+                        else ""
+                    )
+                    # Don't use markdown code-fence markers as evidence — they're
+                    # noise (e.g. ```bash). The capability still counts as present.
+                    if snippet.startswith("```"):
+                        continue
+                    cap.evidence.append(Evidence(sf.path, line, snippet[:120]))
+    return list(caps.values())
+
+
+def present_keys(caps: list[Capability]) -> set[str]:
+    return {c.key for c in caps if c.present}