1, CSRF (cross-site request forgery) overview
Before explaining Jenkins' Cross-Site Request Forgery (CSRF) protection mechanism, let's start with a brief overview of CSRF as a security threat and its importance.
1.1 Principles of CSRF (Cross Site Request Forgery)
CSRF (i.e. cross-site request forgery) refers to the use of the victim's invalid authentication information, (cookies, sessions, etc.), to lure them to click on a malicious link or visit the page containing the attack code, in the case of the victim is not aware of the victim's identity to the (authentication information corresponds to the) server to send a request, so as to complete the illegal operation (transfer of funds, change passwords, etc.) CSRF CSRF is a business logic vulnerability in which all requests appear to the server to be legitimate and normal (the request is authenticated).
Because of CSRF attacks, the user's cookies are reused, and when it comes to cookies, you have to start with the HTTP protocol.
1.1.1 HTTP protocol
No memorization:
HTTP is a stateless protocol, which means that the server does not retain the state it had when it transacted with the client.
User A sends the same request to the web server twice in a short time interval, and the server does not fail to respond to the second request just because it has already responded to the request once, because the server does not know that it has already responded to the request once.
Assuming that a user has completed a login operation on one page of website A, an operation performed on another page of that website that requires validation of the user's login still requires the user to log in again because HTTP doesn't know that you are already logged in, and it doesn't maintain your login status.
Because it was too much trouble to log in multiple times, a cookie mechanism was introduced to allow the server to remember the user.
1.1.2 Cookie mechanism
When a user visits the site, the site assigns a cookie value to that user, which the site uses to tag thesubscribersWhen the user's browser receives a packet containing a cookie, the value of the cookie is retrieved and stored in the browser.The browser then automatically fills the cookie value in the packet sent to the site; it is the browser's behavior to fill the cookie value.
1.1.3 Principles of CSRF (Cross Site Request Forgery)
When the browser automatically completes the filling of cookies, the target website will mistakenly believe that the packet is sent by the administrator, and will carry out the relevant operations with the administrator's privileges.
1.2 CSRF (Cross Site Request Forgery) Common Defense Schemes
The essential reason why CSRF attacks occur is that hackers can forge user requests, and user request information actually exists in cookies, so hackers can skip security verification directly without knowing the above verification information. Therefore, the key point of defending against CSRF is that when the user's request is sent, the hacker cannot forge the information, and this information cannot exist in the cookie.
1.2.1 Adding an HTTP Referer
Referer is a field in the header of the HTTP message that is provided by the browser.The source address of the current request can be recorded (identifying the source of the request)The hacker can only construct the request on his own website when he forges the request. Hackers in the forged request can only be constructed on their own Web site request, so that the server to verify the Referer can know that the request is not their own Web site within the request, but the hacker forged, directly rejected. Take a file in Baidu as an example:
The advantage of using this approach is simple, convenient, general developers do not have to worry about CSRF security vulnerabilities, just need to add an interceptor on the server side to verify the value of the request Referer can be. This way of verifying the Referer is certainly simple and efficient, but it is not foolproof, although the value of the Referer is provided by the browser, but in some browsers hackers can send a request to tamper with the value of the Referer or other Header, which is equivalent to skipping the validation, which can be used to carry out CSRF attacks.
1.2.2 Anti CSRF Token
Anti CSRF Token. Token, is the token, the biggest characteristic is randomness, unpredictable.
Anti CSRF Token is in principle implemented through Session Token. When a client requests a page, the server generates a random number of tokens, places them in the session, and then sends the tokens to the client (usually by constructing a Hidden form). The next time the client submits a request, the Token will be submitted with the form to the server, the server will receive the request with an interceptor to verify the value of the Token, determine whether the Token value and the Session is equal, if equal, it can prove that the request is valid and not forged, if there is no Token or the Token is incorrect, it will be considered an attack! If there is no Token or the Token is incorrect, the request will be considered as an attack and will be directly discarded.
GET request
http://url?csrftoken=tokenvalue
POST request
<input type="hidden" name="csrftoken" value="tokenvalue" />
1.2.3 User authentication
For sensitive operations, users can be required to perform additional authentication (e.g., enter a password or verification code).
1.2.4 Avoid using GET requests for state changes
Ensure that state change operations (e.g., data modification, deletion) use the POST, PUT, or DELETE method rather than the GET method.GET requests should only be used for data fetch operations.
2, Jenkins cross-site request forgery protection function
Jenkins' CSRF protection uses a Token (called Crumb in Jenkins), which is created by Jenkins and sent to the user. Any form submission that results in a modification or similar action, e.g., triggering a task or modifying the build configuration, requires the Crumb to be supplied.The Crumb contains information that identifies the user who created it, so commits that use other user tokens will be rejected. All of this happens in the background and has no noticeable effect except in rare cases, for example, when a user's session expires and they log in again.
2.1 Cross-site request forgery protection configuration
Dashboard " Manage Jenkins " Security, administrators can configure CSRF Protection. additionally, starting with Jenkins 2.214 and Jenkins LTS 2.222.1, Jenkins enables by default cross-site Request Forgery Protection by default and is not allowed to be turned off in the Jenkins graphical page.
The *Default Crumb Issuer, which is enabled by default, is an interceptor that calculates whether the hash of the Crumb value passed by the client is an available hash, which is generated from the username, sessionID, request IP, and unique identifier of the jenkins being accessed.
The only supported option, Enable Proxy Compatibility, removes information about the user's IP address from the token. This can be useful when Jenkins is running behind a reverse proxy and the user IP address seen from Jenkins changes periodically.
Note 1: The default Crumb Issuer generates a hash of Crumb and encodes the following information in it (if proxy compatibility is enabled, the request Ip is no longer used when generating the Crumb hash):
- Generate a Crumb username for it
- Generating Crumb's Web Session ID
- IP address of the user for whom Crumb was generated
- Salt unique to this Jenkins instance
When Crumb is sent back to Jenkins, all of this information needs to match in order for the commit to be considered valid.
Note 2: CrumbIssuer is an algorithm that generates a value called Crumb to protect against CSRF attacks. crumb is usually a hash value of information that uniquely identifies the proxy (user side) that sends the request and is encrypted to prevent third parties from forging it. the crumb value is generated by the server and sent to the user when the user logs in, and is then verified each time the user logs in. The Crumb value is generated by the server and sent to the user when they log in, and is then verified each time they log in. The Crumb value is generated by the server when the user logs in and sent to the user, and is then verified each time the user logs in.
2.2 Using Crumb in APIs
POST requests sent to Jenkins typically require a Crumb to be supplied.This also applies to scripting clients that use usernames and passwords for authentication. Since Crumb contains the network session ID, the client needs to do the following:
- Send a request to /CrumbIssuer/api requesting Crumb, note the Set-Cookie response header
- For all subsequent requests, Crumb and session cookies are provided in addition to the username and password.
Example (disabling the pipeline project test-crumb):
Check the pipeline status before disabling the pipeline project via the API.
Disable pipelining via the API:
curl -X POST -u zmc:123456 "http://10.20.31.153:8080/jenkins/job/test-crumb/disable"
Reported a 403 error (authentication failure), and the log gives a clear reason for the error, the request is missing a legitimate Crumb. in the second chapter of the introduction of Jenkins cross-site request forgery protection has been said to cause any modification of the form submission or similar operations, you need to provide Crumb.
Then we provide the Crumb value for the interface and get the Crumb of the current user through the API.
curl -s -u zmc:123456 http://10.20.31.153:8080/jenkins/crumbIssuer/api/json
Next the request header carries the current user's Crumb value inside, again disabling the pipeline:
curl -X POST -u zmc:123456 -H "Jenkins-Crumb:98faf768c7d636709ae6e328e7344366614d68db62dcaacf8737c58278cfa71c" "http://10.20.31.153:8080/jenkins/job/ssssss/disable"
Still report lack of legal Crumb error, this is because in addition to providing the username, password, Crumb also need to fill in the session cookie (curl client tool is not a browser will not automatically carry the cookie value inside the request), again through the API to get the current user's Crumb.
curl -s -verbose -u zmc:123456 http://10.20.31.153:8080/jenkins/crumbIssuer/api/json
Next the request header carries the current user's Crumb value inside, the session cookie, and again the pipeline is disabled.
curl -X POST -u zmc:123456 --cookie "JSESSIONID=8A381340DD8DFC299F9A88BBE10880E0" -H "Jenkins-Crumb:a849f65adaf2ecf8ecf95bf957c1b1288fe86bf091af85a1e7d17421525bb8fc" "http://10.20.31.153:8080/jenkins/job/test-crumb/disable"
Check the status of the pipeline project, the project is disabled.
In addition, we know that the Jenkins API authentication method has two forms of username/password + username/Token, for username/password authentication Jenkins any form submission or similar request that results in modification needs to be with Crumb, while for username/API Token then, even if Jenkins opens the CSRF protection, it does not need to provide Crumb.
Example (enable pipeline project test-crumb):
Enable the pipeline items disabled above via API Token.
curl -X POST -u zmc:116e373b20b15ca5788b2a37044f4cb0b5 "http://10.20.31.153:8080/jenkins/job/test-crumb/enable"
Check the status of the pipeline project, the project is enabled.
Note 1: This article mainly explains how to use Jenkins CrumbIssuer defense CSRF attacks, about API authentication how to issue API Token this article does not explain.
Note 2: Crumb's validity period is usually tied to the user's session, as long as the session is valid, Crumb is valid. jenkins itself does not directly configure the session timeout settings, it relies on the underlying Servlet Container's session configuration, assuming that the underlying container uses Tomcat, the default session validity period is 30 minutes.
2.3 Disable cross-site request forgery protection (strongly discouraged)
Outdated plugins that send HTTP requests to Jenkins may not work with CSRF protection enabled. In this case, it may be necessary to temporarily disable CSRF protection. To disable CSRF protection, set the system properties. Set DISABLE_CSRF_PROTECTION to true on startup.
3. Summary
Jenkins' CSRF protection uses a Token (called Crumb in Jenkins), which is created by Jenkins and sent to the user. Any form submission that results in a modification or similar action, e.g., triggering a task or modifying the build configuration, requires the Crumb to be supplied.The Crumb contains information that identifies the user who created it, so commits that use other user tokens will be rejected. All of this happens in the background and has no noticeable effect except in rare cases, for example, when a user's session expires and they log in again.
POST requests sent to Jenkins usually require Crumb (Jenkins) to be provided. This also applies to scripting clients that use username and password for authentication. Since Crumb contains the network session ID, the client needs to do the following:
- Send a request to /CrumbIssuer/api requesting Crumb, note the Set-Cookie response header
- For all subsequent requests, Crumb and session cookies are provided in addition to the username and password.
In addition, we know that the Jenkins API authentication method has two forms of username/password + username/Token, for username/password authentication Jenkins any form submission or similar request that results in modification needs to be with Crumb, while for username/API Token then, even if Jenkins opens the CSRF protection, it does not need to provide Crumb.