Setting up an AppScan Presence to scan a GitLab repository

Use an AppScan Presence to run analysis on GitLab Cloud and GitLab Self-Managed repositories.

AppScan Presence includes support for running static analysis on GitLab repositories from a GitLab Self-Managed server or GitLab Cloud instance using a GitLab app. The GitLab server doesn’t have to be publicly accessible; however, the AppScan user must have network access to the GitLab server and permission to access the repositories in GitLab.

An instance of AppScan Presence with GitLab scanning enabled can be associated with one GitLab Self-Managed server and Cloud instance using one GitLab app defined.

To use an AppScan Presence to connect to and scan GitLab Self-Managed or Cloud repositories:
  1. Create and install an AppScan Presence to a folder location on a private network with access to the GitLab Self-Managed server or Cloud instance.
    Note:
    A single AppScan Presence connected to a single GitLab Self-Managed server or Cloud instance allows all the users in the organization to scan repositories on that server to which they have access.
  2. Create a GitLab app on the GitLab Self-Managed server or Cloud instance.
  3. Activate and configure GitLab-specific parameters in the AppScan Presence.
  4. Create the scan.
To create a GitLab application to work with the AppScan Presence:
  1. Log in to GitLab.
  2. Open profile settings:
    1. In the upper-right, click your avatar.
    2. Click Edit profile.
    3. Click Access.
    4. Click Applications.
    5. On the Applications page, click Add new application.
  3. Specify the following application parameters:
    Parameter Value
    Name Your name for the app
    Redirect URI Your AppScan Presence-embedded web application URL plus /signin-gitlab. For example, https://my-presence-host-fqdn/signin-gitlab.
    Scope Select the OAuth 2 scopes required by AppScan Presence.
  4. Click Save application.
Take note of the following values:
  • Application ID: Used as Client ID.
  • Client Secret: Copy immediately after application creation.
  • Redirect URI: Retain for AppScan Presence configuration.

Configure and activate an AppScan Presence

  1. Create a PAT (Personal Access Token) for the GitLab app:
    1. Sign in to GitLab.
    2. In the upper-right, click your avatar.
    3. Click Edit profile.
    4. Click Access tokens.

      In some GitLab versions, it may be under User settings > Access tokens.

    5. Enter a token name.

      For example “PresenceGitLabTest”.

    6. Set an expiration date if required by your GitLab policy.
    7. Select scopes.

      For repository fetch scenarios such as this, read_api and read_repository are common choices.

    8. Click Create personal access token.
    9. Copy the token immediately.

      GitLab shows this token only once.

  2. In the AppScan Presence installation directory, locate the git_connect_settings.json file and open it for editing.
  3. In the GitConnectOptions section of git_connect_settings.json, edit parameters as follows:
    Parameter Description Example
    GitServerName The name of the GitLab server GitLab Cloud instance or GitLab Self-Managed server.
    GitConnectUrl The URL of the web application exposed by this AppScan Presence. This is the same value as CallbackURL when you created the GitLab app. https://my-presence-host-fqdn:443
    GithubAppId AppId of the GitLab app you created for this connection. 1
    GitHubAppUrl Application URl of the GitLab app. https://gitlab.example.com/oauth/applications/1
    ClientId Application ID of the GitLab app. <oauth client id>
    ClientSecret Client secret of the GitLab app. <oauth client secret>
    GitPlatformDomain URL for the GitLab Self-Managed server or Cloud instance. https://gitlab.example.com
    Proxy If a proxy is required to connect to the GitLab server, uncomment this line and provide the proxy details. 127.0.0.1:8888
    Active Enable or disable GitLab connection functionality in the AppScan Presence. The default value is false. true
    GitPlatformType Type of the config server GitLab
    AccessToken Personal Access Token of the GitLab server <Personal Access Token>
  4. HTTPS is required. In the kestrel section of git_connect_settings.json, edit the parameters as follows to configure your secure connection.
    Parameter Description Example
    Http The protocol to be used by the AppScan Presence Https
    Url The port to be used by the AppScan Presence. https://*:443 (or your default secure port)
    Note:
    AppScan Presence uses Kestrel to host its web application. Kestrel is an embedded web server and it can be configured using the Kestrel section in the configuration file. For more information on the structure of this server configuration, see Configure endpoints for the ASP.NET Core Kestrel web server.
Once the configuration is set, the AppScan Presence can be started (or restarted) and scanning can begin. Logs are written to the console and to log files located under the logs folder.

AppScan Presence GitLab scanning flow



  1. The user logs in to ASoC. (1,2)
  2. From ASoC, users select the SCM GitLab and then choose GitLab Self-Managed server or GitLab Cloud. A list of configured enabled AppScan Presencees with the connected servers is returned. The user then chooses Presence.
  3. When the user clicks Authorize presence, ASoC opens a new browser tab that points to AppScan Presence (3) which initiates the oAuth Authorization code flow. The user is then redirected to the GitLab Self-Managed server or Cloud instance, logs in, consents to AppScan Presence accessing the GitLab account, and then is redirected back to the AppScan Presence with the authorization code.
  4. AppScan Presence gets the user access token from the GitLab Self-Managed server or Cloud instance or cloud (4) and sends it back to the user (3) together with a script that sends the token to ASoC using window.postMessage.
  5. ASoC uses the GitLab access token (3) to get a list of repositories that are accessible by the user and to the GitLab app that is used by AppScan Presence. The user can then choose a repository to scan.
  6. Before a scan is created for the selected repository, ASoC verifies that the repository is accessible by the user. The AppScan Presence API (3) function RepoSignature creates a signature for the repository details (repository owner and repository name). Once access is verified, the repository details are signed with a private key that is unique for the AppScan Presence. The signature is returned by the API call to ASoC.
  7. ASoC creates a scan using UsersAPI (2) by provisioning the AppScan Presence ID (Git Connect), the repository details and the signature. UserAPI verifies the signature using a public key associated with the provided AppScan Presence instance. If the validation succeeds, a scan is created for the repository.
  8. The AppScan Presence service, which polls the AppScan Presence WebAPI (5) for tasks, gets a new task to fetch the scanned repository. The AppScan Presence connects to the GitLab Self-Managed server or Cloud instance (6) using access token from config file, fetches the repository as ZIP file, and streams it to the AppScan Presence WebAPI (UploadRepo)
  9. The repository ZIP file is stored in ASoC and can be scanned. When the scan is done, the results are viewed and analyzed in ASoC. The results contain links to the GitLab Self-Managed server or Cloud instance, referencing the relevant lines in the code for triage and remediation. ASoC can open a new tab with the relevant code.