Metadata-Version: 2.5
Name: cookieguard-browser-use
Version: 0.1.0
Summary: CookieGuard authentication-cookie policy checks for Browser Use agents
Project-URL: Homepage, https://github.com/aiscihub/cookieguard-ai/tree/main/integrations/browser-use
Project-URL: Repository, https://github.com/aiscihub/cookieguard-ai
Project-URL: Issues, https://github.com/aiscihub/cookieguard-ai/issues
Author: aiscihub
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,authentication,browser-use,cookies,security,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: browser-use<0.14,>=0.13.14
Requires-Dist: cdp-use<2,>=1.4.5
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: test
Requires-Dist: pytest>=8.3; extra == 'test'
Description-Content-Type: text/markdown

# CookieGuard for Browser Use

**A successful agent login is not a secure session cookie.** CookieGuard for
Browser Use watches the browser your [Browser Use](https://github.com/browser-use/browser-use)
agent drives, checks the authentication cookies it receives, and returns
**PASS / FAIL / INCOMPLETE** with rule IDs, explanations, and fixes. The decision comes
from the local [CookieGuard](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/README.md) policy engine, never from the model.

**Overview** · [Install](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/install.md) · [Policy](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/policy.md) · [How it works](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/how-it-works.md) · [Results](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/results.md) · [Limits & privacy](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/limits-and-privacy.md) · [Demo & tests](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/demo-and-tests.md)

## Your policy decides what fails

<picture>
  <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/aiscihub/cookieguard-ai/browser-use-v0.1.0/integrations/browser-use/docs/policy-dark-mobile.svg">
  <source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/aiscihub/cookieguard-ai/browser-use-v0.1.0/integrations/browser-use/docs/policy-light-mobile.svg">
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/aiscihub/cookieguard-ai/browser-use-v0.1.0/integrations/browser-use/docs/policy-dark.svg">
  <img alt="CookieGuardAudit options decide which findings fail. High-severity rules CG001 Missing HttpOnly, CG002 Missing Secure, CG006 invalid prefix, and CG007 regression fail by default. With fail_on set to medium, CG003 SameSite and CG005 lifetime fail too. CG004 Domain sharing fails only with require_host_only. CG008 and CG009 are review only. The result is FAIL (exit 1), INCOMPLETE (exit 2, which overrides FAIL), or PASS (exit 0)." src="https://raw.githubusercontent.com/aiscihub/cookieguard-ai/browser-use-v0.1.0/integrations/browser-use/docs/policy-light.svg" width="100%">
</picture>

`fail_on` sets the line: a confirmed finding at or above it fails the run; anything below
is reported. Only cookies you name in `auth_cookies` can be confirmed.
All options and a stricter example: **[Policy](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/policy.md)**.

## See it run

![A Browser Use agent logs in to two local apps. Both logins succeed. CookieGuard fails the first with CG001 Missing HttpOnly (exit 1) and passes the second (exit 0).](https://raw.githubusercontent.com/aiscihub/cookieguard-ai/browser-use-v0.1.0/integrations/browser-use/docs/cookieguard-browser-use-demo.gif)

Claude (`claude-opus-5-5`) drives a real Browser Use agent through the same login twice.
The insecure app's cookie lacks `HttpOnly`, so CookieGuard returns **FAIL — CG001** (exit 1).
The secure app gets **PASS** (exit 0). Recorded from a real run: **[Demo & tests](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/demo-and-tests.md)**.

## Add it to your agent

```python
from browser_use import Agent, BrowserProfile, BrowserSession, Tools
from cookieguard_browser_use import CookieGuardAudit

audit = CookieGuardAudit(
    allowed_origins=['http://127.0.0.1:3000'],  # exact origins you are authorized to test
    auth_cookies=['session_id'],                # the real session cookie name(s)
    fail_on='high',
)
session = BrowserSession(browser_profile=BrowserProfile(
    keep_alive=True,                            # required: Agent.run() otherwise closes the browser
    enable_default_extensions=False,            # avoid the bundled cookie-consent extension
    allowed_domains=audit.browser_allowed_domains(),
))
tools = Tools()
audit.register_tools(tools)                     # optional agent-visible check

await session.start()
await audit.start(session)                      # before the login
agent = Agent(task=..., llm=..., browser_session=session, tools=tools,
              sensitive_data={'http://127.0.0.1': {'login_password': '...'}})
await agent.run()
result = await audit.finish()                   # decided by the CookieGuard engine
await session.kill()

print(result.summary)
result.assert_policy()                          # raises CookiePolicyError on FAIL or INCOMPLETE
```

`assert_policy()` raises even if the agent never called the tool, or reported
success. `CookieGuardAudit` is also an async context manager; `close()` stops
collection without a result. One instance audits one workflow.

Needs Python 3.11+, Node.js 24+, and Chrome or Chromium: **[Install](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/install.md)**.

Install [version 0.1.0 from PyPI](https://pypi.org/project/cookieguard-browser-use/):

```bash
pip install cookieguard-browser-use
```

Status: `0.1.0`, tested with browser-use 0.13.14 on Linux (Python 3.11–3.13) and macOS (Python 3.12).
See [tested environments](https://github.com/aiscihub/cookieguard-ai/blob/browser-use-v0.1.0/integrations/browser-use/docs/limits-and-privacy.md#tested-environments-and-dependencies).
This is a community integration, not an official Browser Use package.
