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).
