sudo apt install python3 python3-venv
git clone https://github.com/ernos/extension-scanner.git
cd extension-scanner

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

git clone https://github.com/ernos/extension-scanner.git
cd extension-scanner
chmod +x extension-scanner.py
mkdir -p ~/.local/share/bin
ln -s $PWD/extension-scanner.py ~/.local/share/bin/extension-scanner


# Required for LSB steganography analysis (optional but recommended)
pip install pillow numpy

# OPTION 1. Only for current user:
# Enable bash completions for simpler use (TAB for autocompleting commands)
mkdir -p ~/.local/share/bash-completion/completions
cp extension-scanner-completions ~/.local/share/bash-completion/completions
echo "source ~/.local/share/bash-completion/completions/extension-scanner-completions" >> ~/.bashrc

# OPTION 2. Enable completions globally for all users (Should be auto-sourced from your .bashrc)
cp extension-scanner-completions /usr/share/bash-completion/completions

usage: xpiscanner [-h] [--update-blocklist] [--min-severity {CRITICAL,HIGH,MEDIUM,LOW,INFO}] [--json] [--compact] [-v] [-m] [--scans CHECK [CHECK ...]]
                  [targets ...]

Firefox Extension Scanner - Scans XPI files for security risks and malware indicators

positional arguments:
  targets               One or more XPI files or directories containing XPIs to analyze

options:
  -h, --help            show this help message and exit
  --update-blocklist, --update, -u
                        Fetch fresh domain blocklists from URLhaus and Peter Lowe's list, merge with the bundled snapshot, and saves to
                        /home/peb/projects/Firefox-Extensions/extension-scanner/blocklist.json. Exits after updating.
  --min-severity {CRITICAL,HIGH,MEDIUM,LOW,INFO}
                        Minimum severity to display (CRITICAL, HIGH, MEDIUM, LOW, INFO; default: INFO)
  --json                Output results as JSON instead of formatted text
  --compact, -c         Print each finding on 1-2 lines instead of the default 3-line format
  -v, --verbose         Enable verbose output: show additional context for findings
  -m, --manifest        Show full extension manifest for each target
  --scans, -s CHECK [CHECK ...]
                        Limit analysis to specific check types. Choices: anti-analysis, api-abuse, credentials, cross-file,
                        file-meta, hidden-elements, obfuscation, payloads, permissions, polyglot, remote-code,
                        signatures, steganography, time-bomb, zip-tricks. Omit to run all checks (default).

    extension-scanner.py — Analyze Firefox (and other browsers) extension XPI files for security risks and malware indicators.

    Read README.md for information on how to interpret findings, limitations, and best practices for use.  
    This tool is intended for security researchers, analysts, and advanced users who want to perform a 
    comprehensive static analysis of browser extensions. It should work well for other browsers as well, 
    but this has only been tested on firefox.

Usage:
    python3 extension-scanner.py [OPTIONS] targets...

Targets can be individual .xpi files or directories containing .xpi files. Use glob patterns (e.g. *.xpi) for convenience.

Available check types:
    permissions               Dangerous/broad manifest permissions and CSP issues
    remote-code               Background pages or service workers loaded from remote URLs
    obfuscation               eval/atob/encoding tricks, suspicious URLs, high-entropy strings
    payloads                  Base64-encoded blobs decoded and scanned for executables/scripts
    steganography             PNG appended data (auto-decoded via base64/zlib/gzip), unknown chunks, LSB channel analysis
    credentials               Hardcoded API keys, tokens, passwords, private keys, IP addresses
    file-meta                 Magic bytes, double extensions, suspicious filenames, file entropy
    polyglot                  Files valid in two formats simultaneously (e.g. HTML+ZIP)
    zip-tricks                Path traversal, null bytes, duplicate entries, ZIP comments
    cross-file                HTML class tokens cross-referenced against JS localStorage keys
    signatures                Known strings from confirmed malicious extension families (qingcaila, YTMP4, etc.)
    api-abuse                 Browser API calls indicating data theft or exfiltration (cookies, tabs, history, keylogger, clipboard, executeScript)
    hidden-elements           Invisible iframes, zero-dimension element injection, tracking pixels (new Image().src)
    time-bomb                 Long-delay setTimeout, Date.now() gates, localStorage install-date checks, Math.random() gates
    anti-analysis             navigator.webdriver, zero-size window, bare debugger statement, performance.now() timing

Examples:
    python3 extension-scanner.py extension.xpi
    python3 extension-scanner.py *.xpi
    python3 extension-scanner.py /path/to/extensions/
    python3 extension-scanner.py a.xpi b.xpi --min-severity HIGH
    python3 extension-scanner.py ext.xpi --scans obfuscation payloads
    python3 extension-scanner.py ext.xpi --s steganography zip-tricks file-meta
    python3 extension-scanner.py ext.xpi --verbose
    python3 extension-scanner.py --update-blocklist
    python3 extension-scanner.py --manifest

Tips:
    - Make sure to source scanner-completions.sh from your .bashrc or .zshrc to enable tab completion for --scans categories and target file paths.
    - Use --min-severity to focus on the most critical findings first.
    - Use --scans to limit the analysis to specific categories of checks if you're looking for something specific or want to speed up the scan.
    - Review the full manifest with --manifest for context on permissions, content scripts, and other extension metadata that can help interpret findings.
    - Regularly update the blocklist with --update-blocklist to ensure the latest malicious domains are included in the checks.

Credits:
    Developed by Ernos @ https://www.yourdev.net
    Email: max at yourdev.net
    GitHub: https://www.github.com/ernos/extension-scanner

════════════════════════════════════════════════════════════════════════════
  XPI ANALYZER — example.xpi
════════════════════════════════════════════════════════════════════════════
  Overall verdict: HIGH RISK

  Findings: 1 CRITICAL  3 HIGH  2 MEDIUM  1 LOW

  ── CRITICAL ────────────────────────────────────────────────────────────
  [CRITICAL ] [JS_OBFUSCATION] content.js
           eval() call — can execute arbitrary code from strings
           Evidence: var x = eval(atob("dmFyIGE9MTs…"))

  ── HIGH ────────────────────────────────────────────────────────────────
  [HIGH     ] [PERMISSION] manifest.json
           Dangerous permission: 'nativeMessaging' — Can spawn native OS …
           Evidence: permissions: ['nativeMessaging', 'storage', '<all_urls>']
  …

python3 extension-scanner.py extension.xpi --min-severity HIGH
if [ $? -eq 2 ]; then echo "CRITICAL issues found!"; fi