Security & Sensitive Data
Relevant source files
The following files were used as context for generating this wiki page:
Security and sensitive data management in the browser-use library are handled through a multi-layered approach involving domain restriction, privacy-aware logging, and secure browser environment configurations. The system is designed to allow AI agents to interact with web content while providing developers with tools to limit the agent's scope and protect user information during automated tasks.
This module focuses on ensuring that browser sessions are isolated, communications with external URLs are controlled via allowlists, and sensitive information—such as passwords or personal data—is handled with appropriate logging suppression to prevent exposure in logs or terminal outputs.
Sources: browser_use/browser/context.py, browser_use/controller/service.py
URL Restriction and Domain Control
The library provides a mechanism to restrict the AI agent's navigation to a specific set of allowed domains. This is primarily managed through the BrowserContextConfig and enforced during navigation events within the BrowserContext.
Domain Validation Logic
When allowed_domains are configured, the BrowserContext intercepts navigation attempts. It parses the target URL and compares the domain against the whitelist. If a navigation to a non-allowed domain is detected, the system raises a URLNotAllowedError and attempts to go back to the previous allowed state.
This diagram shows the decision flow when an agent attempts to change the browser's URL.
Sources: browser_use/browser/context.py:441-477, browser_use/browser/context.py:110-113
Sensitive Data Handling in Actions
The Controller service manages how data is passed to web elements, specifically providing support for flagging data as sensitive. This is particularly relevant for the input_text action, where user-provided secrets should not be echoed in logs.
Sensitive Logging Suppression
The input_text function accepts a has_sensitive_data boolean parameter. When set to True, the controller logs a generic message ("Input sensitive data into index X") instead of the actual text being typed into the browser.
| Component | Logic | Description |
|---|---|---|
input_text | has_sensitive_data flag | Determines if the input value is logged or masked. |
Controller.act | sensitive_data dict | Passes mapping of sensitive keys/values to actions. |
ActionResult | extracted_content | The result returned to the agent; contains masked info if flagged. |
Sources: browser_use/controller/service.py:107-124, browser_use/controller/service.py:410-417
Multi-Action Sequence Flow
When executing multiple actions, the controller ensures that the sensitive data context is maintained throughout the loop.
This sequence illustrates how sensitive data is passed through the controller to the browser while maintaining privacy in the logging layer.
Sources: browser_use/controller/service.py:410-450
Browser Security Configuration
The BrowserContextConfig allows for fine-grained control over browser security features. While the library supports disabling security for specific testing environments (e.g., bypassing CSP), the default state favors standard browser protections.
Key Security Configurations
| Parameter | Type | Default | Description |
|---|---|---|---|
disable_security | bool | False | Disables browser security features like CSP and ignores HTTPS errors. |
allowed_domains | list[str] | None | Whitelist of domains the browser is permitted to access. |
bypass_csp | bool | Derived | Internal Playwright setting to bypass Content Security Policy. |
Sources: browser_use/browser/context.py:59-120
Anti-Detection Measures
To prevent scripts from being identified as automated bots—which can be a security risk for certain tasks—the BrowserContext injects anti-detection scripts that modify browser properties like navigator.webdriver, navigator.languages, and navigator.plugins.
Sources: browser_use/browser/context.py:199-239
DOM Safety and Visibility
The DOM extraction process ensures that the AI agent only interacts with elements that are actually "interactive" and "top-level." This prevents the agent from being "tricked" by hidden elements or overlay attacks.
Element Validation Logic
The isInteractiveElement and isTopElement functions in the JavaScript DOM parser filter the tree.
- Interactive Check: Validates roles (button, link, etc.), event listeners (click, mousedown), and ARIA properties.
- Visibility Check: Uses
getBoundingClientRectandgetComputedStyleto ensure elements are not hidden. - Top Element Check: Uses
elementFromPointto verify the element isn't covered by another layer.
Sources: browser_use/dom/buildDomTree.js:154-320, browser_use/dom/buildDomTree.js:338-410
Vulnerability Reporting
The project maintains a formal security policy for reporting vulnerabilities.
- Non-Public Reporting: Security issues must not be reported via public GitHub issues, discussions, or PRs.
- Official Channel: Vulnerabilities should be reported via a GitHub Security Advisory.
- Required Information: Reports should include the issue type, full source paths, affected code location (commit/branch), reproduction steps, and impact assessment.
Sources: SECURITY.md:1-20
Summary
The "Security & Sensitive Data" implementation in browser-use focuses on providing a controlled environment for AI-driven browser interactions. By utilizing domain whitelists, sensitive logging flags in the controller, and strict DOM element validation, the library mitigates risks associated with unintended navigation and data exposure. Developers are encouraged to use the allowed_domains configuration and the has_sensitive_data flag in custom actions to maintain a secure automation pipeline.