DomSanitizer

DomSanitizer helps preventing Cross Site Scripting Security bugs (XSS) by sanitizing values to be safe to use in the different DOM contexts.

DomSanitizer 可以把值净化为在不同 DOM 上下文中的安全内容,来帮你防范跨站脚本攻击(XSS)类的安全问题。

安全风险

Calling any of the bypassSecurityTrust... APIs disables Angular's built-in sanitization for the value passed in. Carefully check and audit all values and code paths going into this call. Make sure any user data is appropriately escaped for this security context. For more detail, see the Security Guide.

调用任何 bypassSecurityTrust... API 都会禁用 Anuglar 对传入的值的内置净化机制。 要小心翼翼的检查和审计所有的值和到该调用的代码执行路径。 要确保任何一个用户数据都针对这个安全上下文进行过适当的转义(escape)。 欲知详情,参见安全

abstract class DomSanitizer implements Sanitizer { abstract sanitize(context: SecurityContext, value: SafeValue | string | null): string | null abstract bypassSecurityTrustHtml(value: string): SafeHtml abstract bypassSecurityTrustStyle(value: string): SafeStyle abstract bypassSecurityTrustScript(value: string): SafeScript abstract bypassSecurityTrustUrl(value: string): SafeUrl abstract bypassSecurityTrustResourceUrl(value: string): SafeResourceUrl }

说明

For example, when binding a URL in an <a [href]="someValue"> hyperlink, someValue will be sanitized so that an attacker cannot inject e.g. a javascript: URL that would execute code on the website.

比如,如果要在 <a [href]="someValue"> 的链接中绑定一个 URL,someValue 将会被净化, 以防范攻击者注入 javascript: 之类的 URL,并借此在网站上执行代码。

In specific situations, it might be necessary to disable sanitization, for example if the application genuinely needs to produce a javascript: style link with a dynamic value in it. Users can bypass security by constructing a value with one of the bypassSecurityTrust... methods, and then binding to that value from the template.

在特定场景下,可能要禁用净化机制,比如,如果应用程序真的需要生成具有动态值的 javascript: 链接。 用户可以通过使用 bypassSecurityTrust... 方法来构建出一个值,以绕过安全性检查,并在模板中绑定它。

These situations should be very rare, and extraordinary care must be taken to avoid creating a Cross Site Scripting (XSS) security bug!

这种场景其实非常罕见,必须特别小心,避免引入跨站脚本攻击(XSS)类的安全风险。

When using bypassSecurityTrust..., make sure to call the method as early as possible and as close as possible to the source of the value, to make it easy to verify no security bug is created by its use.

当使用 bypassSecurityTrust... 时,请尽量确保尽早调用该方法,并且让他尽可能接近值的来源,以便能更容易地验证使用它时有没有引入安全风险。

It is not required (and not recommended) to bypass security if the value is safe, e.g. a URL that does not start with a suspicious protocol, or an HTML snippet that does not contain dangerous code. The sanitizer leaves safe values intact.

如果该值本身是安全的,则不需要绕过安全性检查,比如那些没有使用可疑协议的 URL 或者不包含危险代码的 HTML 片段。 净化器会确保值的安全性。

方法

Sanitizes a value for use in the given SecurityContext.

为在给定的 SecurityContext 中使用而对 value 进行转义。

abstract sanitize(context: SecurityContext, value: SafeValue | string | null): string | null

参数

context

Type: SecurityContext.

value

Type: SafeValue | string | null.

返回值

string | null

If value is trusted for the context, this method will unwrap the contained safe value and use it directly. Otherwise, value will be sanitized to be safe in the given context, for example by replacing URLs that have an unsafe protocol part (such as javascript:). The implementation is responsible to make sure that the value can definitely be safely used in the given context.

如果这个值在这个上下文中是可信的,则该方法会解开所包含的安全值,并且直接使用它;否则,这个值就会根据给定的安全上下文净化成安全的,比如替换那些具有不安全协议(例如 javascript:)的 URL。 该实现负责确保在给定的上下文中可以绝对安全的使用该值。

Bypass security and trust the given value to be safe HTML. Only use this when the bound HTML is unsafe (e.g. contains <script> tags) and the code should be executed. The sanitizer will leave safe HTML intact, so in most situations this method should not be used.

绕过安全检查,并信任给定的值是一个安全的 HTML。只有当要绑定的 HTML 是不安全内容(比如包含 <script>)而且你确实希望运行这些代码时,才需要使用它。 净化器会确保安全 HTML 的完整性,因此在大多数场景下都不需要使用该方法。

abstract bypassSecurityTrustHtml(value: string): SafeHtml

参数

value

Type: string.

返回值

SafeHtml

WARNING: calling this method with untrusted user data exposes your application to XSS security risks!

警告: 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!

Bypass security and trust the given value to be safe style value (CSS).

绕过安全检查,并信任给定的值是一个安全的样式(CSS)。

abstract bypassSecurityTrustStyle(value: string): SafeStyle

参数

value

Type: string.

返回值

SafeStyle

WARNING: calling this method with untrusted user data exposes your application to XSS security risks!

警告: 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!

Bypass security and trust the given value to be safe JavaScript.

绕过安全检查,并信任给定的值是一个安全的JavaScript。

abstract bypassSecurityTrustScript(value: string): SafeScript

参数

value

Type: string.

返回值

SafeScript

WARNING: calling this method with untrusted user data exposes your application to XSS security risks!

警告: 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!

Bypass security and trust the given value to be a safe style URL, i.e. a value that can be used in hyperlinks or <img src>.

绕过安全检查,并信任给定的值是一个安全的样式 URL。也就是说该值可安全地用在链接或 <img src> 中。

abstract bypassSecurityTrustUrl(value: string): SafeUrl

参数

value

Type: string.

返回值

SafeUrl

WARNING: calling this method with untrusted user data exposes your application to XSS security risks!

警告: 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!

Bypass security and trust the given value to be a safe resource URL, i.e. a location that may be used to load executable code from, like <script src>, or <iframe src>.

绕过安全检查,并信任给定的值是一个安全的资源 URL。也就是说该地址可以安全的用于加载可执行代码,比如 <script src><iframe src>

abstract bypassSecurityTrustResourceUrl(value: string): SafeResourceUrl

参数

value

Type: string.

返回值

SafeResourceUrl

WARNING: calling this method with untrusted user data exposes your application to XSS security risks!

警告: 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!