GitHub Action

The Vulnara GitHub Action starts a Vulnara scan on the branch your workflow runs on, waits for it to finish, and fails the job when it finds something at or above the severity you choose. It signs in with a service account, so no person's credentials are stored in GitHub.

What it is for

• Checking every push and pull request before it merges, without anyone opening the web app.
• Blocking a merge when a scan finds a Critical or High finding.
• Keeping a link from each CI run to the full scan in Vulnara.

How it works

1. The action exchanges your service account name and token for a short-lived access token. It renews the token by itself during a long scan.
2. It looks up the repository in your workspace by its GitHub owner/name. The repository must already be in Vulnara.
3. It matches each entry in scan-tools to a scanner in the Vulnara scanner catalogue.
4. It starts one scan per scanner on the branch, then checks each scan's status every poll-interval seconds until it finishes.
5. It counts the findings per severity, writes a job summary, sets its outputs, and passes or fails the job.

The platform clones the branch and runs the scanners. The action itself runs no scanner and downloads nothing at run time. It is a container action, so it runs on Linux runners only.

What you can set

These are the inputs you will use most. The full list, with defaults, and an interactive workflow builder are on the GitHub Action reference.

• service-account (required): the service account name, as shown in the Service Accounts list.
• token (required): the service account token. Pass it from a GitHub secret.
• tenant (required): the id of the workspace the service account and the repository belong to.
• scan-tools (required): the scanners to run, as a comma-separated list of scanner ids.
• fail-on: the lowest severity that fails the job: none, low, medium, high or critical. The default is critical.
• branch: the branch to scan. By default, the branch that triggered the workflow.
• repository: the owner/name to look up in Vulnara. By default, the repository the workflow runs in.
• git-token-id: the id of a Vulnara git token that can clone the repository. Needed for private repositories.
• create-issue: open an issue in the repository for the findings. Off by default.
• auto-remediate: open a pull request that fixes the findings. Needs create-issue. Off by default.
• wait-timeout: how many seconds to wait for each scan before failing. The default is 1800.
• poll-interval: how many seconds between status checks. The default is 15.

Outputs

• scan-result-ids: the ids of the scans that were started, separated by spaces.
• highest-severity: the highest severity found, in lower case, or none.
• passed: true if the job passed the fail-on gate, false if it did not.

The outputs are written before the job fails, so a later step with if: always() can still read them.

Do it

1. Add the repository to Vulnara

   Connect the git workspace and make sure the repository is imported and enabled. See Connect GitHub or GitLab and Repositories. The action finds the repository by name and matches the owner, so the git workspace name in Vulnara should match the GitHub owner.

2. Create a service account

   In the workspace that owns the repository, go to Access & Security, then Service Accounts, and create one. Copy the token when it is shown: you will not see it again. See Service accounts.

3. Store the credentials in GitHub

   In your repository settings, add the token as an Actions secret, for example VULNARA_TOKEN. The service account name is not secret, so you can store it as a variable, for example VULNARA_SERVICE_ACCOUNT.

4. Find your scanner ids

   List the scanners with dockerScanTools or the MCP tool docker_scan_tools. See Scanners.

5. Add the workflow

   Save this as .github/workflows/vulnara.yml and fill in your workspace id and scanner ids.

   yamlKopieren

   name: Vulnara Scan
   on:
     push:
       branches: [main]
     pull_request:
   
   jobs:
     vulnara:
       runs-on: ubuntu-latest
       timeout-minutes: 45
       steps:
         - uses: theorigamicorporation/vulnara-action@v1
           id: vulnara
           with:
             service-account: ${{ vars.VULNARA_SERVICE_ACCOUNT }}
             token: ${{ secrets.VULNARA_TOKEN }}
             tenant: my-workspace
             scan-tools: '<scanner id>,<scanner id>'
             fail-on: high
             # git-token-id: ${{ vars.VULNARA_GIT_TOKEN_ID }}   # for private repositories
         - name: Fail if no scan ran
           if: ${{ always() && steps.vulnara.outputs.scan-result-ids == '' }}
           run: exit 1

The fail-on gate

The job fails when the highest severity found is at or above fail-on.

• fail-on: high fails on High and Critical findings, and passes on Medium and Low.
• fail-on: critical fails only on Critical findings.
• fail-on: none never fails the job on findings. Use it to report without blocking.

The value is not case sensitive. Any other value stops the run before it scans, with an error naming the accepted values.

The job summary

After the scans, the action writes a summary to the workflow run:

• a Passed or Failed heading;
• the repository, provider, visibility, branch, languages, gate setting, highest severity and total time;
• the number of findings per severity;
• one row per scan, with the scanner's display name, its duration, its finding count and a link to the scan in Vulnara;
• a table of up to 50 findings, highest severity first, each linking to the exact line of code at the commit that was scanned.

The summary shows scanners by their display names, such as Ripley. scan-tools does not accept those names: pass the scanner ids.

Private repositories

Vulnara needs a git token to clone a private repository. Add one in Vulnara (see Connect GitHub or GitLab) and pass its id as git-token-id. Without it, the action warns that cloning may fail and starts the scan anyway. The scan then fails, and so does the job.

Issues and fix pull requests

Set create-issue: true to have Vulnara open an issue in the repository for the findings. Add auto-remediate: true to also have it open a pull request that fixes them. See AI remediation.

Good to know

• Permissions: starting a scan needs the editor role in the workspace. A service account has the viewer role, which is read-only. If a scan is refused with an authorization error, the account is missing that role. See Teams and roles.
• The repository must exist: if Vulnara has no repository with that name in the workspace, the action fails and tells you to add it first. A disabled repository gets a warning, and the scan is usually refused.
• Same name under two owners: the action prefers the repository whose owner matches. If none matches, it uses the first repository with that name, which may be the wrong one. The job log and summary show which repository was scanned.
• Timeouts add up: wait-timeout applies to each scan, not to the whole run. With several scanners, set a limit for the whole job with timeout-minutes.
• A timed-out scan keeps running: when the action gives up waiting, the scan continues in Vulnara. Open it from the link in the log.
• Failed scans fail the job: a scan that ends as failed or cancelled fails the job, whatever fail-on says.
• Findings with no file: they count towards the totals and the gate, but are left out of the table of located findings.
• Plan limits apply: CI scans use your plan's scan minutes like any other scan. See Plans, usage and billing.
• Wrong credentials: the action prints the reason from the sign-in response and fails with "could not authenticate the service account". Check the service account name, the token, and that tenant is the workspace the account belongs to.