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
adminscope. - The code as one
.zipfile 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
| Limit | Value |
|---|---|
| Formats | .zip and .tar.gz. The format is recognised from the file's contents, not from its name or its Content-Type. |
| Upload size | Up to 200 MB, compressed. |
| Unpacked size | Up to 1 GB in total. |
| Largest single file | 256 MB once unpacked. |
| Entries | Up to 100,000. |
| Archives kept per organisation | 20. Remove one to upload another. |
| Name | Up 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
.gitfolder 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
- Open Pentests and press New pentest.
- On the first step, under Or upload the source as an archive, choose the file.
- 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 code | Meaning | What to do |
|---|---|---|
400 bad_archive | The 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_large | The upload is over 200 MB. | Leave out build output, dependencies and binaries, or upload one part of the code. |
400 bad_request | The 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_many | The organisation already keeps 20 archives. | Remove one first. |
400 not_configured | Uploading 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