fix(2023): Proofreading

Author: PauloASilva

2023/en/src/0xa1-broken-object-level-authorization.md

@@ -22,13 +22,14 @@ disclosure, modification, or destruction of all data.
 
 Comparing the user ID of the current session (e.g. by extracting it from the
 JWT token) with the vulnerable ID parameter isn't a sufficient solution to
-solve BOLA. This approach could address only a small subset of cases.
+solve Broken Object Level Authorization (BOLA). This approach could address
+only a small subset of cases.
 
 In the case of BOLA, it's by design that the user will have access to the
 vulnerable API endpoint/function. The violation happens at the object level,
 by manipulating the ID. If an attacker manages to access an API
-endpoint/function they should not have access to - this is a case of BFLA
-rather than BOLA.
+endpoint/function they should not have access to - this is a case of [Broken
+Function Level Authorization][5] (BFLA) rather than BOLA.
 
 ## Example Attack Scenarios
 
@@ -37,7 +38,7 @@ rather than BOLA.
 An e-commerce platform for online stores (shops) provides a listing page with
 the revenue charts for their hosted shops. Inspecting the browser requests, an
 attacker can identify the API endpoints used as a data source for those charts
-and their pattern `/shops/{shopName}/revenue_data.json`. Using another API
+and their pattern: `/shops/{shopName}/revenue_data.json`. Using another API
 endpoint, the attacker can get the list of all hosted shop names. With a
 simple script to manipulate the names in the list, replacing `{shopName}` in
 the URL, the attacker gains access to the sales data of thousands of e-commerce
@@ -52,7 +53,7 @@ As part of this flow, the user sends the Vehicle Identification Number (VIN) to
 the API.
 The API fails to validate that the VIN represents a vehicle that belongs to the
 logged in user, which leads to a BOLA vulnerability. An attacker can access
-vehicles that don't belong to them.
+vehicles that don't belong to him.
 
 ### Scenario #3
 
@@ -75,8 +76,8 @@ POST /graphql
 }
 ```
 
-Since a document ID is deleted without any further permission checks, a user
-may be able to delete another user's document.
+Since the document with the given ID is deleted without any further permission
+checks, a user may be able to delete another user's document.
 
 ## How To Prevent
 
@@ -89,7 +90,6 @@ may be able to delete another user's document.
 * Write tests to evaluate the vulnerability of the authorization mechanism. Do
   not deploy changes that make the tests fail.
 
-
 ## References
 
 ### OWASP
@@ -106,3 +106,4 @@ may be able to delete another user's document.
 [2]: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Testing_Automation_Cheat_Sheet.html
 [3]: https://cwe.mitre.org/data/definitions/285.html
 [4]: https://cwe.mitre.org/data/definitions/639.html
+[5]: ./0xa5-broken-function-level-authorization.md

2023/en/src/0xa2-broken-authentication.md

@@ -8,7 +8,8 @@ API2:2023 Broken Authentication
 
 ## Is the API Vulnerable?
 
-Authentication endpoints and flows are assets that need to be protected. Additionally, "Forgot password / reset password" should be treated the same way
+Authentication endpoints and flows are assets that need to be protected.
+Additionally, "Forgot password / reset password" should be treated the same way
 as authentication mechanisms.
 
 An API is vulnerable if it:
@@ -82,11 +83,11 @@ Authorization: Bearer <token>
 { "email": "<new_email_address>" }
 ```
 
-Because the API does not require the user to confirm their identity by
-providing their current password, bad actors are able to put themselves in a
-position to steal the auth token.They also might be able to take over the
-victim's account by starting the reset password workflow after updating the
-email address of the victim's account.
+Because the API does not require users to confirm their identity by providing
+their current password, bad actors able to put themselves in a position to
+steal the auth token might be able to take over the victim's account by starting
+the reset password workflow after updating the email address of the victim's
+account.
 
 ## How To Prevent
 

