If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/h4ckf0r0day/obscura shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 12 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live h4ckf0r0day/obscura repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/h4ckf0r0day/obscura.

What it runs against: a local clone of h4ckf0r0day/obscura — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in h4ckf0r0day/obscura | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of h4ckf0r0day/obscura. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/h4ckf0r0day/obscura.git
#   cd obscura
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of h4ckf0r0day/obscura and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "h4ckf0r0day/obscura(\\.git)?\\b" \\
  && ok "origin remote is h4ckf0r0day/obscura" \\
  || miss "origin remote is not h4ckf0r0day/obscura (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/obscura-browser/src/lib.rs" \\
  && ok "crates/obscura-browser/src/lib.rs" \\
  || miss "missing critical file: crates/obscura-browser/src/lib.rs"
test -f "crates/obscura-cdp/src/lib.rs" \\
  && ok "crates/obscura-cdp/src/lib.rs" \\
  || miss "missing critical file: crates/obscura-cdp/src/lib.rs"
test -f "crates/obscura-js/src/runtime.rs" \\
  && ok "crates/obscura-js/src/runtime.rs" \\
  || miss "missing critical file: crates/obscura-js/src/runtime.rs"
test -f "crates/obscura-net/src/client.rs" \\
  && ok "crates/obscura-net/src/client.rs" \\
  || miss "missing critical file: crates/obscura-net/src/client.rs"
test -f "crates/obscura-dom/src/tree.rs" \\
  && ok "crates/obscura-dom/src/tree.rs" \\
  || miss "missing critical file: crates/obscura-dom/src/tree.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/h4ckf0r0day/obscura"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Obscura is a headless browser engine written in Rust that executes real JavaScript via V8 and speaks the Chrome DevTools Protocol (CDP). It's designed as a lightweight, fast alternative to headless Chrome for web scraping and AI agent automation, consuming 30 MB RAM vs. 200+ MB for Chrome, with built-in anti-detection capabilities. Rust workspace monorepo with five core crates: obscura-cdp implements Chrome DevTools Protocol domains (network, page, runtime, etc.), obscura-browser manages page lifecycle and context, obscura-dom handles HTML parsing and CSS selectors via html5ever, obscura-js wraps V8 JavaScript execution, and obscura-cli provides the command-line interface (fetch, scrape commands).

Web scrapers, AI agent developers, and automation engineers who need to run JavaScript-heavy websites at scale without the memory and startup overhead of headless Chrome; users of Puppeteer or Playwright who want a drop-in replacement with better resource efficiency.

Actively developed and feature-complete enough for production use: supports both Puppeteer and Playwright APIs, ships release binaries for Linux/macOS/Windows, and has foundational CI/CD (release.yml workflow). The project is gaining traction (10k stars mentioned in README) but is maintained by a single author with upcoming hosted cloud offering planned.

Single-maintainer risk is the primary concern; the repo shows active development but depends heavily on V8 compilation (5-minute first build), which could break on future Rust/V8 version changes. No visible extensive test suite in the file structure (tests/ directory not listed), and the stealth mode feature is behind a compile-time flag, suggesting incomplete hardening.

Active development toward a hosted cloud version (Obscura Cloud waitlist in README); the codebase is stable with release automation in place. The main thrust appears to be stabilizing the open-source engine as a feature-complete alternative to headless Chrome while building commercial infrastructure around it.

git clone https://github.com/h4ckf0r0day/obscura.git
cd obscura
cargo build --release
# First build ~5 min due to V8 compilation
./target/release/obscura fetch https://example.com --eval "document.title"

Daily commands: Development: cargo build (debug) or cargo build --release (optimized). CLI usage: ./obscura fetch <url> for single-page scraping, ./obscura scrape <url> for parallel jobs (requires both obscura and obscura-worker binaries in same directory). With stealth mode: cargo build --release --features stealth.

• crates/obscura-browser/src/lib.rs — Main browser API entry point; defines core Browser and Page types that all other modules depend on.
• crates/obscura-cdp/src/lib.rs — Chrome DevTools Protocol server implementation; handles all Puppeteer/Playwright communication.
• crates/obscura-js/src/runtime.rs — V8 JavaScript runtime integration; executes user scripts and provides JS bindings to browser APIs.
• crates/obscura-net/src/client.rs — HTTP client with cookie management, blocklisting, and anti-detect features; handles all network I/O.
• crates/obscura-dom/src/tree.rs — DOM tree representation and traversal; parses HTML and provides CSS selector matching for queries.
• crates/obscura-cli/src/main.rs — CLI entry point and worker orchestration; demonstrates how to spawn and manage browser instances.
• Cargo.toml — Workspace configuration defining all six crates and their interdependencies.

