Fixes
Automations
Start a verified fix by itself for each new finding that matches your rules, choose who is told how it ended, and read the run history.
An automation is a rule: when a new finding matches it, Nullgap starts a fix run for that finding by itself. The run checks the finding is real, writes the smallest fix, runs your tests and opens a pull request for your team. Nothing is ever merged for you.
You find automations in the console under Automations. The page has two tabs: Rules, the automations themselves, and Run history, every fix run of the workspace, whoever or whatever started it.
#Who can do what
| Role | On the Automations page |
|---|---|
| Member | Reads the rules and the run history. The page says that only admins and owners can change automations. |
| Admin, owner | Creates, edits, switches on and off, and deletes automations. |
An API key needs the admin scope to change automations; any key can read them. See API keys.
#Create an automation
- Open Automations and choose New automation.
- Give it a Name (up to 80 characters).
- Tick the severities that should start a run. Critical and high are ticked to begin with.
- Tick the repositories it covers, or leave them all unticked for every repository.
- Optional: name up to two Branches a fix may be written against, and a Credit cap per run.
- Choose whether a run may also open a draft pull request when the finding cannot be reproduced. Off by default; see below.
- Choose who is told when a run finishes: Post to the connected Slack channel, and Email.
- Choose Create. A new automation is created switched off. Switch it on in the list when you are ready.
#Who is told when a run finishes
| Where | What is sent |
|---|---|
| Slack | One message in the channel of the Slack integration, if Post to the connected Slack channel is ticked and Slack is connected. |
| One message to each address in Email: up to 20, comma-separated. |
The Email field takes the addresses of members of the workspace only. An address outside the workspace is refused when you save, with the address named, because the message names the finding. If someone leaves the workspace later, they stop receiving the messages: the list is checked again each time a run finishes. What the e-mail contains is on the e-mail page.
A fix run you start by hand sends no e-mail. Every fix run, however it was started, sends the remediation.completed webhook event.
#What starts a run, and what does not
- A new finding from a pull request review or a pentest whose severity and repository match. A finding that a later run reports again does not start another.
- Each finding gets at most one automatic run. You can still press Remediate on the finding to start another by hand.
- If several automations match one finding, one of them runs.
- A finding from a pull request opened from a fork never gets a run.
- With no automation credits left, the run is not started, and the skip is written to the audit log as
automation.skipped. See automation credits. - A fix that would target a branch outside Branches fails and says so.
#When a finding cannot be reproduced
An automatic run that cannot reproduce the finding ends as failed and opens nothing, because nobody asked for it. If you tick Also open a draft pull request when the finding cannot be reproduced, and the workspace setting Propose a fix when a finding cannot be reproduced is on, the run may instead propose a fix as a draft pull request marked "Not proven". See when the flaw cannot be reproduced.
#The run history
Run history lists every fix run, newest first, with its finding, repository, outcome and pull request. The tiles above it count the last seven days:
| Tile | Counts |
|---|---|
| Fixed | Runs whose fix was proven by reproducing the flaw. |
| Proposed, not proven | Draft pull requests for a person to review. |
| Failed | Runs that produced no fix, with how many needed no fix and how many are still running. |
Open a run to read what it checked and why it ended as it did. See reading the run.
#Change or delete an automation
Choose an automation in Rules to edit it. Each change of whether it may open unproven fixes is written to the audit log with automation.updated.
Deleting an automation stops it starting new runs. Runs it already started carry on and stay in the history.
| Audit action | When |
|---|---|
automation.created | An automation was created. |
automation.updated | An automation was changed or switched on or off. |
automation.deleted | An automation was deleted. |
automation.skipped | A run was not started for lack of automation credits. |
#In the API
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Fix serious findings on main","enabled":true,"trigger":{"severities":["critical","high"],"repoIds":[]},"environment":{"branches":["main"],"maxCreditsPerRun":null},"notifier":{"slack":true,"emails":["dana@acme.example"]}}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/automations"
An address in notifier.emails that is not a member's is refused with 400 bad_request. The fields, and the routes to list, change and delete automations and to read fix runs, are in the fixes reference.
Nullgap documentation