Nullgap.dev Docs

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

  1. Choose Add application.
  2. Pick the Repository, give the application a Name, and enter its Folder (relative to the top of the repository, without ..; . for the whole repository).
  3. 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

PartWhat it holds
SummaryWhat the application does and what would hurt most if it went wrong.
AssetsWhat needs protecting.
ActorsWho can reach the application, people and machines.
Entry pointsWhere input comes in: a name, an optional file, a description.
Trust boundariesWhere data crosses from one level of trust to another.
ControlsWhat already stands in an attacker's way.
Your notesFree text from your team, passed to reviewers word for word.
Learned from feedbackLessons 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

RoleOn the Context page
MemberReads every application, edits threat models, notes and project rules, and regenerates a threat model.
Admin, ownerEverything 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