ProdGuard Documentation

ProdGuard User Guide ​

What is ProdGuard? ​

ProdGuard is a Chrome extension that helps prevent accidental clicks on high-risk actions in web applications.

When a click matches a protected selector, ProdGuard intercepts it and asks for explicit confirmation before allowing the action.

Local-First Execution and Network Usage ​

ProdGuard runs locally on the user's machine.

What runs locally:

  • Click interception and security challenge logic
  • Environment rules and selector matching
  • Import/export processing
  • Local configuration storage in the browser extension storage

When internet is required:

  • License activation and deactivation
  • License validation checks

Operational implication:

  • Protection behavior continues to work without internet for already-configured environments.
  • Connectivity is only needed for license-related operations.

Why It Is Important for Any User Handling Critical Actions ​

In production environments, one accidental click can trigger destructive operations. ProdGuard adds a deliberate safety step so critical actions are less likely to be executed by mistake.

Key benefits:

  • Prevents accidental clicks on dangerous UI elements
  • Adds a confirmation challenge before proceeding
  • Supports environment-specific configuration
  • Works with built-in selectors out of the box
  • Supports advanced custom selector workflows for technical and operations teams

Getting Started ​

  1. Open the extension popup on the site you want to protect.
  2. Configure the environment settings in the Protection tab.
  3. Click Enable for this site.
  4. Keep the Master Switch enabled.
  5. Trigger a protected element to verify that the challenge appears.

Verify with the badge: Once enabled, the badge in the browser toolbar will dynamically update to show the number of protected elements found on the current page (for example 6 in cyan). This confirms ProdGuard is active and matching real elements on this site. The badge count will change as you navigate to different pages within your configured domain. See Understanding Dynamic Badges for details.

If you are using Premium features, validate your license in the Premium tab before configuring custom selectors and confirmation words.

Understanding Dynamic Badges ​

ProdGuard displays dynamic badges in the browser toolbar that reflect the real-time status of protection on the current site.

What the Badge Shows ​

The badge appears next to the ProdGuard icon in your browser toolbar and changes based on the Master Switch state, site configuration, and—when active—the actual number of protected elements found on the current page.

Badge States ​

