Skip to main content

Connect source control

Everything in Dwaar starts from your code. Until a repository is connected, there is nothing to discover, scan or grade, so this is the first integration to set up.

The fastest way to lose an hour here is an over-scoped or under-scoped token. Every connect form has a guide beside it that walks you through creating exactly the credential Dwaar needs, on the provider's own pages. This page explains the choices behind those guides.

Prerequisites​

  • A role that holds integrations:create, such as Security admin or Administrator.
  • For a token: the token itself, created with the scopes below. For the GitHub App: owner rights on the GitHub organization.

Connect a provider​

  1. Open Integrations and choose your provider, then Add connection.
  2. Pick a Method if the provider offers more than one.
  3. Name the connection after the org or group it covers.
  4. Follow the guide beside the form to create the credential, and fill in the fields.
  5. Press Test connection. Dwaar signs in with these values and saves nothing.
  6. Check who the token belongs to and what discovery would find.
  7. On the discovery step, choose All or Selected, set the exclusions and frequency, and save.

On a narrow window the guide sits above the form under How to get these values. Open it there.

Keep Skip archived and Skip forks on unless you have a reason not to. Archived repositories rarely ship, and forks of other people's repositories are usually not yours to fix.

What you should see​

Your repositories appear under Resources after the first discovery, and scans queue in Scan Center based on the triggers you left on. The default branch is always scanned. Add branch names or globs on the Scanning tab, and at most 3 matching branches are scanned besides the default.

GitHub​

GitHub offers three methods. Pick by what you are connecting:

MethodUse it forWhat you hand Dwaar
GitHub AppAn organization. This is the one to use.Nothing. You install Dwaar's app and choose the repositories on GitHub.
Access tokenA personal account, or an organization where you cannot install apps.A token you create and rotate.
Public repositoryOne public repository you do not own, such as an open source dependency.Nothing. Dwaar reads it with its own account.

GitHub App​

In preview

GitHub App appears under Method once the Dwaar GitHub App is enabled for your Dwaar environment. Until then, connect with Access token.

A token is a secret someone has to create, store and remember to rotate, and it acts with its owner's access to everything. The app removes all three problems. Dwaar keeps no secret of yours: each time it needs GitHub, it asks GitHub for a token that lasts an hour and carries only what you allowed.

  1. Open Integrations, choose GitHub, then Add connection.
  2. Leave Method on GitHub App and name the connection after the organization.
  3. Under What Dwaar may do, keep the ticks Dwaar starts with unless you need more. The table below says what each one allows.
  4. Press Continue to GitHub.
  5. On GitHub, pick the organization, then All repositories or Only select repositories, and select Install.
  6. GitHub asks you to authorize Dwaar. This proves the installation is yours. If you have authorized Dwaar before, GitHub sends you straight back.
  7. Dwaar tests the installation, saves the connection and runs its first discovery. You land on the connection's Discovery tab.

There is no Test connection step and no discovery step in the form, because GitHub is where you choose the repositories. Change the discovery frequency and rules on the Discovery tab afterwards.

What each tick allows​

TickGitHub permissionsStartsWhat Dwaar does with it
Scan repositoriesMetadata, Contents: readOn, alwaysLists the repositories you gave the app and clones them to scan.
Check organization settingsAdministration, Members, Organization administration: readOnReads branch protection, members and two-factor rules for the daily settings posture check.
Check pull requestsChecks: write, Pull requests: readOffSaved with the connection. Dwaar does not post checks yet.
Open fix pull requestsContents, Pull requests: writeOffSaved with the connection. Dwaar does not open them yet.

Why GitHub lists more than you ticked​

GitHub installs an app whole. Its install page lists every permission the Dwaar app is registered with, write access included, whatever you ticked. This surprises people, so it is worth knowing before you show the page to your security team.

Your ticks are still enforced, by GitHub. Every token Dwaar asks for on this connection names only the ticked permissions, and GitHub refuses it anything else. The token Dwaar hands a scan to clone a repository is narrower still: it reads that one repository and nothing more.

If you are not an owner​

Dwaar connects an installation only for an owner of its organization, or for the account itself when you install on your personal account. When a member tries to install, GitHub turns the install into a request, and Dwaar tells you An owner must approve the install. Once an owner approves it on GitHub, open Add connection again and choose GitHub App.

Change it later​

  • Repositories: open the connection's Connection tab and choose Manage on GitHub, or go to the organization's Settings › GitHub Apps on GitHub. The next discovery follows the change.
  • Ticks: connect again. A GitHub App connection has no Replace credential, because there is no credential of yours to replace.

