|
| 1 | +# V8Log Forensics |
| 2 | + |
| 3 | +> Use V8Log only for authorized privacy validation sessions. |
| 4 | +
|
| 5 | +--- |
| 6 | + |
| 7 | +<a id="overview"></a> |
| 8 | +## Overview |
| 9 | + |
| 10 | +V8Log is a gated, privacy-focused browser-runtime forensics mode that records calls into local JSONL files. It is intended for short, controlled validation sessions where teams need evidence of how page scripts collect browser signals. |
| 11 | + |
| 12 | +This is useful when source review is incomplete because a page uses packed JavaScript, VM-style bundles, or WebAssembly. V8Log records the runtime call sequence, arguments, return previews, frame context, and event order so the collection behavior can be reviewed directly. |
| 13 | + |
| 14 | +V8Log does not change normal browsing behavior when disabled. Release use is gated by profile entitlement and build policy. |
| 15 | + |
| 16 | +For background on browser fingerprinting as a privacy issue, see [Fingerprint Privacy](../../../FINGERPRINT_PRIVACY.md). |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +<a id="quick-start"></a> |
| 21 | +## Quick Start |
| 22 | + |
| 23 | +Create a writable directory and launch BotBrowser with V8Log enabled: |
| 24 | + |
| 25 | +```bash |
| 26 | +mkdir -p /tmp/botbrowser-v8log |
| 27 | + |
| 28 | +chromium-browser \ |
| 29 | + --bot-profile="/path/to/profile.enc" \ |
| 30 | + --bot-v8-log=sample \ |
| 31 | + --bot-v8-log-dir=/tmp/botbrowser-v8log \ |
| 32 | + --user-data-dir="$(mktemp -d)" \ |
| 33 | + "https://example.com" |
| 34 | +``` |
| 35 | + |
| 36 | +For deeper validation review, use `full` only when requested: |
| 37 | + |
| 38 | +```bash |
| 39 | +--bot-v8-log=full |
| 40 | +--bot-v8-log-dir=/tmp/botbrowser-v8log |
| 41 | +``` |
| 42 | + |
| 43 | +Disable V8Log explicitly with: |
| 44 | + |
| 45 | +```bash |
| 46 | +--bot-v8-log=none |
| 47 | +``` |
| 48 | + |
| 49 | +--- |
| 50 | + |
| 51 | +<a id="modes"></a> |
| 52 | +## Modes |
| 53 | + |
| 54 | +| Mode | Use | |
| 55 | +|------|-----| |
| 56 | +| `none` | V8Log disabled. This is the normal default. | |
| 57 | +| `sample` | Reduced evidence trace for most validation reproductions. | |
| 58 | +| `full` | Fuller evidence trace for short, guided reproductions. | |
| 59 | + |
| 60 | +Use the shortest page flow that reproduces the behavior. Evidence files can grow quickly on complex pages. |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +<a id="sample-jsonl"></a> |
| 65 | +## Sample JSONL |
| 66 | + |
| 67 | +An interactive sample is available in the [V8Log Viewer](https://botswin.github.io/BotBrowser/tools/v8log/v8log_viewer.html?jsonl=https://botswin.github.io/BotBrowser/tools/v8log/fonts_v8log_sample.jsonl). |
| 68 | + |
| 69 | +The viewer is preloaded with a short public-page capture. It shows how V8Log connects call expressions, arguments, return previews, frame context, API group, and event order. |
| 70 | + |
| 71 | +--- |
| 72 | + |
| 73 | +<a id="playwright"></a> |
| 74 | +## Playwright Example |
| 75 | + |
| 76 | +```javascript |
| 77 | +import { chromium } from "playwright-core"; |
| 78 | + |
| 79 | +const browser = await chromium.launch({ |
| 80 | + executablePath: process.env.BOTBROWSER_EXEC_PATH, |
| 81 | + headless: true, |
| 82 | + args: [ |
| 83 | + `--bot-profile=${process.env.BOT_PROFILE_PATH}`, |
| 84 | + "--bot-v8-log=sample", |
| 85 | + "--bot-v8-log-dir=/tmp/botbrowser-v8log", |
| 86 | + ], |
| 87 | +}); |
| 88 | + |
| 89 | +const page = await browser.newPage(); |
| 90 | +await page.goto("https://example.com"); |
| 91 | +await page.waitForTimeout(5000); |
| 92 | +await browser.close(); |
| 93 | +``` |
| 94 | + |
| 95 | +--- |
| 96 | + |
| 97 | +<a id="troubleshooting"></a> |
| 98 | +## Troubleshooting |
| 99 | + |
| 100 | +| Problem | Solution | |
| 101 | +|---------|----------| |
| 102 | +| No files are written | Confirm `--bot-v8-log` is not `none`, the directory exists, and the browser process can write to it. | |
| 103 | +| Files are too large | Use `sample`, shorten the reproduction, and close the browser immediately after the target behavior appears. | |
| 104 | +| V8Log does not start in release | Confirm the profile and subscription include V8Log support. | |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## Related Documentation |
| 109 | + |
| 110 | +- [CLI Flags Reference](../../../CLI_FLAGS.md#--bot-v8-log) |
| 111 | +- [V8Log Tool](../../../tools/v8log/) |
| 112 | +- [Automation Consistency Practices](AUTOMATION_CONSISTENCY.md) |
| 113 | +- [Profile Management](PROFILE_MANAGEMENT.md) |
| 114 | + |
| 115 | +--- |
| 116 | + |
| 117 | +**[Legal Disclaimer & Terms of Use](https://github.com/botswin/BotBrowser/blob/main/DISCLAIMER.md) • [Responsible Use Guidelines](https://github.com/botswin/BotBrowser/blob/main/RESPONSIBLE_USE.md)**. BotBrowser is for authorized fingerprint protection and privacy research only. |
0 commit comments