2023/en/src/0xa3-broken-object-property-level-authorization.md

@@ -65,48 +65,61 @@ As part of this flow, an API call is sent by the host to
 `POST /api/host/approve_booking` with the following legitimate payload:
 
 ```
-{"approved":true,"comment":"Check-in is after 3pm"}
+{
+  "approved": true,
+  "comment": "Check-in is after 3pm"
+}
 ```
 
 The host replays the legitimate request, and adds the following malicious
 payload:
 
 ```
-{"approved":true,"comment":"Check-in is after 3pm","total_stay_price":"$1,000,000"}
+{
+  "approved": true,
+  "comment": "Check-in is after 3pm",
+  "total_stay_price": "$1,000,000"
+}
 ```
 
 The API endpoint is vulnerable because there is no validation that the host
-should have access to the internal object property - "total_stay_price", and
+should have access to the internal object property - `total_stay_price`, and
 the guest will be charged more than she was supposed to be.
 
 ### Scenario #3
 
 A social network that is based on short videos, enforces restrictive content
 filtering and censorship. Even if an uploaded video is blocked, the user can
-change the description of the video using the following API request
+change the description of the video using the following API request:
 
 ```
 PUT /api/video/update_video
 
-{"description":"a funny video about cats"}
+{
+  "description": "a funny video about cats"
+}
 ```
 
 A frustrated user can replay the legitimate request, and add the following
 malicious payload:
 
 ```
-{"description":"a funny video about cats","blocked":false}
+{
+  "description": "a funny video about cats",
+  "blocked": false
+}
 ```
 
 The API endpoint is vulnerable because there is no validation if the user
-should have access to the internal object property - "blocked", and the user
-can change the value from "true" to "false" and unlock their own blocked content.
+should have access to the internal object property - `blocked`, and the user
+can change the value from `true` to `false` and unlock their own blocked
+content.
 
 ## How To Prevent
 
 * When exposing an object using an API endpoint, always make sure that the user
   should have access to the object's properties you expose.
-* Avoid using generic methods such as to_json() and to_string(). Instead,
+* Avoid using generic methods such as `to_json()` and `to_string()`. Instead,
   cherry-pick specific object properties you specifically want to return.
 * If possible, avoid using functions that automatically bind a client's input
   into code variables, internal objects, or object properties

2023/en/src/0xa4-unrestricted-resource-consumption.md

@@ -30,45 +30,84 @@ inappropriately (e.g. too low/high):
 
 ### Scenario #1
 
-An attacker uploads a large image by issuing a POST request to /api/v1/images.
-When the upload is complete, the API creates multiple thumbnails with different
-sizes. Due to the size of the uploaded image, available memory is exhausted
-during the creation of thumbnails and the API becomes unresponsive.
+A social network implemented a “forgot password” flow using SMS verification,
+enabling the user to receive a one time token via SMS in order to reset their
+password.
+
+Once a user clicks on "forgot password" an API call is sent from the user's
+browser to the back-end API:
+
+```
+POST /initiate_forgot_password
+
+{
+  "step": 1,
+  "user_number": "6501113434"
+}
+```
+
+Then, behind the scenes, an API call is sent from the back-end to a 3rd party
+API that takes care of the SMS delivering:
+
+```
+POST /sms/send_reset_pass_code
+
+Host: willyo.net
+
+{
+  "phone_number": "6501113434"
+}
+```
+
+The 3rd party provider, Willyo, charges $0.05 per this type of call.
+
+An attacker writes a script that sends the first API call tens of thousands of
+times. The back-end follows and requests Willyo to send tens of thousands of
+text messages, leading the company to lose thousands of dollars in a matter of
+minutes.
 
 ### Scenario #2
 