StateBadge DisplayColorMeaning
ACTIVENumber (e.g., 5, 12)Cyan Bright (#208a99)Master ON, Site Protected — showing actual protected elements found on this page
INACTIVE_SITE− (minus)Orange Bright (#f6c85f)Site not configured or disabled
DISABLED✕ (X)Red Bright (#ff4a4a)Master Switch is OFF (global protection disabled)
DISABLED_FOR_SITE○ (circle)Orange Medium (#e5b567)This specific site is disabled

How the Counter Works ​

When ProdGuard is ACTIVE on the current site:

  • The badge displays the actual number of protected elements found on the current page.
  • This count updates dynamically every time you:
    • Switch to a different tab
    • Navigate to a different page within the same domain
    • Enable or disable a site
  • Hovering over the badge shows a tooltip with detailed information, for example: "ProdGuard: Active (Master ON, Site Protected) - 5 selector(s) active"

What This Means ​

The badge now shows what's actually being protected on THIS specific page, not just how many selectors you've configured.

Examples ​

  • Badge shows 3: Your current page has exactly 3 elements matching your configured selectors (for example, 3 delete buttons).
  • Badge shows 8: Your staging admin panel has 8 dangerous actions you're protected against (not all pages have the same count).
  • Badge shows 0: You're on a page that matches the configured domain, but no protected elements are present on this specific page.
  • Badge shows −: You haven't configured this site yet in ProdGuard.
  • Badge shows ✕: Master Switch is OFF globally—protection is disabled everywhere.

Using the Badge Information ​

The badge count helps you:

  • See real-time protection: At a glance, know exactly how many dangerous actions exist on the current page.
  • Identify varying risk levels: Some pages might have many protected actions (badge 12), others might have fewer (badge 2).
  • Verify protection is active: If the badge shows a number greater than 0, your selectors are matching real elements on this page.
  • Spot configuration issues: If you expect protected elements but the badge shows 0, your selectors might not match the page's actual HTML.

Color Semantics ​

  • Cyan (Active): Protection is working on this page, and elements are found.
  • Orange (Warning): This site is not protected or no elements match your selectors.
  • Red (Danger): Master protection is OFF; dangerous actions are not intercepted anywhere.
  • Orange (Disabled Site): This specific site has been temporarily turned off.

Toggling Protection ​

To change badge state:

  1. Turn OFF Master Switch: Badge becomes ✕ (red) everywhere.
  2. Disable this site: Badge becomes ○ (orange) only on this site.
  3. Enable this site: Badge becomes the count of protected elements found.
  4. Navigate to different pages: Badge updates automatically to reflect new element counts.

In the Popup ​

When you open the ProdGuard popup, the Protection tab shows:

  • Current site environment status
  • Master Switch toggle
  • List of configured selectors for this site

The badge count (shown in the browser toolbar) automatically updates to reflect the actual number of elements found matching your selectors on each page you visit.

Security Challenge and Confirmation Word ​

When ProdGuard detects a protected click, it blocks the click first and opens a security challenge.

Expected flow:

  1. User clicks a protected element.
  2. ProdGuard prevents the click.
  3. Challenge modal appears with the required confirmation word.
  4. User must type the exact word and confirm.
  5. If correct, ProdGuard replays the click.
  6. If canceled or incorrect, the action does not proceed.

Configuration:

  • In Premium mode, you can set a custom confirmation word in the Protection tab.
  • In Free mode, default values are used.

Free vs Premium ​

Free Mode ​

Free mode includes full click interception using the built-in default selectors. No license is required.

Available:

  • Master protection toggle
  • Site-level protection enable/disable
  • Environment list management
  • Full click interception with built-in selectors
  • Security challenge flow
  • Show Matches button (✨) to highlight matching elements on page
  • Import and export of JSON configuration

Default selector baseline:

css
.btn-danger,
[class*="danger" i],
[class*="delete" i],
[aria-label*="delete" i],
[data-testid*="delete" i],
button[type="submit"]

How this baseline is used:

  • Free mode: always uses the default selector baseline. Custom selectors are preserved in storage but not used for interception.
  • Premium mode: uses custom selectors when configured; otherwise falls back to this default baseline.

Restricted in Free mode:

  • Custom badge text is locked to default
  • Custom confirmation word is locked to default
  • Custom selector input is disabled (custom selectors are stored but not active)
  • Picker Tool is disabled

Premium Mode ​

Premium mode is unlocked by validating a License Key in the Premium tab.

Available in Premium:

  • Custom badge text
  • Custom confirmation word
  • Custom CSS selectors (full add/remove/edit)
  • Picker Tool for visual selector capture
  • Show Matches button (✨) reflects custom active selectors
  • License activation/deactivation in-app

Downgrading from Premium

If your license expires or is deactivated, ProdGuard automatically reverts to the default selector baseline. Your custom selectors remain saved in storage and will be restored the next time you activate a valid license. Configuration exports always include your custom selectors regardless of license status.

Feature Availability (Free vs Premium) ​

FeatureFreePremiumNotes
Master protection toggleAvailableAvailableGlobal protection control
Site-level enable/disableAvailableAvailablePer-site protection state
Click interceptionAvailableAvailableUses default selectors (Free) or custom selectors (Premium)
Built-in default selectorsAvailableAvailableAlways active in Free; fallback in Premium if no custom set
Show Matches (✨)AvailableAvailableHighlights matching elements on current page
Import/Export JSONAvailableAvailableExport always includes custom selectors regardless of tier
Custom badge textNot availableAvailableEditable in Protection tab
Custom confirmation wordNot availableAvailableRequired for security challenge
Custom CSS selectorsNot availableAvailableAdd, edit or remove selectors; stored even when downgraded
Picker Tool (🎯)Not availableAvailableVisual selector capture from active page
License activate/deactivateNot availableAvailableManaged from Premium tab

Using the Picker Tool ​

The Picker Tool (🎯) lets you click any element on the page directly and save the generated CSS selector to your configuration.

How to use it:

  1. Open ProdGuard popup.
  2. Go to the Protection tab.
  3. Click the 🎯 button near CSS Selectors to Guard.
  4. The popup closes and picker mode starts on the active tab.
  5. Hover to see elements highlighted with a red dashed outline.
  6. Click the target element — a confirmation dialog appears showing the generated selector.
  7. Click OK to save it, or Cancel to discard.

Notes:

  • Picker mode is available only when Premium is active.
  • The current site must already be enabled/configured in ProdGuard.
  • Browser internal pages (for example chrome://) are not supported.
  • The generated selector is CSS-escaped automatically to ensure validity.

Using Show Matches ​

The Show Matches button (✨) highlights all elements on the current page that match your active selectors, so you can verify what ProdGuard is protecting at a glance.

How to use it:

  1. Open ProdGuard popup.
  2. Go to the Protection tab.
  3. Click the ✨ button near CSS Selectors to Guard.
  4. If matches are found, the popup closes and matched elements flash with a green outline on the page.
  5. If no elements match, a "No Matches" notification appears in the popup.

What it shows:

  • Free mode: highlights elements matching the default selector baseline.
  • Premium mode: highlights elements matching your custom configured selectors.

Useful for:

  • Verifying that your selectors target the right elements before relying on interception.
  • Spot-checking a new page to understand its risk exposure.
  • Diagnosing why the badge counter shows an unexpected value.

Import and Export Configuration ​

ProdGuard supports configuration portability through JSON files from the Site List tab.

What Export Includes ​

Export creates a JSON file with:

  • source: fixed value ProdGuard
  • version: export schema version
  • exportDate: ISO timestamp
  • environments: full list of saved site environments

Important:

  • License information is not included in exported files.
  • Master switch state is not included in exported files.
  • Export focuses on environment rules and selectors.

Export Steps ​

  1. Open the extension popup.
  2. Go to Site List.
  3. Click Export JSON.
  4. Save the generated file (for example prodguard-config-YYYY-MM-DD.json).

Import Steps ​

  1. Open the extension popup.
  2. Go to Site List.
  3. Click Import JSON.
  4. Select a previously exported ProdGuard file.
  5. Wait for the success message with imported and total counts.

When moving from one computer to another, treat migration as a two-part process: license transfer and configuration transfer.

Migration Checklist ​

Use this checklist to perform a safe device migration:

  • [ ] Export JSON from the old device.
  • [ ] Store the export file in a secure location.
  • [ ] Deactivate license on the old device.
  • [ ] Install ProdGuard on the new device.
  • [ ] Activate the same license on the new device.
  • [ ] Import JSON on the new device.
  • [ ] Verify protected environments are present.
  • [ ] Verify critical selectors are still matching target elements.
  • [ ] Run one end-to-end security challenge test on a protected action.

Recommended sequence:

  1. On the old device, open Site List and run Export JSON.
  2. Save the exported file in a safe location.
  3. On the old device, open Premium tab and run license deactivation.
  4. Install ProdGuard on the new device.
  5. On the new device, activate the same license key.
  6. Open Site List on the new device and run Import JSON.
  7. Verify critical environments and selectors before using in production.

Why this order matters:

  • Deactivating first helps avoid activation-limit conflicts.
  • Export/import preserves your environment rules and selectors.
  • Validation after import reduces risk of incomplete migration.

If you no longer have access to the old device, you can still activate and rebuild configuration manually, but this is slower and error-prone compared with export/import.

Import Validation and Merge Behavior ​

During import, ProdGuard validates file origin using the source field:

  • If source is not ProdGuard, import is rejected.
  • If valid, environments are merged by urlPattern.

Merge strategy:

  • Existing environment with same urlPattern: replaced with imported value.
  • New urlPattern: added as a new environment.
  • Non-overlapping existing environments remain unchanged.

Minimal Example File ​

json
{
  "source": "ProdGuard",
  "version": "1.0",
  "exportDate": "2026-04-16T14:20:00.000Z",
  "environments": [
    {
      "urlPattern": "app.example.com",
      "tabIcon": "🔴",
      "indicatorType": "ribbon",
      "indicatorColor": "#ff4a4a",
      "indicatorText": "PROD",
      "siteEnabled": true,
      "confirmWord": "PROD",
      "selectors": ".btn-danger, [data-testid*=\"delete\" i]"
    }
  ]
}
  • Keep one baseline export in version control for team reference.
  • Re-export after major selector updates.
  • Import into staging profile first, then production profile.
  • Avoid manual edits unless you validate JSON syntax carefully.

Troubleshooting ​

  1. Refresh the page and try again.
  2. Verify Master Switch is ON.
  3. Verify the site is enabled in ProdGuard.
  4. Confirm the clicked element matches a protected selector.
  5. Avoid browser internal pages like chrome:// where content scripts do not run.

Picker Tool does not start ​

  1. Confirm Premium is active.
  2. Refresh the target page and retry.
  3. Ensure the site is configured in ProdGuard first.
  4. Do not run picker on browser system pages.

Show Matches (✨) shows "No Matches" on a page I expect to have protected elements ​

  1. Verify the site is active (Master Switch ON, site enabled).
  2. If you are in Free mode, the active selectors are the defaults — check if the page has any matching elements.
  3. If you are in Premium mode, review your custom selectors and confirm they target the visible HTML structure on this specific page.
  4. Use browser DevTools to manually test the selector in the console: document.querySelectorAll('YOUR_SELECTOR').
  5. Use the Picker Tool (Premium) to capture a fresh selector from the exact element.

Selector was saved but action is not intercepted ​

  1. Inspect the target element and verify selector accuracy.
  2. Simplify overly specific selectors.
  3. Re-run Picker Tool and confirm the new selector.
  4. Check the badge on the toolbar: if it shows 0, your selectors don't match any elements on this page.

Badge shows 0 when I expected protected elements ​

  1. Your site is configured and enabled (otherwise badge would show − or ○).
  2. But no elements on the current page match your configured selectors.
  3. This is normal if the page layout is different from where you defined the selectors.

To fix:

  • Use browser DevTools Inspector to examine the actual HTML structure of the dangerous element.
  • Confirm your CSS selector matches the real element attributes.
  • Re-run Picker Tool to generate a new selector from this page's element.
  • Test again on this page—the badge should update to show the count.

License validation issues ​

ProdGuard protection features run locally. Internet is required only for license operations.

  1. Check internet connectivity.
  2. Re-enter the License Key and validate again.
  3. If migrating devices, deactivate license on the old machine first.
  4. Use Export JSON on the old device and Import JSON on the new one to preserve environments and selectors.

Changes do not seem to apply ​

  1. Save the environment again in the popup.
  2. Reload the active tab.
  3. Reopen popup and verify current site state.
  • Standardize environment naming (for example PROD, STAGING).
  • Use consistent confirmation words policy per environment.
  • Maintain a shared baseline selector set and refine it over time.
  • Test protection rules after major UI changes in your product.

ProdGuard is most effective when teams treat it as part of their production safety process, not just a one-time setup.