Nullgap.dev Docs

Connect your code

Archive upload

Upload source code as a .zip or .tar.gz so that it can be pentested without a code host.

Code that is not on a code host Nullgap can reach can be uploaded as an archive. The upload becomes a repository in your organisation that can be pentested.

An uploaded archive 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.
  • The code as one .zip file or one gzip-compressed tar file (.tar.gz).

To make one from a Git checkout, without the .git folder and without untracked files:

git archive -o code.zip HEAD

#Formats and limits

LimitValue
Formats.zip and .tar.gz. The format is recognised from the file's contents, not from its name or its Content-Type.
Upload sizeUp to 200 MB, compressed.
Unpacked sizeUp to 1 GB in total.
Largest single file256 MB once unpacked.
EntriesUp to 100,000.
Archives kept per organisation20. Remove one to upload another.
NameUp to 80 characters: letters, digits, spaces, dots, dashes and underscores, starting with a letter or digit.

The size limits are enforced on what actually comes out while unpacking, not on the sizes the archive states about itself.

A zip is refused when it is password-protected, split into several parts, or uses a compression method other than the standard one (deflate).

#What is left out

Only regular files and folders are kept. These are skipped without failing the upload:

  • symbolic links, hard links and device files;
  • a .git folder at the top of the archive;
  • entries with an absolute path, and entries whose path points outside the archive (../).

Nothing in the archive is run or interpreted when it is unpacked.

#Upload in the console

  1. Open Pentests and press New pentest.
  2. On the first step, under Or upload the source as an archive, choose the file.
  3. When the upload has been checked, the new repository is selected and you continue with the pentest as usual.

It is also listed under Repositories, marked Uploaded archive: pentests only.

#Upload with the API

The request body is the archive itself, not JSON. The display name goes in the name query parameter.

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @code.zip \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/archive?name=shop"

Abridged answer:

{
  "id": "repo_4e5f6a7b8c9d",
  "provider": "archive",
  "fullName": "upload/shop",
  "defaultBranch": "upload",
  "private": true,
  "reviewEnabled": false
}

Use the id as repoId when you estimate and start a pentest. An archive has one version, so ref can be left out.

The archive is unpacked once at upload, to check it. A bad archive is refused then, not later when a pentest starts.

#How it is stored and used

  • The archive file is stored for your organisation only. See code handling.
  • Each estimate and each pentest unpacks it into a fresh folder, which is removed afterwards.
  • To test a newer version of the code, upload a new archive. An upload cannot be replaced in place.

#What can go wrong

Status and codeMeaningWhat to do
400 bad_archiveThe archive was refused. The message says why: damaged, cut short, empty, containing no files, neither of the two formats, a zip that is password-protected, split or oddly compressed, or over one of the unpacking limits.Recreate the archive. If it is too large, upload a smaller part of the code.
413 too_largeThe upload is over 200 MB.Leave out build output, dependencies and binaries, or upload one part of the code.
400 bad_requestThe upload is empty, or the name contains characters that are not allowed.Send the file as the request body and check the name.
409 too_manyThe organisation already keeps 20 archives.Remove one first.
400 not_configuredUploading is not switched on for your Nullgap service.See getting help.

Trying to switch on pull request review, or to start a fix, for an uploaded archive answers read_only_repository.

#Deleting

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

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

The stored archive file is deleted with the repository, and so are its pentest schedules. Pentests already run, their reports and their findings are kept, including the code excerpts in those findings. To remove those as well, see data retention.

Nullgap documentation