-In order to activate a credit card the following API request should be issued
-providing the last four digits printed on it (only users with physical access
-to the card should be able to perform such operation):
+A GraphQL API Endpoint allows the user to upload a profile picture.
 
 ```
 POST /graphql
 
 {
   "query": "mutation {
-    validateOTP(token: \"abcdef\", card: \"123456\") {
-      authToken
+    uploadPic(name: \"pic1\", base64_pic: \"R0FOIEFOR0xJVA…\") {
+      url
     }
   }"
 }
 ```
 
-Bad actors will be able to perform the credit card activation without physical
-access to it, crafting a request like the one below:
+Once the upload is complete, the API generates multiple thumbnails with
+different sizes based on the uploaded picture. This graphical operation takes a
+lot of memory from the server.
+
+The API implements a traditional rate limiting protection - a user can't access
+the GraphQL endpoint too many times in a short period of time. The API also
+checks for the uploaded picture's size before generating thumbnails to avoid
+processing pictures that are too large.
+
+An attacker can easily bypass those mechanisms, by leveraging the flexible
+nature of GraphQL:
 
 ```
 POST /graphql
 
 [
-  {"query": "mutation {activateCard(token: \"abcdef\", card: \"0000\") {authToken}}"},
-  {"query": "mutation {activateCard(token: \"abcdef\", card: \"0001\") {authToken}}"},
+  {"query": "mutation {uploadPic(name: \"pic1\", base64_pic: \"R0FOIEFOR0xJVA…\") {url}}"},
+  {"query": "mutation {uploadPic(name: \"pic2\", base64_pic: \"R0FOIEFOR0xJVA…\") {url}}"},
   ...
-  {"query": "mutation {activateCard(token: \"abcdef\", card: \"9999\") {authToken}}"}
+  {"query": "mutation {uploadPic(name: \"pic999\", base64_pic: \"R0FOIEFOR0xJVA…\") {url}}"},
 }
 ```
 
-Because the API does not limit the number of times the activateCard operation
-can be attempted, one of the mutations will succeed.
+Because the API does not limit the number of times the `uploadPic` operation can
+be attempted, the call will lead to exhaustion of server memory and Denial of
+Service.
 
 ### Scenario #3
 
@@ -86,7 +125,8 @@ the next monthly bill increases from US$13, on average, to US$8k.
 ## How To Prevent
 
 * Use a solution that makes it easy to limit [memory][1],
