How to create a Github Personal Access Token to scan your repositories

Given you want to use our DeepScan service to scan a repository that has access protection, you are requested to provide a username and password combination, so that our service may access your repository on your behalf. This article will describe how you may arrange this and how you may configure your token to prevent unwanted access or loss of confidentiality.

When and where to scan

Scanning your repositories time by time on file base is a useful hygiene activity. This prevents you from surprise of unwanted code artefacts, on the other hand it will allow you to learn about the re-use of files across your solution portfolio. 

On the other hand scanning on file level is a high computational effort, costing energy and time. Thus we recommend not to use it on an every-commit-base. Even in structures under heavy development typically only a small fraction of the codebase is changing. Therefor we recommend to focus on new components when they enter the project. Given these are open source  components, please also see our DeepScan Scaleout solution.  

However, if you feel like it is about time for a scan on file-level, you may either scan repositories using the DeepScan CLI tool, see the help for details, include it in your commit flow through automation via ts-scan or initiate a scan using the build-in service from TrustSource. While the first two options will run on your infrastructure, the latter requires to clone the code to the DeepScan service.

The DeepScan service will ramp up a container within our infrastructure, clone the code to a ephemeral disc space accessible only for this container, execute the scan, upload the scan results to TrustSource, erase the disc and terminate. 

Generating a PAT

Since a while GitHub requires especially enterprise users to setup Multi factor authentication (MFA). This is preventing you from providing your username and password combination to TrustSource for access. But GitHub allows to generate so called Personal Access Tokens or short PATs.

To generate such a token, go to Github, signin and click on your profile picture on the upper right corner. In the menu select SETTINGS and scroll down to the bottom of the page. Select DEVELOPER SETTINGS from the menu on the left side. From the new page pick PERSONAL ACCESS TOKENS. This will open a submenu where you pick FINE-GRAINED TOKENS.

This will show a list of tokens you already generated. If this will be your first token, no worries, we will guide you through the next steps. On the upper right side of the content area you will see a button GENERATE NEW TOKEN. Press this and follow the next steps:

1. Assign a name

Assign your token a meaningful name, so that you will understand it s purpose later. You also may add a useful description.

2. Identify Resource Owner

The you need to select the resource owner. Most likely this will be the organisation owning the TrustSource account but it also may be that it is a 3rd party organisation. In that case it may be required that you complete a request declaring why you plan to generate this token, e.g. "Allow DeepScan by TrustSource"

3. Scope the PAT 

In the next step you will select the scope of the token. You may allow it for all public repositories of this organisation to access :

• all public repositories
• all repositories within the organisation, including the private ones you have access to
• selected repositories

We recommend to keep the scope as limited as possible. Given you are working with a selected group of repositories, it may be practical to allow access to several at once. But we would recommend to keep it to the target repository.

4. Limit validity 

Github allows you to limit the lifespan of the token. Given you want the token to be used only once, you may select a few hours as lifespan. TrustSource does not store the token! Thus, you will have to keep the token either in a password store for later use, or re-generate the token anyway. 

Given you want to run DeepScans on a regular base, we suggest to use a Github action and a ts-scan command instead. This allows you better control over the use of access tokens. See the ts-scan help for more information (last section on the page) on that option.

5. Define required permissions

In the next step you will define the permissions Github shall grant to the token, respectively to TrustSource. As of now, we only require the right to clone the repository. However, to avoid conflicts with upcoming service implementation, we suggest to grant the following 4 rights with the READ-ONLY option: Attestations Codespaces  Codespaces metadata Contents

And there you are all set. Generate the PAT.

Apply the PAT

The token will have a structure like displayed in the following schema:

github_pat_123456789ABCdefGhiJkLmnoPQRstUvWxyZ123'*?/&%

You should copy the token. It will be visible only once.

Finally paste it in the password / token section of the form and you are ready to go.