agentic-stealth-browser 0.8.0__py3-none-any.whl

agentic_stealth_browser-0.8.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: agentic-stealth-browser
+Version: 0.8.0
+Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
+Author-email: Shane W <shanewas@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shanewas/agentic-stealth-browser
+Project-URL: Repository, https://github.com/shanewas/agentic-stealth-browser
+Project-URL: Issues, https://github.com/shanewas/agentic-stealth-browser/issues
+Project-URL: Documentation, https://github.com/shanewas/agentic-stealth-browser/tree/master/docs
+Project-URL: Changelog, https://github.com/shanewas/agentic-stealth-browser/blob/master/CHANGELOG.md
+Keywords: stealth,browser,automation,playwright,anti-bot,scraping,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright
+Requires-Dist: aiohttp
+Requires-Dist: cryptography
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# Agentic Stealth Browser
+
+[![CI](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-493%20passing-brightgreen)](tests/)
+
+A Python framework that makes browser automation look human. Built for autonomous agents that need to navigate websites protected by Cloudflare, LinkedIn, Amazon, and other anti-bot systems.
+
+## Why This Exists
+
+Standard browser automation (`page.goto()`, `page.click()`) gets detected instantly. This framework solves that by combining:
+
+- **TLS fingerprint spoofing** — matches real browser TLS handshakes
+- **Human behavior simulation** — natural mouse, typing, scrolling with realistic imperfections
+- **Automatic recovery** — detects blocks (CAPTCHAs, rate limits) and recovers without crashing
+- **Account lifecycle management** — warming, health scoring, cooling off
+
+## Installation
+
+```bash
+pip install agentic-stealth-browser
+playwright install --with-deps chromium
+```
+
+## Quick Start
+
+```python
+from core.agent_browser import AgentBrowser
+import asyncio
+
+async def main():
+    browser = AgentBrowser(session_name="demo")
+    await browser.launch(headless=True)
+
+    # This handles stealth, human behavior, and recovery automatically
+    await browser.safe_goto("https://example.com")
+
+    # Add human-like actions
+    await browser.human.scroll_naturally(400)
+    await browser.human.think(1500, 2800)
+
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Real-World Example
+
+For protected sites, load real cookies and use a platform preset:
+
+```python
+browser = AgentBrowser(session_name="linkedin")
+await browser.launch(preset="linkedin_2026")
+await browser.load_cookies_from_file("cookies.json")
+await browser.warm_up_before_work(intensity="heavy")
+await browser.safe_goto("https://www.linkedin.com/feed/", platform="linkedin")
+```
+
+The flow: **cookies → warm-up → navigate → recover if blocked → act human**.
+
+## How It Works
+
+```
+AgentBrowser
+├── Stealth      → TLS profiles, canvas/WebGL spoofing, WebRTC isolation
+├── Behavior     → Bézier mouse, natural typing, distraction simulation
+├── Recovery     → Detects blocks → rotates proxy/session → retries
+├── Accounts     → Health scoring, 14-day warming, session checkpointing
+└── Proxy        → Residential proxy with rotation and health tracking
+```
+
+## Key Features
+
+| Feature | What It Does |
+|---|---|
+| **TLS Fingerprinting** | Region-specific profiles (US, Japan, EU, Korea) with JA3/JA4 support |
+| **Human Behavior** | Mouse with wobble, typing with mistakes, variable scrolling, fatigue |
+| **Auto Recovery** | Detects CAPTCHAs, rate limits, blocks — recovers automatically |
+| **Account Warming** | 14-day gradual ramp-up so new accounts don't get flagged |
+| **Session Checkpoints** | Export/import browser state for cross-host migration |
+| **Platform Presets** | Pre-configured profiles for LinkedIn, Amazon, Cloudflare |
+| **MCP Server** | Integration with AI agents via Model Context Protocol |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `STEALTH_REGION` | TLS fingerprint region | `japan` |
+| `STEALTH_HEADLESS` | Run browser headless | `true` |
+| `STEALTH_PROXY` | Use residential proxy | `false` |
+
+### Platform Presets
+
+```python
+await browser.launch(preset="linkedin_2026")   # LinkedIn
+await browser.launch(preset="amazon_2026")     # Amazon
+await browser.launch(preset="cloudflare")      # Cloudflare-protected sites
+```
+
+## Project Structure
+
+```
+agentic-stealth-browser/
+├── core/           # AgentBrowser main class
+├── stealth/        # TLS fingerprinting, script injection, caching
+├── behavior/       # Human-like mouse, typing, scrolling, personas
+├── recovery/       # Block detection, anti-block orchestrator
+├── proxy/          # Proxy management and rotation
+├── sessions/       # Session and cookie management
+├── audit/          # Structured logging and audit trails
+├── ai/             # AI hooks and content analysis
+├── production/     # CLI, Docker, rate limiting, metrics
+├── linkedin/       # LinkedIn-specific actions
+├── scraping/       # Safe page scraping utilities
+├── docs/           # Architecture Decision Records and guides
+└── tests/          # 493 tests across 23 files
+```
+
+## Documentation
+
+- [Architecture Decision Records](docs/adr/)
+- [Visual Debugging Guide](docs/VISUAL_DEBUGGING.md)
+- [Stealth Limitations](docs/STEALTH_LIMITATIONS.md)
+- [Threat Model](docs/THREAT_MODEL.md)
+- [Common Pitfalls](docs/COMMON_PITFALLS.md)
+- [Rate Limiting & Backoff](docs/RATE_LIMITING_BACKOFF.md)
+- [Cookie & Session Resilience](docs/COOKIE_SESSION_RESILIENCE.md)
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and best practices.
+
+## Responsible Use
+
+This framework is designed for legitimate automation use cases such as:
+
+- Testing your own applications and infrastructure
+- Automating workflows on platforms that permit automation
+- Research and security analysis
+- Accessibility testing
+
+**Important:** Many websites (including LinkedIn, Amazon, and others) prohibit automated access in their Terms of Service. Always:
+
+1. Review the target site's Terms of Service and robots.txt
+2. Obtain proper authorization before automating access
+3. Respect rate limits and avoid causing harm to services
+4. Use this tool responsibly and legally
+
+This project is provided as-is under the MIT License. Users are responsible for complying with applicable laws and terms of service.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

agentic_stealth_browser-0.8.0.dist-info/RECORD

@@ -0,0 +1,53 @@
+agentic_stealth_browser-0.8.0.dist-info/licenses/LICENSE,sha256=OHalejGTK-x9OKISC5qIzC5WG5UdVYms8MvPYuITTwA,1063
+ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ai/ai_hooks.py,sha256=aKm64VpU6Xyh4BXtsi1zjDWQsv3qDcabjuuyHha1yYw,5449
+audit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audit/logger.py,sha256=APFZ9Q4e8uVhfHyslV_yAgxfTJB1L9zW4EIEuKHTF5g,18065
+behavior/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+behavior/adaptive_tuner.py,sha256=P4SpoRiV0fxKLI6zOWkJKncsPy0wFpE38Ge00bdTyWg,6466
+behavior/human_behavior.py,sha256=aYhD9h_a94n8jTB2Lmtf1oHcPtobyDh3BxXBgvfBATk,39843
+behavior/orchestration.py,sha256=UgCYf-AG5D4QgaF_gEQcgQh_IDFss8D9DrvevpIJD28,5183
+behavior/persona_rotator.py,sha256=5kObwFkKirKfEEBkH5q-EyFXgZ4EN1Ew0A5DIg7sa1k,13703
+core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+core/account_health.py,sha256=7maJ5S8GLw4eIZsIONrqMSkfRPZ1aNERWNlqT4HMHTs,11210
+core/account_warming.py,sha256=qyiIoaGGnD4E1JOvAaZV-bLzOoxrsnaxG9dk6qgFHPc,11029
+core/agent_browser.py,sha256=L2i1AJzWEbw5bOVtaWKWxitjAspTw3vW_VHIPdOHL4U,82777
+core/connection_pool.py,sha256=DFwDXZAIX0s3_uZW98GMX6YpDlmv26-wyMIlaUYmyIs,4314
+core/error_messages.py,sha256=lC6bLUXAn-kLrOunujYOaayWgqqUTlIEL_P9LEK51us,7537
+core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+core/session_checkpoint.py,sha256=wDA4elYk1mBgPMUodjyaMsFBPi7U8CBcCpRHS88twLY,13004
+core/types.py,sha256=EDDJL31oMv8tM9sO7jGdn3Oakk2uX4MD7yj70-DUPNI,4755
+linkedin/__init__.py,sha256=TdLucVbGu1c_f5xidQw7urwTO2FctpNTKxbmH5PaU0M,149
+linkedin/actions.py,sha256=uhpSzXKNgHt0395pHuUzB9NF4VuNOfBrBniihpD3q9g,5733
+production/Dockerfile,sha256=uIFGtcykrtnqiukPgAnSzNHkMVOrfHhxhhkseMGTl0I,2214
+production/__init__.py,sha256=yVLj-2coZXgbDFrTQbDXg4xEaMUY8YnL6z_RybvCNek,302
+production/cli.py,sha256=z-PsEtgqL0e7yMluMAgQ9EN16UBuqwIuDSesoKUoSAg,9564
+production/docker-compose.yml,sha256=nV5qEJHLU38oOOaN6JC5lJDRN_kGn_OO9SIIzYWteaQ,1368
+production/docker-healthcheck.py,sha256=TJhCh1aYlyPfM6_qcBSknYWX0-5-4KNCHVSmaS5gInc,485
+production/metrics.py,sha256=XgRRVMveElkmkpR1joM-1o8GMTuMi-PjycQt4Qq_QIw,6163
+production/otel_export.py,sha256=ZK1s4Hx-8sicqceu9bI1tizwXjysrU4qC_ydfD0Z5Zs,7108
+production/rate_limiter.py,sha256=4te3x6AjzicpiHFuqPYiYPUUV5aeEdT7zbHuAw1ixWQ,12773
+proxy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxy/proxy_manager.py,sha256=vGugVpSXw7hUvjatlMKtD5kkXMidCoPhSYK4mO83g8s,14620
+recovery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+recovery/anti_block_orchestrator.py,sha256=DvM6GrI1RaWWcS4BflZYc7mPYkvLhBUaTXWsncUGtbU,37034
+recovery/detectors.py,sha256=AMs7dTQ3CEXvWWC29YmYXc-lPbNMqO2lWjO3AuJTpWQ,9598
+recovery/explain_blocked.py,sha256=9CvZEva-u4HWL9cnVWRDcs8eHO_eSKqsZf7NUH48ruo,5171
+scraping/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scraping/scraper.py,sha256=wddQTNlgG7K2gZ5cusGeqWGPYo23z4RV3j38oDMRuOo,3947
+sessions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sessions/cookie_manager.py,sha256=BQxTXRRuWLsnVN0tAFZ0zNeBtUi_BIUPtqAaqm54LWs,37921
+sessions/session_manager.py,sha256=Bo-uDOtVu_FW4eJn_VPUKSXTdlr-y7gHnFvy6WYlhTs,11429
+stealth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stealth/advanced_stealth.py,sha256=Mq-j8t4K4O5G7IcS_SnDRfBHkYnGLiuXJbM8FUW2FYs,26328
+stealth/cache.py,sha256=a4zfwoEPkPQozR-I6I7UCqVko6jekEXjRi1q-uDhrLI,4979
+stealth/headers.py,sha256=LN-s0FllcCPgdrGzazYduD-YPrq3riXjIUG2zAIC2tw,1914
+stealth/presets.py,sha256=1epbVDWY5S1l4uja9qWr5goHEXY02oy44cmpSGq956o,10553
+stealth/profiles.py,sha256=FGPLc8aQ6qKY7HofSCCIxMO_Vk_D99jvcIUio_LD7Nw,8015
+stealth/tls_fingerprint.py,sha256=VGmUoJOEveL5HnZGBVzrqR5n2qAt6tVGQ5GknKMMPEM,11243
+stealth/tls_ja3_ja4.py,sha256=uRkvUw2Wy1gnMeYnwwwGwd9thx2VRiHw50XGPq8TMn4,6199
+agentic_stealth_browser-0.8.0.dist-info/METADATA,sha256=IcM7nyeg8VBytoSnGGy3E_w7ofutzqf87-hdY0OjdWk,7643
+agentic_stealth_browser-0.8.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentic_stealth_browser-0.8.0.dist-info/entry_points.txt,sha256=7FmBqyu4LJZJFRMpch2bnvUrZVj6HukbyTQqJgl0SaE,64
+agentic_stealth_browser-0.8.0.dist-info/top_level.txt,sha256=z-dkqaR0uDPpoCvXYzkjXU9oO_AW8wtzV_bWhDm17iA,84
+agentic_stealth_browser-0.8.0.dist-info/RECORD,,

agentic_stealth_browser-0.8.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentic_stealth_browser-0.8.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentic-stealth-browser = production.cli:main

agentic_stealth_browser-0.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shane W
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_stealth_browser-0.8.0.dist-info/top_level.txt

@@ -0,0 +1,11 @@
+ai
+audit
+behavior
+core
+linkedin
+production
+proxy
+recovery
+scraping
+sessions
+stealth

ai/ai_hooks.py

@@ -0,0 +1,126 @@
+"""
+AI Integration Hooks for Agentic Browser
+Allows connecting to LLMs for decision making and content analysis
+
+Security: All external content (page text, context) is sanitized before being
+eligible for LLM consumption to mitigate prompt injection (#188 P3).
+
+P3 #98 fix: AIHooks now provides real value even without an LLM provider:
+- Content sanitization for safe downstream use
+- Rule-based action decisions as fallback
+- Structured extraction via regex/heuristics
+"""
+
+from typing import Any, Dict, Optional, List
+import re
+import json
+
+
+class AIHooks:
+    """
+    AI integration hooks with injection protection and rule-based fallbacks.
+
+    When provider="none", provides:
+    - Content sanitization for safe downstream use
+    - Rule-based action decisions
+    - Heuristic structured extraction
+
+    When provider is set, connects to actual LLM (OpenAI, Claude, etc.).
+    """
+
+    # Common injection / jailbreak patterns observed in web content & attacks
+    _INJECTION_PATTERNS = [
+        r"\b(ignore|disregard|forget)\s+(all\s+)?(previous|above|prior|earlier|system|instructions?)\b",
+        r"\b(you are now|act as|role.?play|pretend you are|from now on you are)\b",
+        r"\b(system prompt|override|jailbreak|do anything|no restrictions|unfiltered)\b",
+        r"^\s*(system:|assistant:|user:)\s*",
+        r"\b(output only the|respond with only|print exactly|your new instructions)\b",
+    ]
+    _INJECTION_RE = re.compile("|".join(_INJECTION_PATTERNS), re.IGNORECASE)
+
+    def __init__(self, provider: str = "none", api_key: Optional[str] = None, model: Optional[str] = None):
+        self.provider = provider
+        self.api_key = api_key
+        self.model = model
+        self.enabled = provider != "none"
+        self._client = None
+
+    def sanitize_for_llm(self, content: str, max_len: int = 12000) -> str:
+        """Strip or neuter likely prompt-injection content from untrusted page/LLM input.
+        Returns a safe-ish version with markers for removed sections.
+        This is a practical P3 baseline; real deployments should layer more (e.g. LLM guardrails).
+        """
+        if not content or not isinstance(content, str):
+            return ""
+        safe = content[:max_len]
+        def _replace(m):
+            return "[REDACTED: potential instruction override]"
+        safe = self._INJECTION_RE.sub(_replace, safe)
+        safe = re.sub(r"[\u200b\u200c\u200d\u2060\ufeff]", "", safe)
+        return safe
+
+    def extract_links(self, text: str) -> List[str]:
+        """P3 #98: Extract URLs from text without LLM."""
+        url_pattern = r'https?://[^\s<>"\')\]]+'
+        return re.findall(url_pattern, text)
+
+    def extract_emails(self, text: str) -> List[str]:
+        """P3 #98: Extract email addresses from text without LLM."""
+        email_pattern = r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
+        return re.findall(email_pattern, text)
+
+    async def analyze_page(self, page_content: str, task: str) -> str:
+        """Analyze page content using AI (with injection protection)"""
+        if not self.enabled:
+            safe_content = self.sanitize_for_llm(page_content)
+            links = self.extract_links(safe_content)
+            emails = self.extract_emails(safe_content)
+            word_count = len(safe_content.split())
+            return (
+                f"Heuristic analysis (AI disabled):\n"
+                f"  Word count: {word_count}\n"
+                f"  Links found: {len(links)}\n"
+                f"  Emails found: {len(emails)}\n"
+                f"  Content sanitized: {len(safe_content)} chars\n"
+                f"  Task: {task}\n"
+                f"  Enable AI provider for deeper analysis."
+            )
+
+        safe_content = self.sanitize_for_llm(page_content)
+        return f"[AI Analysis Placeholder] Task: {task} (content sanitized: {len(safe_content)} chars kept)"
+
+    async def decide_next_action(self, context: Dict) -> str:
+        """Let AI decide next browsing action (with injection protection on any text fields)"""
+        if not self.enabled:
+            url = context.get("url", "")
+            status = context.get("status", 200)
+            if status in (403, 429, 503):
+                return "backoff_and_retry"
+            if "login" in url.lower() or "signin" in url.lower():
+                return "wait_for_user"
+            if not context.get("has_content", False):
+                return "scroll"
+            return "extract_and_continue"
+
+        safe_ctx = {}
+        for k, v in (context or {}).items():
+            if isinstance(v, str):
+                safe_ctx[k] = self.sanitize_for_llm(v)
+            else:
+                safe_ctx[k] = v
+        return "scroll"
+
+    async def extract_structured_data(self, text: str, schema: Dict) -> Dict:
+        """Extract structured data using AI (sanitized input)"""
+        if not self.enabled:
+            safe_text = self.sanitize_for_llm(text)
+            result = {
+                "links": self.extract_links(safe_text),
+                "emails": self.extract_emails(safe_text),
+                "phones": re.findall(r'\+?[\d\s\-\(\)]{10,}', safe_text),
+                "prices": re.findall(r'\$[\d,]+\.?\d*', safe_text),
+            }
+            return {"status": "heuristic_extraction", "data": result, "sanitized_len": len(safe_text)}
+
+        safe_text = self.sanitize_for_llm(text)
+        return {"status": "ai_disabled", "data": {}, "sanitized_len": len(safe_text)}