DeepTraQ Chrome Extension — User Guide

Overview

The DeepTraQ Chrome Extension lets you record real browser sessions as HAR (HTTP Archive) files and automatically upload them to Cloudflare R2. These recordings become authenticated, real-traffic inputs for the DeepTraQ web security scanner — replacing synthetic crawls with actual user flows.

---

Prerequisites

• Google Chrome (v110+)
• A DeepTraQ account with access to the target project
• The target domain must already have a project registered in DeepTraQ (a scan must have been run at least once)
• Your email address must be listed under the project's authorized emails

---

1. Install the Chrome Extension

From the Chrome Web Store (when published)

1. Visit the DeepTraQ listing in the Chrome Web Store.
2. Click Add to Chrome → Add Extension.
3. The DeepTraQ icon appears in your toolbar.

Manual / Developer Install

1. Download the extension package (.zip) from your DeepTraQ dashboard.
2. Unzip it to a local folder.
3. Open Chrome and go to chrome://extensions.
4. Enable Developer mode (toggle, top-right).
5. Click Load unpacked and select the unzipped folder.
6. Pin the DeepTraQ icon from the extensions menu.

---

2. Authenticate the Extension

Authentication is scoped to a single project and uses a short-lived OTP so no password is ever stored.

Step 1 — Request an OTP

Open the extension popup and fill in:

Field	Example
Organization ID	org_abc123
Email	you@company.com
Target Domain	https://app.example.com

Click Send Code.

What happens under the hood:

• The extension calls POST /api/extension/auth with your org ID, email, and domain.
• The backend strips the domain to its hostname (e.g. app.example.com), looks up the matching project, and verifies your email is authorized.
• A 6-digit OTP is generated, hashed, and stored in MongoDB (otp_sessions) with a 10-minute expiry.
• The OTP is emailed to you from DeepTraQ.

Step 2 — Enter the OTP

Check your inbox for an email with subject "Your DeepTraQ verification code".

Enter the 6-digit code in the extension popup and click Verify.

Security limits:

• OTP expires in 10 minutes.
• Maximum 5 attempts before the session is locked (request a new OTP).
• The OTP is deleted from the database immediately after a successful verify.

What happens under the hood:

• The extension calls POST /api/extension/verify-otp.
• On success, a JWT (valid for 2 hours, type extension_session) is issued and stored locally in the extension. It encodes your organization_id, project_id, and email.

---

3. Record a Session

Once authenticated, the extension is ready to record.

1. Navigate to the target site in Chrome.
2. Click the DeepTraQ icon → Start Recording.
3. Browse the application normally — log in, use features, submit forms.
4. Click Stop Recording when done.

The extension captures all network requests as a HAR file during this session.

Session Identity

Each recording session has a unique Session ID (UUID) generated by the extension. All HAR chunks from one recording share the same Session ID — this is how the backend groups multi-chunk uploads into a single coherent session.

---

4. How Recorded Data is Saved to Cloudflare R2

The extension uploads the recorded HAR data in chunks as you browse (or on stop). Each chunk upload follows this flow:

Upload Request

POST /api/extension/upload-har
Authorization: Bearer <JWT>
X-Session-Id: <session-uuid>
Body: raw HAR binary stream

What Happens Server-Side

1. JWT is verified — confirms the token is a valid extension_session.
2. R2 storage path is computed:

   har/<organization_id>/<project_id>/<session_id>/chunk_<timestamp>.har

   Example:

   har/org_abc123/proj_xyz/550e8400-e29b-41d4-a716/chunk_2026-05-27T10-30-00-000Z.har

3. A pre-signed PUT URL (5-minute expiry) is generated for that R2 path.
4. MongoDB har_sessions is upserted — tracking:
   • project_id, organization_id
   • r2_prefix (the folder path)
   • chunk_name and signedUrl for the latest chunk
   • last_accessed_at timestamp
   • num_chunks (incremented per upload)
   • created_at (set only on first insert)
5. The signed URL is returned to the extension, which streams the HAR chunk directly to R2 — no HAR data passes through the Worker server memory.

R2 Folder Layout

har/
└── <org_id>/
    └── <project_id>/
        └── <session_id>/
            ├── chunk_2026-05-27T10-30-00-000Z.har
            ├── chunk_2026-05-27T10-31-15-123Z.har
            └── chunk_2026-05-27T10-33-42-456Z.har

All chunks from one recording session live under the same prefix and are later merged by the scanner.

---

5. Using HAR Sessions as Web Scanner Input

Once a session is recorded and stored in R2, it can drive the DeepTraQ web security scanner instead of (or alongside) a synthetic crawl.

Why HAR-Based Scanning?

Synthetic Crawl	HAR-Based Scan
Discovers only publicly visible pages	Covers authenticated, post-login flows
May miss complex JS-rendered interactions	Replays exact real-user traffic
No session/cookie context	Uses the real auth tokens from recording

Triggering a Scan from a HAR Session

From the DeepTraQ dashboard:

1. Go to your project → Sessions tab.
2. Locate the recorded session (identified by Session ID and timestamp).
3. Click Run Scan from Session.

Or via CLI / API:

node web-scanner.local.js zap-auth \
  --target https://app.example.com \
  --har-session <session_id> \
  --api-key <X_CFIX_API_KEY>

What the Scanner Does with the HAR

1. Reads all chunk_*.har files from har/<org_id>/<project_id>/<session_id>/ in R2.
2. Merges chunks into a unified request list.
3. Feeds each recorded request through the active scan rules (SQLi, XSS, IDOR, auth bypass, etc.).
4. Reports findings with the original request context (headers, cookies, body) preserved.

---

6. Token Lifecycle & Re-Authentication

Event	Action
Token valid (< 2 hours)	Extension uploads silently
Token expired	Extension shows "Session expired — re-authenticate"
Wrong email / unauthorized	Auth request returns 401
OTP expired (> 10 min)	Request a new OTP
Too many wrong OTP attempts	Request a new OTP

You can verify a stored token without re-entering credentials:

GET /api/extension/verify-token
Authorization: Bearer <JWT>

Returns 200 OK if valid, 401 if expired or tampered.

---

7. Troubleshooting

Problem	Likely Cause	Fix
"No project registered for this domain"	Project not yet created in DeepTraQ	Run an initial scan from the dashboard first
"Email not authorized for this project"	Email not in project's emailIds list	Ask your admin to add the email to the project
OTP email not received	Spam filter or wrong email entered	Check spam; re-request OTP with correct email
Upload fails mid-session	Signed URL expired (> 5 min since issued)	The extension will request a fresh signed URL automatically on retry
"Invalid token type" on upload	Using a dashboard JWT, not an extension JWT	Re-authenticate via the extension popup

---

8. Security Notes

• OTPs are never stored in plain text — only a SHA-256 hash is persisted.
• JWTs are scoped — each token is tied to a specific organization_id, project_id, and email; it cannot access other projects.
• HAR data goes directly to R2 — the Worker acts only as a signed-URL broker; raw traffic bytes never touch server memory.
• Signed URLs expire in 5 minutes — a leaked URL cannot be used to overwrite R2 objects after that window.