DTrack Analyzer (WIP)

Prerequisites

To run analysis for your projects against DTrack (https://dtrack.int.ibmix.de), you need to aquire the following keys first: DTRACK_API_KEY and DTRACK_PROJECT_ID

The DTRACK_API_KEY is client-based, which means per client a respective security group will be created within DTrack. The key itself is then bound to the security group.

Under each security group, as many projects as required can be created. Per project, you will get the respective DTRACK_PROJECT_ID.

Example:

Client	Project	Token
My Client		DTRACK_API_KEY
	Backend App	DTRACK_PROJECT_ID #1
	Frontend App	DTRACK_PROJECT_ID #2

For the keys and required DTrack configuration, reach out to one of the DTrack responsible colleagues, e.g. Bernhard Schleicher or Daniel Tobner!

Installation

The following instructions are assuming that your CI/CD environment is capable of running Docker Containers!

DTrack Analyzer Docker Container Installation

You need the following files:

• .env
• docker-compose.yml
• Dockerfile
• entrypoint.sh

Adapt the .env file and replace the placeholder YourDTRACK_API_KEY with the DTRACK_API_KEY you acquired as prerequisite.

Perform the following command to build the DTrack Analyzer Docker Image with the name dtrack-analyzer:

docker compose build

CI/CD Pipeline Integration

In your CI/CD pipeline integrate the following script:

Jenkins Bash Example:

#!/bin/bash -e

docker run -e DTRACK_PROJECT_TYPE=YourDTRACK_PROJECT_TYPE -e DTRACK_PROJECT_ID=YourDTRACK_PROJECT_ID -v $WORKSPACE:/dtrack --rm dtrack-analyzer

Replace the following placeholders with your values:

• YourDTRACK_PROJECT_TYPE:
  • The DTrack Analyzer is currently optimized/tested for the values node.js and java. For a full list of options see https://github.com/CycloneDX/cdxgen#supported-languages-and-package-format.
    • For SAP CX projects use the type universal.
    • If your required type needs enhancements on the DTrack Analyzer, please reach out to Daniel Tobner!
• YourDTRACK_PROJECT_ID:
  • The respective DTRACK_PROJECT_ID you acquired as prerequisite.

Error Handling

Based on the configuration #!/bin/bash -e from the Bash example above, this script will automatically detect if the DTrack Analyzer failed and also fail the build step.

In addition, you can also check the execution status of the last operation by calling $?. If the last operation was successful, the result will be 'true' or '0', otherwise 'false' or '1' (depending on the OS).

If the DTrack Analyzer failed, you will also find a respective message in the pipeline output:

Example for wrong DTrack API URL:

...
[DTrack Analyzer] running ...
[DTrack Analyzer] FAILED:
Executing '/dtrack/mvnw org.cyclonedx:cyclonedx-maven-plugin:2.7.2:makeAggregateBom -DoutputName=bom -q' in /dtrack
HTTPError: Response code 405 (Not Allowed)
    at Request.<anonymous> (/usr/local/lib/node_modules/@appthreat/cdxgen/node_modules/got/dist/source/as-promise/index.js:118:42)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5) {
  code: 'ERR_NON_2XX_3XX_RESPONSE',
...

Jenkins example

node() //docker-agent
{
    stage("process dt")
    {
        cleanWs()
        dir("checkdir")
        {
                sh """
                cp -f /var/jenkins_home/.ssh/id_ed25519-ix-as-travel-emails /var/jenkins_home/.ssh/id_ed25519
                git clone git@github.ibm.com:IBM-iX-DACH/ix-as-travel-emails.git
                """
            dir("ix-as-travel-email")
            {
                sh "docker run -e DTRACK_PROJECT_TYPE=\"node.js\" -e DTRACK_API_KEY=\"odt_VHHytA3pxjywBo8JJvhLH4WjXtGG1tpT\" -e DTRACK_PROJECT_ID=\"370fd5e4-36a8-415f-921e-143893818539\" -v /mnt/c/Users/059007618/Docker/linux-container/jenkins/data/workspace/dt-ix-travel-emails/checkdir/ix-as-travel-emails:/dtrack --add-host=\"dtrack-api.int.ibmix.de:172.19.4.7\" --rm registry.local.lan/dtrack-analyzer"
            }
        }
    }
}