This GitHub action validates CVE JSON 5.0 format records and (optionally) submits them to the CVE RSUS service.
Required CVE services user name (usually the email address)
Required CVE services organisation
Required CVE services api key (Please store this in a GitHub secret)
Required CVE services environment (defaults to test)
Set to true to publish the records to the CVE services (defaults to false)
Path to find CVE records in. Any *.json file in this directory is considered a CVE record (defaults to .)
Path to find CVE ID reservations in. Any *.json file in this directory is considered a CVE ID reservation (defaults to <path>/reservations)
Comma separted list of checks to ignore.
Create a pull request to bring local records in line with remote records (defaults to false)
A github token to be used by this action. Default . Recommended value: ${{ secrets.GITHUB_TOKEN }}
If you want github actions to run on pull requests created by this action you will have to use a personal Github Access token with at least the repo and org:read scopes and grant the bot write access to the repo.
Minimum number of records to reserve in one go (0=do not make reservations). This parameter defaults to 0 because maintaining a "stockpile" of CVE IDs is discouraged.
Minimum number of reserved records for the current year.
Action will fail if the number of records in RESERVED state drops below this amount. If reserve is set to a number above 0 this action will reserve this many new records.
Create pull request (if pr is set to true) to expire reservations this much time after the end of the year.
Example values are:
4dfor 4 days, reservations will expire on or after 5 Jan3wfor 4 weeks, reservations will expire on or after 15 Jan2mfor 2 months, reservations will expire on or after 1 Mar1yfor 1 year, reserveration will expire on or after 1 Jan for reservations before the previous year
Set to true to skip running cvelint validation checks. (Defaults to false)
This is useful when you want to bypass the cvelint validation step, for example during testing or when using custom validation workflows.
Set to true to increase the output levels. (Defaults to false)
Set to true to output only the minimul output. (Defaults to false)
If both verbose and quiet are set, quiet wins
For the stable version use DIVD-NL/cna-bot@v1 (recommended)
For the current beta version use DIVD-NL/cna-bot@v1.4
See: https://github.com/DIVD-NL/cna-admin-test
In this repo the CVE records are in ./records and it has this workflow configuration
# test_and_update_cve_records.yml
on:
push:
branches:
- 'main'
pull_request:
branches:
- 'main'
schedule:
- cron: "5 4 * * *" # This should be changed to another cron value.
jobs:
test_and_update_cve_records:
runs-on: ubuntu-latest
steps:
# Get the repository's code
- name: Checkout
uses: actions/checkout@v3
# Check CVE records and publish them
- name: CVE RSUS check and upload
uses: DIVD-NL/cna-bot@v1
with:
cve-user : ${{ secrets.CVE_USER }}
cve-org : ${{ secrets.CVE_ORG }}
cve-api-key : ${{ secrets.CVE_API_KEY }}
cve-environment : test # Change to prod for actual use
publish : ${{ github.ref == 'refs/heads/main' }} # Only publish when we merge into the main branch
path : records # This is where the CVE records live
reservations-path : records/reservations # This is where reservation CVE IDs live
ignore : "" # Don't ignore any checks
min-reserved : 0 # Don't pre-reserve records
reserve : 0 # Don't pre-reserve records
pr : ${{ github.event_name != 'pull_request' }} # Create a PR when we push or run on schedule
github-token : ${{ secrets.GITHUB_TOKEN }}
expire-after : "1y"
Instead of using a Personal Access Token, a GitHub App can be used. This is advantagus since all the pull requests are created in the name of the App and not a personal account.
Steps:
- Register new GitHub App
- Store the App's ID in your repository environment variables (example:
APP_ID) - Store the App's private key in your repository secrets (example:
PRIVATE_KEY) - Install the App for your Organization
# test_and_update_cve_records.yml
on:
push:
branches:
- 'main'
pull_request:
branches:
- 'main'
schedule:
- cron: "5 4 * * *" # This should be changed to another cron value.
jobs:
test_and_update_cve_records:
runs-on: ubuntu-latest
steps:
# Get the repository's code
- name: Checkout
uses: actions/checkout@v3
# Request Token via App Credentials
- uses: actions/create-github-app-token@v1
id: app-token
with:
app-id: ${{ vars.APP_ID }}
private-key: ${{ secrets.PRIVATE_KEY }}
# Check CVE records and publish them
- name: CVE RSUS check and upload
uses: DIVD-NL/cna-bot@v1
with:
# ...
github-token: ${{ steps.app-token.outputs.token }} # Use token from `app-token` step
The reservations.lock file can be used to make sure reservations don't expire and to reserve CVE records. You can also use if for local administration.
You can CVE ID reservations from automatic expiry to do this you can create one or more reservation.lock files anywhere in the reservations-path. You must include one CVE ID per line and # style comments are allowed.
In order to reserve a record you can add special lines to the reservations.lock file. E.g.
NEW-CVE-2024 # Reserves a single CVE id in the year 2024
NEW-CVES-2025-12 # Reserves a sequential block of 12 CVEs for 2025
When these lines are encountered a number of things will happen
- The number of records in the year will be requested via the CVE services api
- Reservation records will we written in the same directory the
reservations.lockfile is in - The
reservations.lockfile will be updated to contain the newly reserved CVE IDs
You can also use this file for some local administration.
E.g.
# reservations.lock
# DIVD-2010-00001
# Owner: Frank
CVE-2010-66666 # Ticket: 1245
CVE-2010-66667 # Ticket: 1246
# DIVD-2010-00002
CVE-2010-66668 # Ticket: 1249
CVE-2010-66669 # Ticket: 1250
I will explain each part of the workflow, in detail
We will run this workflow on pull requests agains main and on pushes to the main branch and run at 4:05 at night.
# test_and_update_cve_records.yml
on:
push:
branches:
- 'main'
pull_request:
branches:
- 'main'
schedule:
- cron: "5 4 * * *"The we need to check out the code
jobs:
test_and_update_cve_records:
runs-on: ubuntu-latest
steps:
# Get the repository's code
- name: Checkout
uses: actions/checkout@v2
```yml
After the code is checkout out, we are going to test the CVE records
```yml
# Check CVE records and publish them
- name: CVE RSUS check and upload
uses: DIVD-NL/cna-bot@v1The iputs that start with cve- are our CVE credentials to log in. We suggest you store these in your github secrets
with:
cve-user : ${{ secrets.CVE_USER }}
cve-org : ${{ secrets.CVE_ORG }}
cve-api-key : ${{ secrets.CVE_API_KEY }}
cve-environment : test # Change to prod for actual useNext we want to instruct the action to only publish.update records if we have merged them into main.
publish : ${{ github.ref == 'refs/heads/main' }} # Only publish when we merge into the main branchWe need to tell the action where our records live.
path : records/ # This is where the CVE records liveWith this option we can ignore certain check, e.g. set it to published_in_path if you don't wat to check that each published CVE has a record in this directory.
ignore : "" # Don't ignore any checksIf the remote record does not match the local record, create a pull reuqest to update the local records. These changes should mostly be about metadata and to incorporate CVE ID reservations into your repo.
pr : ${{ github.event_name != 'pull_request' }} # Create a PR when we push or run on schedule
github-token: ${{ secrets.GITHUB_TOKEN }} Note: If you want github actions to run on pull requests created by this action you will have to use either a personal Github Access token or a GitHub app token with at least the repo, org:read and discussion:read scopes.
The parameters below control CVE record pre-reservation. min-reserved sets the minimum number of available CVE records to keep in stock for the (current) year. If the number of reserved records drops below this threshold the action will fail, or reserve more CVE IDs depending on the setting of reserve.
If reserve is set to a positive number, the action will reserve this number of records. If more records are needed to go back the the minimum, this ammount will be reserved instead.
min-reserved : 0 # Don't pre-reserve records
reserve : 0 # Don't pre-reserve recordsPlease note: pre-reservation of records is not considered best practise. These values are set to 0 by default. Instead use the NEW-CVE-yyyy or NEW-CVES-yyyy-nn syntax in reservation.lock files for just in time reservation of records.
expire-after : "1y"If we have reservations of 1 year before last year, in the state RESERVED, then automatically create a pull-request to set them to REJECTED.