virgilhq 0.3.0__tar.gz

virgilhq-0.3.0/.gitignore

@@ -0,0 +1,65 @@
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+*.pid
+*.log
+build/
+dist/
+venv/
+.venv/
+env/
+
+# Node / Next.js
+node_modules/
+.next/
+out/
+*.tsbuildinfo
+next-env.d.ts
+.npm
+.eslintcache
+yarn-error.log
+npm-debug.log*
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Audit runtime artifacts
+/var/
+audit-*.pdf
+audit-*.md
+audit-*.json
+audit-*.sarif
+audit-*.csv
+audit-*.xlsx
+
+# Local docker / state
+docker/data/
+*.sqlite
+*.sqlite3
+
+# Secrets — defense in depth (we never want a real .env or token file
+# committed; .env.example is the only env file that should be tracked).
+*.pem
+*.key
+*.p12
+.github-token
+secrets/

virgilhq-0.3.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: virgilhq
+Version: 0.3.0
+Summary: CLI for Virgil — self-hosted security audit with the triage built in. Real scanners + clustering + LLM priority queue + code-grounded chat. Installs as `virgil` on your PATH.
+Project-URL: Homepage, https://virgilhq.app
+Project-URL: Repository, https://github.com/ayaanmaliksgithub/virgil
+Project-URL: Issues, https://github.com/ayaanmaliksgithub/virgil/issues
+Project-URL: Documentation, https://github.com/ayaanmaliksgithub/virgil#readme
+Project-URL: Changelog, https://github.com/ayaanmaliksgithub/virgil/releases
+Author: Virgil contributors
+License: Apache-2.0
+Keywords: ai,audit,cli,code-audit,gitleaks,llm,sast,sca,security,self-hosted,semgrep,trivy,vulnerability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# virgil
+
+> Terminal client for [Virgil](https://github.com/ayaanmaliksgithub/virgil) —
+> self-hosted security audit with the triage built in. Real scanners +
+> clustering + LLM priority queue + code-grounded chat.
+
+The CLI is a thin shell over a running Virgil API. It bundles your working
+directory, submits a scan, streams progress, and prints the ranked findings
+with CI-friendly exit codes.
+
+## Install
+
+```bash
+pip install virgilhq        # or: pipx install virgilhq
+```
+
+The PyPI package is `virgilhq` (the bare `virgil` name was already taken).
+The command on your `$PATH` is still just `virgil`.
+
+You'll also need a running Virgil instance. The standard self-hosted setup
+is `docker compose up` from the [main repo](https://github.com/ayaanmaliksgithub/virgil)
+— takes about a minute the first time.
+
+## Usage
+
+```bash
+# Scan and land on triage (counts → ranked clusters → next-steps hint).
+virgil scan .
+
+# Or land on a different surface after the scan finishes.
+virgil scan . --show report        # exec narrative
+virgil scan . --show surface       # languages / frameworks / IaC profile
+virgil scan . --show ask_virgil    # drop into the chat REPL pre-flighted
+
+# Scan a GitHub URL instead of a local path.
+virgil scan --url https://github.com/OWASP/NodeGoat
+
+# PR mode — only flag findings on lines changed between two SHAs.
+virgil scan . --base-sha abc1234 --head-sha def5678
+
+# Don't wait for the scan to finish; print the audit ID and return.
+virgil scan . --no-wait
+
+# After a scan, drill in:
+virgil clusters <audit-id>               # every cluster, sorted by severity
+virgil clusters <audit-id> --sev high    # filter
+virgil cluster  <audit-id> <key>         # one cluster in detail (prefix match ok)
+virgil findings <audit-id>               # raw findings table
+virgil chat     <audit-id>               # interactive Q&A grounded in this audit
+virgil chat     <audit-id> -m "what's the worst finding?"   # one-shot
+virgil open     <audit-id>               # launch the web app on the triage tab
+virgil open     <audit-id> --page chat   # …or chat / findings / report / attack-surface
+virgil status   <audit-id>
+
+# Reports in any supported format.
+virgil report <audit-id> --format md
+virgil report <audit-id> --format sarif -o findings.sarif
+virgil report <audit-id> --format json
+virgil report <audit-id> --format pdf
+```
+
+## Config
+
+Persistent settings live in `~/.config/virgil/config.json`:
+
+```bash
+virgil config show
+virgil config set api_url=https://virgil.example.com/api
+virgil config set web_url=https://virgil.example.com
+virgil config set default_fail_on=high
+virgil config set default_post_scan_view=ask_virgil     # triage | report | surface | ask_virgil
+virgil config unset default_fail_on
+virgil config path
+```
+
+Resolution order for each setting: **env var → config file → built-in default.**
+
+## CI integration
+
+```bash
+virgil scan . --fail-on critical     # exits 1 on any Critical
+virgil scan . --fail-on high         # exits 1 on Critical or High
+virgil scan . --fail-on never        # always exits 0
+```
+
+Exit codes:
+
+| Code | Meaning |
+| ---: | --- |
+| `0` | scan finished, no findings exceeded `--fail-on` |
+| `1` | scan finished, findings exceed the configured threshold |
+| `2` | the audit itself failed (clone error, scanner crash, etc.) |
+| `3` | could not reach the Virgil API |
+
+## Environment
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `VIRGIL_API` | `http://localhost:8000` | API base URL. |
+| `VIRGIL_WEB` | `http://localhost:3000` | Web app base URL used by `virgil open`. |
+| `VIRGIL_FAIL_ON` | `critical` | Default `--fail-on` threshold for `virgil scan`. |
+| `VIRGIL_SHOW` | `triage` | Default `--show` surface after `virgil scan` (`triage` / `report` / `surface` / `ask_virgil`). |
+| `VIRGIL_CONFIG_DIR` | `~/.config/virgil` | Override the config directory. |
+
+## What the output looks like
+
+```
+$ virgil scan .
+bundle /work/myrepo → zip → submit
+┌─ [ virgil ] ───────────────────────────────────────────────────────────────┐
+│ audit_id  c9b1…                                                            │
+│ source    scan.zip                                                         │
+│ state     succeeded  phase=completed                                       │
+└────────────────────────────────────────────────────────────────────────────┘
+
+ CRIT  HIGH  MED   LOW   INFO  KEV  unreach
+   2     7    14    6     3     1     19
+
+╭─ [ fix.this_week() · ranked ] ─────────────────────────────────────────────╮
+│ #01 [ CRIT ]  Hard-coded AWS access key in source  ×3                      │
+│      Critical credential exposure with CISA-KEV-adjacent risk profile…     │
+│ #02 [ HIGH ]  SQL injection via raw query helper  ×12                      │
+│      12 callsites share src/db/query.py — fix the helper, not callsites.   │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/ayaanmaliksgithub/virgil/blob/main/LICENSE).

virgilhq-0.3.0/README.md

@@ -0,0 +1,129 @@
+# virgil
+
+> Terminal client for [Virgil](https://github.com/ayaanmaliksgithub/virgil) —
+> self-hosted security audit with the triage built in. Real scanners +
+> clustering + LLM priority queue + code-grounded chat.
+
+The CLI is a thin shell over a running Virgil API. It bundles your working
+directory, submits a scan, streams progress, and prints the ranked findings
+with CI-friendly exit codes.
+
+## Install
+
+```bash
+pip install virgilhq        # or: pipx install virgilhq
+```
+
+The PyPI package is `virgilhq` (the bare `virgil` name was already taken).
+The command on your `$PATH` is still just `virgil`.
+
+You'll also need a running Virgil instance. The standard self-hosted setup
+is `docker compose up` from the [main repo](https://github.com/ayaanmaliksgithub/virgil)
+— takes about a minute the first time.
+
+## Usage
+
+```bash
+# Scan and land on triage (counts → ranked clusters → next-steps hint).
+virgil scan .
+
+# Or land on a different surface after the scan finishes.
+virgil scan . --show report        # exec narrative
+virgil scan . --show surface       # languages / frameworks / IaC profile
+virgil scan . --show ask_virgil    # drop into the chat REPL pre-flighted
+
+# Scan a GitHub URL instead of a local path.
+virgil scan --url https://github.com/OWASP/NodeGoat
+
+# PR mode — only flag findings on lines changed between two SHAs.
+virgil scan . --base-sha abc1234 --head-sha def5678
+
+# Don't wait for the scan to finish; print the audit ID and return.
+virgil scan . --no-wait
+
+# After a scan, drill in:
+virgil clusters <audit-id>               # every cluster, sorted by severity
+virgil clusters <audit-id> --sev high    # filter
+virgil cluster  <audit-id> <key>         # one cluster in detail (prefix match ok)
+virgil findings <audit-id>               # raw findings table
+virgil chat     <audit-id>               # interactive Q&A grounded in this audit
+virgil chat     <audit-id> -m "what's the worst finding?"   # one-shot
+virgil open     <audit-id>               # launch the web app on the triage tab
+virgil open     <audit-id> --page chat   # …or chat / findings / report / attack-surface
+virgil status   <audit-id>
+
+# Reports in any supported format.
+virgil report <audit-id> --format md
+virgil report <audit-id> --format sarif -o findings.sarif
+virgil report <audit-id> --format json
+virgil report <audit-id> --format pdf
+```
+
+## Config
+
+Persistent settings live in `~/.config/virgil/config.json`:
+
+```bash
+virgil config show
+virgil config set api_url=https://virgil.example.com/api
+virgil config set web_url=https://virgil.example.com
+virgil config set default_fail_on=high
+virgil config set default_post_scan_view=ask_virgil     # triage | report | surface | ask_virgil
+virgil config unset default_fail_on
+virgil config path
+```
+
+Resolution order for each setting: **env var → config file → built-in default.**
+
+## CI integration
+
+```bash
+virgil scan . --fail-on critical     # exits 1 on any Critical
+virgil scan . --fail-on high         # exits 1 on Critical or High
+virgil scan . --fail-on never        # always exits 0
+```
+
+Exit codes:
+
+| Code | Meaning |
+| ---: | --- |
+| `0` | scan finished, no findings exceeded `--fail-on` |
+| `1` | scan finished, findings exceed the configured threshold |
+| `2` | the audit itself failed (clone error, scanner crash, etc.) |
+| `3` | could not reach the Virgil API |
+
+## Environment
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `VIRGIL_API` | `http://localhost:8000` | API base URL. |
+| `VIRGIL_WEB` | `http://localhost:3000` | Web app base URL used by `virgil open`. |
+| `VIRGIL_FAIL_ON` | `critical` | Default `--fail-on` threshold for `virgil scan`. |
+| `VIRGIL_SHOW` | `triage` | Default `--show` surface after `virgil scan` (`triage` / `report` / `surface` / `ask_virgil`). |
+| `VIRGIL_CONFIG_DIR` | `~/.config/virgil` | Override the config directory. |
+
+## What the output looks like
+
+```
+$ virgil scan .
+bundle /work/myrepo → zip → submit
+┌─ [ virgil ] ───────────────────────────────────────────────────────────────┐
+│ audit_id  c9b1…                                                            │
+│ source    scan.zip                                                         │
+│ state     succeeded  phase=completed                                       │
+└────────────────────────────────────────────────────────────────────────────┘
+
+ CRIT  HIGH  MED   LOW   INFO  KEV  unreach
+   2     7    14    6     3     1     19
+
+╭─ [ fix.this_week() · ranked ] ─────────────────────────────────────────────╮
+│ #01 [ CRIT ]  Hard-coded AWS access key in source  ×3                      │
+│      Critical credential exposure with CISA-KEV-adjacent risk profile…     │
+│ #02 [ HIGH ]  SQL injection via raw query helper  ×12                      │
+│      12 callsites share src/db/query.py — fix the helper, not callsites.   │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/ayaanmaliksgithub/virgil/blob/main/LICENSE).

virgilhq-0.3.0/cli/__init__.py

@@ -0,0 +1,10 @@
+"""Virgil CLI.
+
+Thin terminal client for Virgil — the security audit platform. Submits
+scans, streams audit progress, prints findings, fetches reports — talks
+to a running API instance (default `http://localhost:8000`). The CLI
+never runs scanners itself; that work belongs in the sandboxed worker.
+
+Distribution: `pip install virgil` (or via `pipx`).
+"""
+__version__ = "0.3.0"

virgilhq-0.3.0/cli/client.py

@@ -0,0 +1,196 @@
+"""HTTP client for the audit API.
+
+Thin wrapper over `requests`. Centralizes the base URL + error handling so
+the command modules stay readable. Does NOT carry retry logic — a CLI
+session is interactive, and silent retries on top of `requests` calls
+hide signal a user wants to see (network down, server hung).
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Iterator
+
+import requests
+
+from cli import config
+
+
+HTTP_TIMEOUT = 30
+CHAT_TIMEOUT = 120  # LLM round-trips can sit well past the default.
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, detail: str = ""):
+        super().__init__(f"API {status}: {detail}".rstrip(": "))
+        self.status = status
+        self.detail = detail
+
+
+class ApiUnreachable(RuntimeError):
+    """Network failure — distinct from a 5xx so the CLI can suggest
+    `docker compose up` vs. "check API logs"."""
+
+
+def _base_url() -> str:
+    return config.api_url().rstrip("/")
+
+
+def _request(method: str, path: str, **kwargs) -> requests.Response:
+    url = _base_url() + path
+    kwargs.setdefault("timeout", HTTP_TIMEOUT)
+    try:
+        res = requests.request(method, url, **kwargs)
+    except requests.exceptions.ConnectionError as e:
+        raise ApiUnreachable(str(e)) from e
+    except requests.exceptions.Timeout as e:
+        raise ApiUnreachable(f"timeout after {HTTP_TIMEOUT}s") from e
+    if not res.ok:
+        raise ApiError(res.status_code, res.text[:500])
+    return res
+
+
+def submit_zip(zip_path: Path) -> dict:
+    with zip_path.open("rb") as f:
+        files = {"file": (zip_path.name, f, "application/zip")}
+        res = _request("POST", "/v1/audits", files=files)
+    return res.json()
+
+
+def submit_url(repo_url: str, *, base_sha: str | None = None, head_sha: str | None = None) -> dict:
+    body: dict = {"repo_url": repo_url}
+    if base_sha and head_sha:
+        body["base_sha"] = base_sha
+        body["head_sha"] = head_sha
+    res = _request("POST", "/v1/audits/json", json=body)
+    return res.json()
+
+
+def get_audit(audit_id: str) -> dict:
+    return _request("GET", f"/v1/audits/{audit_id}").json()
+
+
+def list_findings(audit_id: str, *, include_suppressed: bool = False) -> list[dict]:
+    params = {}
+    if include_suppressed:
+        params["include_suppressed"] = "true"
+    return _request("GET", f"/v1/audits/{audit_id}/findings", params=params).json()["items"]
+
+
+def get_clusters(audit_id: str, *, include_unreachable: bool = False) -> dict:
+    params = {"include_unreachable": "true"} if include_unreachable else {}
+    return _request("GET", f"/v1/audits/{audit_id}/findings/clusters", params=params).json()
+
+
+def get_finding(finding_id: str) -> dict:
+    return _request("GET", f"/v1/findings/{finding_id}").json()
+
+
+def get_suggested_questions(audit_id: str) -> list[str]:
+    return _request("GET", f"/v1/audits/{audit_id}/chat/suggested").json().get("items", [])
+
+
+def post_chat(audit_id: str, message: str, *, session_id: str | None = None) -> dict:
+    body: dict = {"message": message}
+    if session_id:
+        body["session_id"] = session_id
+    res = _request("POST", f"/v1/audits/{audit_id}/chat", json=body, timeout=CHAT_TIMEOUT)
+    return res.json()
+
+
+def post_chat_stream(audit_id: str, message: str, *, session_id: str | None = None) -> Iterator[dict]:
+    """Stream chat tokens as SSE.
+
+    Yields decoded events: `{"event": "session"|"token"|"done"|"error", "data": ...}`
+    where `data` is the already-JSON-decoded payload from the SSE frame.
+
+    On `done` the caller should replace whatever tokens were rendered with the
+    final `message.content`: the safety validator runs at end-of-stream and
+    may refuse — in which case the visible tokens are stale.
+    """
+    body: dict = {"message": message}
+    if session_id:
+        body["session_id"] = session_id
+    url = _base_url() + f"/v1/audits/{audit_id}/chat/stream"
+    try:
+        with requests.post(url, json=body, stream=True, timeout=CHAT_TIMEOUT) as res:
+            if not res.ok:
+                raise ApiError(res.status_code, res.text[:500])
+            event = "message"
+            data_lines: list[str] = []
+            for raw in res.iter_lines(decode_unicode=True):
+                if raw is None:
+                    continue
+                if raw == "":
+                    if data_lines:
+                        import json as _json
+                        joined = "\n".join(data_lines)
+                        try:
+                            payload = _json.loads(joined)
+                        except _json.JSONDecodeError:
+                            payload = {"raw": joined}
+                        yield {"event": event, "data": payload}
+                    event, data_lines = "message", []
+                    continue
+                if raw.startswith(":"):
+                    continue
+                if raw.startswith("event:"):
+                    event = raw[6:].strip()
+                elif raw.startswith("data:"):
+                    data_lines.append(raw[5:].lstrip(" "))
+    except requests.exceptions.ConnectionError as e:
+        raise ApiUnreachable(str(e)) from e
+
+
+def get_chat_session(audit_id: str, session_id: str) -> dict:
+    return _request("GET", f"/v1/audits/{audit_id}/chat/{session_id}").json()
+
+
+def get_report(audit_id: str, *, view: str = "technical", format: str = "json") -> bytes:
+    res = _request(
+        "GET",
+        f"/v1/audits/{audit_id}/report",
+        params={"view": view, "format": format},
+    )
+    return res.content
+
+
+def stream_events(audit_id: str) -> Iterator[dict]:
+    """Yield decoded SSE event dicts until the stream ends.
+
+    Each event looks like `{"event": "log"|"done", "phase": str, "message": str}`.
+    """
+    url = _base_url() + f"/v1/audits/{audit_id}/events"
+    try:
+        with requests.get(url, stream=True, timeout=None) as res:
+            if not res.ok:
+                raise ApiError(res.status_code, res.text[:500])
+            event = "message"
+            data_lines: list[str] = []
+            for raw in res.iter_lines(decode_unicode=True):
+                if raw is None:
+                    continue
+                if raw == "":
+                    if data_lines:
+                        yield {"event": event, "data": "\n".join(data_lines)}
+                    event, data_lines = "message", []
+                    continue
+                if raw.startswith(":"):
+                    continue
+                if raw.startswith("event:"):
+                    event = raw[6:].strip()
+                elif raw.startswith("data:"):
+                    data_lines.append(raw[5:].lstrip(" "))
+    except requests.exceptions.ConnectionError as e:
+        raise ApiUnreachable(str(e)) from e
+
+
+def poll_until_terminal(audit_id: str, *, interval: float = 1.5, max_seconds: float = 1800) -> dict:
+    """Polling fallback when SSE is unavailable. Returns the final audit dict."""
+    deadline = time.time() + max_seconds
+    while time.time() < deadline:
+        audit = get_audit(audit_id)
+        if audit["state"] in ("succeeded", "failed"):
+            return audit
+        time.sleep(interval)
+    raise TimeoutError(f"audit {audit_id} did not finish within {max_seconds}s")

virgilhq-0.3.0/cli/config.py

@@ -0,0 +1,77 @@
+"""Persisted CLI config — `~/.config/virgil/config.json`.
+
+Precedence for each setting: env var > config file > built-in default.
+JSON over TOML to avoid a stdlib gap on Python 3.10 (`tomllib` is 3.11+).
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+CONFIG_DIR = Path(os.environ.get("VIRGIL_CONFIG_DIR", str(Path.home() / ".config" / "virgil")))
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+DEFAULT_API_URL = "http://localhost:8000"
+DEFAULT_WEB_URL = "http://localhost:3000"
+DEFAULT_FAIL_ON = "critical"
+DEFAULT_POST_SCAN_VIEW = "triage"
+
+# Keys we know about — used by `virgil config set` to reject typos before
+# they end up silently ignored on disk.
+KNOWN_KEYS = {"api_url", "web_url", "default_fail_on", "default_post_scan_view"}
+
+
+def load() -> dict[str, Any]:
+    if not CONFIG_PATH.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_PATH.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def save(data: dict[str, Any]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+
+
+def get(key: str, default: Any = None) -> Any:
+    return load().get(key, default)
+
+
+def set_(key: str, value: str) -> None:
+    data = load()
+    data[key] = value
+    save(data)
+
+
+def unset(key: str) -> bool:
+    data = load()
+    if key not in data:
+        return False
+    del data[key]
+    save(data)
+    return True
+
+
+def api_url() -> str:
+    return os.environ.get("VIRGIL_API") or get("api_url") or DEFAULT_API_URL
+
+
+def web_url() -> str:
+    return os.environ.get("VIRGIL_WEB") or get("web_url") or DEFAULT_WEB_URL
+
+
+def default_fail_on() -> str:
+    return os.environ.get("VIRGIL_FAIL_ON") or get("default_fail_on") or DEFAULT_FAIL_ON
+
+
+def default_post_scan_view() -> str:
+    return (
+        os.environ.get("VIRGIL_SHOW")
+        or get("default_post_scan_view")
+        or DEFAULT_POST_SCAN_VIEW
+    )