Autonomous web agents require detailed structural and visual understanding of browser interfaces to complete tasks. However, passing unredacted webpage state, raw DOM nodes, or unmasked screenshots to external language models presents severe privacy and security risks.
This project delivers an on-device perception middleware that sits between the browser instance and the intelligent agent. The middleware extracts, detects, and redacts sensitive user data locally before sending sanitized interface representations to upstream models. When the agent issues action commands referencing opaque tokens, the local execution engine resolves the tokens back to their original values strictly at the execution boundary.
- Multi-Modal Feature Extraction: Combine DOM structure, optical character recognition (OCR), visual object detection, and named entity recognition (NER) for comprehensive interface understanding.
- Zero-Trust Network Boundary: Ensure raw sensitive data (PII, credentials, financial identifiers) never leaves the host machine.
- Tokenized Redaction & State Isolation: Replace sensitive values with opaque structural tokens, maintaining local in-memory mappings for execution recovery.
- Deterministic Intent Ranking: Utilize an Okapi BM25 ranking engine over non-sensitive metadata for precise, local element targeting.
- Validated Action Execution: Verify agent action requests against active page state schemas prior to local browser dispatch.
The middleware architecture is structured into isolated layers covering perception, privacy sanitization, intent ranking, and local action dispatching.
graph TD
subgraph Client_Layer ["Client & Interaction Layer"]
A[Browser Environment / Chrome Extension]
B[Developer Inspection Dashboard]
C[Autonomous LLM / BM25 Agent]
end
subgraph API_Gateway ["FastAPI Middleware Gateway"]
D[Gateway API Router]
E[Action Validator]
end
subgraph Perception_Engine ["Multi-Modal Perception Subsystem"]
F[DOM Extraction Engine]
G[ONNX / YOLOv8 Vision Engine]
H[Tesseract OCR Engine]
I[spaCy Named Entity Recognizer]
end
subgraph Privacy_Layer ["Privacy & Sanitization Middleware"]
J[Multi-Layer PII Detector]
K[Sanitization & Tokenization Engine]
L[Local Encrypted Value Store]
end
subgraph Execution_Engine ["Execution Engine"]
M[Playwright Browser Connector]
N[Extension Bridge Dispatcher]
end
A -->|Raw Page State / Signals| D
D --> Perception_Engine
Perception_Engine --> J
J --> K
K -->|Store Raw Value| L
K -->|Sanitized State JSON| C
C -->|Action with Token| E
E -->|Resolved Value from Store| L
L --> Execution_Engine
Execution_Engine -->|Execute Interaction| A
D -->|Telemetry & Metrics| B
- Local Boundary Enforcement: All PII detection algorithms and token stores operate strictly within the local process runtime.
- Decoupled Gateway: The FastAPI gateway exposes standardized REST endpoints for agent context querying and action submission.
- Fail-Safe Fallbacks: If vision, OCR, or NER models are unavailable, the system gracefully degrades to DOM-based extraction and deterministic regular expression filtering without throwing fatal runtime errors.
The perception subsystem transforms raw webpage interfaces into structured, actionable domain models through four complementary analysis engines:
- Performs recursive tree walks over accessible DOM elements.
- Identifies interactive nodes (inputs, buttons, anchor tags, select boxes, ARIA roles).
- Computes bounding client rectangles, accessibility attributes, node depth, and visible text content.
- Analyzes rendered viewport screenshots to localize UI elements independently of DOM representation.
- Detects visual bounding boxes for custom-rendered buttons, icons, and non-standard control elements.
- Applies Non-Maximum Suppression (NMS) to eliminate duplicate detection candidates.
- Processes rendered screenshot regions to extract textual content embedded within images, canvas elements, or styled components.
- Correlates extracted text coordinates with DOM bounding boxes to verify element labels.
- Analyzes natural language strings extracted from webpage text nodes.
- Identifies semantic entities including personal names, organization titles, geographic locations, and monetary values.
The privacy layer employs a four-tiered detection methodology to ensure high sensitivity and low false-negative rates across global and regional data formats.
graph TD
A[Raw Webpage Capture] --> B[DOM & Screenshot Ingestion]
subgraph Data_Extraction ["Feature Extraction"]
B --> C1[DOM Tree Traversal]
B --> C2[Visual Object Detection]
B --> C3[OCR Text Recognition]
B --> C4[NLP Named Entity Recognition]
end
subgraph PII_Analysis ["Multi-Layer PII Detection"]
C1 --> D1[DOM Attribute Analysis<br/>input type, name, aria-label]
C2 & C3 & C4 --> D2[Pattern & Entity Matching<br/>Regex, spaCy NER, Identifiers]
end
D1 & D2 --> E[Aggregated PII Candidates]
subgraph Sanitization_Phase ["Tokenization & Isolation"]
E --> F[Generate Opaque Tokens<br/>e.g., EMAIL_0, AADHAAR_1]
F --> G1[Store Map in Local In-Memory Store]
F --> G2[Redact Raw Values in Page State]
end
G2 --> H[Sanitized Page State JSON]
H --> I[External Agent / LLM Model]
Analyzes HTML input element classifications and attribute metadata:
type="password",type="email",type="tel",type="credit-card"- Attributes containing
autocomplete="cc-number",aria-label="Social Security" - Field identifiers matching security keywords (
pin,cvv,secret,ssn,password)
Executes compiled regular expressions against extracted text values for standard global and regional formats:
| Identifier Type | Matching Pattern / Schema | Example Target |
|---|---|---|
| Email Address | [a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+ |
user@organization.com |
| Global Phone Number | \+?\d{1,4}[-.\s]?\(?\d{1,3}\)?[-.\s]?\d{3,4}[-.\s]?\d{4} |
+1-555-0199 |
| Credit Card Number | Luhn-validated digit sequences (13 to 19 digits) | 4532-XXXX-XXXX-8923 |
| Aadhaar Number (India) | \d{4}[-\s]?\d{4}[-\s]?\d{4} |
1234 5678 9012 |
| PAN Card (India) | [A-Z]{5}[0-9]{4}[A-Z]{1} |
ABCDE1234F |
| Indian Phone Number | (?:\+91[-.\s]?)?[6-9]\d{9} |
+91 9876543210 |
| IFSC Code (India) | [A-Z]{4}0[A-Z0-9]{6} |
SBIN0001234 |
| Driving License (India) | [A-Z]{2}[0-9]{2}[0-9]{11} |
DL1420110012345 |
Uses spaCy statistical models to classify unstructured contextual text:
PERSONentities -> Tokenized as[PERSON_NAME_N]ORGentities -> Tokenized as[ORGANIZATION_N]GPEentities -> Tokenized as[LOCATION_N]MONEYentities -> Tokenized as[FINANCIAL_N]
Cross-references OCR text locations against detected PII regions to ensure values rendered within canvas or non-standard HTML elements are fully redacted in visual screenshots and DOM models.
When sensitive data is identified:
- The raw value is stored in a thread-safe, local in-memory
ValueStoreindexed by a cryptographically generated token (e.g.,[EMAIL_0],[PASSWORD_1]). - The raw value in the DOM state, text attributes, and input values is replaced with the token.
- Screenshots are dynamically blurred over the bounding boxes of sensitive elements.
- Only the tokenized
SanitizedPageStateis exposed to external agents.
To enable accurate, lightweight target element selection without requiring large generative models for simple interactions, the system includes an Okapi BM25 ranking engine.
graph TD
A[Agent Intent Query<br/>e.g., 'Enter email address'] --> B[Query Tokenization & Normalization]
C[Sanitized Page State] --> D[Extract Candidate Interactive Elements]
subgraph Corpus_Extraction ["Safe Corpus Generation"]
D --> E[Extract Non-Sensitive Textual Metadata<br/>label, role, type, element_id, non-PII text]
E --> F[Tokenize Metadata per Element]
end
B & F --> G[Compute Term Frequency & Inverse Document Frequency]
G --> H[Okapi BM25 Scoring Formula<br/>k1=1.5, b=0.75]
H --> I[Rank Elements by Score Descending]
I --> J{Top Score >= Threshold?}
J -- Yes --> K[Select Best Candidate Element]
J -- No --> L[Return Null / Fail Safe]
For a natural language intent query
Where:
-
$f(q_i, D)$ is the term frequency of query token$q_i$ in the safe metadata corpus of element$D$ . -
$|D|$ is the length of document$D$ in tokens. -
$\text{avgdl}$ is the average document length across all candidate elements on the page. -
$k_1 = 1.5$ (term frequency saturation parameter). -
$b = 0.75$ (document length normalization parameter). - Inverse Document Frequency (IDF) is calculated as:
The BM25 corpus extractor strictly processes non-sensitive structural attributes (label, type, role, element_id, sanitized placeholder text). Redacted token strings and raw sensitive values are excluded from document indexing to prevent statistical leaking.
When an agent decides to interact with a page element, it sends an action payload containing element identifiers and value tokens back to the gateway.
sequenceDiagram
autonumber
participant Agent as Autonomous Agent / LLM
participant Gateway as FastAPI Gateway (/agent/action)
participant Validator as Action Validator
participant Store as Secure Value Store
participant Driver as Playwright / Extension Driver
participant Browser as Web Browser DOM
Agent->>Gateway: POST /agent/action (Action: fill, Token: [EMAIL_0], Target: input_1)
Gateway->>Validator: Validate Action Request against Sanitized State
alt Validation Failure
Validator-->>Gateway: Return Validation Error
Gateway-->>Agent: HTTP 400 (Invalid Action or Stale State)
else Validation Success
Validator-->>Gateway: Action Approved
Gateway->>Store: Resolve Token ([EMAIL_0], Session ID)
Store-->>Gateway: Return Raw Value ("user@example.com")
Gateway->>Driver: Dispatch Action with Raw Value
Driver->>Browser: Perform DOM Interaction (e.g., type into field)
Browser-->>Driver: Dom Interaction Completed
Driver-->>Gateway: Execution Result
Gateway-->>Agent: HTTP 200 (Success, Updated Sanitized State)
end
Before execution, the ActionValidator verifies:
- Target Existence: The specified
element_idexists within the active page snapshot. - Interactability: The element is visible, enabled, and accepts the specified action type (e.g., preventing
fillon non-input nodes). - Token Ownership: The submitted token exists in the active session's
ValueStore. - Origin Alignment: Navigation requests match origin security policies.
The architecture supports both direct Playwright browser control and live Chrome extension integration for user-driven sessions.
graph LR
subgraph Chrome_Browser ["Chrome Browser (User Session)"]
ExtScript[Content Script / DOM Collector]
ExtExec[Action Runner]
end
subgraph Extension_Bridge ["Local Bridge Middleware"]
Ingress[POST /browser/perception]
StateStore[Local Session Manager]
ActionQueue[Action Queue Buffer]
Egress[GET /browser/actions/next]
ResultIngress[POST /browser/actions/result]
end
subgraph Agent_Boundary ["Agent Environment"]
AgentCore[Agent / Gateway Core]
end
ExtScript -->|Raw DOM & Context| Ingress
Ingress -->|Sanitize & Store| StateStore
AgentCore -->|Read Context| StateStore
AgentCore -->|Enqueue Action| ActionQueue
ActionQueue --> Egress
Egress -->|Poll Next Action| ExtExec
ExtExec -->|Report Execution Status| ResultIngress
sih-1/
├── backend/
│ ├── actions/
│ │ ├── executor.py # Playwright action execution engine
│ │ └── validator.py # Action validation rules and safety checks
│ ├── agent_gateway/
│ │ ├── bm25_ranker.py # Okapi BM25 implementation for UI elements
│ │ ├── mock_agent.py # Deterministic BM25 mock agent
│ │ └── provider.py # External LLM provider interfaces
│ ├── api/
│ │ └── gateway.py # FastAPI server endpoints and CORS middleware
│ ├── browser/
│ │ ├── connector.py # Async Playwright browser lifecycle manager
│ │ └── extension_bridge.py # Session bridge for live Chrome Extension
│ ├── capture/
│ │ └── service.py # Multi-modal state capture coordinator
│ ├── config/
│ │ ├── logging.py # Application logging setup
│ │ └── settings.py # Pydantic configuration settings
│ ├── demo/
│ │ └── run_chrome_agent.py # End-to-end integration demo script
│ ├── models/
│ │ ├── domain.py # Core Pydantic domain models
│ │ └── download_models.py # Script for fetching ML model artifacts
│ ├── perception/
│ │ ├── dom_engine.py # DOM tree extraction module
│ │ ├── ocr_engine.py # Tesseract OCR extraction engine
│ │ └── vision_engine.py # ONNX/YOLOv8 visual object detector
│ ├── pii/
│ │ └── detector.py # Multi-layer PII detection suite
│ ├── sanitization/
│ │ └── engine.py # Tokenization and redaction engine
│ ├── security/
│ │ ├── origin_policy.py # URL origin validation policy
│ │ └── store.py # Local thread-safe in-memory value store
│ └── tests/ # Pytest automated test suites
├── dashboard/ # Developer inspection dashboard (Next.js/React)
├── extension/ # Manifest V3 Chrome Extension source
├── requirements.txt # Python dependencies specification
├── main.py # Entry point for backend server execution
└── run_server.py # Standalone server runner
- Python: Version 3.10 or higher
- Node.js: Version 18.0 or higher (for the developer dashboard)
- Tesseract OCR: (Optional, for visual text extraction)
- Ubuntu/Debian:
sudo apt-get install tesseract-ocr - macOS:
brew install tesseract - Windows: Install via Tesseract installer binary
- Ubuntu/Debian:
- Playwright System Dependencies: Required for headless browser instances
# Clone the repository
cd /path/to/sih-1
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install Python dependencies
pip install -r requirements.txt# Install Playwright browser binaries
playwright install chromium
# Download spaCy English NLP model (for NER PII detection)
python -m spacy download en_core_web_mdCreate a .env file in the root directory to override default settings:
HOST=127.0.0.1
PORT=8000
LOG_LEVEL=INFO
BROWSER_HEADLESS=true
OCR_ENABLED=true
NER_ENABLED=true
PII_DETECTION_ENABLED=true
DEVICE=auto# Start backend server via Uvicorn runner
python run_server.py
# Alternatively, run directly with Uvicorn CLI
python -m uvicorn backend.api.gateway:app --host 127.0.0.1 --port 8000 --reloadVerify backend health by querying the health endpoint:
curl http://127.0.0.1:8000/healthExpected Response:
{
"status": "healthy",
"uptime_seconds": 12.4,
"browser_status": "healthy",
"version": "1.0.0"
}cd dashboard
npm install
npm run devNavigate to http://localhost:3000 to inspect raw versus sanitized DOM elements, view processing latency metrics, monitor real-time server logs, and test perception triggers.
python backend/demo/run_chrome_agent.pyEndpoint: POST /agent/context
Captures the current browser state, applies multi-layer PII detection, stores raw values locally, and returns the tokenized page context.
{
"task": "Log into user account and retrieve statement",
"session_id": "optional_session_identifier"
}{
"task": "Log into user account and retrieve statement",
"session_id": null,
"page_revision": 1,
"page": {
"url": "https://example.com/login",
"title": "Account Login",
"elements": [
{
"element_id": "input_email_1",
"type": "input",
"role": "textbox",
"label": "Email Address",
"value": "[EMAIL_0]",
"text": null,
"is_sensitive": true,
"is_interactive": true,
"bbox": { "x": 100, "y": 200, "width": 300, "height": 40 }
},
{
"element_id": "input_pass_2",
"type": "password",
"role": "textbox",
"label": "Password",
"value": "[PASSWORD_1]",
"text": null,
"is_sensitive": true,
"is_interactive": true,
"bbox": { "x": 100, "y": 260, "width": 300, "height": 40 }
}
],
"viewport": { "width": 1280, "height": 720 },
"timestamp": 1724965200.0
}
}Endpoint: POST /agent/action
Validates and executes an action command on the browser instance. Resolves value tokens locally before DOM interaction.
{
"action": "fill",
"element_id": "input_email_1",
"value_token": "[EMAIL_0]",
"value": null,
"url": null,
"session_id": null,
"page_revision": 1
}{
"success": true,
"new_state": {
"url": "https://example.com/login",
"title": "Account Login",
"elements": [],
"viewport": { "width": 1280, "height": 720 },
"timestamp": 1724965202.5
},
"error": null
}Endpoint: POST /browser/perception
Receives raw page state captured by the Chrome extension, sanitizes it locally, and stores it in the active session bridge.
{
"session_id": "chrome_session_88",
"page": {
"url": "https://example.com/portal",
"title": "User Portal",
"dom_elements": [],
"screenshot_base64": null,
"viewport": { "width": 1920, "height": 1080 },
"timestamp": 1724965210.0
}
}Returns the sanitized SanitizedPageState model.
- Network Data Leakage: Raw PII values (passwords, emails, phone numbers, identity cards, credit cards) are tokenized before state representations exit the FastAPI gateway runtime.
- Visual Privacy: Rendered screenshots stored or transmitted to frontends undergo bounding-box redaction and blurring over sensitive form fields.
- Untrusted Agent Isolation: Upstream agents operate strictly on opaque tokens (
[TOKEN_N]). Agents cannot read raw stored values.
| Threat Vector | Description | Recommended Production Mitigation |
|---|---|---|
| Process Memory Forensics | Raw sensitive values exist unencrypted in Python heap memory during active sessions. | Implement OS-level memory locking (mlock), encrypt the in-memory value store using AES-256-GCM, and shorten session retention periods. |
| Logging Data Leakage | Raw values or tokens logged to disk files could be exposed if log permissions are weak. | Enforce structural log scrubbers that strip token strings and prohibit raw parameter logging in production configurations. |
| Bypass via Custom Canvas | Non-standard graphical forms rendering text on HTML5 Canvas without ARIA tags. | Enable OCR visual detection layer for all page captures to catch non-DOM text nodes. |
The codebase includes an automated test suite implemented using pytest.
# Run all unit and integration tests
pytest backend/tests/ -v
# Test specific subsystems
pytest backend/tests/test_comprehensive.py -v # Comprehensive PII & Sanitization tests
pytest backend/tests/test_bm25_agent.py -v # BM25 ranker & Mock Agent tests
pytest backend/tests/test_privacy_boundary.py -v # End-to-end privacy boundary verification
pytest backend/tests/test_network_privacy.py -v # Network isolation and token leakage tests- PII Detection Accuracy: Validation across email, phone, SSN, Aadhaar, PAN, IFSC, and driving license schemas.
- Zero Raw Value Transmission: Verification that zero raw sensitive strings appear in exported state objects or API JSON payloads.
- Token Resolution Correctness: Verification that
ActionExecutorresolves tokens to their correct raw values during browser interaction. - BM25 Ranking Accuracy: Verification that natural language intent queries correctly resolve to target DOM elements.
Latency and resource benchmarks measured on standard execution hardware (4-core CPU, 16GB RAM):
| Processing Phase | Average Latency | Bottleneck Source / Notes |
|---|---|---|
| Playwright Screenshot Capture | 180 ms - 350 ms | Headless browser frame buffer retrieval |
| DOM Tree Traversal & Normalization | 40 ms - 90 ms | DOM node extraction (scaled by node count) |
| Multi-Layer PII Detection | 30 ms - 80 ms | Parallel regex matching and attribute scanning |
| spaCy NER Inference (Optional) | 70 ms - 140 ms | CPU-based NLP inference |
| Tesseract OCR Extraction (Optional) | 200 ms - 450 ms | Image-to-text visual scan |
| Tokenization & Sanitization | 10 ms - 25 ms | In-memory token replacement and dictionary map |
| BM25 Intent Selection | 2 ms - 8 ms | Okapi BM25 scoring over candidate list |
| Total Capture-to-Sanitized State | 260 ms - 650 ms | Standard DOM + Regex configuration |
- Base Runtime Process: ~95 MB
- Per Active Captured Snapshot: +15 MB to 35 MB (DOM model + image buffers)
- In-Memory Value Store: < 1 MB for typical session execution (100-500 entries)
| Layer | Component | Technology / Library | License |
|---|---|---|---|
| Backend API Gateway | Web Server & Routing | FastAPI / Uvicorn | MIT |
| Browser Driver | Web Automation | Playwright for Python | Apache 2.0 |
| NLP Subsystem | Named Entity Recognition | spaCy (en_core_web_md) |
MIT |
| OCR Subsystem | Optical Character Recognition | Tesseract / Pytesseract | Apache 2.0 |
| Vision Inference | Visual UI Detection | ONNX Runtime / OpenCV | MIT |
| Information Retrieval | Ranking Engine | Okapi BM25 (Custom Python) | MIT |
| Data Validation | Schema Enforcers | Pydantic v2 / BaseSettings | MIT |
| Testing | Test Automation | Pytest / Pytest-Asyncio | MIT |
Browser Perception Middleware — Developed for Smart India Hackathon (SIH) 2026. Distributed under the MIT License.