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_category_scan, scan_findings. A command's flags are the fields of that operation's input, so start_repository_category_scan takes --repositoryId, --category, --branch and so on. Run vulnara --help for the list, and vulnara <command> --help for a command's flags.

The commands that read a single item are named after it: repository, scan_result, git_entity, git_token, network, network_scan_result and notification_scope. Versions before 0.1.15 called them get_repository and so on, and those names still work as aliases, so existing scripts keep running.

A few API operations have no command: the two live-update subscriptions, and operations that take more than one argument, such as clearFindingTriage and revealScanFindingMatch. Use the GraphQL API for those.

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. category=<value> is checked before the request is sent and must be SAST, SCA, SECRETS, PII or DAST, in either case.
• --category: on start_repository_category_scan and the schedule commands, the category to scan for: SAST, SCA, SECRETS or PII, in either case. Any other value is refused. Web application scans have their own commands; see Scan a web application.
• --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:

   shCopia

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

   shCopia

   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

   shCopia

   vulnara set_default_tenant --tenant my-workspace

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

4. Run a command

   shCopia

   vulnara repositories --limit 20
   vulnara repositories --filters repositoryName=my-app
   vulnara scan_categories
   vulnara start_repository_category_scan --repositoryId <id> --category SECRETS --branch main
   vulnara scan_findings --filters scanResultId=<id> --filters category=secrets --output findings.json

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

Scan by category or by scanner id

start_repository_category_scan starts every scanner serving a category that your workspace may run, the same as the scan form in the web app. scan_categories lists the categories you may use. Scan results carry the categories their scanner covers, and findings carry their own category, which is null for findings recorded before categories existed.

start_repository_scan --dockerScanToolId <id> still starts one scanner by its id, so scripts that pin an id keep working. vulnara docker_scan_tools lists the ids your workspace may run, each with the categories it covers and never a name.

Scan a web application

Add a web application, scan it and read what it found:

vulnara create_web_target --name "Customer portal" --baseUrl https://app.example.com --ownershipConsent=true
vulnara start_web_scan --webTargetId <web-target-id>
vulnara web_scan_results
vulnara dast_findings -f webTargetId=<web-target-id>

web_targets and web_target list and read targets, dast_finding_triage and set_dast_finding_triage read and record triage decisions, and tasks shows a running web scan with its progress. See Scan a web application.

Commands that need a confirmation

A flag ending in Consent, such as --ownershipConsent on create_git_entity, create_network and create_web_target, is a statement you make: that your workspace owns the target or is authorised to scan it. It is required, and the command refuses to send a request unless you pass it as true.

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 zsh
vulnara completion fish

• bash: adds a line to ~/.bashrc that loads completion, and prints the completion script.
• zsh: adds . <(vulnara completion zsh) to ~/.zshrc, creating the file if needed, and prints the completion script. Running it again does not add the line twice.
• fish: writes ~/.config/fish/completions/vulnara.fish.
• 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 and readable only by you, the first time it runs.

Good to know

• Exit codes: a failed API call, a result that cannot be written to --output, or a value the CLI refuses on its own exits with a non-zero status, so a script can check $?. Versions before 0.1.15 exited 0 on a failed call.
• File permissions: the CLI creates the token files and the service account file readable only by your user. Token files an earlier version created readable by everyone are restricted the next time the CLI saves a token. Check the service account file yourself if you created it by hand.
• 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.
• Only the flags you pass are sent: a flag you leave out is not sent. A flag you pass is sent as given, including false and 0, so --isActive=false really turns something off. An empty list flag is not sent.
• List flags of objects take JSON: a flag such as --headers on the notification scope commands takes one JSON object per entry, for example --headers '{"name":"X-Key","value":"v"}', and repeats for more.
• 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.