Get started

Quickstart

Run a scan on a repository, read the verdict, and connect GitHub so agents start auditing on their own. This takes about ten minutes.

#Before you begin

You need a Mac running macOS 14 or later on Apple Silicon, and the Xcode Command Line Tools, which provide python3 and git. If they are missing, run this once.

xcode-select --install

#1. Run your first scan

The scanner is a single command that reads a folder and prints a JSON verdict. It uses only the Python standard library, so there is nothing to install. Point PYTHONPATH at the python folder of your Kelvar install and scan any repository.

PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli scan ./your-repo

The output is a verdict, a count by severity, and a list of findings.

{
  "target": "/work/your-repo",
  "verdict": "block",
  "summary": { "critical": 1, "medium": 1 },
  "findings": [
    {
      "check": "zero_click",
      "severity": "critical",
      "path": "webhook_handler.py",
      "line": 4,
      "message": "unsafe deserialization sink (zero-click RCE vector)"
    },
    {
      "check": "deps",
      "severity": "medium",
      "path": "requirements.txt",
      "line": 1,
      "message": "requests 2.30.0 affected by CVE-2023-32681: Proxy-Authorization header leak"
    }
  ]
}

The verdict is block when any finding is high or critical, and pass otherwise. The command exits with status 1 when it blocks, so you can use it directly in a script or a CI job. See Gate merges.

To scan only the files with uncommitted changes, add --diff. It reads git status, so on a clean checkout it scans nothing.

PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli scan . --diff

#2. Open the app

Agents run inside the Kelvar app. On first launch the app walks you through setup.

1. Choose a model provider. Sign in with ChatGPT, or enter a key for another provider. See Bring your own model.
2. Set a local password. It guards the app on this machine.
3. Start the system. The embedded terminal prepares a command that ends in vigil up. Press Enter and wait for the ready state.
4. Pick a starting structure. Setup creates Home and five security projects. Select Set up Kelvar.
5. Say something in Home. A reply proves the model connection.

#3. Connect GitHub

Open Applications, choose GitHub, and paste a personal access token with read access. Kelvar connects through a read-only guard, so it can read repositories, pull requests, workflows and alerts but cannot push or merge.

Connecting starts an audit automatically and repeats it every 24 hours. You do not need to ask. Details are in Connect GitHub.

#4. Read your findings

Open Dashboard. It opens on the Findings screen, which lists every confirmed finding with its severity, file, line, evidence and remediation. Repeat audits merge into the same row, so the list stays short.

From any finding you can hand work to an agent.

#Next steps

• Read How Kelvar works to understand what happened during that first audit.
• Add the scanner to your CI with Gate merges.
• Check Pricing and billing before you use Kelvar on a private repository.