skillctl-secure 0.28.2__tar.gz → 0.28.3__tar.gz

{skillctl_secure-0.28.2 → skillctl_secure-0.28.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: skillctl-secure
-Version: 0.28.2
+Version: 0.28.3
 Summary: Package manager, trust layer, and portability layer for Agent Skills
 Project-URL: Homepage, https://github.com/brian-scardina/skillctl
 Project-URL: Repository, https://github.com/brian-scardina/skillctl

{skillctl_secure-0.28.2 → skillctl_secure-0.28.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "skillctl-secure"
-version = "0.28.2"
+version = "0.28.3"
 description = "Package manager, trust layer, and portability layer for Agent Skills"
 readme = "README.md"
 license = "Apache-2.0"

skillctl_secure-0.28.3/skillctl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.28.3"

skillctl_secure-0.28.3/skillctl/findings_tui.py

@@ -0,0 +1,108 @@
+"""Read-only finding explanations and an explicit re-audit action."""
+from textual import work
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, Static
+
+
+GUIDANCE = {
+    "Destructive recursive delete": ("A recursive delete can permanently remove files outside the intended workspace.", "Constrain deletion to a validated workspace path, reject empty/root paths, and require confirmation for destructive operations."),
+    "Privilege escalation / sudo usage": ("Elevated commands can modify protected system files and settings.", "Use user-owned directories and minimum permissions; document and confirm any necessary elevated operation."),
+    "SSH credential access": ("Access to SSH credentials can expose keys or allow impersonation.", "Remove private-key reads; use an SSH agent or a narrowly scoped credential integration."),
+    "Credential/environment secret reference": ("Secrets may be exposed through logs, files, or outbound requests if mishandled.", "Use a secret store or scoped environment variable, redact output, and verify that credentials only reach the intended service."),
+    "Dynamic code execution": ("Untrusted input reaching eval/exec can execute arbitrary code.", "Replace dynamic evaluation with structured parsing or allowlisted operations; trace and validate all inputs."),
+    "Outbound download command": ("Downloaded content may be untrusted or change before execution.", "Verify the source and integrity, pin versions, and inspect downloads before executing them."),
+    "Process execution": ("Commands built from untrusted input can execute unintended programs or arguments.", "Use argument arrays without a shell, validate inputs, and restrict executable paths and permissions."),
+    "External URL / network reference": ("An external reference may introduce downloads or outbound data transfers; a link alone does not prove network activity.", "Check the destination and actual use. Restrict transmitted data and validate any downloaded content; ordinary reference links may need no change."),
+    "Marks file executable": ("Executable permissions allow a downloaded or modified file to run.", "Review the file and its provenance before granting execute permission; scope permissions to the intended file."),
+    "Prompt-injection override language": ("Instructions may attempt to override the user's request or trusted instructions.", "Remove override directives, or clearly isolate quoted attack examples as untrusted data."),
+    "Potential secret exfiltration instruction": ("Instructions could cause credentials or other secrets to be sent to an external destination.", "Remove secret-transfer instructions and use scoped authentication that does not expose credential values."),
+    "Instruction to access SSH credentials": ("Instructions could lead an agent to read private SSH credentials.", "Remove instructions to read private keys and use an SSH agent or scoped authentication instead."),
+    "Potential encoded/dynamic payload handling": ("Decoded or deserialized input may conceal executable content; unsafe deserialization can run code.", "Inspect decoded content, avoid unsafe deserialization of untrusted data, and prefer validated JSON or other data-only formats."),
+    "Large file (>2 MB)": ("The heuristic scanner skipped this file, leaving its contents unreviewed.", "Remove unnecessary large assets or review the file separately with appropriate tools."),
+    "Non-text/binary or unrecognized file type": ("The heuristic scanner did not inspect the contents of this file type.", "Verify provenance and inspect with tools for that file type; remove unnecessary binaries."),
+}
+
+
+def render_findings(audit, stale=False):
+    """Plain text: source-controlled strings must never become Rich markup."""
+    if audit.get("error"):
+        status = f"Audit failed: {audit['error']}\nResults may be incomplete. Re-audit to retry."
+    elif not audit.get("checked_at"):
+        status = "Audit pending. Run Re-audit to inspect this skill."
+    elif stale:
+        status = "Cached audit is stale. Re-audit to check the current source."
+    else:
+        status = "Latest cached audit results."
+    findings = audit.get("findings", [])
+    lines = [status, f"\n{len(findings)} finding(s)",
+             "Heuristic matches require review; they are not confirmed vulnerabilities. Documentation examples may be benign."]
+    if not findings and audit.get("checked_at") and not audit.get("error"):
+        lines.append("\nNo heuristic findings in this cached audit.")
+    for i, finding in enumerate(sorted(findings, key=lambda f: {"HIGH": 0, "MEDIUM": 1, "LOW": 2}.get(f.get("severity"), 3)), 1):
+        message = finding.get("message", "Unknown finding")
+        risk, fix = GUIDANCE.get(message, (
+            "The scanner flagged this content; specific risk guidance is unavailable.",
+            "Inspect the referenced source and its inputs and effects, then correct unsafe behavior and re-audit."))
+        lines.extend([f"\n{i}. {finding.get('severity', 'UNKNOWN')} — {message}",
+                      f"Location: {finding.get('path') or 'Unavailable'}", f"Risk: {risk}", f"Suggested fix: {fix}"])
+    lines.append("\nApply changes in the skill's maintained source, then re-audit. Managed installed copies may be overwritten by updates.")
+    return "\n".join(lines)
+
+
+class FindingsScreen(ModalScreen):
+    BINDINGS = [Binding("escape", "dismiss", "Close")]
+    CSS = """
+    FindingsScreen { align: center middle; background: $background 85%; }
+    #findings-dialog { width: 90%; height: 90%; border: solid $accent; background: $surface; padding: 1 2; }
+    #findings-title { height: auto; margin-bottom: 1; text-style: bold; }
+    #findings-scroll { height: 1fr; }
+    #findings-content { height: auto; }
+    #findings-actions { height: 3; margin-top: 1; }
+    #findings-actions Button { width: 1fr; }
+    """
+
+    def __init__(self, manager, name):
+        super().__init__()
+        self.manager = manager
+        self.skill_name = name
+
+    def compose(self):
+        with Vertical(id="findings-dialog"):
+            yield Static(f"Audit findings · {self.skill_name}", id="findings-title", markup=False)
+            with VerticalScroll(id="findings-scroll"):
+                yield Static("Loading findings…", id="findings-content", markup=False)
+            with Horizontal(id="findings-actions"):
+                yield Button("Re-audit", id="findings-audit", variant="primary")
+                yield Button("Close", id="findings-close")
+
+    def on_mount(self):
+        self.load_findings()
+
+    @work(thread=True, exclusive=True, group="finding-inspection")
+    def load_findings(self, refresh=False):
+        try:
+            spec = self.manager.get(self.skill_name)
+            if refresh:
+                self.manager.audit(spec)
+            audit = (self.manager._load_state().get(self.skill_name, {}) or {}).get("audit", {}) or {}
+            result = render_findings(audit, self.manager.audit_needed(spec))
+        except Exception as exc:
+            result = f"Unable to load audit findings: {exc}\nUse Re-audit to retry."
+        self.app.call_from_thread(self.show_result, result)
+
+    def show_result(self, result):
+        if not self.is_mounted:
+            return
+        self.query_one("#findings-content", Static).update(result)
+        self.query_one("#findings-audit", Button).disabled = False
+
+    def on_button_pressed(self, event):
+        event.stop()
+        if event.button.id == "findings-close":
+            self.dismiss()
+        elif event.button.id == "findings-audit":
+            event.button.disabled = True
+            self.query_one("#findings-content", Static).update("Auditing skill…")
+            self.load_findings(refresh=True)

{skillctl_secure-0.28.2 → skillctl_secure-0.28.3}/skillctl/tui_interaction.py

@@ -96,6 +96,7 @@ def install_interaction_responsiveness(SkillCtlTUI) -> None:
         self.call_from_thread(_update_audit_activity, self)
         if not pending:
             return
+        failed = 0
         self.call_from_thread(_safe_worker_log, self, f"Automatic audit: {len(pending)} new/stale skill(s) queued.")
         for spec in pending:
             try:
@@ -106,13 +107,20 @@ def install_interaction_responsiveness(SkillCtlTUI) -> None:
                     low = sum(f.severity == "LOW" for f in findings)
                     self.call_from_thread(_safe_worker_log, self, f"Audited {spec.name}: HIGH:{high} MED:{medium} LOW:{low}")
             except Exception as exc:
+                failed += 1
                 self.call_from_thread(_safe_worker_log, self, f"Automatic audit failed for {spec.name}: {exc}")
             finally:
                 self.auto_audit_done += 1
                 self.call_from_thread(_update_audit_activity, self, spec.name)
         self.auto_audit_running = False
         self.call_from_thread(_update_audit_activity, self)
-        self.call_from_thread(_safe_worker_log, self, "Automatic catalog audit complete; press Ctrl+R to refresh audit badges.")
+        # Refresh once through the asynchronous snapshot worker, never per skill.
+        self.call_from_thread(self.action_refresh)
+        message = (f"Automatic audit finished: {failed}/{len(pending)} failed; see the log for details."
+                   if failed else "Automatic catalog audit complete.")
+        self.call_from_thread(_safe_worker_log, self, message)
+        if failed:
+            self.call_from_thread(self.notify, message, severity="warning", timeout=10)
 
     SkillCtlTUI._load_skill_detail = load_detail
     SkillCtlTUI._show_detail = show_detail

{skillctl_secure-0.28.2 → skillctl_secure-0.28.3}/skillctl/tui_original.py

@@ -187,7 +187,7 @@ class SkillCtlTUI(App):
     #catalog { width: 2fr; }
     #detail-column { width: 3fr; display: none; }
     #detail-column.open { display: block; }
-    #btn-close-detail { height: 3; width: 100%; }
+    #btn-close-detail, #btn-findings { height: 3; width: 100%; }
     #global-actions { height: 4; }
     #global-actions > Horizontal { width: 1fr; height: 4; border-top: solid $panel; }
     #detail { height: 1fr; padding: 1 2; border: solid $accent; overflow-y: auto; }
@@ -300,6 +300,7 @@ class SkillCtlTUI(App):
                     yield DataTable(id="table-hosts", cursor_type="row")
             with Vertical(id="detail-column"):
                 yield Button("Close details", id="btn-close-detail", tooltip="Return to the full table (Escape)")
+                yield Button("View audit findings", id="btn-findings", tooltip="Inspect findings, risks, and suggested fixes")
                 yield Static("Select a skill", id="detail", markup=True)
                 with Horizontal(id="skill-actions"):
                     yield Button("Install", id="btn-install", variant="primary", disabled=True)
@@ -745,6 +746,7 @@ class SkillCtlTUI(App):
 
 
     def _update_skill_action_buttons(self, installed: bool | None) -> None:
+        self.query_one("#btn-findings", Button).display = self.selected_kind == "skill"
         install=self.query_one("#btn-install", Button)
         update=self.query_one("#btn-update", Button)
         update.label = "Update"
@@ -1244,6 +1246,12 @@ class SkillCtlTUI(App):
         return self.manager.get(self.selected_name)
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "btn-findings":
+            event.stop()
+            if self.selected_kind == "skill" and self.selected_name:
+                from .findings_tui import FindingsScreen
+                self.push_screen(FindingsScreen(self.manager, self.selected_name), lambda _: self.action_refresh())
+            return
         if event.button.id == "btn-close-detail":
             event.stop()
             self.action_close_detail()

skillctl_secure-0.28.2/skillctl/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.28.2"