Access token​

Method: Access token.

FieldRequiredValue
Organization or userYesThe GitHub organization or user whose repositories Dwaar discovers, for example acme.
TokenYesA fine-grained token with read access to Metadata and Contents, or a classic token with repo (private) or public_repo.

Prefer the fine-grained token. Classic repo is the only classic scope that covers private repositories, and it grants far more than Dwaar reads. Most organizations require an owner to approve fine-grained tokens. Until one does, the token only reads public repositories, so Test connection passes and lists none of your private ones.

Public repository​

Method: Public repository. For one public repository, with no token of yours.

  1. Enter owner/repo in Repository, or paste the repository's github.com address.
  2. Press Look up. Dwaar checks that the repository exists and is public, and shows its default branch.
  3. Press Add and scan.

Dwaar follows the default branch. Discovery runs every day: a new commit gets a full scan, and an unchanged one is checked for new vulnerabilities. A private repository is refused here. Connect it with GitHub App or Access token instead.

A public repository connection follows that one repository for good. It has no Replace credential and no settings posture check. To scan another repository, add another connection.

GitLab​

Method: Access token.

FieldRequiredValue
Server URLNoLeave as is for GitLab.com. Use your instance URL for GitLab Self-Managed.
GroupNoA group path such as acme/platform. Leave empty to discover every project the token can see.
TokenYesA group access token with the Reporter role, or a project or personal access token, with the read_api and read_repository scopes.

Do not drop read_repository. Without it discovery works and every scan of a private project fails, because Dwaar cannot clone the code.

Bitbucket​

Method: API token. Bitbucket Cloud only.

FieldRequiredValue
WorkspaceYesThe Bitbucket Cloud workspace id.
Atlassian account emailDependsNeeded for an Atlassian API token. Leave empty for a workspace or repository access token.
TokenYesAn API token with read:workspace:bitbucket and read:repository:bitbucket, or a workspace or repository access token with Repositories: Read.

The workspace scope is easy to forget. Without it the test fails, because Dwaar reads the workspace before its repositories.

Azure DevOps​

Method: Personal access token.

FieldRequiredValue
Server URLNoLeave as is for Azure DevOps Services. Use your collection URL for Azure DevOps Server.
OrganizationYesThe Azure DevOps organization.
TokenYesA PAT with Code (Read) and Project and Team (Read).

GitHub Enterprise Server​

Method: Personal access token.

FieldRequiredValue
Server URLYesYour GitHub Enterprise Server URL, for example https://github.acme.com.
Organization or userYesThe organization or user whose repositories Dwaar discovers.
TokenYesA fine-grained token with read access to Metadata and Contents, or a classic token with repo.
Important

The server has to be reachable from Dwaar over the internet with a certificate from a public certificate authority, or from an outpost the connection runs on. Private and internal addresses are refused unless the connection runs on an outpost. If the test says the server cannot be reached, the fix is in your network path or your URL, not your token. A server on a private network needs an outpost: set Runs on under Where it runs before you test.

Settings posture on GitHub​

GitHub and GitHub Enterprise connections get one more check. Once a day after discovery, Dwaar checks the organization's settings and its tracked repositories' settings, such as branch protection, two-factor and Actions permissions. A token connection uses its token. A GitHub App connection uses a token with the Check organization settings permissions, so it only runs when that tick is on: without it, the connection's Scanning tab reads Off for this connection. A public repository connection is never checked. You can turn the check off in Scan Center.

When the test fails​

Dwaar tells you which kind of failure you hit, and the kinds have different fixes.

ReasonWhat to do
CredentialsCheck the token, its scopes and the account, then test again.
UnreachableCheck the server URL and that Dwaar, or the connection's outpost, can reach it.
TimeoutThe provider did not answer in time. Try again.

A GitHub App install that stops part way shows its reason on the page GitHub returns you to:

MessageWhat to do
This GitHub install expired or was already usedStart again from Add connection. An install must finish within 30 minutes, by the person who started it.
You are not an owner of the organizationAsk an owner of that organization to connect it.
The installation has not granted what this connection asks forAn owner accepts the app's new permissions on GitHub, then test the connection again.
The Dwaar app is no longer installed on this accountSomeone removed the app on GitHub. Connect again.

Try this next​

Connect a single organization with the GitHub App, leaving the ticks as they start, and give it a handful of repositories rather than all of them. Watch the first discovery on the Discovery tab, then add the rest on GitHub with Manage on GitHub. A short, honest list of repositories gives you a much more useful first grade than everything at once. Next, add a registry so Dwaar can follow your code into what you ship.