zenveil 1.0.0__tar.gz

zenveil-1.0.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.1
+Name: zenveil
+Version: 1.0.0
+Summary: AI-powered security scanner for repositories and APIs.
+Project-URL: Homepage, https://zenveil.dev
+Project-URL: Documentation, https://zenveil.dev/docs
+Project-URL: Repository, https://github.com/oyugirachel/zen-guard
+Requires-Python: >=3.8

zenveil-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zenveil"
+version = "1.0.0"
+description = "AI-powered security scanner for repositories and APIs."
+requires-python = ">=3.8"
+dependencies = []
+
+[project.urls]
+Homepage = "https://zenveil.dev"
+Documentation = "https://zenveil.dev/docs"
+Repository = "https://github.com/oyugirachel/zen-guard"
+
+[project.scripts]
+zenguard = "zenguard.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["zenguard*"]

zenveil-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zenveil-1.0.0/zenguard/__init__.py

@@ -0,0 +1 @@
+"""ZenGuard client — AI-powered security scanner."""

zenveil-1.0.0/zenguard/api_client.py

@@ -0,0 +1,94 @@
+"""HTTP client that talks to the ZenGuard API server."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Iterator
+
+from zenguard import config
+
+
+def _headers(api_key: str) -> dict[str, str]:
+    return {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": "zenguard-client/1.0.0",
+    }
+
+
+def _post(path: str, payload: dict, api_key: str, base_url: str) -> dict:
+    url = f"{base_url.rstrip('/')}{path}"
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers=_headers(api_key), method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        try:
+            detail = json.loads(body).get("detail", body)
+        except json.JSONDecodeError:
+            detail = body
+        raise RuntimeError(f"API error {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Could not reach ZenGuard API: {exc.reason}") from exc
+
+
+def _stream(path: str, payload: dict, api_key: str, base_url: str) -> Iterator[str]:
+    url = f"{base_url.rstrip('/')}{path}"
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers={
+        **_headers(api_key),
+        "Accept": "text/plain",
+    }, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            while True:
+                chunk = resp.read(256)
+                if not chunk:
+                    break
+                yield chunk.decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"API error {exc.code}: {body}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Could not reach ZenGuard API: {exc.reason}") from exc
+
+
+class ZenGuardClient:
+    def __init__(self, api_key: str | None = None, api_url: str | None = None) -> None:
+        self._api_key = api_key or config.get_api_key()
+        self._api_url = api_url or config.get_api_url()
+        if not self._api_key:
+            raise RuntimeError(
+                "No API key found. Run `zenguard login` or set ZENGUARD_API_KEY."
+            )
+
+    def scan_github(
+        self,
+        repository: str,
+        token: str | None = None,
+        ref: str | None = None,
+        check_cves: bool = False,
+    ) -> dict:
+        return _post("/v1/scan/github", {
+            "repository": repository,
+            "token": token,
+            "ref": ref,
+            "check_cves": check_cves,
+        }, self._api_key, self._api_url)
+
+    def scan_api(self, url: str) -> dict:
+        return _post("/v1/scan/api", {"url": url}, self._api_key, self._api_url)
+
+    def explain_stream(self, finding: dict) -> Iterator[str]:
+        yield from _stream("/v1/explain", {"finding": finding}, self._api_key, self._api_url)
+
+    def fix_stream(self, finding: dict) -> Iterator[str]:
+        yield from _stream("/v1/fix", {"finding": finding}, self._api_key, self._api_url)
+
+    def triage_stream(self, scan: dict) -> Iterator[str]:
+        yield from _stream("/v1/triage", {"scan": scan}, self._api_key, self._api_url)

zenveil-1.0.0/zenguard/cli.py

@@ -0,0 +1,310 @@
+"""ZenGuard thin CLI client — talks to the ZenGuard API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from zenguard import config
+from zenguard.api_client import ZenGuardClient
+from zenguard.render import render_list, render_scan, render_stats
+
+_LAST_SCAN_FILE = Path(".zenguard-last-scan.json")
+
+
+def _save_scan(result: dict) -> None:
+    _LAST_SCAN_FILE.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+
+
+def _load_scan() -> dict:
+    if not _LAST_SCAN_FILE.exists():
+        raise ValueError("No cached scan found. Run `zenguard scan` first.")
+    return json.loads(_LAST_SCAN_FILE.read_text(encoding="utf-8"))
+
+
+def _client() -> ZenGuardClient:
+    return ZenGuardClient()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="zenguard", description="AI-powered security scanner.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # login
+    login_p = subparsers.add_parser("login", help="Save your ZenGuard API key.")
+    login_p.add_argument("api_key", help="Your ZenGuard API key.")
+    login_p.add_argument("--url", dest="api_url", help="Custom API URL (optional).")
+
+    # scan
+    scan_p = subparsers.add_parser("scan", help="Run a security scan.")
+    scan_sub = scan_p.add_subparsers(dest="target_type", required=True)
+
+    github_p = scan_sub.add_parser("github", help="Scan a GitHub repository.")
+    github_p.add_argument("repository", help="owner/repo or GitHub URL.")
+    github_p.add_argument("--token", dest="token", help="GitHub token for private repos.")
+    github_p.add_argument("--ref", dest="ref", help="Branch, tag, or commit.")
+    github_p.add_argument("--check-cves", action="store_true", dest="check_cves")
+
+    api_p = scan_sub.add_parser("api", help="Scan an API URL.")
+    api_p.add_argument("url", help="API base URL.")
+
+    # list
+    list_p = subparsers.add_parser("list", help="List findings from the last scan.")
+    list_p.add_argument("--severity", dest="severity_filter", help="e.g. high,critical")
+    list_p.add_argument("--scanner", dest="scanner_filter", help="e.g. secrets")
+
+    # stats
+    subparsers.add_parser("stats", help="Show statistics for the last scan.")
+
+    # explain
+    explain_p = subparsers.add_parser("explain", help="AI explanation of a finding.")
+    explain_p.add_argument("finding_id", help="Finding ID (e.g. ZG-ABC123).")
+
+    # fix
+    fix_p = subparsers.add_parser("fix", help="AI-generated fix for a finding.")
+    fix_p.add_argument("finding_id", help="Finding ID (e.g. ZG-ABC123).")
+
+    # triage
+    subparsers.add_parser("triage", help="AI-prioritized remediation plan for all findings.")
+
+    # ignore
+    ignore_p = subparsers.add_parser("ignore", help="Suppress a finding.")
+    ignore_p.add_argument("finding_id", help="Finding ID to ignore.")
+    ignore_p.add_argument("--reason", dest="reason", default="")
+
+    # report
+    report_p = subparsers.add_parser("report", help="Export the last scan.")
+    report_sub = report_p.add_subparsers(dest="report_type", required=True)
+    json_p = report_sub.add_parser("json", help="Write last scan to JSON.")
+    json_p.add_argument("output_file")
+    html_p = report_sub.add_parser("html", help="Write last scan to HTML.")
+    html_p.add_argument("output_file")
+
+    # help
+    subparsers.add_parser("help", help="List all commands.")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "login":
+            data = config.load()
+            data["api_key"] = args.api_key
+            if getattr(args, "api_url", None):
+                data["api_url"] = args.api_url
+            config.save(data)
+            print(f"API key saved to {config._CONFIG_FILE}")
+            return 0
+
+        if args.command == "scan":
+            c = _client()
+            if args.target_type == "github":
+                print(f"Scanning {args.repository}…")
+                result = c.scan_github(
+                    args.repository,
+                    token=getattr(args, "token", None),
+                    ref=getattr(args, "ref", None),
+                    check_cves=getattr(args, "check_cves", False),
+                )
+            else:
+                print(f"Scanning {args.url}…")
+                result = c.scan_api(args.url)
+            print(render_scan(result))
+            _save_scan(result)
+            findings = result.get("findings", [])
+            return 1 if any(f["severity"] in {"HIGH", "CRITICAL"} for f in findings) else 0
+
+        if args.command == "list":
+            result = _load_scan()
+            print(render_list(result.get("findings", []), {
+                "severity": getattr(args, "severity_filter", None),
+                "scanner": getattr(args, "scanner_filter", None),
+            }))
+            return 0
+
+        if args.command == "stats":
+            print(render_stats(_load_scan()))
+            return 0
+
+        if args.command == "explain":
+            result = _load_scan()
+            index = {f["id"]: f for f in result.get("findings", [])}
+            finding = index.get(args.finding_id.upper())
+            if not finding:
+                print(f"Finding {args.finding_id.upper()} not found.", file=sys.stderr)
+                return 2
+            print(f"\nExplaining {finding['id']}: {finding['title']}\n")
+            for chunk in _client().explain_stream(finding):
+                print(chunk, end="", flush=True)
+            print()
+            return 0
+
+        if args.command == "fix":
+            result = _load_scan()
+            index = {f["id"]: f for f in result.get("findings", [])}
+            finding = index.get(args.finding_id.upper())
+            if not finding:
+                print(f"Finding {args.finding_id.upper()} not found.", file=sys.stderr)
+                return 2
+            print(f"\nGenerating fix for {finding['id']}: {finding['title']}\n")
+            for chunk in _client().fix_stream(finding):
+                print(chunk, end="", flush=True)
+            print()
+            return 0
+
+        if args.command == "triage":
+            result = _load_scan()
+            if not result.get("findings"):
+                print("No findings to triage.")
+                return 0
+            print(f"\nTriaging {result['finding_count']} finding(s)…\n")
+            for chunk in _client().triage_stream(result):
+                print(chunk, end="", flush=True)
+            print()
+            return 0
+
+        if args.command == "ignore":
+            result = _load_scan()
+            index = {f["id"]: f for f in result.get("findings", [])}
+            finding = index.get(args.finding_id.upper())
+            if not finding:
+                print(f"Finding {args.finding_id.upper()} not found.", file=sys.stderr)
+                return 2
+            ignore_file = Path(".zenguard-ignore.json")
+            ignored = {}
+            if ignore_file.exists():
+                ignored = json.loads(ignore_file.read_text(encoding="utf-8"))
+            ignored[args.finding_id.upper()] = {
+                "title": finding["title"],
+                "scanner": finding["scanner_name"],
+                "severity": finding["severity"],
+                "reason": args.reason,
+            }
+            ignore_file.write_text(json.dumps(ignored, indent=2) + "\n", encoding="utf-8")
+            print(f"Suppressed {args.finding_id.upper()} ({finding['title']}).")
+            return 0
+
+        if args.command == "report":
+            result = _load_scan()
+            if args.report_type == "json":
+                Path(args.output_file).write_text(
+                    json.dumps(result, indent=2) + "\n", encoding="utf-8"
+                )
+                print(f"Wrote JSON report to {args.output_file}")
+            elif args.report_type == "html":
+                _write_html_report(result, args.output_file)
+                print(f"Wrote HTML report to {args.output_file}")
+            return 0
+
+        if args.command == "help":
+            _print_help()
+            return 0
+
+    except (RuntimeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    return 0
+
+
+def _write_html_report(result: dict, output_file: str) -> None:
+    import html as h
+    findings = result.get("findings", [])
+    _SEV_COLOR = {"CRITICAL": "#c0392b", "HIGH": "#e67e22", "MEDIUM": "#f1c40f", "LOW": "#2ecc71"}
+    _SEV_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+    sorted_findings = sorted(findings, key=lambda f: _SEV_ORDER.get(f["severity"].upper(), 99))
+    findings_html = ""
+    for f in sorted_findings:
+        color = _SEV_COLOR.get(f["severity"].upper(), "#888")
+        loc = f["location"]
+        loc_str = loc.get("target", "")
+        if loc.get("path"):
+            loc_str += f" → {loc['path']}"
+        if loc.get("line"):
+            loc_str += f" : line {loc['line']}"
+        findings_html += f"""
+        <div class="finding">
+          <div class="finding-header" style="border-left:6px solid {color}">
+            <span class="badge" style="background:{color}">{h.escape(f['severity'])}</span>
+            <span class="fid">{h.escape(f['id'])}</span>
+            <span class="ftitle">{h.escape(f['title'])}</span>
+          </div>
+          <div class="finding-body">
+            <table>
+              <tr><th>Scanner</th><td>{h.escape(f['scanner_name'])}</td></tr>
+              <tr><th>Location</th><td>{h.escape(loc_str)}</td></tr>
+              <tr><th>Evidence</th><td><code>{h.escape(f['evidence'])}</code></td></tr>
+              <tr><th>Description</th><td>{h.escape(f['description'])}</td></tr>
+              <tr><th>Remediation</th><td>{h.escape(f['remediation'])}</td></tr>
+            </table>
+          </div>
+        </div>"""
+    page = f"""<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"/>
+<title>ZenGuard Report — {h.escape(result.get('target',''))}</title>
+<style>body{{font-family:sans-serif;background:#f4f6f9;color:#222;padding:24px}}
+.finding{{background:#fff;border-radius:6px;margin-bottom:16px;box-shadow:0 1px 4px rgba(0,0,0,.1);overflow:hidden}}
+.finding-header{{display:flex;align-items:center;gap:10px;padding:12px 16px;background:#fafafa}}
+.badge{{color:#fff;border-radius:4px;padding:2px 8px;font-weight:700;font-size:.78rem;text-transform:uppercase}}
+.fid{{font-family:monospace;font-size:.85rem;color:#555}}.ftitle{{font-weight:600}}
+.finding-body{{padding:12px 16px}}table{{border-collapse:collapse;width:100%;font-size:.88rem}}
+th{{text-align:left;color:#555;font-weight:600;width:110px;padding:4px 8px 4px 0;vertical-align:top}}
+code{{background:#f0f0f0;padding:1px 4px;border-radius:3px;font-size:.82rem;word-break:break-all}}
+</style></head><body>
+<h1>ZenGuard Security Report</h1>
+<p>Target: <strong>{h.escape(result.get('target',''))}</strong> | Findings: {result.get('finding_count',0)}</p>
+{findings_html if findings_html else '<p>No findings.</p>'}
+</body></html>"""
+    Path(output_file).write_text(page, encoding="utf-8")
+
+
+def _print_help() -> None:
+    print("""
+ZenGuard — AI-powered security scanner
+=======================================
+
+ACCOUNT
+  zenguard login <api-key>              Save your API key
+
+SCANNING
+  zenguard scan github <owner/repo>     Scan a GitHub repository
+  zenguard scan github <url> --token    Use a GitHub token for private repos
+  zenguard scan api <url>               Scan an API endpoint
+
+FINDINGS
+  zenguard list                         List findings from the last scan
+  zenguard list --severity high,critical
+  zenguard list --scanner secrets
+  zenguard stats                        Scan statistics
+
+AI ANALYSIS
+  zenguard explain <id>                 Explain a finding
+  zenguard fix <id>                     Generate a fix
+  zenguard triage                       Prioritized remediation plan
+
+REPORTING
+  zenguard report json <file>           Export to JSON
+  zenguard report html <file>           Export to HTML
+
+MANAGEMENT
+  zenguard ignore <id>                  Suppress a finding
+  zenguard ignore <id> --reason "text"
+  zenguard help                         Show this help
+
+ENVIRONMENT VARIABLES
+  ZENGUARD_API_KEY    Your ZenGuard API key
+  ZENGUARD_API_URL    Custom API URL (default: https://api.zenveil.dev)
+  GITHUB_TOKEN        GitHub token for private repo scans
+
+Get your API key at https://zenveil.dev
+""")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zenveil-1.0.0/zenguard/config.py

@@ -0,0 +1,35 @@
+"""Stores ZenGuard API key and server URL locally."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+_CONFIG_DIR = Path.home() / ".zenguard"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+
+DEFAULT_API_URL = "https://api.zenveil.dev"
+
+
+def load() -> dict:
+    if _CONFIG_FILE.exists():
+        try:
+            return json.loads(_CONFIG_FILE.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def save(data: dict) -> None:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    _CONFIG_FILE.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    _CONFIG_FILE.chmod(0o600)
+
+
+def get_api_key() -> str | None:
+    return os.environ.get("ZENGUARD_API_KEY") or load().get("api_key")
+
+
+def get_api_url() -> str:
+    return os.environ.get("ZENGUARD_API_URL") or load().get("api_url") or DEFAULT_API_URL

zenveil-1.0.0/zenguard/render.py

@@ -0,0 +1,97 @@
+"""Console rendering for scan results from the API."""
+
+from __future__ import annotations
+
+_SEV_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+_SEV_PREFIX = {"CRITICAL": "[CRITICAL]", "HIGH": "[HIGH]", "MEDIUM": "[MEDIUM]", "LOW": "[LOW]"}
+
+
+def render_scan(result: dict) -> str:
+    findings = result.get("findings", [])
+    counts: dict[str, int] = {}
+    for f in findings:
+        sev = f["severity"].upper()
+        counts[sev] = counts.get(sev, 0) + 1
+
+    sev_str = ", ".join(
+        f"{s}={counts.get(s, 0)}"
+        for s in ["LOW", "MEDIUM", "HIGH", "CRITICAL"]
+    )
+
+    lines = [
+        "",
+        "ZenGuard Scan Report",
+        f"Target: {result.get('target_type', '')} {result.get('target', '')}",
+        f"Findings: {result.get('finding_count', 0)}",
+        f"Severity: {sev_str}",
+        "",
+    ]
+
+    sorted_findings = sorted(findings, key=lambda f: _SEV_ORDER.get(f["severity"].upper(), 99))
+    for f in sorted_findings:
+        sev = f["severity"].upper()
+        prefix = _SEV_PREFIX.get(sev, f"[{sev}]")
+        loc = f["location"]
+        location_str = loc.get("path") or loc.get("url") or loc.get("target", "")
+        if loc.get("line"):
+            location_str = f"{location_str}:{loc['line']}"
+
+        lines += [
+            f"{prefix} {f['title']}",
+            f"ID: {f['id']}",
+            f"Category: {f['category']}",
+            f"Scanner: {f['scanner_name']}",
+            f"Location: {location_str}",
+            f"Evidence: {f['evidence']}",
+            f"Description: {f['description']}",
+            f"Remediation: {f['remediation']}",
+            "",
+        ]
+
+    return "\n".join(lines)
+
+
+def render_list(findings: list[dict], filters: dict | None = None) -> str:
+    if filters:
+        sev = {s.strip().lower() for s in (filters.get("severity") or "").split(",") if s.strip()}
+        scanner = (filters.get("scanner") or "").lower()
+        if sev:
+            findings = [f for f in findings if f["severity"].lower() in sev]
+        if scanner:
+            findings = [f for f in findings if f["scanner_name"].lower() == scanner]
+
+    if not findings:
+        return "No findings match the given filters."
+
+    sorted_findings = sorted(findings, key=lambda f: (_SEV_ORDER.get(f["severity"].upper(), 99), f["title"]))
+    lines = [f"\n{'ID':<18} {'SEV':<9} {'SCANNER':<15} {'TITLE'}", "-" * 80]
+    for f in sorted_findings:
+        lines.append(f"{f['id']:<18} {f['severity']:<9} {f['scanner_name']:<15} {f['title']}")
+    lines.append(f"\n{len(sorted_findings)} finding(s) shown.\n")
+    return "\n".join(lines)
+
+
+def render_stats(result: dict) -> str:
+    findings = result.get("findings", [])
+    sev_counts: dict[str, int] = {}
+    scanner_counts: dict[str, int] = {}
+    for f in findings:
+        sev_counts[f["severity"]] = sev_counts.get(f["severity"], 0) + 1
+        scanner_counts[f["scanner_name"]] = scanner_counts.get(f["scanner_name"], 0) + 1
+
+    lines = [
+        f"\nScan target  : {result.get('target')} ({result.get('target_type')})",
+        f"Started      : {result.get('started_at')}",
+        f"Completed    : {result.get('completed_at')}",
+        f"Total findings: {result.get('finding_count', 0)}",
+    ]
+    if sev_counts:
+        lines.append("\nBy severity:")
+        for sev in sorted(sev_counts, key=lambda s: _SEV_ORDER.get(s.upper(), 99)):
+            lines.append(f"  {sev:<10} {sev_counts[sev]}")
+    if scanner_counts:
+        lines.append("\nBy scanner:")
+        for sc, cnt in sorted(scanner_counts.items(), key=lambda x: -x[1]):
+            lines.append(f"  {sc:<20} {cnt}")
+    lines.append("")
+    return "\n".join(lines)

zenveil-1.0.0/zenveil.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.1
+Name: zenveil
+Version: 1.0.0
+Summary: AI-powered security scanner for repositories and APIs.
+Project-URL: Homepage, https://zenveil.dev
+Project-URL: Documentation, https://zenveil.dev/docs
+Project-URL: Repository, https://github.com/oyugirachel/zen-guard
+Requires-Python: >=3.8

zenveil-1.0.0/zenveil.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+pyproject.toml
+zenguard/__init__.py
+zenguard/api_client.py
+zenguard/cli.py
+zenguard/config.py
+zenguard/render.py
+zenveil.egg-info/PKG-INFO
+zenveil.egg-info/SOURCES.txt
+zenveil.egg-info/dependency_links.txt
+zenveil.egg-info/entry_points.txt
+zenveil.egg-info/top_level.txt

zenveil-1.0.0/zenveil.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zenveil-1.0.0/zenveil.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zenguard = zenguard.cli:main

zenveil-1.0.0/zenveil.egg-info/top_level.txt

@@ -0,0 +1 @@
+zenguard