-  [CPU][2], [number of restarts][3], [file descriptors, and processes][4] such as Containers / Serverless code (e.g. Lambdas).
+  [CPU][2], [number of restarts][3], [file descriptors, and processes][4] such
+  as Containers / Serverless code (e.g. Lambdas).
 * Define and enforce a maximum size of data on all incoming parameters and
   payloads, such as maximum length for strings, maximum number of elements in
   arrays, and maximum upload file size (regardless of whether it is stored

2023/en/src/0xa5-broken-function-level-authorization.md

@@ -25,8 +25,8 @@ Don't assume that an API endpoint is regular or administrative only based on
 the URL path.
 
 While developers might choose to expose most of the administrative endpoints
-under a specific relative path, like `/api/admins`, it's very common to find these
-administrative endpoints under other relative paths together with regular
+under a specific relative path, like `/api/admins`, it's very common to find
+these administrative endpoints under other relative paths together with regular
 endpoints, like `/api/users`.
 
 ## Example Attack Scenarios
@@ -48,7 +48,10 @@ The attacker exploits the issue and sends a new invite with admin privileges:
 ```
 POST /api/invites/new
 
-{"email":"attacker@somehost.com","role":"admin"}
+{
+  "email": "attacker@somehost.com",
+  "role":"admin"
+}
 ```
 
 Later on, the attacker uses the maliciously crafted invite in order to create
@@ -70,7 +73,6 @@ module that is invoked from all your business functions. Frequently, such
 protection is provided by one or more components external to the application
 code.
 
-
 * The enforcement mechanism(s) should deny all access by default, requiring
   explicit grants to specific roles for access to every function.
 * Review your API endpoints against function level authorization flaws, while

2023/en/src/0xa7-server-side-request-forgery.md

@@ -8,10 +8,10 @@ API7:2023 Server Side Request Forgery
 
 ## Is the API Vulnerable?
 
-Server-Side Request Forgery (SSRF) flaws occur whenever an API is fetching a
-remote resource without validating the user-supplied URL. It allows an attacker
-to coerce the application to send a crafted request to an unexpected
-destination, even when protected by a firewall or a VPN.
+Server-Side Request Forgery (SSRF) flaws occur when an API is fetching a remote
+resource without validating the user-supplied URL. It enables an attacker to
+coerce the application to send a crafted request to an unexpected destination,
+even when protected by a firewall or a VPN.
 
 Modern concepts in application development make SSRF more common and more
 dangerous.
@@ -24,7 +24,6 @@ More dangerous - Modern technologies like cloud providers, Kubernetes, and
 Docker expose management and control channels over HTTP on predictable,
 well-known paths. Those channels are an easy target for an SSRF attack.
 
-
 It is also more challenging to limit outbound traffic from your application,
 because of the connected nature of modern applications.
 
@@ -42,14 +41,18 @@ image. Choosing the second, will trigger the following API call:
 ```
 POST /api/profile/upload_picture
 
-{"picture_url":"http://example.com/profile_pic.jpg"}
+{
+  "picture_url": "http://example.com/profile_pic.jpg"
+}
 ```
 
 An attacker can send a malicious URL and initiate port scanning within the
 internal network using the API Endpoint.
 
 ```
-{"picture_url":"localhost:8080"}
+{
+  "picture_url": "localhost:8080"
+}
 ```
 
 Based on the response time, the attacker can figure out whether the port is
@@ -91,7 +94,7 @@ POST /graphql
 
 ```
 
-During the creation process, the API backend sends a test request to the
+During the creation process, the API back-end sends a test request to the
 provided webhook URL, and presents to the user the response.
 
 An attacker can leverage this flow, and make the API request a sensitive
@@ -129,7 +132,7 @@ can view the credentials of the cloud environment.
 
 * Isolate the resource fetching mechanism in your network: usually these
   features are aimed to retrieve remote resources and not internal ones.
-* Whenever possible, use allow lists of
+* Whenever possible, use allow lists of:
   * Remote origins users are expected to download resources from (e.g. Google
     Drive, Gravatar, etc.)
   * URL schemes and ports

2023/en/src/0xa8-security-misconfiguration.md

@@ -56,14 +56,14 @@ not required):
 GET /dm/user_updates.json?conversation_id=1234567&cursor=GRlFp7LCUAAAA
 ```
 
-Because the API response does not include the Cache-Control HTTP response
+Because the API response does not include the `Cache-Control` HTTP response
 header, private conversations end-up cached by the web browser, allowing
 malicious actors to retrieve them from the browser cache files in the
 filesystem.
 
 ## How To Prevent
 
-The API life cycle should include
+The API life cycle should include:
 
 * A repeatable hardening process leading to fast and easy deployment of a
   properly locked down environment
@@ -86,8 +86,6 @@ Furthermore:
   * include applicable Security Headers
 * Restrict incoming content types/data formats to those that meet the business/
   functional requirements.
-* Implement a proper Cross-Origin Resource Sharing (CORS) policy on APIs
-  expected to be accessed from browser-based clients (e.g. web app front-ends).
 * Ensure all servers in the HTTP server chain (e.g. load balancers, reverse
   and forward proxies, and back-end servers) process incoming requests in a
   uniform manner to avoid desync issues.

2023/en/src/0xa9-improper-inventory-management.md

@@ -104,4 +104,3 @@ sells the information for malicious purposes.
 * [CWE-1059: Incomplete Documentation][1]
 
 [1]: https://cwe.mitre.org/data/definitions/1059.html
-