Security Hardening, CSRF, Agent-to-Controller Controls, Script Security, CSP, TLS, and Reverse Proxies: Concepts, Architecture, and Mental Model

1. The problem: Jenkins is an execution control plane

Jenkins is not just another web application. A controller stores job configuration, credentials metadata, plugin code, build history and orchestration state, and it can direct agents to execute arbitrary build instructions. A single boundary failure can therefore turn a web, script, plugin or agent weakness into controller-level code execution or credential exposure.

Previous chapters separated identities, credentials, agents, external providers and administrative interfaces. This chapter composes those ideas into a security posture. The goal is not to “lock down everything” blindly. It is to make each trust boundary explicit, expose only what is necessary, and collect evidence proving that an attacker-controlled build cannot silently become a controller administrator.

2. Mental model: seven boundaries, seven different jobs

Follow the request from outside to inside. A client first reaches a network endpoint. A reverse proxy may terminate TLS and forward the request. Jenkins then authenticates the identity, authorizes the requested operation and applies CSRF protection to state-changing browser/session requests. The request may reach controller APIs or configuration. Groovy and plugin code cross a stronger in-process execution boundary. Agents communicate with the controller over Remoting, but current Jenkins restricts what an agent can ask the controller to do. Build steps execute on agents, while browser rendering of archived or workspace content has its own CSP/user-content risks.

flowchart TD
  A[Client or automation] --> B[TLS / reverse proxy boundary]
  B --> C[Authentication + authorization + CSRF]
  C --> D[Jenkins web/API controller surface]
  D --> E[Script / plugin trust boundary]
  D --> F[Remoting agent-to-controller boundary]
  F --> G[Agent executor + workspace]
  G --> H[Artifacts / reports / user content]
  H --> I[Browser CSP / Resource Root boundary]

The arrows matter. TLS protects traffic; it does not grant Jenkins permissions. Authentication proves an identity; authorization decides whether that identity may configure a job or administer Jenkins. CSRF protects a logged-in browser/session from unwanted state changes; it is not a substitute for authorization. Script Security constrains supported Groovy surfaces; it does not sandbox Script Console. CSP constrains browser execution; it does not make an unsafe plugin or build trustworthy.

3. State ledger before hardening

Security work is risky when the operator cannot say which persisted state will change. Record this ledger before touching the controller.

4. Read-only inspection first

Begin with screenshots or exported text from Manage Jenkins → Security, Nodes, System, Script Approval and Plugins. Also record the public Jenkins URL and how the backend listens. On the host, use OS/network tools that do not modify state:

# Controller-local examples; adapt paths/ports to your disposable lab.
java -version
ss -ltnp | grep -E ':(8080|50000|443)\\b' || true
curl -sS -D - -o /dev/null http://127.0.0.1:8080/login

# From an authenticated read-only API identity, record exact core identity.
curl -fsS -u "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "$JENKINS_URL/api/json?tree=nodeName,url"

Do not place a token literally in the command line or shell history. Load it from a protected environment/file for the disposable lab and redact it from any evidence packet.

5. Controller isolation: executor count is a security setting

The built-in node shares the controller process host and usually its filesystem namespace. Build authors may control build scripts, tests and tool invocation, so routine builds on that node enlarge the blast radius. Jenkins security guidance recommends executing builds on separate agents. Set the built-in node executor count to 0 once a suitable agent exists, then prove the change by showing that buildable jobs can only acquire agent executors.

6. CSRF: keep crumbs enabled and understand the exception

Current Jenkins binds a crumb to the user and web session. A scripted client using username/password must fetch a crumb and preserve the matching session cookie before a state-changing POST. A request authenticated with an API token is exempt from crumb validation. That exemption is intentional; it is not a reason to disable CSRF globally.

# Read-only: discover crumb field/value with a session-aware cookie jar.
curl -sS -c cookies.txt -u "$JENKINS_USER:$JENKINS_PASSWORD" \
  "$JENKINS_URL/crumbIssuer/api/json"