Add a new CDP domain command

1. Create a new domain module in crates/obscura-cdp/src/domains/ (e.g., new_feature.rs) with a struct implementing the command handler. (crates/obscura-cdp/src/domains/new_feature.rs)
2. Register the domain in the mod.rs file and add it to the dispatch router. (crates/obscura-cdp/src/domains/mod.rs)
3. Define request/response types in crates/obscura-cdp/src/types.rs and implement serialization. (crates/obscura-cdp/src/types.rs)
4. Add dispatcher logic in dispatch.rs to route messages to your new domain. (crates/obscura-cdp/src/dispatch.rs)

Add a new JavaScript native operation

1. Define the operation signature in crates/obscura-js/src/ops.rs as a V8 callback function. (crates/obscura-js/src/ops.rs)
2. Implement the operation logic, converting V8 values to/from Rust types. (crates/obscura-js/src/ops.rs)
3. Register the operation in the global scope during runtime initialization in runtime.rs. (crates/obscura-js/src/runtime.rs)
4. Test by invoking the operation from user scripts via page.evaluate(). (crates/obscura-browser/src/page.rs)

Add request interception/blocking logic

1. Extend the blocklist or add custom filtering logic in crates/obscura-net/src/blocklist.rs. (crates/obscura-net/src/blocklist.rs)
2. Implement the filter as a predicate function in crates/obscura-net/src/interceptor.rs and integrate with the request pipeline. (crates/obscura-net/src/interceptor.rs)
3. Expose the interception handler via CDP in a Network domain command (e.g., setRequestInterception). (crates/obscura-cdp/src/domains/network.rs)
4. Allow users to call the handler from Page API or CDP protocol. (crates/obscura-browser/src/page.rs)

Add a new DOM selector or query method

1. Extend CSS selector support or add custom selectors in crates/obscura-dom/src/selector.rs. (crates/obscura-dom/src/selector.rs)
2. Implement the traversal logic in crates/obscura-dom/src/tree.rs (e.g., query_selector, query_all). (crates/obscura-dom/src/tree.rs)
3. Expose the new method via JavaScript bindings in crates/obscura-js/src/ops.rs. (crates/obscura-js/src/ops.rs)
4. Wire it into the Page API in crates/obscura-browser/src/page.rs for Rust callers. (crates/obscura-browser/src/page.rs)

• Rust + Tokio — Systems language with async runtime enables low-memory (30MB vs 200MB Chrome), fast startup, and parallel browser instance management at scale.
• V8 via rusty_v8 — Real JavaScript engine ensures DOM APIs and user scripts work identically to Chrome; critical for AI agent and scraping compatibility.
• html5ever + selectors — Servo-compatible HTML parsing and CSS selector matching without shipping a full rendering engine; keeps binary small (70MB vs 300MB).
• Chrome DevTools Protocol — Wire protocol allows Puppeteer/Playwright to control Obscura as a drop-in Chrome replacement; maximizes tool ecosystem compatibility.
• Tokio-tungstenite — WebSocket library for CDP server; enables async bidirectional communication with clients.
• reqwest — Async HTTP client with cookie jar and customizable middleware; integrates anti-detect (user agents, header spoofing, blocklists).

• No full rendering engine (Chromium/Gecko)

  • Why: Reduces binary size (70MB vs 300MB) and memory (30MB vs 200MB); fits AI agent containerization and serverless constraints.
  • Consequence: No visual layout or paint operations; suitable for scraping and JS execution but not pixel-perfect visual testing.

• Single V8 instance per browser, no process isolation

  • Why: undefined
  • Consequence: undefined

V8 compilation from source on first build takes ~5 minutes and requires a C++ compiler toolchain (not documented explicitly but implied by V8 build process). The obscura-worker binary must be in the same directory as obscura for the scrape command to function (stated in README but easy to miss). Stealth mode is gated behind --features stealth at compile time, not runtime, so you must rebuild to enable/disable it. CDP server listens on localhost by default with no explicit configuration docs visible; check obscura-cdp/src/server.rs for binding address.

