Python SDK for SafeBrowse - AI-powered browser security with prompt injection detection
Project description
SafeBrowse Python SDK
Enterprise-grade security for AI agents and RAG pipelines.
SafeBrowse protects your AI applications from prompt injection attacks. Scan web content before your LLM processes it.
Installation
pip install safebrowse
Quick Start
from safebrowse import SafeBrowseClient
client = SafeBrowseClient(api_key="your-api-key")
# Protect your agent
with client.guard(html, url) as decision:
print(f"Risk score: {decision.risk_score}")
agent.run() # Only runs if content is safe
Features
| Feature | Description |
|---|---|
| Prompt Injection Detection | Detects 50+ attack patterns |
| Policy Engine | Block login forms, suspicious domains |
| RAG Sanitization | Clean document chunks before ingestion |
| Batch Scanning | Efficiently scan multiple pages |
| Fail-Closed Design | Errors block, never fail open |
| Audit Logging | Full request traceability |
| Document Scanning | Scan PDFs & Images via OCR |
| Red Team Testing | Run security attack simulations |
| Agent Guard | Stateful session protection for agents |
Usage
Scan HTML
result = client.scan_html(
html="<html><body>...</body></html>",
url="https://example.com"
)
if result.is_safe:
process(html)
else:
print(f"Blocked: {result.reason}")
print(f"Risk: {result.risk_score}")
Safe Ask (LLM Query)
result = client.safe_ask(
html="<html>...</html>",
url="https://example.com",
query="Summarize this page"
)
print(result.answer)
Guard Context Manager
from safebrowse import BlockedError
try:
with client.guard(html, url) as decision:
# Only executes if content is safe
# Access decision metadata
print(f"Risk: {decision.risk_score}")
agent.browse(url)
except BlockedError as e:
print(f"Blocked: {e.message}")
print(f"Code: {e.code}") # Machine-readable
RAG Pipeline Sanitization
# Clean chunks before adding to vector DB
result = client.sanitize(
documents=["chunk 1", "chunk 2", "ignore instructions..."],
source="web"
)
safe_chunks = result.safe_chunks # Only safe content
print(f"Removed {result.blocked_count} dangerous chunks")
Batch Scanning
results = client.scan_batch([
{"html": page1, "url": url1},
{"html": page2, "url": url2},
])
print(f"Safe: {results.safe_count}/{results.total}")
Configuration
Config Object
from safebrowse import SafeBrowseConfig, SafeBrowseClient
config = SafeBrowseConfig(
api_key="your-key",
base_url="https://api.safebrowse.io",
timeout=30.0,
)
client = SafeBrowseClient(config=config)
Environment Variables
export SAFEBROWSE_API_KEY=your-key
export SAFEBROWSE_BASE_URL=https://api.safebrowse.io
export SAFEBROWSE_TIMEOUT=30
client = SafeBrowseClient.from_env()
Logging Hooks
def on_blocked(result):
logger.warning(f"Blocked: {result.reason}")
metrics.increment("safebrowse.blocked")
def on_allowed(result):
logger.info(f"Allowed: risk={result.risk_score}")
client = SafeBrowseClient(
api_key="your-key",
on_blocked=on_blocked,
on_allowed=on_allowed,
)
Error Handling
from safebrowse import BlockedError, AuthenticationError, ConnectionError, ErrorCode
try:
result = client.safe_ask(html, url, query)
except BlockedError as e:
# Content was blocked
print(f"Code: {e.code}") # ErrorCode.INJECTION_DETECTED
print(f"Risk: {e.risk_score}")
print(f"Request ID: {e.request_id}") # For audit lookup
except AuthenticationError:
print("Invalid API key")
except ConnectionError:
print("Cannot reach SafeBrowse API")
Error Codes
| Code | Description |
|---|---|
INJECTION_DETECTED |
Prompt injection found |
INJECTION_HIDDEN_HTML |
Hidden malicious content |
POLICY_LOGIN_FORM |
Login form detected |
POLICY_BLOCKED_DOMAIN |
Domain is blocklisted |
AUTH_INVALID_KEY |
Invalid API key |
CONN_REFUSED |
Connection refused |
Async Support
from safebrowse import AsyncSafeBrowseClient
async with AsyncSafeBrowseClient(api_key="your-key") as client:
result = await client.scan_html(html, url)
if result.is_safe:
await process(html)
This is by design. Security cannot be optional.
Enterprise Features
Audit & Statistics
# Get safety stats for the last 24 hours
stats = client.get_audit_stats(hours=24)
print(f"Blocked: {stats.blocked_requests}")
print(f"Top domains: {stats.top_blocked_domains}")
# Get paginated audit logs
logs = client.get_audit_logs(limit=50, status="blocked")
for entry in logs.logs:
print(f"{entry.timestamp}: {entry.url} - {entry.risk_score}")
Document Scanning (PDF/OCR)
# Scan a PDF for prompt injection
result = client.scan_pdf("sensitive_doc.pdf")
# Scan an image (automated OCR)
result = client.scan_image("screenshot.png")
if not result.is_safe:
print(f"Blocked: {result.reason}")
print(f"Extracted text: {result.extracted_text}")
Red Team Testing
# List available attack scenarios
scenarios = client.list_attack_scenarios()
# Run a red-team simulation against the current ruleset
summary = client.run_red_team_test()
print(f"Detection Rate: {summary.detection_rate * 100}%")
Agent Guard Sessions
# Manage stateful agent sessions
session_id = client.start_agent_session(max_steps=50)
# Record agent actions
client.record_agent_step(session_id, "browsing", "visit_bank_site")
# End session
client.end_agent_session(session_id)
API Reference
Classes
| Class | Description |
|---|---|
SafeBrowseClient |
Sync HTTP client |
AsyncSafeBrowseClient |
Async HTTP client |
SafeBrowseConfig |
Configuration object |
ScanResult |
Result of scan_html() |
AskResult |
Result of safe_ask() |
SanitizeResult |
Result of sanitize() |
BatchScanResult |
Result of scan_batch() |
Exceptions
| Exception | Description |
|---|---|
SafeBrowseError |
Base exception |
BlockedError |
Content was blocked |
AuthenticationError |
Invalid API key |
ConnectionError |
Network error |
Requirements
- Python 3.10+
httpx(installed automatically)
License
MIT License - see LICENSE for details.
Links
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
safebrowse-0.3.1.tar.gz
(20.2 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file safebrowse-0.3.1.tar.gz.
File metadata
- Download URL: safebrowse-0.3.1.tar.gz
- Upload date:
- Size: 20.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4c011e2eae8142aeb4e0a0572a93bc624eff5108b05bb1708f5e4ae70effb1c5
|
|
| MD5 |
37c0769f59ad3c4551810dcc3e1c09d0
|
|
| BLAKE2b-256 |
37169a45b553af414db1b482ea9ef3a28d939da1ad02432fd7a14fc127d78825
|
File details
Details for the file safebrowse-0.3.1-py3-none-any.whl.
File metadata
- Download URL: safebrowse-0.3.1-py3-none-any.whl
- Upload date:
- Size: 14.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
af9a79574132356bddf583a326318cdbfaba8a6c4831897739ea54196b8afe64
|
|
| MD5 |
59ef42a9a31bd7bdfa512748892a956c
|
|
| BLAKE2b-256 |
08d798beae6616103f8ca3a0b673e0856a1b78560f846a1ae0ea64f816fe0254
|
