# Jenkins

SureCloud connects to Jenkins to retrieve job and pipeline configuration, build history, and security plugin status. This allows SureCloud to verify that CI/CD pipelines include required security steps, that build jobs are protected by access controls, and that Jenkins itself is configured securely — providing evidence for secure development lifecycle and build pipeline security controls.

{% hint style="info" %}
Jenkins is self-hosted software. The SureCloud integration connects to your Jenkins instance's REST API over HTTPS. Ensure your Jenkins instance is accessible from the SureCloud collector network before configuring the connection.
{% endhint %}

## Authentication and setup

Jenkins authenticates API requests using HTTP Basic Authentication with a username and API token. SureCloud uses a dedicated Jenkins service account with read-only permissions.

{% stepper %}
{% step %}
**Create a dedicated Jenkins service account**

In Jenkins, navigate to **Manage Jenkins → Manage Users** and create a new user (e.g. `surecloud-integration`). If your Jenkins instance uses an external authentication provider (LDAP, Active Directory), create the service account there instead.
{% endstep %}

{% step %}
**Assign read-only permissions**

Navigate to **Manage Jenkins → Configure Global Security → Authorization**. Using your configured authorisation strategy (Matrix-based security recommended), grant the `surecloud-integration` user the following permissions: **Overall/Read**, **Job/Read**, **View/Read**. Do not grant Build, Configure, or Admin permissions.
{% endstep %}

{% step %}
**Generate an API token for the service account**

Log in to Jenkins as the `surecloud-integration` user. Navigate to **\[Username] → Configure → API Token** and click **Add New Token**. Name it `SureCloud CCM` and click **Generate**. Copy the token.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Jenkins → Connect**. Enter your Jenkins base URL (e.g. `https://jenkins.yourcompany.com`), the service account username, and the API token. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API token securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Jenkins → \[Username] → Configure → API Token** and update it in **SureCloud → Integrations → Jenkins → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                      | Use Case                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------ |
| `GET /api/json`                               | Retrieve top-level Jenkins instance info and installed plugins list      |
| `GET /api/json?tree=jobs[name,url,color]`     | Enumerate all jobs and their current build status                        |
| `GET /job/{job-name}/api/json`                | Retrieve job configuration including SCM settings and build triggers     |
| `GET /job/{job-name}/lastBuild/api/json`      | Retrieve the most recent build result and timestamp per job              |
| `GET /job/{job-name}/{build-number}/api/json` | Retrieve individual build detail including stages and result             |
| `GET /pluginManager/api/json?depth=1`         | Retrieve installed plugin list and versions for security plugin evidence |
| `GET /securityRealm/api/json`                 | Retrieve authentication realm configuration                              |

## Pagination

Jenkins does not use standard cursor or token pagination. `GET /api/json?tree=jobs[...]` returns all top-level jobs in a single response. For large Jenkins instances with many jobs, SureCloud uses the `tree` parameter to limit the fields returned per job and reduce response size. Folder-organised jobs are traversed recursively using the folder API:

```http
GET /job/{folder-name}/api/json?tree=jobs[name,url,color]
```

Build history is retrieved by iterating build numbers from `lastBuild.number` downwards for a defined lookback window.

## Required permissions

SureCloud requires a Jenkins user with the following permissions:

| Permission   | Purpose                                            |
| ------------ | -------------------------------------------------- |
| Overall/Read | Access the Jenkins API and top-level configuration |
| Job/Read     | Read job configuration and build history           |
| View/Read    | Access view listings                               |

No Build, Configure, Delete, or Admin permissions are required.

## Polling frequency

| Data Type                             | Interval       |
| ------------------------------------- | -------------- |
| Job inventory and latest build status | Every 24 hours |
| Build history                         | Every 6 hours  |
| Installed plugins and versions        | Every 24 hours |
| Security realm configuration          | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test fails or returns 403 Forbidden</summary>

The service account does not have **Overall/Read** permission, or the Jenkins CSRF protection is blocking API requests. Verify the permission assignment in **Manage Jenkins → Configure Global Security**. If CSRF is enabled, ensure SureCloud's requests include the required crumb header — SureCloud handles crumb fetching automatically, but confirm that the crumb issuer is enabled in your Jenkins security configuration.

</details>

<details>

<summary>Jobs are missing — only top-level jobs appear</summary>

Jobs organised in folders are not returned by the root `GET /api/json` call alone. SureCloud traverses Jenkins folders recursively, but very deep or large folder hierarchies may result in some jobs being missed on the first collection cycle. Trigger a manual refresh from **SureCloud → Integrations → Jenkins** to re-traverse the job tree.

</details>

<details>

<summary>Jenkins instance is unreachable</summary>

Confirm the Jenkins URL is correct and accessible from the SureCloud collector network over HTTPS. Self-hosted Jenkins instances on private networks require a firewall rule permitting inbound connections from SureCloud's collector IP range. Contact SureCloud Support for the current collector IP range.

</details>

<details>

<summary>Plugin list returns empty</summary>

The `pluginManager` endpoint requires **Overall/Read** permission at minimum. If this endpoint returns empty or 403, confirm the service account has the correct permissions. If Jenkins uses a non-standard plugin manager configuration, contact SureCloud Support.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/jenkins.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.