Nullgap.dev Docs

Connect your code

Public repository by address

Add a public Git repository by its https address so that it can be pentested, without connecting a code host.

You can pentest a public repository by giving Nullgap its address. Nullgap clones it over https with no credentials. Nothing is installed on the code host and nothing is written to it.

A repository added this way is read-only: it can be pentested, and that is all. Pull request review, checks, comments and fix pull requests need a connected code host.

#What you need first

  • To be an admin or owner of the organisation, or an API key with the admin scope.
  • A repository that anyone can clone over https without signing in.

#Which addresses are accepted

Use the https address of the repository, for example https://github.com/acme/shop. It does not have to be on GitHub: any host that serves a public Git repository over https works.

RuleDetail
Schemehttps only.
CredentialsNone. An address containing a user name or password is refused.
Query and fragmentNot allowed. Give the repository's own address, not a link to a file or a branch page.
HostA public host name that resolves only to public addresses. Private, loopback and internal addresses are refused.
PathTwo to six segments, ending in the owner and the repository name, for example /acme/shop or /group/subgroup/project. A trailing .git or / is ignored.
RedirectsNot followed. Give the address the repository is actually served from.

The repository must have a default branch.

#Add it in the console

  1. Open Pentests and press New pentest.
  2. On the first step, under Or test a public repository by its address, paste the address and add it.
  3. The repository is selected, and you continue with the pentest as usual.

It is also listed under Repositories, marked Added by address: pentests only.

#Add it with the API

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/acme/shop"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/public"

Abridged answer:

{
  "id": "repo_9d8c7b6a5f4e",
  "provider": "public",
  "fullName": "github.com/acme/shop",
  "defaultBranch": "main",
  "private": false,
  "reviewEnabled": false
}

Use the id as repoId when you estimate and start a pentest. Adding an address that is already on the list returns the existing repository.

#Limits

LimitValue
Repositories added by address, per organisation50
Address length500 characters
Size of the checked-out codeCapped. A repository over the cap cannot be estimated or pentested. Narrowing paths does not help, because the cap applies to the whole checkout; upload the part you need as an archive.

#How the code is fetched

  • Each estimate and each pentest fetches the version you name at that moment: a branch, a tag or a commit. Nothing is kept between runs.
  • Only that one version is fetched, without history.
  • Submodules are not fetched. Code that lives in a submodule is not examined.
  • The address is checked again on every fetch. If the host name no longer resolves to public addresses, the fetch is refused.

#What can go wrong

Adding an address fails with 400 bad_repository and a message that says why.

MessageWhat to do
That is not a valid addressUse the form https://host/owner/name.
Use an https addressReplace http://, git:// or an SSH address with the https one.
The address must not contain credentialsRemove the user name and password. A private repository needs a connected code host.
The address must be a public oneThe host is private or internal. Connect the code host, or upload an archive.
That does not look like a repository addressThe path must end in the owner and repository name.
The repository could not be readCheck the address and that the repository is public.
The repository has no default branch to testPush a branch and set it as the default.

Other answers: 409 too_many when the organisation already has 50, and 400 not_configured if adding by address is not switched on for your Nullgap service.

Trying to switch on pull request review, or to start a fix, for such a repository answers read_only_repository.

#Removing

On Repositories, press Remove next to it. With the API:

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/repo_9d8c7b6a5f4e"

Its pentest schedules are removed with it. Pentests already run, their reports and their findings are kept.

Nullgap documentation