From bbbd4c3ac87bf5ff0fb2b080cff4890d66ed0269 Mon Sep 17 00:00:00 2001
From: WD Snoeijer <88512452+dsnoeijer@users.noreply.github.com>
Date: Fri, 7 Oct 2022 04:17:00 +0200
Subject: [PATCH] docs: fix linter errors for security.md (#47688)

PR Close #47688
---
 aio/content/guide/security.md | 76 ++++++++++++++++++++---------------
 1 file changed, 43 insertions(+), 33 deletions(-)

diff --git a/aio/content/guide/security.md b/aio/content/guide/security.md
index 7946336b92f..1b10a62d52c 100644
--- a/aio/content/guide/security.md
+++ b/aio/content/guide/security.md
@@ -3,7 +3,7 @@
 This topic describes Angular's built-in protections against common web-application vulnerabilities and attacks such as cross-site scripting attacks.
 It doesn't cover application-level security, such as authentication and authorization.
 
-For more information about the attacks and mitigations described below, see [OWASP Guide Project](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).
+For more information about the attacks and mitigations described below, see the [Open Web Application Security Project (OWASP) Guide](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).
 
 You can run the <live-example></live-example> in Stackblitz and download the code from there.
 
@@ -27,8 +27,8 @@ For more information about how Google handles security issues, see [Google's sec
 
 | Practices                                                           | Details |
 |:---                                                                 |:---     |
-| Keep current with the latest Angular library releases               | We regularly update the Angular libraries, and these updates might fix security defects discovered in previous versions. Check the Angular [change log](https://github.com/angular/angular/blob/main/CHANGELOG.md) for security-related updates. |
-| Don't modify your copy of Angular                                   | Private, customized versions of Angular tend to fall behind the current version and might not include important security fixes and enhancements. Instead, share your Angular improvements with the community and make a pull request.              |
+| Keep current with the latest Angular library releases               | The Angular libraries get regular updates, and these updates might fix security defects discovered in previous versions. Check the Angular [change log](https://github.com/angular/angular/blob/main/CHANGELOG.md) for security-related updates. |
+| Don't alter your copy of Angular                                   | Private, customized versions of Angular tend to fall behind the current version and might not include important security fixes and enhancements. Instead, share your Angular improvements with the community and make a pull request.              |
 | Avoid Angular APIs marked in the documentation as "*Security Risk*" | For more information, see the [Trusting safe values](guide/security#bypass-security-apis) section of this page.                                                                                                                                    |
 
 </div>
@@ -36,12 +36,12 @@ For more information about how Google handles security issues, see [Google's sec
 ## Preventing cross-site scripting (XSS)
 
 [Cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers to inject malicious code into web pages.
-Such code can then, for example, steal user data \(in particular, login data\) or perform actions to impersonate the user.
+Such code can then, for example, steal user and login data, or perform actions that impersonate the user.
 This is one of the most common attacks on the web.
 
-To block XSS attacks, you must prevent malicious code from entering the DOM \(Document Object Model\).
+To block XSS attacks, you must prevent malicious code from entering the Document Object Model (DOM).
 For example, if attackers can trick you into inserting a `<script>` tag in the DOM, they can run arbitrary code on your website.
-The attack isn't limited to `<script>` tags &mdash;many elements and properties in the DOM allow code execution, for example, `<img onerror="...">` and `<a href="javascript:...">`.
+The attack isn't limited to `<script>` tags &mdash;many elements and properties in the DOM allow code execution, for example, `<img alt="" onerror="...">` and `<a href="javascript:...">`.
 If attacker-controlled data enters the DOM, expect security vulnerabilities.
 
 ### Angular's cross-site scripting security model
@@ -51,13 +51,13 @@ When a value is inserted into the DOM from a template binding, or interpolation,
 If a value was already sanitized outside of Angular and is considered safe, communicate this to Angular by marking the [value as trusted](#bypass-security-apis).
 
 Unlike values to be used for rendering, Angular templates are considered trusted by default, and should be treated as executable code.
-Never generate templates by concatenating user input and template syntax.
+Never create templates by concatenating user input and template syntax.
 Doing this would enable attackers to [inject arbitrary code](https://en.wikipedia.org/wiki/Code_injection) into your application.
-To prevent these vulnerabilities, always use the default [AOT template compiler](guide/security#offline-template-compiler) in production deployments.
+To prevent these vulnerabilities, always use the default [Ahead-Of-Time (AOT) template compiler](guide/security#offline-template-compiler) in production deployments.
 
-An additional layer of protection can be provided through the use of Content security policy and Trusted Types.
-These web platform features operate at the DOM level which is the most effective place to prevent XSS issues because they can't be bypassed using other, lower-level APIs.
-For this reason, we strongly encourage developers to take advantage of these features by configuring the [content security policy](#content-security-policy) for their application and enabling [trusted types enforcement](#trusted-types).
+An extra layer of protection can be provided through the use of Content security policy and Trusted Types.
+These web platform features operate at the DOM level which is the most effective place to prevent XSS issues. Here they can't be bypassed using other, lower-level APIs.
+For this reason, it is strongly encouraged to take advantage of these features. To do this, configure the [content security policy](#content-security-policy) for the application and enable [trusted types enforcement](#trusted-types).
 
 ### Sanitization and security contexts
 
@@ -75,20 +75,20 @@ Angular defines the following security contexts:
 | URL               | Used for URL properties, such as `<a href>`.                                      |
 | Resource URL      | A URL that is loaded and executed as code, for example, in `<script src>`.        |
 
-Angular sanitizes untrusted values for HTML, styles, and URLs; sanitizing resource URLs isn't possible because they contain arbitrary code.
+Angular sanitizes untrusted values for HTML, styles, and URLs. Sanitizing resource URLs isn't possible because they contain arbitrary code.
 In development mode, Angular prints a console warning when it has to change a value during sanitization.
 
 ### Sanitization example
 
-The following template binds the value of `htmlSnippet`, once by interpolating it into an element's content, and once by binding it to the `innerHTML` property of an element:
+The following template binds the value of `htmlSnippet`. Once by interpolating it into an element's content, and once by binding it to the `innerHTML` property of an element:
 
 <code-example header="src/app/inner-html-binding.component.html" path="security/src/app/inner-html-binding.component.html"></code-example>
 
 Interpolated content is always escaped &mdash;the HTML isn't interpreted and the browser displays angle brackets in the element's text content.
 
 For the HTML to be interpreted, bind it to an HTML property such as `innerHTML`.
-But binding a value that an attacker might control into `innerHTML` normally causes an XSS vulnerability.
-For example, one could execute JavaScript in a following way:
+Be aware that binding a value that an attacker might control into `innerHTML` normally causes an XSS vulnerability.
+For example, one could run JavaScript in a following way:
 
 <code-example header="src/app/inner-html-binding.component.ts (class)" path="security/src/app/inner-html-binding.component.ts" region="class"></code-example>
 
@@ -104,20 +104,20 @@ Angular recognizes the value as unsafe and automatically sanitizes it, which rem
 
 Unless you enforce Trusted Types, the built-in browser DOM APIs don't automatically protect you from security vulnerabilities.
 For example, `document`, the node available through `ElementRef`, and many third-party APIs contain unsafe methods.
-In the same way, if you interact with other libraries that manipulate the DOM, you likely won't have the same automatic sanitization as with Angular interpolations.
+Likewise, if you interact with other libraries that manipulate the DOM, you likely won't have the same automatic sanitization as with Angular interpolations.
 Avoid directly interacting with the DOM and instead use Angular templates where possible.
 
 For cases where this is unavoidable, use the built-in Angular sanitization functions.
 Sanitize untrusted values with the [DomSanitizer.sanitize](api/platform-browser/DomSanitizer#sanitize) method and the appropriate `SecurityContext`.
-That function also accepts values that were marked as trusted using the `bypassSecurityTrust`&hellip; functions, and will not sanitize them, as [described below](#bypass-security-apis).
+That function also accepts values that were marked as trusted using the `bypassSecurityTrust` &hellip; functions, and does not sanitize them, as [described below](#bypass-security-apis).
 
 <a id="bypass-security-apis"></a>
 
 ### Trusting safe values
 
 Sometimes applications genuinely need to include executable code, display an `<iframe>` from some URL, or construct potentially dangerous URLs.
-To prevent automatic sanitization in any of these situations, tell Angular that you inspected a value, checked how it was generated, and made sure it will always be secure.
-But *be careful*.
+To prevent automatic sanitization in these situations, tell Angular that you inspected a value, checked how it was created, and made sure it is secure.
+Do *be careful*.
 If you trust a value that might be malicious, you are introducing a security vulnerability into your application.
 If in doubt, find a professional security reviewer.
 
@@ -147,8 +147,8 @@ To prevent this, mark the URL value as a trusted URL using the `bypassSecurityTr
 
 If you need to convert user input into a trusted value, use a component method.
 The following template lets users enter a YouTube video ID and load the corresponding video in an `<iframe>`.
-The `<iframe src>` attribute is a resource URL security context, because an untrusted source can, for example, smuggle in file downloads that unsuspecting users could execute.
-So call a method on the component to construct a trusted video URL, which causes Angular to let binding into `<iframe src>`:
+The `<iframe src>` attribute is a resource URL security context, because an untrusted source can, for example, smuggle in file downloads that unsuspecting users could run.
+To prevent this, call a method on the component to construct a trusted video URL, which causes Angular to let binding into `<iframe src>`:
 
 <code-example header="src/app/bypass-security.component.html (iframe)" path="security/src/app/bypass-security.component.html" region="iframe"></code-example>
 
@@ -176,20 +176,24 @@ default-src 'self'; style-src 'self' 'unsafe-inline';
 | `style-src 'self' 'unsafe-inline';` | Allows the page to load global styles from the same origin \(`'self'`\) and enables components to load their styles \(`'unsafe-inline'` - see [`angular/angular#6361`](https://github.com/angular/angular/issues/6361)\). |
 
 Angular itself requires only these settings to function correctly.
-As your project grows, however, you may need to expand your CSP settings beyond this minimum to accommodate additional features specific to your application.
+As your project grows, you may need to expand your CSP settings to accommodate extra features specific to your application.
 
 <a id="trusted-types"></a>
 
+<!-- vale Angular.Google_Headings = NO -->
+
 ### Enforcing Trusted Types
 
-We recommend the use of [Trusted Types](https://w3c.github.io/webappsec-trusted-types/dist/spec) as a way to help secure your applications from cross-site scripting attacks.
+<!-- vale Angular.Google_Headings = YES -->
+
+It is recommended that you use [Trusted Types](https://w3c.github.io/webappsec-trusted-types/dist/spec) as a way to help secure your applications from cross-site scripting attacks.
 Trusted Types is a [web platform](https://en.wikipedia.org/wiki/Web_platform) feature that can help you prevent cross-site scripting attacks by enforcing safer coding practices.
 Trusted Types can also help simplify the auditing of application code.
 
 <div class="callout is-helpful">
 
 Trusted Types might not yet be available in all browsers your application targets.
-In the case your Trusted-Types-enabled application runs in a browser that doesn't support Trusted Types, the functionality of the application will be preserved, and your application will be guarded against XSS by way of Angular's DomSanitizer.
+In the case your Trusted-Types-enabled application runs in a browser that doesn't support Trusted Types, the features of the application are preserved. Your application is guarded against XSS by way of Angular's DomSanitizer.
 See [caniuse.com/trusted-types](https://caniuse.com/trusted-types) for the current browser support.
 
 </div>
@@ -200,8 +204,8 @@ To enforce Trusted Types for your application, you must configure your applicati
 |:---                     |:---    |
 | `angular`               | This policy is used in security-reviewed code that is internal to Angular, and is required for Angular to function when Trusted Types are enforced. Any inline template values or content sanitized by Angular is treated as safe by this policy.                           |
 | `angular#unsafe-bypass` | This policy is used for applications that use any of the methods in Angular's [DomSanitizer](api/platform-browser/DomSanitizer) that bypass security, such as `bypassSecurityTrustHtml`. Any application that uses these methods must enable this policy.                   |
-| `angular#unsafe-jit`    | This policy is used by the [JIT compiler](api/core/Compiler). You must enable this policy if your application interacts directly with the JIT compiler or is running in JIT mode using the [platform browser dynamic](api/platform-browser-dynamic/platformBrowserDynamic). |
-| `angular#bundler`       | This policy is used by Angular CLI's bundler when creating lazy chunk files.                    |
+| `angular#unsafe-jit`    | This policy is used by the [Just-In-Time (JIT) compiler](api/core/Compiler). You must enable this policy if your application interacts directly with the JIT compiler or is running in JIT mode using the [platform browser dynamic](api/platform-browser-dynamic/platformBrowserDynamic). |
+| `angular#bundler`       | This policy is used by the Angular CLI bundler when creating lazy chunk files.                    |
 
 You should configure the HTTP headers for Trusted Types in the following locations:
 
@@ -217,7 +221,7 @@ Content-Security-Policy: trusted-types angular; require-trusted-types-for 'scrip
 
 </code-example>
 
-The following is an example of a header specifically configured for Trusted Types and Angular applications that use any of the methods in Angular's [DomSanitizer](api/platform-browser/DomSanitizer) that bypasses security.
+An example of a header specifically configured for Trusted Types and Angular applications that use any of Angular's methods in [DomSanitizer](api/platform-browser/DomSanitizer) that bypasses security:
 
 <code-example format="html" language="html">
 
@@ -236,7 +240,9 @@ Content-Security-Policy: trusted-types angular angular#unsafe-jit; require-trust
 The following is an example of a header specifically configured for Trusted Types and Angular applications that use lazy loading of modules:
 
 <code-example language="html">
+
 Content-Security-Policy: trusted-types angular angular#bundler; require-trusted-types-for 'script';
+
 </code-example>
 
 <div class="callout is-helpful">
@@ -257,7 +263,7 @@ The AOT template compiler prevents a whole class of vulnerabilities called templ
 The AOT template compiler is the default compiler used by Angular CLI applications, and you should use it in all production deployments.
 
 An alternative to the AOT compiler is the JIT compiler which compiles templates to executable template code within the browser at runtime.
-Angular trusts template code, so dynamically generating templates and compiling them, in particular templates containing user data, circumvents Angular's built-in protections and is a security anti-pattern.
+Angular trusts template code, so dynamically generating templates and compiling them, in particular templates containing user data, circumvents Angular's built-in protections. This is a security anti-pattern.
 For information about dynamically constructing forms in a safe way, see the [Dynamic Forms](guide/dynamic-form) guide.
 
 <a id="server-side-xss"></a>
@@ -268,10 +274,12 @@ HTML constructed on the server is vulnerable to injection attacks.
 Injecting template code into an Angular application is the same as injecting executable code into the application:
 It gives the attacker full control over the application.
 To prevent this, use a templating language that automatically escapes values to prevent XSS vulnerabilities on the server.
-Don't generate Angular templates on the server side using a templating language; doing this carries a high risk of introducing template-injection vulnerabilities.
+Don't create Angular templates on the server side using a templating language. This carries a high risk of introducing template-injection vulnerabilities.
 
 <a id="http"></a>
 
+<!-- vale Angular.Google_Acronyms = NO -->
+
 ## HTTP-level vulnerabilities
 
 Angular has built-in support to help prevent two common HTTP vulnerabilities, cross-site request forgery \(CSRF or XSRF\) and cross-site script inclusion \(XSSI\).
@@ -281,22 +289,22 @@ Both of these must be mitigated primarily on the server side, but Angular provid
 
 ### Cross-site request forgery
 
-In a cross-site request forgery \(CSRF or XSRF\), an attacker tricks the user into visiting a different web page \(such as `evil.com`\) with malignant code that secretly sends a malicious request to the application's web server \(such as `example-bank.com`\).
+In a cross-site request forgery \(CSRF or XSRF\), an attacker tricks the user into visiting a different web page \(such as `evil.com`\) with malignant code. This web page secretly sends a malicious request to the application's web server \(such as `example-bank.com`\).
 
 Assume the user is logged into the application at `example-bank.com`.
 The user opens an email and clicks a link to `evil.com`, which opens in a new tab.
 
 The `evil.com` page immediately sends a malicious request to `example-bank.com`.
 Perhaps it's a request to transfer money from the user's account to the attacker's account.
-The browser automatically sends the `example-bank.com` cookies \(including the authentication cookie\) with this request.
+The browser automatically sends the `example-bank.com` cookies, including the authentication cookie, with this request.
 
 If the `example-bank.com` server lacks XSRF protection, it can't tell the difference between a legitimate request from the application and the forged request from `evil.com`.
 
 To prevent this, the application must ensure that a user request originates from the real application, not from a different site.
 The server and client must cooperate to thwart this attack.
 
-In a common anti-XSRF technique, the application server sends a randomly generated authentication token in a cookie.
-The client code reads the cookie and adds a custom request header with the token in all subsequent requests.
+In a common anti-XSRF technique, the application server sends a randomly created authentication token in a cookie.
+The client code reads the cookie and adds a custom request header with the token in all following requests.
 The server compares the received cookie value to the request header value and rejects the request if the values are missing or don't match.
 
 This technique is effective because all browsers implement the *same origin policy*.
@@ -312,6 +320,8 @@ The Stanford University paper [Robust Defenses for Cross-Site Request Forgery](h
 
 See also Dave Smith's [talk on XSRF at AngularConnect 2016](https://www.youtube.com/watch?v=9inczw6qtpY "Cross Site Request Funkery Securing Your Angular Apps From Evil Doers").
 
+<!-- vale Angular.Google_Acronyms = YES -->
+
 <a id="xssi"></a>
 
 ### Cross-site script inclusion (XSSI)