Command-line interface

The vulnara command-line interface is a single binary that talks to the Vulnara GraphQL API. It gives you one command for each API operation, so you can list repositories, start scans and read findings from a terminal or a script. It prints results as JSON.

What it is for

• Starting scans and reading results without opening the web app.
• Scripting against Vulnara, with a service account instead of a person's login.
• Pulling findings into other tools as JSON files.

How it works

Each command maps to one API operation, named in snake case: repositories, start_repository_scan, scan_findings. A command's flags are the fields of that operation's input, so start_repository_scan takes --repositoryId, --branch, --dockerScanToolId and so on. Run vulnara --help for the list, and vulnara <command> --help for a command's flags.

Before each command, the CLI finds an access token, picks the workspace, sends the request, and prints the result.

Besides the API commands, there are four of its own: login, set_default_tenant, completion and add_to_path.

What you can set

• --tenant: run one command against this workspace instead of your default one. Works on every API command.
• --output: write the raw JSON result to a file instead of printing it. Works on every API command.
• --filters (or -f): on list commands, filter by field=value. Repeat it to add more filters.
• --limit and --skip: on list commands, page through results.
• --sort and --order: on list commands, sort by a field, ASC or DESC.
• --search: on list commands, a free-text search.
• VULNARA_TIMEOUT: how long a request may take, in seconds. The default is 300.
• VULNARA_LOG_LEVEL and VULNARA_LOG_FORMAT: turn on diagnostic logs (debug, info, warn, error) as json or text. They are off by default.

Do it

1. Install

   The CLI is distributed as release archives for Linux x86_64, macOS on Apple silicon and Intel, and Windows x86_64: vulnara-cli_Linux_x86_64.tar.gz, vulnara-cli_Darwin_arm64.tar.gz, vulnara-cli_Darwin_x86_64.tar.gz and vulnara-cli_Windows_x86_64.zip. Unpack the archive. The binary inside is called vulnara and needs no other setup.

   To put it on your PATH, run it once from where you unpacked it:

   shKopieren

   ./vulnara add_to_path

   This adds the binary's directory to ~/.bashrc, ~/.zshrc and ~/.bash_profile, and to ~/.config/fish/config.fish, but only to the files that already exist. Restart your shell afterwards.

2. Sign in

   shKopieren

   vulnara login

   Your browser opens the Vulnara sign-in page. Sign in within 3 minutes. The CLI receives the tokens on a local port between 10000 and 10010, and stores them. It renews them by itself when they expire.

3. Set a default workspace

   shKopieren

   vulnara set_default_tenant --tenant my-workspace

   Every command now runs against my-workspace unless you pass --tenant.

4. Run a command

   shKopieren

   vulnara repositories --limit 20
   vulnara repositories --filters repositoryName=my-app
   vulnara start_repository_scan --repositoryId <id> --dockerScanToolId <id> --branch main
   vulnara scan_findings --filters scanResultId=<id> --output findings.json

The full list of commands and their flags is on the CLI reference.

Use a service account in scripts and CI

For a machine with no browser, use a service account. Write its name and token to ~/.config/vulnara/sa/service_account.json:

{ "username": "<service account name>", "password": "<token>" }

When this file is filled in, the CLI signs in with it on every run and needs no login. Set the workspace with set_default_tenant or --tenant as usual.

Shell completion

vulnara completion bash
vulnara completion fish

• bash: adds a line to ~/.bashrc that loads completion, and prints the completion script.
• fish: writes ~/.config/fish/completions/vulnara.fish.
• zsh: vulnara completion zsh does nothing yet. Add . <(vulnara completion zsh) to ~/.zshrc yourself.
• PowerShell: vulnara completion powershell prints the line to add to your profile instead of installing it.

Where the CLI keeps its state

Everything lives under ~/.config/vulnara/:

• sa/service_account.json: the service account name and token, if you use one.
• jwt/access_token and jwt/refresh_token: the tokens from login or from the service account.
• tenant/default_tenant: the workspace set with set_default_tenant.

The CLI creates these files, empty, the first time it runs.

Good to know

• File permissions: the token files and the service account file are created readable by every user on the machine. On a shared machine, restrict them yourself, for example with chmod 600.
• No default workspace: if you have not set one and pass no --tenant, the CLI warns you and sends the request with no workspace. Set a default to avoid surprises.
• Empty values are not sent: a flag set to false, 0 or an empty string is treated as not given. --limit 0 and --skip 0 have no effect.
• Filters need an equals sign: --filters repositoryName without =value is rejected.
• Command names with acronyms: check vulnara --help for the exact spelling of a command whose operation name contains an acronym.
• Login needs a local browser: vulnara login only works where the browser can reach localhost on the same machine. If all ports from 10000 to 10010 are busy, or it times out, use a service account instead.
• Two browser tabs: vulnara login may open the sign-in page twice. Complete it in either tab.
• Logs and JSON: diagnostic logs go to stdout. Leave VULNARA_LOG_LEVEL unset when you pipe output into jq, or use --output.
• Roles still apply: the CLI can do only what your role in the workspace allows. See Teams and roles.