• Chrome DevTools Protocol (CDP) — Obscura's entire remote control interface is built on CDP; understanding domain structure (Page, Network, Runtime, etc.) is essential for any feature work
• V8 Engine Embedding — Obscura delegates all JavaScript execution to V8 via FFI bindings; knowledge of V8's isolate/context/scope model is needed for extending JS capabilities
• WebSocket Protocol (for CDP transport) — CDP messages flow over WebSocket (via tokio-tungstenite); understanding frame multiplexing and async message handling is critical for CDP server debugging
• DOM Tree Representation (html5ever) — Obscura uses html5ever's tree model for DOM parsing and CSS selector evaluation; the tree structure and node types directly affect selector performance
• Async/await with Tokio — All I/O in Obscura (HTTP, WebSocket, filesystem) is async-first via Tokio; you cannot use blocking calls in the main browser loop
• CSS Selector Parsing (selectors crate) — Obscura implements document.querySelector and DOM traversal via the selectors crate; understanding selector compilation and matching is needed for query optimization
• Memory-mapped I/O and resource pooling — Obscura's low 30 MB memory footprint relies on careful pooling of HTTP clients, browser contexts, and V8 isolates; leaks in any layer will break resource guarantees

• puppeteer/puppeteer — Obscura implements the Puppeteer protocol compatibility; understanding Puppeteer's CDP expectations is essential for validating Obscura's domain implementations
• microsoft/playwright — Obscura supports Playwright automation; Playwright's protocol handling patterns inform compatibility requirements
• GoogleChrome/devtools-protocol — Official Chrome DevTools Protocol schema and documentation; the source of truth for all CDP domain specifications Obscura implements
• rustwasm/wasm-bindgen — Similar Rust FFI patterns for JS engine integration; relevant for understanding Obscura's V8 bindings architecture
• denoland/deno — Deno also embeds V8 in Rust; architectural patterns for async JS execution and permission models are comparable

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for obscura-dom tree parsing and selector evaluation

The obscura-dom crate (crates/obscura-dom/src) handles critical DOM tree construction and CSS selector evaluation, but there are no visible test files. This is a core dependency for web scraping. Adding unit tests for tree.rs, selector.rs, and serialize.rs would ensure correctness of DOM traversal, serialization, and CSS selector matching—especially important since the crate wraps html5ever and selectors libraries.

• [ ] Create crates/obscura-dom/tests/test_tree.rs to test tree building from HTML with various nesting levels and edge cases
• [ ] Create crates/obscura-dom/tests/test_selector.rs to verify CSS selector evaluation (pseudo-classes, combinators, attribute selectors) matches expected nodes
• [ ] Add integration test in crates/obscura-dom/tests/test_serialize.rs to validate HTML serialization round-trip integrity
• [ ] Ensure tests cover malformed HTML and deeply nested structures since these are common in real-world scraping scenarios

Add integration tests for obscura-cdp domain implementations with mock protocol messages

The obscura-cdp crate implements 9 CDP domains (accessibility, browser, dom, fetch, input, lp, network, page, runtime, storage, target) in crates/obscura-cdp/src/domains/, but there's no evidence of tests validating that dispatched CDP protocol messages are correctly handled. Adding tests would ensure the headless browser correctly responds to Puppeteer/Playwright SDK calls.

• [ ] Create crates/obscura-cdp/tests/test_dispatch.rs with mock WebSocket messages testing dispatch.rs routing logic for various domain methods
• [ ] Create crates/obscura-cdp/tests/test_page_domain.rs validating page navigation, screenshot, and evaluate methods return correct protocol responses
• [ ] Create crates/obscura-cdp/tests/test_network_domain.rs testing request interception and response mocking (critical for anti-detect advertised feature)
• [ ] Verify error handling for malformed CDP messages and missing required parameters

Add CI workflow for cross-platform binary builds and publish release artifacts

The repo has .github/workflows/release.yml but the file structure suggests it may be incomplete or missing platform-specific builds. As a headless browser replacement for Chrome, users need precompiled binaries for Linux, macOS, and Windows. This PR would add a robust release workflow that builds and publishes artifacts, making the project accessible to non-Rust users.

