Pull request review
Context and threat models
The Context page: one application per service in a repository, its threat model, how it is drafted from the code and improved by your team, and who can change it.
Reviews and pentests read your code better when they know what the code is for. The Context page holds that knowledge: for each application, a threat model (what it protects, who can reach it, what stands in the way), your team's notes and your project rules. Reviewers read it on every pull request review and pentest.
#Applications
An application is one deployable service inside a repository: a name, a folder and its context. A repository with one service needs one application covering the whole repository (folder .); a repository with several services can have one per folder, such as services/api and apps/web.
Every repository gets an application automatically the first time it is reviewed or pentested. It covers the whole repository, is named after it, and starts with an empty threat model.
The Context page lists the applications as cards, each with its repository, folder, threat-model version, a short summary and how many entry points, assets and lessons it holds.
#Add an application
- Choose Add application.
- Pick the Repository, give the application a Name, and enter its Folder (relative to the top of the repository, without
..;.for the whole repository). - Choose Add application. It starts with an empty threat model (version 0).
Two applications cannot cover the same folder of the same repository, and two in one repository cannot have the same name (case does not matter): either is refused, with the application that is already there named. Open that one instead. A folder is compared however it is written, so ./apps/web/ and apps/web are the same folder.
#Delete an application
Open the application and choose Delete, then confirm. Its threat model, project rules and what was learned from your team's replies are deleted; this cannot be undone. The repository, its findings and past reviews and pentests are not touched.
#The threat model
| Part | What it holds |
|---|---|
| Summary | What the application does and what would hurt most if it went wrong. |
| Assets | What needs protecting. |
| Actors | Who can reach the application, people and machines. |
| Entry points | Where input comes in: a name, an optional file, a description. |
| Trust boundaries | Where data crosses from one level of trust to another. |
| Controls | What already stands in an attacker's way. |
| Your notes | Free text from your team, passed to reviewers word for word. |
| Learned from feedback | Lessons added when your team marks a finding as a false positive or an accepted risk, with the reason given. Read-only. |
#Draft it from the code
Choose Regenerate from code on the application. Nullgap AI reads the code on the default branch and writes the summary, assets, actors, entry points, trust boundaries and controls again. Your notes and Learned from feedback are always kept. The draft is written in the background; the page picks it up when it is ready, and the version number goes up by one.
Save or discard your own changes first: the button is unavailable while the page has unsaved changes.
#Correct it by hand
Edit any part and choose Save. Each save raises the version by one and records when it was edited. If you leave the page with unsaved changes, the console asks first.
#How it improves
When someone triages a finding as a false positive or an accepted risk, the reason becomes a lesson under Learned from feedback, so later reviews do not raise the same thing again for the same reason. See triage.
#Who can do what
| Role | On the Context page |
|---|---|
| Member | Reads every application, edits threat models, notes and project rules, and regenerates a threat model. |
| Admin, owner | Everything a member can, and adds and deletes applications. |
Every change is written to the audit log as application.created, application.updated, application.regenerate or application.deleted.
#Which application a run uses, and the limits
Which application a pull request review or a pentest reads, the project rules, how much of the context reviewers are given, the limits of each field and the API calls are on project rules and custom checks.
Nullgap documentation