# For automation, prefer an API token and exact authorization rather than a password.
# Do not echo either value into the build log.

Older reverse-proxy advice may mention “proxy compatibility” for IP-address changes. Since Jenkins 2.543 the crumb no longer uses client IP in the default issuer, and that option was removed. Diagnose current session/header issues instead of applying obsolete settings.

7. Script Security: sandbox is a control, not a magic shield

Pipeline, Job DSL and other plugins can use Script Security’s sandbox and approval mechanisms. Approving a signature broadens what sandboxed code may do; approving a whole script or trusted library can be much more powerful. Review every approval as controller configuration with an owner and reason.

On 16 September 2026 Jenkins disclosed multiple high-severity Script Security sandbox bypasses affecting 1415.v9a_f9b_3a_c253d and earlier. The fixed version is 1422.v06869826dd9b_. A controller teaching sandbox boundaries should not keep the known-vulnerable version merely because a Pipeline “still works.”

8. CSP and user-generated content are separate browser boundaries

Jenkins 2.539+ includes general UI Content Security Policy support. It is disabled by default because some plugins still rely on browser features blocked by a strict policy. Jenkins recommends observing violations and updating incompatible plugins before enforcing the policy.

Workspace files and archived artifacts are attacker-influenced content. General UI CSP does not fully isolate them when they share the Jenkins origin. A Resource Root URL gives stronger origin separation. Do not “fix” an HTML report by emptying the user-content CSP header; either make the report compatible or move user content to the intended isolated origin.

9. TLS and reverse proxy: preserve the original request identity

A reverse proxy may terminate TLS and forward plain HTTP on a private/loopback backend. Jenkins must still know the original scheme, host and port so redirects, absolute URLs and callbacks are correct. Preserve the host and set X-Forwarded-Proto; when required, set forwarded port/host and WebSocket upgrade headers. Keep the Jenkins context path the same on both sides.

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

# Teaching fragment — local/disposable only. Certificate paths are lab placeholders.
server {
  listen 8443 ssl;
  server_name jenkins.lab.test;
  ssl_certificate     /etc/nginx/tls/jenkins-lab.crt;
  ssl_certificate_key /etc/nginx/tls/jenkins-lab.key;

  location / {
    proxy_pass http://jenkins:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }
}

Bind the backend so it is not an unintended second public entry point. A proxy that offers HTTPS while leaving :8080 internet-accessible has not established one controlled ingress boundary.

10. DevOps evidence: prove controls rather than assume them

A reproducible hardening change has a before state, an intended mutation, a verification and a rollback boundary. Capture controller/core/plugin versions, the exact security setting, public URL/proxy config revision, agent identity, a harmless authorization/CSRF test and relevant response headers. Do not include credentials or private keys in the packet.

11. Shortcuts that destroy the model

• Turning off CSRF because a scripted POST returns 403.
• Running “just one” untrusted build on the built-in node because an agent is offline.
• Approving every Script Security signature to stop approval prompts.
• Publishing a reverse proxy while leaving the backend controller port broadly reachable.
• Setting CSP to an empty policy so an unsafe HTML report renders.
• Installing convenience plugins without checking maintenance/security state.

Each shortcut removes the boundary that produced useful failure evidence. Repair the client, agent, plugin or proxy instead.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog — confirms Jenkins 2.568.3 (2 September 2026) and tested Java 21/25.
• Securing Jenkins — access control, controller isolation, CSRF, CSP, user content, ports and credentials.
• Controller Isolation — do not run builds on the built-in node; agent→controller access control is always enabled since Jenkins 2.326.
• CSRF Protection — crumb/session behavior and API-token exemption.
• Content Security Policy — general UI CSP in Jenkins 2.539+, rollout guidance and Resource Root URL recommendation for user content.
• Reverse proxy configuration — request/response rewriting, forwarded headers, context paths and WebSocket handling.
• Script Security plugin and Jenkins Security Advisory 2026-09-16 — sandbox fixes in Script Security 1422.v06869826dd9b_.