• [ ] Extend or create .github/workflows/release.yml with matrix strategy for ubuntu-latest, macos-latest, and windows-latest
• [ ] Add build steps for obscura-cli (the binary entrypoint) using cargo build --release with platform-specific optimizations
• [ ] Configure artifact upload to GitHub Releases with proper naming (obscura-cli-{os}-{arch})
• [ ] Add a step to generate and publish obscura-cdp server binary as a standalone service for non-CLI users (Puppeteer integration)

• Add integration tests for the Page domain methods in crates/obscura-cdp/src/domains/page.rs (navigate, evaluate, screenshot); currently no test files visible in the crate structure.
• Document the Chrome DevTools Protocol domain implementations with examples in a domains/README.md showing how to call each domain method via the CLI or Puppeteer API.
• Implement missing DOM selector edge cases: add tests and handling for :nth-child(), :not(), and attribute combinators in crates/obscura-dom/src/selector.rs.

• High · Outdated tokio-tungstenite Dependency — Cargo.toml - workspace.dependencies. tokio-tungstenite 0.26 has known security vulnerabilities (CVE-2024-24576). WebSocket implementations in this version may be susceptible to Denial of Service attacks through malformed frames. Fix: Update tokio-tungstenite to version 0.21.0 or higher where the vulnerability is patched
• High · Potential Command Injection in Browser Execution — crates/obscura-js/src/ops.rs, crates/obscura-js/js/bootstrap.js. The project implements a headless browser that executes JavaScript and interacts with web content. File structure shows JavaScript execution via V8 (obscura-js crate). Without proper sandboxing and input validation, arbitrary JavaScript execution could lead to command injection or RCE. Fix: Implement strict sandboxing for JavaScript execution, validate all user-provided scripts before execution, use V8 context isolation, and implement Content Security Policy-like restrictions
• High · Insecure Network Request Handling — crates/obscura-net/src/interceptor.rs, crates/obscura-net/src/client.rs. The browser can make arbitrary network requests (obscura-net crate with blocklist.rs and interceptor.rs). Without proper validation of URLs and request targets, this could enable SSRF (Server-Side Request Forgery) attacks to access internal network resources. Fix: Implement URL validation to block private IP ranges (127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), use allowlists for internal endpoints, and validate all request parameters
• Medium · Missing Security Headers Validation — crates/obscura-browser/src/page.rs. As a browser implementation used for web scraping and automation, there's no evidence of proper CORS, CSP, or X-Frame-Options validation/enforcement in the codebase structure. Fix: Implement validation and enforcement of security headers, implement proper CORS handling, validate X-Frame-Options, and enforce CSP policies
• Medium · Cookie Management Security — crates/obscura-net/src/cookies.rs. The obscura-net crate includes cookie handling (cookies.rs) but without visible implementation details, there's a risk of improper cookie validation, allowing cookie injection or manipulation attacks. Fix: Implement strict cookie validation, use secure and httpOnly flags, validate SameSite attributes, implement proper cookie isolation between contexts
• Medium · DOM Parsing from Untrusted Input — crates/obscura-dom/src/tree_sink.rs, crates/obscura-dom/src/serialize.rs. The obscura-dom crate parses HTML/DOM from web content without visible sanitization (tree.rs, tree_sink.rs). This could enable XSS-style attacks if the parsed DOM is used unsafely. Fix: Sanitize and validate all DOM content before processing, implement proper output encoding, use an HTML sanitizer library for untrusted content
• Medium · Runtime Module Loading Security — crates/obscura-js/src/module_loader.rs. The JavaScript runtime includes a custom module loader (module_loader.rs) which could be vulnerable to path traversal or unauthorized module loading if not properly restricted. Fix: Implement module path validation, use allowlists for permitted modules, prevent directory traversal attacks, validate file permissions
• Low · Dependency on native-tls-vendored — Cargo.toml - reqwest feature. Using native-tls-vendored for TLS adds complexity and maintenance burden. If OpenSSL version becomes vulnerable, updates require recompilation. Fix: Consider using rustls instead of native-tls-vendored for better maintainability and reduced attack surface
• Low · No Visible Input Validation Framework — undefined. The codebase structure doesn't show a comprehensive input validation or sanitization framework for user-provided data, configuration, and scripts. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.