About the connector

Jenkins is an open-source automation server widely used to implement Continuous Integration (CI) and Continuous Delivery (CD) pipelines. It helps automate the parts of software development related to building, testing, and deploying, facilitating faster and more reliable software delivery.

This document provides information about the Jenkins connector, which facilitates automated interactions, with a Jenkins server using FortiSOAR™ playbooks. Add the Jenkins connector as a step in FortiSOAR™ playbooks and perform automated operations with Jenkins.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.4.1-3167

Jenkins Version Tested on:

Authored By: Fortinet

Certified: No

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-jenkins

Prerequisites to configuring the connector

• You must have the credentials of Jenkins server to which you will connect and perform automated operations.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the Jenkins server.

Minimum Permissions Required

• Not applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Jenkins connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter	Description
Server URL	Provide the host URL of the jenkins server to connect and perform automated operations.
Username	Username of the jenkins server to which you will connect and perform automated operations.
API Token	Specify the API token of the jenkins server to which you will connect and perform automated operations.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified. By default, this option is selected, i.e., set to true.

Actions supported by the connector

You can use the following automated operations in playbooks and also use the annotations to access operations:

Function	Description	Annotation and Category
Get List Jobs	Retrieves a list of all available jobs from the Jenkins server.	get_list_jobs Investigation
Trigger Job	Triggers a Jenkins job with specified parameters.	trigger_job Investigation
Get Job Status	Retrieves the current status and details of the specified Jenkins job.	get_job_status Investigation
Resume Jenkins Job with Input	Submits input to a paused Jenkins pipeline job that is waiting at a user input to resume execution.	resume_jenkins_job_with_input Investigation
Execute an API Request	Sends an API request to any API endpoint based on specified HTTP method, endpoint, and other input parameters that you have specified, enabling flexible API interactions tailored to user needs.	generic_rest_api_call Investigation

operation: Get List Jobs

Input parameters

Parameter	Description
Job Path	(Optional) Specify the name or full path of the Jenkins job to retrieve the list of jobs. For jobs inside folders, include the full folder hierarchy using repeated /job/ segments.

Output

The output contains the following populated JSON schema:

{
    "_class": "",
    "assignedLabels": [
        {}
    ],
    "mode": "",
    "nodeDescription": "",
    "nodeName": "",
    "numExecutors": "",
    "description": "",
    "jobs": [
        {
            "_class": "",
            "name": "",
            "url": "",
            "color": ""
        }
    ],
    "overallLoad": {},
    "primaryView": {
        "_class": "",
        "name": "",
        "url": ""
    },
    "quietingDown": "",
    "slaveAgentPort": "",
    "unlabeledLoad": {
        "_class": ""
    },
    "useCrumbs": "",
    "useSecurity": "",
    "views": [
        {
            "_class": "",
            "name": "",
            "url": ""
        }
    ]
}

operation: Trigger Job

Input parameters

Parameter	Description
Job Path	Specify the name or full path of the Jenkins job to be triggered. For jobs inside folders, include the full folder hierarchy using repeated /job/ segments
Build Parameters	(Optional) Specify the parameters in JSON format as key-value pairs to be passed to the job

Output

The output contains the following populated JSON schema:

{
    "job_name": "",
    "build_no": "",
    "job_build_url": ""
}

operation: Get Job Status

Input parameters

Parameter	Description
Job Path	Specify the name or full path of the Jenkins job Jenkins job to retrieve its status and detailed information. For jobs inside folders, include the full folder hierarchy using repeated /job/ segments
Build Number	Specify the build number of the Jenkins job to retrieve its status and detailed information.

Output

The output contains the following populated JSON schema:

{
    "_class": "",
    "actions": [
        {
            "_class": "",
            "parameters": [
                {
                    "_class": "",
                    "name": "",
                    "value": ""
                }
            ]
        },
        {
            "_class": "",
            "causes": [
                {
                    "_class": "",
                    "shortDescription": "",
                    "userId": "",
                    "userName": ""
                }
            ]
        }
    ],
    "artifacts": [],
    "building": "",
    "description": "",
    "displayName": "",
    "duration": "",
    "estimatedDuration": "",
    "executor": "",
    "fullDisplayName": "",
    "id": "",
    "keepLog": "",
    "number": "",
    "queueId": "",
    "result": "",
    "timestamp": "",
    "url": "",
    "builtOn": "",
    "changeSet": {
        "_class": "",
        "items": [],
        "kind": ""
    }
}

operation: Resume Jenkins Job with Input

Input parameters

Parameter	Description
Job Path	Specify the name or full path of the Jenkins job to resume. For jobs inside folders, include the full folder hierarchy using repeated /job/ segments
Build Number	Specify the build number of the Jenkins job to resume execution with user-provided input.
Input ID	Specify the unique identifier for a specific input step or approval request within a Jenkins build.
Input Parameters	Specify the parameters as key-value pairs in JSON format to be passed to the job and resume execution. For example: [{"name":"param1","value":"valueOfParam1"},{"name":"param2","value":"valueOfParam2"}]
Job Status	Specify the parameters as key-value pairs in JSON format to be passed to the job and resume execution. For example: [{"name":"param1","value":"valueOfParam1"},{"name":"param2","value":"valueOfParam2"}]

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "response": ""
}

operation: Execute an API Request

Input parameters

Parameter	Description
Endpoint URL	Specify the target API URL path for the request. For example, if the website is https://example.com and URL path is https://example.com/api/v2/incidents/search, the endpoint would be /api/v2/incidents/search.
Method	Select an HTTP action for the request. You can select from the following options: GET, DELETE, PATCH, POST, PUT.
Query Parameters	(Optional) Specify any optional parameters to add to the URL and refine the request.
Payload	(Optional) Specify data, as JSON, to be sent as the request payload (typically for POST or PUT requests).

Output

The output contains a non-dictionary value.

Included playbooks

The Sample - Jenkins - 1.0.0 playbook collection comes bundled with the Jenkins connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Jenkins connector.

• Execute an API Request
• Get Job Status
• Get List Jobs
• Resume Jenkins Job with Input
• Trigger Job

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling events/alerts/incidents, based on the requirement.

TODO: provide the list of steps to configure the ingestion with the screen shots and limitations if any in this section.