Quick start for developers

This guide takes you from nothing to a scan started from your terminal, and then to a GitHub workflow that fails the build when a scan finds something serious. You need a Vulnara account and a workspace with at least one repository imported. If you have neither, start with the quick start for security teams, which connects GitHub from the web app.

Scan from your terminal

1. Install the CLI

   The CLI is a single binary called vulnara. Builds exist for Linux (x86_64), macOS (Apple silicon and Intel) and Windows (x86_64). See CLI for where to get it.

   Unpack the archive, then optionally add the binary to your shell's PATH and turn on completion:

   shCopy

   ./vulnara add_to_path && source ~/.bashrc
   vulnara completion bash && source ~/.bashrc

2. Sign in

   shCopy

   vulnara login

   Your browser opens the CLI Authentication page. Sign in if you are asked to, then choose Authenticate CLI. The CLI waits up to 3 minutes for the browser to hand it your session, and stores it under ~/.config/vulnara/. After that, commands refresh the session on their own.

   vulnara login needs a browser on the same machine. On a server or in CI, use a service account instead (see below).

3. Pick a workspace

   Every command runs against one workspace. The workspace id is the workspace name shown in the web app's account menu. Save it once:

   shCopy

   vulnara set_default_tenant --tenant my-team

   To run a single command against another workspace, add --tenant other-team to it.

4. List your repositories

   shCopy

   vulnara repositories --limit 20

   The response is JSON. Note the id of the repository you want to scan. Add --search <text> to narrow the list, or --output repos.json to write the raw JSON to a file.

5. Start a scan

   A scan runs one scanner on one repository. You need the scanner's id: see Scanners, or read it with the dockerScanTools query.

   shCopy

   vulnara start_repository_scan --repositoryId <repository-id> --dockerScanToolId <scanner-id> --branch main

   Leave out --branch to scan every branch. For a private repository, add --gitTokenId <token-id>. The scan appears under Repository Scans in the web app, and its findings in Vulnerabilities when it finishes.

Starting a scan needs the EDITOR role in the workspace. See start_repository_scan for every flag.

Gate CI with the GitHub Action

1. Check the repository in Vulnara

   The repository must already be imported, with the same owner name as on GitHub, and it must be enabled. See Repositories.

2. Create a service account

   A workspace ADMIN does this. In the web app, open Access & Security, then Service Accounts, and choose Create Service Account. Give it a Name and an Expires At date.

   Vulnara shows the secret once. Copy it before you close the dialog. The name shown in the list, which Copy name copies, is the service account username.

3. Store the credentials in GitHub

   In your GitHub repository settings, add:

   • VULNARA_SERVICE_ACCOUNT: an Actions variable holding the service account username.
   • VULNARA_TOKEN: an Actions secret holding the secret you copied.

4. Add the workflow

   Create .github/workflows/vulnara-scan.yml:

   yamlCopy

   name: Vulnara Scan
   on:
     push:
       branches: [main]
     pull_request:
   
   jobs:
     scan:
       runs-on: ubuntu-latest
       steps:
         - uses: theorigamicorporation/vulnara-action@v1
           with:
             service-account: ${{ vars.VULNARA_SERVICE_ACCOUNT }}
             token: ${{ secrets.VULNARA_TOKEN }}
             tenant: my-team
             scan-tools: <scanner-id>
             fail-on: high

   scan-tools takes one or more scanner ids, separated by commas. fail-on: high fails the job on High or Critical findings. The branch defaults to the one that triggered the workflow. For a private repository, add git-token-id.

5. Push and read the result

   Commit the file and push. The job starts one scan per scanner, waits for them to finish, and writes a job summary with the findings per severity and a link to each scan in Vulnara. The job fails when the highest severity reaches fail-on.

Good to know

• A CLI command that gets an error back from the API still exits with status 0. In scripts, read the output rather than relying on the exit code.
• The CLI stores its session and any service account file under ~/.config/vulnara/, readable by other users of the machine. On a shared host, restrict those files yourself.
• To use the CLI in CI instead of the action, write the service account to ~/.config/vulnara/sa/service_account.json as {"username": "...", "password": "..."}. The CLI picks it up without vulnara login.
• The action runs on Linux runners only, and waits for the whole scan. Its wait-timeout (default 1800 seconds) applies to each scan, so several scanners take longer.
• Every input and output of the action is listed in the GitHub Action reference.

Next steps