jenkins-plugin

The official Meterian plugin for Jenkins.

This has not been published yet, but you can have a look at the code and snoop around. This plugin is expected to work in classic jobs and pipelines (Jenkinsfile) with the ability to include the analysis as part of your build process, as it should be.

The integration that we are building first, also in light that nobody did that before, is with Gerrit Code Review, where we with the help of Robot Comments we can leverage the automatic fixing ability of Meterian with the smooth review flow of Gerrit.

More to be written here after the plugin is launched :)

Build

Build the project with the below command from inside the project root folder:

./bin/build.sh

Note: this runs the unit/integration tests which is part of the project and can take a bit of time.

Tests it runs:

Running InjectedTest:

InjectedTest
SimpleFileCompareTest
ClientDownloaderTest

Look in the target folder for all the generate artifacts, you will find meterian-plugin.jar among others.

Run

Run the project with the below command from inside the project root folder:

./bin/run.sh

This kicks off a full-fledged Jenkins instance and can be access via http://0.0.0.0:8080/jenkins/ or http://localhost:8080/jenkins/ or http://127.0.0.1:8080/jenkins/.

One or more jobs can be executed via this console. When these jobs are executed, and depending on the type of job, the Meterian Jenkins plugin configured with each of the jobs is triggered and the respective actions are executed.

Artifacts

These are the two artifacts are created in the target folder:

target/meterian-plugin.hpi
target/meterian-plugin.jar

The meterian-plugin.hpi is the artifact that will be installed as a Jenkins plugin, via the Jenkins, see https://jenkins.io/doc/book/managing/plugins/.

Configuration

In order to run the tests locally we would need the following two environment variables populated with valid values or else the tests will fail:

METERIAN_API_TOKEN - this is generated via the Meterian dashboard (via https://www.meterian.com, you will need an account)
METERIAN_GITHUB_USER - this is the machine user account created by yourself (learn more about machine user creation at GitHub: developer guides | machine-users), follow the steps mentioned in the link (default: meterian-bot)
METERIAN_GITHUB_EMAIL - this is the email address associated with the machine user account created in the previous step (default: [email protected])
METERIAN_GITHUB_TOKEN - this is the personal token generated from the machine user account created by yourself (learn more about machine user creation at GitHub: developer guides | machine-users), follow the steps mentioned in the link

CircleCI configuration

Ensure the above two environment variables are set via https://circleci.com/gh/[Your GitHub Org]/jenkins-plugin/edit#env-vars.

In addition you would also need to add the SSH key associated with the Machine User created above to the CircleCI SSH keychain, see how that is done via https://circleci.com/docs/2.0/gh-bb-integration/#creating-a-machine-user.

Note: in general the above might not be needed if your CI/CD environment contains the necessary permission to perform git push related actions on the target repo you are analysing.

Run Tests

All tests

mvn test

Specific tests

mvn test -Dtest=MeterianClientTest

Jenkins job types

SimplePipeline

Builds a single branch using the Pipeline facility via the jenkinsfile script.

Technical detail: flows through the MeterianPlugin class and is handled by SimpleOrFreeStyleExecutor.

MultiPipeline

Builds multiple branches concurrently, using the Pipeline facility via the jenkinsfile script.

Technical detail: flows through the MeterianStep class and is handled by StandardExecutor.

FreeStyle

Builds a single branch but does not give the facility to specific Jenkins config via the jenkinsfile.

Technical detail: flows through the MeterianPlugin class and is handled by SimpleOrFreeStyleExecutor.

Meterian features

The below features can be used across the above Jenkins job types.

Only report

Default behaviour no client args required.

This option does the default task of scanning the project and reporting the vulnerabilities, if present, and recommended fixes but does not apply them.

Autofix (report and create Pull Request)

Using the --autofix client arg option (Go to Jenkins > Configure > Meterian for the field Client JVM args).

This option does the task of scanning the project and reporting the vulnerabilities, if present, and also applying the fix to the respective branch and creating a pull request to the repository.

Ensure your GitHub OAuth token to your Organisation and Repo has been added to the Meterian configuration settings under Jenkins > Configure > Meterian. Enter your GitHub OAuth meterianAPIToken in the field GitHub OAUTH token. If this field is empty or incorrect appropriate error messages are displayed in the Jenkins logger (console).

Running Meterian client from CLI

The below command should do it, provided the plugin has already downloaded the client:

java -jar ${HOME}/.meterian/meterian-cli.jar [meterian args]

[meterian args] - one or more args for additional features i.e. --interactive=false or --autofix

On the first run, it will authorise you, so please ensure you have an account on https://www.meterian.com.

Note: the Meterian client is automatically downloaded by the plugin when it detects the absence of it and is saved in the ${HOME}/.meterian folder.

Additional information and sources about writing plugins for Jenkins

See https://stackoverflow.com/questions/43690435/failure-to-find-org-jenkins-ci-pluginspluginpom2-11-in-https-repo-maven-apa on how to avoid the below warning message:

[WARNING] The POM for org.jenkins-ci.tools:maven-hpi-plugin:jar:2.7 is missing, no dependency information available
[WARNING] Failed to build parent project for io.jenkins.plugins:meterian-plugin:hpi:0.1-SNAPSHOT