Pre-Production Scans: Uploads via Jenkins

Add the plugin to your Jenkins

• Open your Jenkins home page

• Click on Manage Jenkins

• Access to Manage Plugins

• On the Available list, search for Send build to Data Theorem

• Click on Install once you find the appropriate entry

Update the plugin

• Open your Jenkins home page

• Click on Manage Jenkins

• Access to Manage Plugins

• On the Updates list, search for Send build to Data Theorem

• Click on Download now and install after restart

• Restart Jenkins

Add your Upload API key to the Jenkins global configuration

Retrieve your Upload API key from the  Data Theorem portal at the link below:

https://www.securetheorem.com/mobile/sdlc/api_access

On the home page of your Jenkins instance:

• Click on Credentials within the sidebar

• Navigate to System

• Click on Add credentials

You will be provided with the option to create a Secret text credentials:

• Add your Upload API key from the steps above to the secret field.

• Add an ID to identify this key e.g. Data_Theorem_ApiKey

• Add a description to explain the purpose of this key e.g. API Key to authenticate to the Data Theorem Upload API.

Add or update a Jenkins job

• Go back to the home page of your Jenkins instance

• Open the configuration page of the job that is used as the CI/CD pipeline of your iOS or Android application

From the configuration page, you will be required to modify multiple sections:

• Build Environment: Unlock the "Binding" section to access the API Key from the credentials

• Build: Add your building steps

• Post-build action : Add your post-build actions, including the Data Theorem plugin

Get access to your API Key (Credentials Binding)

Use the Credential Binding Plugin to bind the API Key added in the previous step to an environment variable which must be named as DATA_THEOREM_UPLOAD_API_KEY.

Add your building steps

Build your sources using the Build section. You will need to generate a valid .apk or .ipa package during this step.

Add the Data Theorem plugin to the job

The Data Theorem plugin can be added from the Add post-build action list

Configure the plugin by indicating the file name that will be generated on the Build To Upload field. This allows the plugin to discover and retrieve the package for upload.

You can use a glob pattern to indicate variable parts of the build's file name (for example, if the app's version number or build date is in the file name). The previously generated artifacts will be automatically discovered from your archive folder or in the current workspace.

Examples of glob patterns:

• app-*.apk : search for any apk starting with app- in workspace root directory

• **/app-*.ipa : search for any ipa starting with app- in any sub directory of the workspace

• {,**/}app-debug*.* : search for any file containing app-debug in root directory or in any sub directory of the workspace

If the file is located at /Users/jenkins/project-workspace/dir1/dir2/app.apk, you should only specify the relative part i.e dir1/dir2/app.apk. This is because the plugin has access to the current Jenkins workspace only.

Advanced Section

Simulating Uploads

You can simulate what file would be sent without actually uploading it to Data Theorem by checking the Don't Upload Build in the advanced options. Builds should be restricted to those that need analysis by Data Theorem's mobile app security services.

The external id field can be set as a custom identifier for this app.

Android Mapping Files

You can upload a mapping file using the Android Mapping File option to have scan results deobfuscated.

• This is not required for scans to be completed. However, once a mapping file has been uploaded once, all subsequent uploads will require the corresponding mapping file unless the requirement is disabled via the Results API v2.

Proxy Configuration

If needed, you can configure the plugin to go through your company proxy on the advanced option of Post-Build Actions. You will have to specify the hostname and the port of the targeted proxy. You can also add your authentication credentials and bypass the certificate validation if needed

Advanced section:

Proxy Configuration section:

Start a new build to test the plugin

You can test that the plugin is correctly configured by starting a new build and then access the last build result. If the plugin works you should get the following console output:

Using the Data Theorem plugin inside a DSL pipeline

As an alternative since version 1.3.0, the Jenkins plugin is compatible with DSL pipelines. To send builds using DSL pipelines:

• Create a new job

• Select Pipeline.

After the different builds stages, add a new stage named as Upload Build To Data Theorem. You will be required to set an environment variable with your secret upload api key using the command withCredentials() from the Credentials Binding Plugin

Inside the withCredentials() scope, use the command sendBuildToDataTheorem with the following parameters:

• buildToUpload: Glob pattern identifying the build you want to send to Data Theorem

• mappingFileToUpload: If your Android application is obfuscated using Proguard, you can upload a mapping file to have scan results deobfuscated. This is not required for scans to be completed. However, once a mapping file has been uploaded once, all subsequent uploads will require the corresponding mapping file unless the requirement is disabled via the Results API v2.

• dontUpload : If set to true, this will simulate what file would be sent without uploading it to Data Theorem

• dataTheoremUploadApiKey: The upload api key environment variable

• proxyHostname: If needed, the proxy hostname you need to go through when uploading the build

• proxyPort: If needed, the proxy port you need to go through when sending the application
  
  

• proxyUsername: If needed, the username you use to authenticate to the proxy

• proxyPassword: If needed, the password you use to authenticate to the proxy

• proxyUnsecuredConnection: If true, the plugin will bypass any SSL certificate validation

• externalId: If set, the externalId field represents your organization's custom identifier for the app.

• releaseType: (optional, but strongly encouraged):

  • This should be set to PRE_PROD or ENTERPRISE, depending on whether the app being uploaded is a pre-production app (or a "test" app) or an enteprise (internal) app (an internal-only production app that will not be published to one of the app stores).

  • If the argument is omitted, then our backend will first try to match the build to any existing ENTERPRISE or PRE_PROD apps. If there is no matching app, then it will default to PRE_PROD.

Scripted Pipeline Integration

The plugin supports scripted pipeline integration. To use this option, you would need to replace the DSL command with the following command:

[$class :'SendBuildToDataTheoremPublisher', buildToUpload: '**/*.apk', mappingFileToUpload: null, dontUpload: false, dataTheoremUploadApiKey: env.DATA_THEOREM_UPLOAD_API_KEY, proxyHostname: '', proxyPort: 0, proxyUsername: '', proxyPassword: '', proxyUnsecuredConnection: false]

Data Theorem DSL Pipeline example stage

Send Application Credentials to Data Theorem

As an optional step, credentials for your application can be supplied to Data Theorem using the plugin for better analysis coverage. If your application has a login page, Data Theorem can use specified credentials to analyze your application.

To send your applications credentials, fill the application credentials section provided by the plugin as follows:

• Username - the name to use to login to your application

• Password - the password to use to login to your application. This field is required if a username is provided.

• Comment - an optional comment indicating the purpose for the credentials.
  
  
  

For DSL pipeline you should add the following parameters to sendBuildToDataTheorem