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
adminscope. - 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.
| Rule | Detail |
|---|---|
| Scheme | https only. |
| Credentials | None. An address containing a user name or password is refused. |
| Query and fragment | Not allowed. Give the repository's own address, not a link to a file or a branch page. |
| Host | A public host name that resolves only to public addresses. Private, loopback and internal addresses are refused. |
| Path | Two 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. |
| Redirects | Not followed. Give the address the repository is actually served from. |
The repository must have a default branch.
#Add it in the console
- Open Pentests and press New pentest.
- On the first step, under Or test a public repository by its address, paste the address and add it.
- 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
| Limit | Value |
|---|---|
| Repositories added by address, per organisation | 50 |
| Address length | 500 characters |
| Size of the checked-out code | Capped. 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.
| Message | What to do |
|---|---|
| That is not a valid address | Use the form https://host/owner/name. |
| Use an https address | Replace http://, git:// or an SSH address with the https one. |
| The address must not contain credentials | Remove the user name and password. A private repository needs a connected code host. |
| The address must be a public one | The host is private or internal. Connect the code host, or upload an archive. |
| That does not look like a repository address | The path must end in the owner and repository name. |
| The repository could not be read | Check the address and that the repository is public. |
| The repository has no default branch to test | Push 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