Threat Model

Relevant source files

The following files were used as context for generating this wiki page:

• THREAT_MODEL.md
• INCIDENT_RESPONSE.md
• SECURITY.md
• package.json
• src/parse.spec.ts
• src/api/attributes.spec.ts

Cheerio is a fast, flexible, and elegant library for parsing and manipulating HTML and XML. This threat model defines the security boundaries, responsibilities, and identified risks associated with using Cheerio in a Node.js environment. It differentiates between vulnerabilities Cheerio is responsible for mitigating and those that fall under the responsibility of the calling application.

Sources: THREAT_MODEL.md:7-9, package.json:3-12

System Boundaries and Trust

Cheerio operates primarily as a library that parses strings into a DOM tree for querying and manipulation. It is designed to run in a server-side Node.js environment, not directly in a browser.

Trust Boundaries

The following diagram illustrates the data flow and trust boundaries within the Cheerio ecosystem.

The diagram shows that input markup and external selectors are considered untrusted, while the runtime and calling application are trusted entities.
Sources: THREAT_MODEL.md:13-33, THREAT_MODEL.md:65-72

Trust Classification

Boundary	Classification	Responsibility
Input Markup	Untrusted	Cheerio must handle safely without crashing or leaking data.
CSS Selectors	Untrusted	External selectors may cause backtracking issues in the engine.
Node.js Runtime	Trusted	Assumed to be a correct, unpatched runtime.
Calling Code	Trusted	Responsible for sanitizing Cheerio's output before rendering.
Parsers	Trusted	parse5 and htmlparser2 are considered part of the internal ecosystem.

Sources: THREAT_MODEL.md:15-31, SECURITY.md:38-46

In-Scope Vulnerabilities

Cheerio identifies specific classes of issues that are treated as security vulnerabilities requiring a patch and disclosure.

Vulnerability Categories

• Denial of Service (DoS): Crafted inputs that cause resource consumption (CPU/Memory) disproportionate to the input size, such as ReDoS or quadratic parsing.
• Prototype Pollution: Parsed content or API calls that modify Object.prototype or other built-in prototypes.
• Unexpected Code Execution: Any path where parsing/serialization leads to the execution of attacker-supplied content (e.g., via eval).
• XSS Enablement: Cases where the serializer produces output more dangerous than the input, such as incorrect attribute escaping.
• Information Disclosure: Unintended leaking of data from the runtime environment.

Sources: THREAT_MODEL.md:35-48, SECURITY.md:40-45

XSS Protection Logic

While Cheerio is not a sanitizer, it must ensure its own manipulation methods do not introduce new vectors through incorrect encoding.

// Example of attribute encoding to prevent XSS enablement
it('(key, value) : should correctly encode then decode unsafe values', () => {
  const $apple = $('.apple');
  $apple.attr(
    'href',
    'http://github.com/"><script>alert("XSS!")</script><br',
  );
  expect($apple.html()).not.toContain('<script>alert("XSS!")</script>');
});

Sources: src/api/attributes.spec.ts:107-119

Out-of-Scope Risks (Non-Vulnerabilities)

Certain behaviors are explicitly excluded from Cheerio's threat model as they belong to application-level security or platform concerns.

• Unsafe Output Rendering: Cheerio provides markup, not "safe" HTML. Applications must use a dedicated sanitizer (like sanitize-html) before rendering output in a browser.
• API Misuse: Passing attacker-controlled strings as property names or unsanitized objects as options (CWE-20).
• Large Input Resource Exhaustion: Legitimate resource use for very large files (e.g., a 500MB HTML file) is expected behavior.
• Third-party Code: Compromised transitive dependencies outside of Cheerio's maintained ecosystem.

Sources: THREAT_MODEL.md:50-63, SECURITY.md:48-52

Incident Response and Remediation

Cheerio follows a structured response plan for reported vulnerabilities, managed through Tidelift or GitHub Private Vulnerability Reporting.

Response Process Flow

The sequence demonstrates the transition from a private report to public disclosure and patching.
Sources: INCIDENT_RESPONSE.md:33-55, SECURITY.md:15-36

Severity Definitions

Severity	Definition	Target Fix
Critical	Active exploitation, RCE, or supply-chain compromise.	< 7 days
High	Easily exploitable DoS, prototype pollution, or XSS enablement.	< 14 days
Medium	Unusual configuration required or limited impact.	Next release
Low	Defense-in-depth or theoretical risks.	Scheduled

Sources: INCIDENT_RESPONSE.md:15-22

Security Assumptions

1. Environment: The library is executed in a server-side Node.js environment.
2. Input Limitation: The caller is responsible for limiting the size of input if accepting markup from untrusted sources to prevent general resource exhaustion.
3. No Execution: Cheerio never executes scripts or evaluates expressions found within the markup.
4. Network Access: Cheerio does not access the network, with the exception of the fromURL helper which uses the undici library.

Sources: THREAT_MODEL.md:11-13, THREAT_MODEL.md:65-72